timeseries class

Create timeseries object

Description

Time series are data vectors sampled over time, in order, often at regular intervals. They are distinguished from randomly sampled data that form the basis of many other data analyses. Time series represent the time-evolution of a dynamic population or process. The linear ordering of time series gives them a distinctive place in data analysis, with a specialized set of techniques. Time series analysis is concerned with:

  • Identifying patterns

  • Modeling patterns

  • Forecasting values

Construction

ts = timeseries creates an empty time-series object.

ts = timeseries(tsname) creates an empty time-series object using the name, tsname, for the time-series object. This name can differ from the time-series variable name.

ts = timeseries(data) creates the time-series object using the specified data.

ts = timeseries(data,time) creates the time-series object using the specified data and time.

ts = timeseries(data,time,quality) specifies quality in terms of codes defined by QualityInfo.Code.

ts = timeseries(data,'Name',tsname) creates the time-series object using the specified data and the name, tsname.

ts = timeseries(data,time,'Name',tsname) creates the time-series object using the specified data, time, and the name, tsname.

ts = timeseries(data,time,quality,'Name',tsname) uses the specified quality and the name, tsname.

Input Arguments

data

The time-series data, which can be an array of samples

tsname

Time-series name specified as a string

Default: ' '

time

The time vector.

When time values are date strings, you must specify Time as a cell array of date strings. When the time vector contains duplicate values:

  • Duplicated values must occupy contiguous elements.

  • Time values must not be decreasing.

Interpolating time-series data using methods like resample and synchronize can produce different results depending on whether the input timeseries contains duplicate times.

Default: A time vector that ranges from 0 to N-1 with a 1-second interval, where N is the number of samples.

quality

An integer vector with values-128 to 127 that specifies the quality in terms of codes defined by QualityInfo.Code

When Quality is a vector:

  • Quality must have the same length as the time vector.

  • Each Quality value applies to the corresponding data sample.

When Quality is an array:

  • Quality must have the same size as the data array.

  • Each Quality value applies to the corresponding data value of the ts.data array.

Properties

Data

Time-series data, where each data sample corresponds to a specific time

The data can be a scalar, a vector, or a multidimensional array. Either the first or last dimension of the data must align with Time.

By default, NaNs represent missing or unspecified data. Set the TreatNaNasMissing property to determine how missing data is treated in calculations.

Attributes:

Dependenttrue

DataInfo

Contains fields for storing contextual information about Data:

  • Unit — String that specifies data units

  • Interpolation — A tsdata.interpolation object that specifies the interpolation method for this timeseries object.

    Fields of the tsdata.interpolation object include:

    • Fhandle — Function handle to a user-defined interpolation function

    • Name — String that specifies the name of the interpolation method. Predefined methods include 'linear' and 'zoh' (zero-order hold). 'linear' is the default.

  • UserData — Any user-defined information entered as a string

Events

An array of tsdata.event objects that stores event information for this timeseries object.

You add events by using the addevent method. Fields of the tsdata.event object include the following:

  • EventData — Any user-defined information about the event

  • Name — String that specifies the name of the event

  • Time — Time value when this event occurs, specified as a real number or a date string

  • Units — Time units

  • StartDate — A reference date specified in MATLAB® date-string format. StartDate is empty when you have a numerical (non-date-string) time vector.

IsTimeFirst

Logical value (true or false) specifies whether the time vector is aligned with the first or last dimension of the Data array. The value is false for 3-D and higher dimensional data and true otherwise.

  • true — The first dimension of the data array is aligned with the time vector. For example, ts = timeseries(rand(3,3),1:3);

  • false — The last dimension of the data array is aligned with the time vector. For example: ts = timeseries(rand(3,4,5),1:5);

Attributes:

Dependenttrue
SetAccess'protected'

Length

Length of the time vector in the timeseries object

Attributes:

Dependenttrue
SetAccess'protected'

Name

The timeseries object name entered as a string, tsname.

This name can differ from the name of the timeseries variable in the MATLAB workspace.

Quality

An integer vector or array containing values -128 to 127 that specify the quality in terms of codes defined by QualityInfo.Code.

When Quality is a vector, it must have the same length as the time vector. In this case, each Quality value applies to a corresponding data sample.

When Quality is an array, it must have the same size as the data array. In this case, each Quality value applies to the corresponding value of the data array.

Attributes:

Dependenttrue

QualityInfo

Provides a lookup table that converts numerical Quality codes to readable descriptions.

QualityInfo fields include the following:

  • Code — Integer vector containing values -128 to 127 that define the "dictionary" of quality codes. You can assign one of these integer values to each Data value by using the Quality property.

  • Description — Cell vector of strings, where each element provides a readable description of the associated quality Code.

  • UserData — Stores any additional user-defined information.

Lengths of Code and Description must match.

Time

Array of time values.

When TimeInfo.StartDate is empty, the numerical Time values are measured relative to 0 in specified units. When TimeInfo.StartDate is defined, the time values are date strings measured relative to the StartDate in specified units.

The length of Time must be the same as either the first or the last dimension of Data. When the data contains three or more dimensions, the length of Time matches the size of the last data dimension. Otherwise, the length of Time matches the size of the first data dimension.

Attributes:

Dependenttrue

TimeInfo

Uses the following fields for storing contextual information about Time:

  • Units — Time units having any of following values: 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds', 'microseconds', or 'nanoseconds'

  • Start — Start time

  • End — End time (read only)

  • Increment — Interval between two subsequent time values

  • Length — Length of the time vector (read only)

  • Format — String defining the date string display format. See the MATLAB datestr function reference page for more information.

  • StartDate — Date string defining the reference date. See the MATLAB setabstime function reference page for more information.

  • UserData — Stores any additional user-defined information

TreatNaNasMissing

Logical value that specifies how to treat NaN values in Data:

  • true — (Default) Treats all NaN values as missing data except during statistical calculations.

  • false — Includes NaN values in statistical calculations, in which case NaN values are propagated to the result.

UserData

Generic field for data of any class that you want to add to the object.

Default: []

Methods

Time-Series Methods

Methods to Query and Set Object Properties and Plot the Data

get

Query timeseries object property values.

getdatasamplesize

Return the size of each data sample in a timeseries object.

getqualitydesc

Return data quality descriptions based on the Quality property values assigned to a timeseries object.

plot

Plot the timeseries object.

set

Set timeseries property values.

Methods to Manipulate Data and Time

addsample

Add a data sample to a timeseries object.

append

Concatenate timeseries objects in the time dimension.

ctranspose

Transpose a timeseries object.

delsample

Delete a sample from a timeseries object.

detrend

Subtract the mean or best-fit line and remove all NaNs from time-series data.

filter

Shape frequency content of time-series data using a 1-D digital filter.

getabstime

Extract a date-string time vector from a timeseries object into a cell array.

getdatasamples

Extract a subset of data samples from an existing timeseries object into an array using a subscripted indexed array.

getsamples

Extract a subset of data samples from an existing timeseries object into a new timeseries object using a subscript indexed array.

getinterpmethod

Get the interpolation method for a timeseries object.

getsampleusingtime

Extract data samples from an existing timeseries object into a new timeseries object based on specified start and end time values.

idealfilter

Apply an ideal pass or notch (noncausal) filter to a timeseries object.

resample

Select or interpolate data in a timeseries object using a new time vector.

setabstime

Set the time values in the time vector as date strings.

setinterpmethod

Set interpolation method for a timeseries object.

setuniformtime

Assign uniform time vector to timeseries object.

synchronize

Synchronize and resample two timeseries objects using a common time vector.

transpose

Transpose a timeseries object.

Event Methods

To construct an event object, use the constructor tsdata.event. For an example of defining events for a time-series object, see Defining Events.

addevent

Add one or more events to a timeseries object.

delevent

Delete one or more events from a timeseries object.

gettsafteratevent

Create a new timeseries object by extracting the samples from an existing time series that occur after or at a specified event.

gettsafterevent

Create a new timeseries object by extracting the samples that occur after a specified event from an existing time series.

gettsatevent

Create a new timeseries object by extracting the samples that occur at the same time as a specified event from an existing time series.

gettsbeforeatevent

Create a new timeseries object by extracting the samples that occur before or at a specified event from an existing time series.

gettsbeforeevent

Create a new timeseries object by extracting the samples that occur before a specified event from an existing time series.

gettsbetweenevents

Create a new timeseries object by extracting the samples that occur between two specified events from an existing time series.

Methods to Arithmetically Combine timeseries Objects

+

Addition of the corresponding data values of timeseries objects.

-

Subtraction of the corresponding data values of timeseries objects.

.*

Element-by-element multiplication of timeseries data.

*

Matrix-multiply timeseries data.

./

Right element-by-element division of timeseries data.

/

Right matrix division of timeseries data.

.\

Element-by-element left-array divide of timeseries data.

\

Left matrix division of timeseries data.

Methods to Calculate Descriptive Statistics for a timeseries Object

iqr

Return the interquartile range of timeseries data.

max

Return the maximum value of timeseries data.

mean

Return the mean of timeseries data.

median

Return the median of timeseries data.

min

Return the minimum of timeseries data.

std

Return the standard deviation of timeseries data.

sum

Return the sum of timeseries data.

var

Return the variance of timeseries data.

Definitions

timeseries

The time-series object, called timeseries, is a MATLAB variable that contains time-indexed data and properties in a single, coherent structure. For example, in addition to data and time values, you can also use the time-series object to store events, descriptive information about data and time, data quality, and the interpolation method.

Data Sample

A time-series data sample consists of one or more values recorded at a specific time. The number of data samples in a time series is the same as the length of the time vector.

For example, suppose that ts.data has the size 3-by-4-by-5 and the time vector has the length 5. Then, the number of samples is 5 and the total number of data values is 3 x 4 x 5 = 60.

Time Vector

A time vector of a timeseries object can be either numerical (double) values or valid MATLAB date strings.

When the timeseries TimeInfo.StartDate property is empty, the numerical time values are measured relative to 0 (or another numerical value) in specified units. In this case, the time vector is described as relative (that is, it contains time values that are not associated with a specific start date).

When TimeInfo.StartDate is nonempty, the time values are date strings measured relative to StartDate in specified units. In this case, the time vector is described as absolute (that is, it contains time values that are associated with a specific calendar date).

MATLAB supports the following date-string formats for time-series applications.

Date-String FormatUsage Example
dd-mmm-yyyy HH:MM:SS01-Mar-2000 15:45:17
dd-mmm-yyyy01-Mar-2000
mm/dd/yy03/01/00
mm/dd03/01
HH:MM:SS15:45:17
HH:MM:SS PM3:45:17 PM
HH:MM15:45
HH:MM PM3:45 PM
mmm.dd,yyyy HH:MM:SSMar.01,2000 15:45:17
mmm.dd,yyyyMar.01,2000
mm/dd/yyyy03/01/2000

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB documentation.

Examples

Create a timeseries object called 'LaunchData' that contains four data sets, each stored as a column of length 5 and using the default time vector:

b = timeseries(rand(5, 4),'Name','LaunchData')

Create a timeseries object containing a single data set of length 5 and a time vector starting at 1 and ending at 5:

b = timeseries(rand(5,1),[1 2 3 4 5])

Create a timeseries object called 'FinancialData' containing five data points at a single time point:

b = timeseries(rand(1,5),1,'Name','FinancialData')
Was this topic helpful?