Main Content

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 method

  • tscollection — Stores a collection of timeseries 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 notation

  • Calling 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 5-by-3 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 M-by-N-by-P-by-... multidimensional array with M samples, the size of each data sample is N-by-P-by-... .

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 24-by-3 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 1-sec 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 zero-order 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 zero-order-hold 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 half-hour mark.

tsc1 = resample(tsc,1:0.5:24)

To add values at each half-hour mark, the default interpolation method of a time series is used. For example, the new data points in intersection1 are calculated by using the zero-order 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 half-hour intervals, and that Intersection 1 uses zero-order-hold 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 NaNs 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

NaN

NaN

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 NaNs 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 NaNs.

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 dot-notation 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 date-string 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 = '25-DEC-2009 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

tsc = tscollection(ts)

Creates a tscollection object tsc that includes one or more timeseries objects.

The ts argument can be one of the following:

  • Single timeseries object in the MATLAB workspace

  • Cell array of timeseries objects in the MATLAB workspace

The timeseries objects share the same time vector in the tscollection.

tsc = tscollection(Time)

Creates an empty tscollection object with the time vector Time.

When time values are date strings, you must specify Time as a cell array of date strings.

tsc = tscollection(Time, TimeSeries, 'Parameter', Value, ...)

Optionally enter the following parameter-value pairs after the Time and TimeSeries arguments:

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

Name

tscollection object name entered as a string. This name can differ from the name of the tscollection variable in the MATLAB workspace.

Time

A vector 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 represent date strings measured relative to StartDate in specified units.

The length of Time must match either the first or the last dimension of the Data property of each tscollection member.

TimeInfo

Uses the following fields to store contextual information about Time:

  • Units — Time units with the following values: 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds', 'microseconds', and 'nanoseconds'

  • Start — Start time

  • End — End time (read-only)

  • Increment — Interval between two subsequent time values. The increment is NaN when times are not uniformly sampled.

  • 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

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

Method

Description

get

Query tscollection object property values.

isempty

Evaluate to true for an empty tscollection object.

length

Return the length of the time vector.

plot

Plot the time series in a collection.

set

Set tscollection property values.

size

Return the size of a tscollection object.

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

addts

Add a timeseries object to a tscollection object.

addsampletocollection

Add data samples to a tscollection object.

delsamplefromcollection

Delete one or more data samples from a tscollection object.

getabstime

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

getsampleusingtime

Extract data samples from an existing tscollectionobject into a new tscollection object.

gettimeseriesnames

Return a cell array of time series names in a tscollection object.

horzcat

Horizontal concatenation of tscollection objects. Combines several timeseries objects with the same time vector into one time series collection.

removets

Remove one or more timeseries objects from a tscollection object.

resample

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

setabstime

Set the time values in the time vector of a tscollection object as date strings.

settimeseriesnames

Change the name of the selected timeseries object in a tscollection object.

vertcat

Vertical concatenation of tscollection objects. Joins several tscollection objects along the time dimension.