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

#### Viewing Time Series Objects

After creating a `timeseries` object, as described in Creating Time Series Objects, you can view it in the Variables editor.

To view a `timeseries` object like `count1` in the Variables editor, use either of the following methods:

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

• On the Home tab, in the Variable section, click Open Variable and select `count1`. This method is not available in MATLAB Online™. #### 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 `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

`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 `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 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 `tscollection`object 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.