timeseries - Create timeseries object - MATLAB (original) (raw)

Description

Time series represent the time-evolution of a dynamic population or process. They are used to identify, model, and forecast patterns and behaviors in data that is sampled over discrete time intervals.

Note

timetable is recommended overtimeseries. Timetables can store time-stamped data of varying types and have a broad set of supporting functions for preprocessing, restructuring, and analysis.

There are no plans to remove the timeseries data type.

Creation

To create a timeseries object, use thetimeseries function with input arguments that describe the data samples.

Syntax

Description

ts = timeseries([datavals](#d126e1510446)) returns a timeseries object containing the data indatavals. It assigns default sample times starting at zero seconds with a time step of one second.

example

ts = timeseries([datavals](#d126e1510446),[timevals](#d126e1510496)) specifies the sample times for the series. The resulting object sorts the data by time.

ts = timeseries([datavals](#d126e1510446),[timevals](#d126e1510496),[quality](#d126e1510611)) specifies quality descriptions in terms of the codes defined byQualityInfo.Code.

ts = timeseries(___,'Name',tsname) specifies a name tsname for thetimeseries object.

ts = timeseries() returns an emptytimeseries object.

ts = timeseries([tsname](#d126e1510668)) creates an empty timeseries object with nametsname.

Input Arguments

expand all

Sample data, specified as a numeric or logical scalar, vector, or multidimensional array.

Sample times, specified as a numeric scalar or vector, or a cell array of date character vectors. Valid date character vectors can have the following forms:

Format	Example
dd-mmm-yyyy HH:MM:SS	01-Mar-2000 15:45:17
dd-mmm-yyyy	01-Mar-2000
mm/dd/yy	03/01/00
mm/dd	03/01
HH:MM:SS	15:45:17
HH:MM:SS PM	3:45:17 PM
HH:MM	15:45
HH:MM PM	3:45 PM
mmm.dd,yyyy HH:MM:SS	Mar.01,2000 15:45:17
mmm.dd,yyyy	Mar.01,2000
mm/dd/yyyy	03/01/2000

Quality codes, specified as [] or a scalar, vector, or multidimensional array of integers ranging from -128 to 127.

When the quality code value is a vector, it must have the same length as the time vector. Each element applies to the corresponding data sample.
When the quality code value is an array, it must have the same size as the data array. Each element applies to the corresponding element of the data array.

timeseries name, specified as a character vector.

Properties

expand all

Sample data, represented as a numeric or logical scalar, vector, or multidimensional array. Either the first or the last dimension of the data must align with the orientation of the time vector.

Data has the following attributes:

Data information, represented as a collection of the following fields:

Units — Character vector specifying data units.
Interpolation — Atsdata.interpolation object that specifies the interpolation method.
Fields of the tsdata.interpolation object include the following:
- Fhandle — Function handle to a user-defined interpolation function.
- Name — Character vector specifying the name of the interpolation method. Methods include 'linear' (default) for linear interpolation and 'zoh' for zero-order hold.
UserData — Additional user-defined information entered as a character vector.

Event information, represented as an array oftsdata.event objects containing event information.

Fields of the tsdata.event object include the following:

EventData — Additional user-defined information about the event.
Name — Character vector specifying the name of the event
Time — Time for which the event occurs, specified as a real number or a date character vector.
Units — Time units.
StartDate — A reference date specified as a date character vector. StartDate is empty when the time vector is numeric.

Time vector alignment, represented as one of the following options:

true — The first dimension of the data array is aligned with the time vector. For example,ts = timeseries(rand(3,3),1:3);
false — The last dimension of the data array is aligned with the time vector. For example,ts = timeseries(rand(3,4,5),1:5);

IsTimeFirst has the following attributes:

Dependent	true
SetAccess	'protected'

Time vector length, represented as a scalar.

Length has the following attributes:

Dependent	true
SetAccess	'protected'

timeseries name, represented as a character vector.

Quality codes, represented as [] or a scalar, vector, or multidimensional array of integers ranging from -128 to 127.

When the quality code value is a vector, it must have the same length as the time vector. Each element applies to the corresponding data sample.
When the quality code value is an array, it must have the same size as the data array. Each element applies to the corresponding element of the data array.

Quality has the following attributes:

Quality information to describe Quality codes, represented as a collection of the following fields:

Code — Integer vector containing values -128 to 127 that define the quality codes. You can assign one of these integer values to each Data value by using theQuality property.
Description — Cell array of character vectors, where each element provides a readable description of the associated qualityCode.
UserData — Additional user-defined information.

The lengths of Code and Description must match.

Time values, represented as a vector.

When TimeInfo.StartDate is empty, values are measured relative to 0. When TimeInfo.StartDate is defined, values represent date character vectors measured relative to theStartDate.

The length of Time must be the same as the first or the last dimension of Data.

Time has the following attributes:

Time information, represented as a collection of the following fields describing the time vector:

Units — Time units with value'weeks', 'days','hours', 'minutes','seconds','milliseconds','microseconds', or'nanoseconds'.
Start — Start time.
End — End time (read only).
Increment — Interval between subsequent time values (NaN when times are not uniformly sampled).
Length — Length of time vector (read only).
Format — Character vector defining the date display (see datestr).
StartDate — Date character vector defining the reference date (see setabstime). Specify StartDate using the same format asFormat.
UserData — Additional user-defined information.

To access the value of a field, use the formts.TimeInfo.field for a timeseries object ts.

Missing value indicator, represented as one of the following options:

true — Treat allNaN values as missing data except for descriptive statistics functions.
false — IncludeNaN values in descriptive statistics functions, propagating NaN to the result.

User data, represented as any additional data to add to thetimeseries object.

Object Functions

expand all

addevent	Add event to timeseries
addsample	Add data sample to timeseries object
append	Concatenate timeseries objects in time
delevent	Remove event from timeseries
delsample	Remove sample from timeseries object
detrend	Subtract mean or best-fit line from timeseries object
filter	Modify frequency content of timeseries objects
idealfilter	timeseries ideal filter
plot	Plot timeseries
resample	Resample time vector in timeseries ortscollection
setabstime	Set timeseries or tscollection times as date character vectors
setinterpmethod	Set default interpolation method for timeseries object
setuniformtime	Modify uniform timeseries time vector
synchronize	Synchronize and resample two timeseries objects using common time vector

iqr	Interquartile range of timeseries data
max	Maximum of timeseries data
mean	Mean of timeseries data
median	Median of timeseries data
min	Minimum of timeseries data
std	Standard deviation of timeseries data
sum	Sum of timeseries data
var	Variance of timeseries data

Examples

collapse all

Create a timeseries object with five scalar data samples, specifying a name for the timeseries. Then display the sample times and the data values.

ts1 = timeseries(([5 10 15 20 25])',"Name","MyTimeSeries")

timeseries

Common Properties: Name: 'MyTimeSeries' Time: [5x1 double] TimeInfo: [1x1 tsdata.timemetadata] Data: [5x1 double] DataInfo: [1x1 tsdata.datametadata]

More properties, Methods

Create a timeseries with five data samples, where each sample is a column vector of length 2. Therefore there are two sample times, starting at zero seconds.

ts2 = timeseries(rand(2,5))

timeseries

Common Properties: Name: 'unnamed' Time: [2x1 double] TimeInfo: [1x1 tsdata.timemetadata] Data: [2x5 double] DataInfo: [1x1 tsdata.datametadata]

More properties, Methods

Create a timeseries with five data samples that were sampled in intervals of 10 seconds.

ts3 = timeseries((1:5)',[0 10 20 30 40])

timeseries

Common Properties: Name: 'unnamed' Time: [5x1 double] TimeInfo: [1x1 tsdata.timemetadata] Data: [5x1 double] DataInfo: [1x1 tsdata.datametadata]

More properties, Methods

tsdata.timemetadata Namespace: tsdata

Uniform Time: Length 5 Increment 10 seconds

Time Range: Start 0 seconds End 40 seconds

Common Properties: Units: 'seconds' Format: '' StartDate: ''

More properties, Methods

Version History

Introduced before R2006a

expand all

When you open a timeseries object in the Variables editor, it now displays the Property, Value, Size, and Class fields directly, rather than displaying a specialized editor for timeseries data. You can still access and view all the properties of the timeseries object and edit some of its property values using this updated display.