Documentation 
On this page… 

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.
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.
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
count = 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 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. 
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.
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)
ans = 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
MATLAB displays the current property values of the count1 timeseries object.
View the current DataInfo properties using dot notation.
count1.DataInfo
tsdata.datametadata Package: tsdata Common Properties: Units: '' Interpolation: linear (tsdata.interpolation)
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
tsdata.datametadata Package: tsdata Common Properties: Units: 'cars' Interpolation: zoh (tsdata.interpolation)
Modify the time units to be 'hours' for the three time series.
count1.TimeInfo.Units = 'hours'; count2.TimeInfo.Units = 'hours'; count3.TimeInfo.Units = 'hours';
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)
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.
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 nameed 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')
Time Series Collection Object: count_coll Time vector characteristics Start time 1 hours End time 24 hours Member Time Series Objects: intersection1 intersection2
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)
Time Series Collection Object: count_coll Time vector characteristics Start time 1 hours End time 24 hours Member Time Series Objects: intersection1 intersection2 intersection3
All three members in the collection are listed.
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)
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.
Interpolate values at each halfhour mark.
tsc1 = resample(tsc,1:0.5:24)
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 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')
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
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 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 
Remove the intersection3 time series from the tscollection object tsc1.
tsc1 = removets(tsc1,'intersection3')
Time Series Collection Object: count_coll Time vector characteristics Start time 1 hours End time 24 hours Member Time Series Objects: intersection1 intersection2
Two time series as members in the collection are now listed.
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 = 'DEC252009 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';
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 xaxis and its data units display on the yaxis. 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 xaxis 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 commmands and overlay a % data grid. xlabel('Time (hours)') ylabel('car count') grid on
For more information on plotting options for time series, see timeseries.
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.
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.
For a description of all the time series methods, see timeseries.
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.
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:
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 parametervalue pairs after the Time and TimeSeries arguments:

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:

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 

Query tscollection object property values.  
Evaluate to true for an empty tscollection object.  
Return the length of the time vector.  
Plot the time series in a collection.  
Set tscollection property values.  
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 

Add a timeseries object to a tscollection object.  
Add data samples to a tscollection object.  
Delete one or more data samples from a tscollection object.  
Extract a datestring time vector from a tscollection object into a cell array.  
Extract data samples from an existing tscollectionobject into a new tscollection object.  
Return a cell array of time series names in a tscollection object.  
Horizontal concatenation of tscollection objects. Combines several timeseries objects with the same time vector into one time series collection.  
Remove one or more timeseries objects from a tscollection object.  
Select or interpolate data in a tscollection object using a new time vector.  
Set the time values in the time vector of a tscollection object as date strings.  
Change the name of the selected timeseries object in a tscollection object.  
Vertical concatenation of tscollection objects. Joins several tscollection objects along the time dimension. 