Main Content

timeseries

Create timeseries object

expand all in page

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 over timeseries. 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 the timeseries function with input arguments that describe the data samples.

Syntax

ts = timeseries(datavals)
ts = timeseries(datavals,timevals)
ts = timeseries(datavals,timevals,quality)
ts = timeseries(___,'Name',tsname)
ts = timeseries()
ts = timeseries(tsname)

Description

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

example

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

ts = timeseries(datavals,timevals,quality) specifies quality descriptions in terms of the codes defined by QualityInfo.Code.

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

ts = timeseries() returns an empty timeseries object.

ts = timeseries(tsname) creates an empty timeseries object with name tsname.

Input Arguments

expand all

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

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

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:

FormatExample
dd-mmm-yyyy HH:MM:SS01-Mar-2000 15:45:17
dd-mmm-yyyy01-Mar-2000
mm/dd/yy03/01/00
mm/dd03/01
HH:MM:SS15:45:17
HH:MM:SS PM3:45:17 PM
HH:MM15:45
HH:MM PM3:45 PM
mmm.dd,yyyy HH:MM:SSMar.01,2000 15:45:17
mmm.dd,yyyyMar.01,2000
mm/dd/yyyy03/01/2000

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | cell

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.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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:

Dependenttrue

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

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

  • Units — Character vector specifying data units.

  • Interpolation — A tsdata.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 of tsdata.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:

Dependenttrue
SetAccess'protected'

Time vector length, represented as a scalar.

Length has the following attributes:

Dependenttrue
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:

Dependenttrue

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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 the Quality property.

  • Description — Cell array of character vectors, where each element provides a readable description of the associated quality Code.

  • 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 the StartDate.

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

Time has the following attributes:

Dependenttrue

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 as Format.

  • UserData — Additional user-defined information.

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

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

  • true — Treat all NaN values as missing data except for descriptive statistics functions.

  • false — Include NaN values in descriptive statistics functions, propagating NaN to the result.

User data, represented as any additional data to add to the timeseries object.

Object Functions

expand all

addeventAdd event to timeseries
addsampleAdd data sample to timeseries object
appendConcatenate timeseries objects in time
deleventRemove event from timeseries
delsampleRemove sample from timeseries object
detrendSubtract mean or best-fit line from timeseries object
filterModify frequency content of timeseries objects
idealfiltertimeseries ideal filter
plotPlot timeseries
resampleResample time vector in timeseries or tscollection
setabstimeSet timeseries or tscollection times as date character vectors
setinterpmethodSet default interpolation method for timeseries object
setuniformtimeModify uniform timeseries time vector
synchronizeSynchronize and resample two timeseries objects using common time vector
getabstimeConvert timeseries or tscollection time vector to cell array
getdatasamplesAccess timeseries data samples
getdatasamplesizetimeseries data sample size
getinterpmethodtimeseries interpolation method
getqualitydesctimeseries data quality
getsamplesSubset of timeseries
getsampleusingtimeSubset of timeseries or tscollection data
gettsafterateventCreate timeseries at or after event
gettsaftereventCreate timeseries after event
gettsateventCreate timeseries at event
gettsbeforeateventCreate timeseries at or before event
gettsbeforeeventCreate timeseries before event
gettsbetweeneventsCreate timeseries between events
iqrInterquartile range of timeseries data
maxMaximum of timeseries data
meanMean of timeseries data
medianMedian of timeseries data
minMinimum of timeseries data
stdStandard deviation of timeseries data
sumSum of timeseries data
varVariance of timeseries data

Examples

collapse all

Open Live Script

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: tsdata.timemetadata
            Data: [5x1 double]
        DataInfo: tsdata.datametadata

ts1.Time
ans = 5×1

     0
     1
     2
     3
     4


ts1.Data
ans = 5×1

     5
    10
    15
    20
    25

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: tsdata.timemetadata
            Data: [2x5 double]
        DataInfo: tsdata.datametadata

ts2.Time
ans = 2×1

     0
     1

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: tsdata.timemetadata
            Data: [5x1 double]
        DataInfo: tsdata.datametadata

ts3.Time
ans = 5×1

     0
    10
    20
    30
    40


ts3.TimeInfo
  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: ''

Version History

Introduced before R2006a

expand all

See Also

| | |

Topics