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
Description
ts = timeseries(
returns a datavals
)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(___,'Name',tsname)
specifies a name tsname
for the
timeseries
object.
ts = timeseries()
returns an empty
timeseries
object.
ts = timeseries(
creates
an empty tsname
)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
— 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.
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 eventTime
— 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
true
| false
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' |
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
to127
that define the quality codes. You can assign one of these integer values to eachData
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
— 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 (seedatestr
).StartDate
— Date character vector defining the reference date (seesetabstime
). SpecifyStartDate
using the same format asFormat
.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 allNaN
values as missing data except for descriptive statistics functions.false
— IncludeNaN
values in descriptive statistics functions, propagatingNaN
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 |
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: 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 R2006aR2022a: Variable Editor warns that support for viewing timeseries
objects will be removed in a future release
The Variable Editor issues a warning that support for viewing
timeseries
objects will be removed from the Variable Editor
in a future release. To view time-indexed data in the Variable Editor use timetable
instead.
R2021b: Variable Editor support for viewing timeseries
objects will be removed in a future release
Variable Editor support for viewing timeseries
objects will be
removed in a future release.
See Also
timetable
| tscollection
| tsdata.event
| timeseries2timetable
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)