Time Series Objects

Introduction

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.

If you prefer to work with a graphical user interface (GUI), use MATLAB Time Series Tools to work with time series data. For more information about Time Series Tools, see Example: Time Series Tools.

Note   If you are new to programming with timeseries and tscollection objects, you might want to start by working with Time Series Tools and enabling Record Code. This option generates reusable MATLAB code based on the operations you perform in the GUI. For more information, see Generating Reusable MATLAB Code.

Back to Top

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.

Back to Top

Example: Time Series Objects and Methods

• Creating Time Series Objects

• Viewing Time Series Objects

• Modifying Time Series Units and Interpolation Method

• Defining Events

• Creating Time Series Collection Objects

• Resampling a Time Series Collection Object

• Adding a Data Sample to a Time Series Collection Object

• Removing and Interpolating Missing Data

• Removing a Time Series from a Time Series Collection

• Displaying Time Vector Values as Date Strings

• Plotting Time Series Collection Members

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.

The sample data provided with this example consists of a 24-by-3 matrix of double values, where each column represents hourly vehicle counts at each of three town intersections.

This adds the variable count to the MATLAB workspace:

%% Import the sample data
load count.dat

To view the count matrix, type

count

MATLAB displays the following 24-by-3 matrix:

11    11     9
 7    13    11
14    17    20
11    13     9
43    51    69
38    46    76
61   132   186
75   135   180
38    88   115
28    36    55
12    12    14
18    27    30
18    19    29
17    15    18
19    36    48
32    47    10
42    65    92
57    66   151
44    55    90
114  145   257
35    58    68
11    12    15
13     9    15
10     9     7

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.

Viewing Time Series Objects

After creating a timeseries object, as described in Creating Time Series Objects, you can view it in either the Variable Editor or Time Series Tools.

To view a timeseries object like count1 in the Variable Editor, use any one of several methods:

• Type open('count1') at the command prompt.

• Select count1 in the Workspace Browser and click the Open selection button .

• Double-click count1 in the Workspace Browser.

• Right-click count1 in the Workspace Browser and select Open selection from the context menu.

To view count1 in Time Series Tools, right-click count1 in the Workspace Browser and choose Open in Time Series Tools from the context menu.

When a timeseries object is opened in either the Variable Editor or Time Series Tools, it is displayed with the Time Series Editor:

For information on using the Time Series Editor, see Editing Data and Time.

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.

To view the current properties of count1, type

get(count1)

MATLAB responds by displaying the current property values of the count1 timeseries object:

               Events: []
                 Name: 'intersection1'
             UserData: []
                 Data: [24x1 double]
             DataInfo: [1x1 tsdata.datametadata]
                 Time: [24x1 double]
             TimeInfo: [1x1 tsdata.timemetadata]
              Quality: []
          QualityInfo: [1x1 tsdata.qualmetadata]
          IsTimeFirst: 1
    TreatNaNasMissing: 1
               Length: 24

View the current DataInfo properties using dot notation:

count1.DataInfo

MATLAB responds with:

tsdata.datametadata
  Package: tsdata

  Common Properties:
               Units: ''
       Interpolation: linear (tsdata.interpolation)

  More properties, Methods

Change the data units and the default interpolation method for count1, as follows:

count1.DataInfo.Units = 'cars';     % Specify new data units
           % Set the interpolation method to zero-order hold
count1.DataInfo.Interpolation = tsdata.interpolation('zoh');

To verify that the DataInfo properties have been modified, type:

count1.DataInfo

  tsdata.datametadata
  Package: tsdata

  Common Properties:
               Units: 'cars'
       Interpolation: zoh (tsdata.interpolation)

  More properties, Methods

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.

Use the following syntax to 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

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.

figure
plot(count1)

The plot reflects that count1 uses zero-order-hold interpolation.

If you plot time series count2, it replaces the count1 display. You see its events and that it uses linear interpolation:

plot(count2)

You can overlay time series plots by setting hold on. When you hold the plot and add new data to it, the title, data units and time units do not display. The plot method cannot determine if the units are the same, so it does not attempt to display x and y axis labels.

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.

Use the following syntax to 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')

MATLAB responds with

Time Series Collection Object: count_coll

Time vector characteristics

      Start time            1 hours
      End time              24 hours

Member Time Series Objects:

      intersection1
      intersection2

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 by using the following syntax:

tsc = addts(tsc, count3)

All three members in the collection are listed:

Time Series Collection Object: count_coll

Time vector characteristics

      Start time            1 hours
      End time              24 hours

Member Time Series Objects:

      intersection1
      intersection2
      intersection3

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.

To resample the time series to include data values every 2 hours instead of every hour and save it as a new tscollection object, enter the following syntax:

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

The result is:

Time Series Collection Object: count_coll

Time vector characteristics

      Start time            1 hours
      End time              23 hours

Member Time Series Objects:

      intersection1
      intersection2
      intersection3

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. For example, the following syntax interpolates values at each half-hour mark:

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

The result is:

Time Series Collection Object: count_coll

Time vector characteristics

      Start time            1 hours
      End time              24 hours

Member Time Series Objects:

      intersection1
      intersection2
      intersection3

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.

You can use the following syntax to 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

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.  Use the following syntax to 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, you must reintroduce NaN values in intersection2 and intersection3 (which you remove):

tsc1 = addsampletocollection(tsc1,'time',3.25,...
       'intersection1',5);

To interpolate the missing values in tsc1 using the current time vector (tsc1.Time), type the following syntax:

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

Removing a Time Series from a Time Series Collection

To remove the intersection3 time series from the tscollection object tsc1, type:

tsc1 = removets(tsc1,'intersection3')

Two time series as members in the collection are now listed:

Time Series Collection Object: count_coll

Time vector characteristics

      Start time            1 seconds
      End time              24 seconds

Member Time Series Objects:

      intersection1
      intersection2

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.

For example, suppose the reference date occurs on December 25, 2009:

tsc1.TimeInfo.Units = 'hours';
tsc1.TimeInfo.StartDate = 'DEC-25-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. and 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. To describe multiple series, add a legend. Set the DisplayName property of the line series to label each member, as follows:

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')

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

The final plot looks like this.

For more information on plotting options for time series, see timeseries.

Back to Top

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.

Back to Top

Time Series Collection Constructor

• Introduction

• Time Series Collection Constructor Syntax

• Time Series Collection Properties

• Time Series Collection Methods

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

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

Time Series Collection Methods

• General Time Series Collection Methods

• Data and Time Manipulation 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

Back to Top

Introduction

Time Series Tools

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit