Time Series Objects and Collections
Types of Time Series and Their Uses
MATLAB^{®} time series objects are of two types:
timeseries
— Stores data and time values, as well as the metadata information that includes units, events, data quality, and interpolation methodtscollection
— Stores a collection oftimeseries
objects that share a common time vector, convenient for performing operations on synchronized time series with different units
This section discusses the following topics:
Using time series constructors to instantiate time series classes
Modifying object properties using
set
methods or dot notationCalling time series functions and methods
To get a quick overview of programming with timeseries
and tscollection
objects, follow the steps in Example: Time Series Objects and Methods.
Time Series Data Sample
To properly understand the description of timeseries
object properties and
methods in this documentation, it is important to clarify some terms
related to storing data in a timeseries
object—the
difference between a data value and a data
sample.
A data value is a single, scalar value
recorded at a specific time. A data sample consists
of one or more values associated with a specific time in the timeseries
object.
The number of data samples in a time series is the same as the length
of the time vector.
For example, consider data that consists of three sensor signals: two signals represent the position of an object in meters, and the third represents its velocity in meters/second.
To enter the data matrix, type the following at the MATLAB prompt:
x = [0.2 0.3 13; 0.1 0.4 15; NaN 2.8 17; 0.5 0.3 NaN; 0.3 0.1 15]
The NaN
value
represents a missing data value. MATLAB displays the following
5by3 matrix:
x= 0.2000 0.3000 13.0000 0.1000 0.4000 15.0000 NaN 2.8000 17.0000 0.5000 0.3000 NaN 0.3000 0.1000 15.0000
The first two columns of x
contain
quantities with the same units and you can create a multivariate timeseries
object
to store these two time series. For more information about creating timeseries
objects,
see Time Series Constructor. The
following command creates a timeseries
object ts_pos
to
store the position values:
ts_pos = timeseries(x(:,1:2), 1:5, 'name', 'Position')
MATLAB responds by displaying
the following properties of ts_pos
:
timeseries Common Properties: Name: 'Position' Time: [5x1 double] TimeInfo: [1x1 tsdata.timemetadata] Data: [5x2 double] DataInfo: [1x1 tsdata.datametadata] More properties, Methods
The Length
of the time vector,
which is 5
in this example, equals the number of
data samples in the timeseries
object. Find the
size of the data sample in ts_pos
by typing the
following at the MATLAB prompt:
getdatasamplesize(ts_pos) ans = 1 2
Similarly,
you can create a second timeseries
object to store
the velocity data:
ts_vel = timeseries(x(:,3), 1:5, 'name', 'Velocity');
Find the size of each data
sample in ts_vel
by typing the following:
getdatasamplesize(ts_vel) ans = 1 1
Notice that ts_vel
has one data value in
each data sample and ts_pos
has two data values
in each data sample.
Note
In general, when the time series data is an MbyNbyPby... multidimensional array with M samples, the size of each data sample is NbyPby... .
If you want to perform operations on the ts_pos
and ts_vel
timeseries
objects
while keeping them synchronized, group them in a time series collection.
For more information, see Time Series Collection Constructor Syntax.
Example: Time Series Objects and Methods
Creating Time Series Objects
This portion of the example illustrates how to create several timeseries
objects from an array.
For more information about the timeseries
object,
see Time Series Constructor.
Import the sample data from count.dat
to the MATLAB workspace.
load count.dat
This adds the 24by3 matrix, count
, to the workspace. Each column of count
represents hourly vehicle counts at each of three town intersections.
View the count
matrix.
count
Create three timeseries
objects to store the data collected at each intersection.
count1 = timeseries(count(:,1), 1:24,'name', 'intersection1'); count2 = timeseries(count(:,2), 1:24,'name', 'intersection2'); count3 = timeseries(count(:,3), 1:24,'name', 'intersection3');
Note
In the above construction, timeseries
objects
have both a variable name (e.g., count1
) and an
internal object name (e.g., intersection1
). The
variable name is used with MATLAB functions. The object name
is a property of the object, accessed with object methods. For more
information on timeseries
object properties and
methods, see Time Series Properties and Time Series Methods.
By default, a time series has a time vector having units of
seconds and a start time of 0 sec. The example constructs the count1
, count2
,
and count3
time series objects with start times
of 1 sec, end times of 24 sec, and 1sec increments. You will change
the time units to hours in Modifying Time Series Units and Interpolation Method.
Note
If you want to create a timeseries
object
that groups the three data columns in count
, use
the following syntax:
count_ts = timeseries(count, 1:24,'name','traffic_counts')
This is useful when all time series have the same units and you want to keep them synchronized during calculations.
Modifying Time Series Units and Interpolation Method
After creating a timeseries
object, as described
in Creating Time Series Objects,
you can modify its units and interpolation method using dot notation.
View the current properties of count1
.
get(count1)
MATLAB displays the current property values of the count1
timeseries
object.
View the current DataInfo
properties using dot notation.
count1.DataInfo
Change the data units for count1
to 'cars'
.
count1.DataInfo.Units = 'cars';
Set the interpolation method for count1
to zeroorder hold.
count1.DataInfo.Interpolation = tsdata.interpolation('zoh');
Verify that the DataInfo
properties have been modified.
count1.DataInfo
Modify the time units to be 'hours'
for the three time series.
count1.TimeInfo.Units = 'hours'; count2.TimeInfo.Units = 'hours'; count3.TimeInfo.Units = 'hours';
Defining Events
This portion of the example illustrates how to define events
for a timeseries
object by using the tsdata.event
auxiliary object. Events
mark the data at specific times. When you plot the data, event markers
are displayed on the plot. Events also provide a convenient way to
synchronize multiple time series.
Add two events to the data that mark the times of the AM commute and PM commute.
Construct and add the first event to all time series. The first event occurs at 8 AM.
e1 = tsdata.event('AMCommute',8); e1.Units = 'hours'; % Specify the units for time count1 = addevent(count1,e1); % Add the event to count1 count2 = addevent(count2,e1); % Add the event to count2 count3 = addevent(count3,e1); % Add the event to count3
Construct and add the second event to all time series. The second event occurs at 6 PM.
e2 = tsdata.event('PMCommute',18); e2.Units = 'hours'; % Specify the units for time count1 = addevent(count1,e2); % Add the event to count1 count2 = addevent(count2,e2); % Add the event to count2 count3 = addevent(count3,e2); % Add the event to count3
Plot the time series, count1
.
figure plot(count1)
When you plot any of the time series, the plot method defined for time series objects displays events as markers. By default markers are red filled circles.
The plot reflects that count1
uses zeroorderhold interpolation.
Plot count2
.
plot(count2)
If you plot time series count2
, it replaces the count1
display. You see its events and that it uses linear interpolation.
Overlay time series plots by setting hold on
.
hold on
plot(count3)
Creating Time Series Collection Objects
This portion of the example illustrates how to create a tscollection
object.
Each individual time series in a collection is called a member.
For more information about the tscollection
object,
see Time Series Collection Constructor.
Note
Typically, you use the tscollection
object
to group synchronized time series that have different units. In this
simple example, all time series have the same units and the tscollection
object
does not provide an advantage over grouping the three time series
in a single timeseries
object. For an example of
how to group several time series in one timeseries
object,
see Creating Time Series Objects.
Create a tscollection
object named count_coll
and use the constructor syntax to immediately add two of the three time series currently in the MATLAB workspace (you will add the third time series later).
tsc = tscollection({count1 count2},'name', 'count_coll')
Note
The time vectors of the timeseries
objects
you are adding to the tscollection
must match.
Notice that the Name
property of the timeseries
objects
is used to name the collection members as intersection1
and intersection2
.
Add the third timeseries
object in the workspace to the tscollection
.
tsc = addts(tsc, count3)
All three members in the collection are listed.
Resampling a Time Series Collection Object
This portion of the example illustrates how to resample each
member in a tscollection
using
a new time vector. The resampling operation is used to either select
existing data at specific time values, or to interpolate data at finer
intervals. If the new time vector contains time values that did not
exist in the previous time vector, the new data values are calculated
using the default interpolation method you associated with the time
series.
Resample the time series to include data values every 2 hours instead of every hour and save it as a new tscollection
object.
tsc1 = resample(tsc,1:2:24)
In some cases you might need a finer sampling of information than you currently have and it is reasonable to obtain it by interpolating data values.
Interpolate values at each halfhour mark.
tsc1 = resample(tsc,1:0.5:24)
To add values at each halfhour mark, the default interpolation
method of a time series is used. For example, the new data points
in intersection1
are calculated by using the zeroorder
hold interpolation method, which holds the value of the previous sample
constant. You set the interpolation method for intersection1
as
described in Modifying Time Series Units and Interpolation Method.
The new data points in intersection2
and intersection3
are
calculated using linear interpolation, which is the default method.
Plot the members of tsc1
with markers to see the results of interpolating.
hold off % Allow axes to clear before plotting plot(tsc1.intersection1,'xb','Displayname','Intersection 1')
You can see that data points have been interpolated at halfhour intervals, and that Intersection 1 uses zeroorderhold interpolation, while the other two members use linear interpolation.
Maintain the graph in the figure while you add the other two members to the plot. Because the plot
method suppresses the axis labels while hold
is on
, also add a legend to describe the three series.
hold on plot(tsc1.intersection2,'.xm','Displayname','Intersection 2') plot(tsc1.intersection3,':xr','Displayname','Intersection 3') legend('show','Location','NorthWest')
Adding a Data Sample to a Time Series Collection Object
This portion of the example illustrates how to add a data sample
to a tscollection
.
Add a data sample to the intersection1
collection member at 3.25 hours (i.e., 15 minutes after the hour).
tsc1 = addsampletocollection(tsc1,'time',3.25,... 'intersection1',5);
There are three members in the tsc1
collection,
and adding a data sample to one member adds a data sample to the other
two members at 3.25 hours. However, because you did not specify the
data values for intersection2
and intersection3
in
the new sample, the missing values are represented by NaN
s
for these members. To learn how to remove or interpolate missing data
values, see Removing Missing Data and Interpolating Missing Data.
tsc1
Data from 2.0 to 3.5 Hours
Hours  Intersection 1  Intersection 2  Intersection 3 

2.0  7  13  11 
2.5  7  15  15.5 
3.0  14  17  20 
3.25  5 


3.5  14  15  14.5 
To view all intersection1
data
(including the new sample at 3.25 hours), type
tsc1.intersection1
Similarly, to view all intersection2
data
(including the new sample at 3.25 hours containing a NaN
value),
type
tsc1.intersection2
Removing and Interpolating Missing Data
Time series objects use NaN
s to represent
missing data. This portion of the example illustrates how to either
remove missing data or interpolate values for it by using the interpolation
method you specified for that time series. In Adding a Data Sample to a Time Series Collection Object,
you added a new data sample to the tsc1
collection
at 3.25 hours.
As the tsc1
collection has three members,
adding a data sample to one member added a data sample to the other
two members at 3.25 hours. However, because you did not specify the
data values for the intersection2
and intersection3
members
at 3.25 hours, they currently contain missing values, represented
by NaN
s.
Removing Missing Data. Find and remove the data samples containing NaN values in the tsc1
collection.
tsc1 = delsamplefromcollection(tsc1,'index',... find(isnan(tsc1.intersection2.Data)));
This command searches one tscollection
member
at a time—in this case, intersection2
. When
a missing value is located in intersection2
, the
data at that time is removed from all members
of the tscollection
.
Note
Use dotnotation syntax to access
the Data
property of the intersection2
member
in the tsc1
collection:
tsc1.intersection2.Data
For a complete list of timeseries
properties,
see Time Series Properties.
Interpolating Missing Data. For the sake of this example, reintroduce NaN
values in intersection2
and intersection3
.
tsc1 = addsampletocollection(tsc1,'time',3.25,... 'intersection1',5);
Interpolate the missing values in tsc1
using the current time vector (tsc1.Time
).
tsc1 = resample(tsc1,tsc1.Time);
This replaces the NaN
values in intersection2
and intersection3
by
using linear interpolation—the default interpolation method
for these time series.
Note
Dot notation tsc1.Time
is used to access
the Time
property of the tsc1
collection.
For a complete list of tscollection
properties,
see Time Series Collection Properties.
To view intersection2
data
after interpolation, for example, type
tsc1.intersection2
New tsc1 Data from 2.0 to 3.5 Hours
Hours  Intersection 1  Intersection 2  Intersection 3 

2.0  7  13  11 
2.5  7  15  15.5 
3.0  14  17  20 
3.25  5  16  17.3 
3.5  14  15  14.5 
Removing a Time Series from a Time Series Collection
Remove the intersection3
time series from the tscollection
object tsc1
.
tsc1 = removets(tsc1,'intersection3')
Two time series as members in the collection are now listed.
Displaying Time Vector Values as Date Strings
This portion of the example illustrates how to control the format
in which numerical time vector display, using MATLAB date strings.
For a complete list of the MATLAB datestring formats supported
for timeseries
and tscollection
objects,
see the definition of time vector definition in the timeseries
reference page.
To use date strings, you must set the StartDate
field
of the TimeInfo
property. All values in the time
vector are converted to date strings using StartDate
as
a reference date.
Suppose the reference date occurs on December 25, 2009.
tsc1.TimeInfo.Units = 'hours'; tsc1.TimeInfo.StartDate = '25DEC2009 00:00:00';
Similarly to what you did with the count1
, count2
, and count3
time series objects, set the data units to of the tsc1
members to the string 'car count'
.
tsc1.intersection1.DataInfo.Units = 'car count'; tsc1.intersection2.DataInfo.Units = 'car count';
Plotting Time Series Collection Members
To plot data in a time series collection, you plot its members one at a time.
First graph tsc1
member intersection1
.
hold off
plot(tsc1.intersection1);
When you plot a member of a time series collection, its time units display on the x
axis and its data units display on the y
axis. The plot title is displayed as 'Time Series Plot:<member name>'
.
If you use the same figure to plot a different member of the collection, no annotations display. The time series plot
method does not attempt to update labels and titles when hold
is on
because the descriptors for the series can be different.
Plot intersection1
and intersection2
in the same figure. Prevent overwriting the plot, but remove axis labels and title. Add a legend and set the DisplayName
property of the line series to label each member.
plot(tsc1.intersection1,'xb','Displayname','Intersection 1') hold on plot(tsc1.intersection2,'.xm','Displayname','Intersection 2') legend('show','Location','NorthWest')
The plot now includes the two time series in the collection: intersection1
and intesection2
. Plotting the second graph erased the labels on the first graph.
Finally, change the date strings on the x
axis to hours
and plot the two time series collection members again with a legend.
Specify time units to be 'hours' for the collection.
tsc1.TimeInfo.Units = 'hours';
Specify the format for displaying time.
tsc1.TimeInfo.Format = 'HH:MM';
Recreate the last plot with new time units.
hold off plot(tsc1.intersection1,'xb','Displayname','Intersection 1') % Prevent overwriting plot, but remove axis labels and title. hold on plot(tsc1.intersection2,'.xm','Displayname','Intersection 2') legend('show','Location','NorthWest') % Restore the labels with the xlabel and ylabel commands and overlay a % data grid. xlabel('Time (hours)') ylabel('car count') grid on
For more information on plotting options for time series, see timeseries
.
Time Series Constructor
Before implementing the various MATLAB functions and methods
specifically designed to handle time series data, you must create
a timeseries
object to store the data. See timeseries
for the timeseries
object
constructor syntax.
For an example of using the constructor, see Creating Time Series Objects.
Time Series Properties
See timeseries
for
a description of all the timeseries
object properties.
You can specify the Data
, IsTimeFirst
, Name
, Quality
,
and Time
properties as input arguments in the constructor.
To assign other properties, use the set
function
or dot notation.
Note
To get property information from the command line, type help
timeseries/tsprops
at the MATLAB prompt.
For an example of editing timeseries
object
properties, see Modifying Time Series Units and Interpolation Method.
Time Series Methods
For a description of all the time series methods, see timeseries
.
Time Series Collection Constructor
Introduction
The MATLAB object, called tscollection
,
is a MATLAB variable that groups several time series with a common
time vector. The timeseries
objects that you include
in the tscollection
object
are called members of this collection, and possess
several methods for convenient analysis and manipulation of timeseries
.
Time Series Collection Constructor Syntax
Before you implement the MATLAB methods specifically designed
to operate on a collection of timeseries
objects,
you must create a tscollection
object
to store the data.
The following table summarizes the syntax for using the tscollection
constructor.
For an example of using this constructor, see Creating Time Series Collection Objects.
Time Series Collection Syntax Descriptions
Syntax  Description 

 Creates a The
The 
 Creates an empty When time
values are date strings, you must specify 
 Optionally enter the following parametervalue pairs
after the

Time Series Collection Properties
This table lists the properties of the tscollection
object.
You can specify the Name
, Time
,
and TimeInfo
properties as input arguments in the tscollection
constructor.
Time Series Collection Property Descriptions
Property  Description 



 A vector of time values. When The
length of 
 Uses the following fields to store contextual information
about

Time Series Collection Methods
General Time Series Collection Methods. Use the following methods to query and set object properties, and plot the data.
Methods for Querying Properties
Data and Time Manipulation Methods. Use the following methods to add or delete data samples, and
manipulate the tscollection
object.
Methods for Manipulating Data and Time
Method  Description 

Add a  
Add data samples to a  
Delete one or more data samples from a  
Extract a datestring time vector from a  
Extract data samples from an existing  
Return a cell array of time series names in a  
Horizontal concatenation of  
Remove one or more  
Select or interpolate data in a  
Set the time values in the time vector of a  
Change the name of the selected  
Vertical concatenation of 