timeseries

Arguments

time

duration or datetime column vector used as time index in the timeseries

var1, ..., varN

vector with the same number of rows.

Each var can be different type.

timeStep

time step, duration or calendarDuration value

sampleRate

number of samples per second (Hz), real scalar

Name, Value

'VariableNames': matrix of strings that contains the name of each ts'column. Default value: ["Time", "Var1", ..., "VarN"]

'VariableUnits': matrix of strings that contains the unit of each column. Default value: ["", ..., ""]

'VariableContinuity': specifies how each variable is filled when calling the retime and synchronize functions: "unset", "continuous", "step", "event". Default value : ["", ..., ""]

'StartTime': specifies the start time of the timeseries. duration or datetime value. Default value: first element of time vector.

ts

timeseries object.

Description

The timeseries function creates a table with the time as index (first table column). The index contains datetime or duration data. The other columns correspond to the variables, one variable by one column. Each variable is a column vector that has its own data type. Warning: they must have the same number of lines.

ts = timeseries(time, var1, ..., varN) or ts = timeseries(var1, ..., varN, 'RowTimes', time) creates a timeseries from the time basis vector time and the data variables var1, ..., varN (column vector).

ts = timeseries(var1, ..., varN, 'TimeStep', timeStep) creates a timeseries whose the time vector is generated from the time step timeStep. timeStep is either a duration or a calendarDuration value. The first value of this time vector is zero seconds and will have the same number of rows as the variable data vectors.

ts = timeseries(var1, ..., varN, 'SampleRate', sampleRate) creates a timeseries whose the time vector is generated from the sample rate sampleRate. sampleRate is a real value, number of samples per second. The first value of this time vector is zero seconds and will have the same number of rows as the variable data vectors.

ts = timeseries(..., Name, Value) can be used to specify the variable names or unit, the start time or the continuity of variables.

• 'VariableNames': specify the name of variables as well as the name of the time column. It is a row vector and the number of names must be equal the number of timeseries variables + 1 (time column). For example, ["Time", "OutdoorTemp", "IndoorTemp"] is the correct vector if the timeseries has two variables. This data is stored in the properties of the timeseries ts in the 'VariableNames' field. For more information, see the Properties section below.

• 'VariableUnits': specify the unit of variables as well as the unit of the time column. It is a row vector and the number of units must be equal the number of timeseries variables + 1 (time column). This data is stored in the properties of the timeseries ts in the 'VariableUnits' field. For more information, see the Properties section below.

• 'VariableContinuity': specify how to fill missing data in the timeseries variables, using different methods:

  • 'unset': fill missing values with the default values for each type (NaN for doubles, "" for strings, NaT for datetimes, ...)

  • 'continuous': fill missing values with linear interpolation.

  • 'step': fill missing values with previous value.

  These methods are used in retime or synchronize functions.

• 'StartTime': specify the start time of timeseries. This property must be used with "TimeStep" or "SampleRate".

Timeseries Properties

ts contains several properties used to describe the index and the variables.

These properties can be accessed/modified by using Properties field of ts.

Here is the list of available fields in ts.Properties:

• Description: contains the description of the timeseries. Default value: "".

• VariableNames: contains the variable names of the timeseries. Default value: ["Time", "Var1", ..., "VarN"].

• VariableDescriptions: contains the variable descriptions of the timeseries. One description by variable (time included). Default value: "".

• VariableUnits: contains the variable units of the timeseries. Default value: "".

• VariableContinuity: contains the methods to fill the missing data when the timeseries is used in retime or syncrhonize functions.

• StartTime: contains the start time, either specified when the timeseries is created or the first row time in timeseries.

• SampleRate: contains the sample rate given during the call ts = timeseries(var1, ..., varN, 'SampleRate', sampleRate).

• TimeStep: contains the time step given during the call ts = timeseries(var1, ..., varN, 'TimeStep', timestep).

Examples

ts = timeseries(time, var1, ..., varN) when time is a datetime column vector

T = datetime(2022, 12, 1:5)';
AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];
ts = timeseries(T, AmbientTemperature, FlowRate)

ts = timeseries(time, var1, ..., varN) when time is a duration column vector

T = [duration(1, 0, 0):minutes(15):duration(2, 0, 0)]';
AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];
ts = timeseries(T, AmbientTemperature, FlowRate)

ts = timeseries(var1, ..., varN, 'RowTimes', time) when time is a datetime column vector

T = datetime(2022, 12, 1:5)';
AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];
ts = timeseries(AmbientTemperature, FlowRate, 'RowTimes', T)

ts = timeseries(var1, ..., varN, 'RowTimes', time) when time is a duration column vector

T = [duration(1, 0, 0):minutes(15):duration(2, 0, 0)]';
AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];
ts = timeseries(AmbientTemperature, FlowRate, 'RowTimes', T)

ts = timeseries(var1, ..., varN, 'TimeStep', timeStep) when timeStep is a duration value

timestep = hours(1);
AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];
ts = timeseries(AmbientTemperature, FlowRate, 'TimeStep', timestep)

ts = timeseries(var1, ..., varN, 'TimeStep', timeStep) when timeStep is a calendarDuration value

AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];
ts = timeseries(AmbientTemperature, FlowRate, 'TimeStep', caldays(1), 'StartTime', datetime(2022, 1, 1))

ts = timeseries(var1, ..., varN, 'SampleRate', sampleRate)

AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];
ts = timeseries(AmbientTemperature, FlowRate, 'SampleRate', 500)

With VariableNames and VariableUnits

T = datetime(2022, 12, 1:5)';
AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];
ts = timeseries(T, AmbientTemperature, FlowRate, 'VariableNames', ["Time", "AmbientTemp", "FlowRate"], "VariableUnits", ["", "C°", "kg/s"])
ts.Properties

With StartTime

timestep = hours(1);
AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];
ts = timeseries(AmbientTemperature, FlowRate, 'TimeStep', timestep, 'StartTime', datetime(2022, 1, 1))

ts = timeseries(AmbientTemperature, FlowRate, 'SampleRate', 500, 'StartTime', duration(0, 0, 30))

With VariableContinuity

T = datetime(["2022-12-01 00:00:00"; "2022-12-01 06:00:00"; "2022-12-01 12:00:00"; ...
"2022-12-01 18:00:00"; "2022-12-02 00:00:00"]);
WindDir = ["NW"; "NW"; "W"; "W"; "NW"];
WindSpeed = [8; 10; 7; 9.5; 10.2];
ts1 = timeseries(T, WindDir, WindSpeed, "VariableNames", ["Time", "WindDirection", "WindSpeed"], "VariableContinuity", ["", "unset", "continuous"])
ts2 = retime(ts1, 'hourly')

Access to properties + modify

T = datetime(2022, 12, 1:5)';
AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];
ts = timeseries(T, AmbientTemperature, FlowRate, 'VariableNames', ["Time", "AmbientTemp", "FlowRate"], "VariableUnits", ["", "C°", "kg/s"])
ts.Properties

ts.Properties.VariableNames = ["Time_in_day", "T_amb", "Qm"];
ts.Properties
ts

Access to data in the timeseries

T = datetime(["2022-12-01 00:00:00"; "2022-12-01 06:00:00"; "2022-12-01 12:00:00"; ...
"2022-12-01 18:00:00"; "2022-12-02 00:00:00"]);
WindDir = ["NW"; "NW"; "W"; "W"; "NW"];
WindSpeed = [8; 10; 7; 9.5; 10.2];
ts1 = timeseries(T, WindDir, WindSpeed, "VariableNames", ["Time", "WindDirection", "WindSpeed"])
ts1([2 4], :)
ts1("WindDirection")
ts1(3, 2) = {11.5}
ts1(datetime(2022,12,1), :) = {"W", 12.8}

See also

• duration — create a duration - duration in hours, minutes and seconds
• datetime — create points in time
• retime — create a new timeserie on a new time basis
• synchronize — synchronize several timeseries on the same time basis
• stackedplot — plot multiple timeseries on time axis