timeseries

Create timeseries object

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.

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

datavals — Sample data

scalar | vector | multidimensional array

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

timevals — Sample times

scalar | vector

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

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

quality — Quality codes

[] (default) | scalar | vector | multidimensional array

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

tsname — timeseries name

character vector

timeseries name, specified as a character vector.

Properties

Data — Sample data

scalar | vector | multidimensional array

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:

Dependent

true

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

DataInfo — Data information

collection of fields

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.

Events — Event information

array of tsdata.event objects

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.

IsTimeFirst — Time vector alignment

Read-only: 1 | 0

This property is read-only.

Time vector alignment, returned as a 1 or 0 of data type logical.

You cannot set the value of the IsTimeFirst property. Its value is determined by the number of dimensions of the data array. If the data array has:

• One or two dimensions, then the first dimension of the data array is aligned with the time vector. For example, ts = timeseries(rand(3,4),1:3) creates a timeseries object where the size of the time vector is 3-by-1 and the value IsTimeFirst is 1.

• Three or more dimensions, then the last dimension of the data array is aligned with the time vector. For example, ts = timeseries(rand(3,4,5),1:5) creates a timeseries object where the size of the time vector is 5-by-1 and the value of IsTimeFirst is 0.

IsTimeFirst has the following attributes:

Dependent	true
SetAccess	'protected'

Length — Time vector length

scalar

Time vector length, represented as a scalar.

Length has the following attributes:

Dependent	true
SetAccess	'protected'

Name — timeseries name

character vector

timeseries name, represented as a character vector.

Quality — Quality codes

[] (default) | scalar | vector | multidimensional array

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:

Dependent

true

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

QualityInfo — Quality information

collection of fields

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 — Time values

vector

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:

Dependent

true

TimeInfo — Time information

collection of fields

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.

TreatNaNasMissing — Missing value indicator

true (default) | false

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.

UserData — User data

[] (default)

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

Object Functions

Modify and Plot

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 or tscollection
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

Query

getabstime	Convert timeseries or tscollection time vector to cell array
getdatasamples	Access timeseries data samples
getdatasamplesize	timeseries data sample size
getinterpmethod	timeseries interpolation method
getqualitydesc	timeseries data quality
getsamples	Subset of timeseries
getsampleusingtime	Subset of timeseries or tscollection data
gettsafteratevent	Create timeseries at or after event
gettsafterevent	Create timeseries after event
gettsatevent	Create timeseries at event
gettsbeforeatevent	Create timeseries at or before event
gettsbeforeevent	Create timeseries before event
gettsbetweenevents	Create timeseries between events

Descriptive Statistics

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

Create timeseries

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

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

  More properties, Methods

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

  More properties, Methods

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

  More properties, Methods

Version History

Introduced before R2006a

R2025a: Variables editor directly displays properties of timeseries objects

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.