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 timeevolution 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 timeseries object.
ts
= timeseries(tsname
)
creates an empty timeseries object using the name, tsname
,
for the timeseries object. This name can differ from the timeseries
variable name.
ts
= timeseries(data
)
creates
the timeseries object using the specified data
.
ts
= timeseries(data
,time
)
creates the timeseries 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 timeseries object using the specified data
and
the name, tsname
.
ts
= timeseries(data
,time
,'Name',tsname
)
creates
the timeseries 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 timeseries data, which can be an array of samples

tsname

Timeseries 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:
Interpolating timeseries 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 N1 with
a 1second interval, where N is the number of samples. 
quality

An integer vector with values128 to 127 that
specifies the quality in terms of codes defined by QualityInfo.Code
When Quality is a vector: When Quality is an array:

Properties
Data

Timeseries 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, NaN s represent missing or unspecified
data. Set the TreatNaNasMissing property to determine
how missing data is treated in calculations.
Attributes:

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 userdefined interpolation function
Name — String that specifies
the name of the interpolation method. Predefined methods include 'linear' and 'zoh' (zeroorder
hold). 'linear' is the default.
UserData — Any userdefined
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 userdefined
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^{®} datestring format. StartDate is
empty when you have a numerical (nondatestring) 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
3D 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:
Dependent  true 
SetAccess  'protected' 

Length

Length of the time vector in the timeseries object
Attributes:
Dependent  true 
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:

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
userdefined 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:

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
userdefined 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
TimeSeries 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. 
delsample
 Delete a sample from a timeseries object. 
detrend
 Subtract the mean or bestfit line and remove all NaN s
from timeseries data. 
filter
 Shape frequency content of timeseries data using a 1D
digital filter. 
getabstime
 Extract a datestring 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. 
Event Methods
To construct an event object, use the constructor tsdata.event
. For an example of defining
events for a timeseries 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. 
.*
 Elementbyelement multiplication of timeseries data. 
*
 Matrixmultiply timeseries data. 
./
 Right elementbyelement division of timeseries data. 
/
 Right matrix division of timeseries data. 
.\
 Elementbyelement leftarray 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 timeseries object, called timeseries
,
is a MATLAB variable that contains timeindexed data and properties
in a single, coherent structure. For example, in addition to data
and time values, you can also use the timeseries object to store
events, descriptive information about data and time, data quality,
and the interpolation method.
Data Sample
A timeseries 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 3by4by5 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 datestring formats for timeseries
applications.
DateString Format  Usage Example 
ddmmmyyyy HH:MM:SS  01Mar2000 15:45:17 
ddmmmyyyy  01Mar2000 
mm/dd/yy  03/01/00 
mm/dd  03/01 
HH:MM:SS  15:45:17 
HH:MM:SS PM  3:45:17 PM 
HH:MM  15:45 
HH:MM PM  3:45 PM 
mmm.dd,yyyy HH:MM:SS  Mar.01,2000 15:45:17 
mmm.dd,yyyy  Mar.01,2000 
mm/dd/yyyy  03/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')
Introduced before R2006a