retime

Arguments

tsin

timeseries object in input

newTimeStep

time step defined by 'yearly', 'monthly', 'daily', 'hourly', 'minutely', 'secondly'

newTimes

new time, duration or datetime column vector.

timeStep

time step, duration or calendarDuration value

sampleRate

number of samples per second (Hz), real scalar

method

method used to fill the missing values or to compute informations for each new row time

methods available to fill the missing value: 'default', 'fillwithmissing', 'fillwihconstant', 'linear', 'spline'

computation methods available: 'count', 'firstvalue', 'lastvalue', 'mode', a Scilab function, or an user function

Name, Value

Name: 'Constant', Value: a cell: option available only with fillwihconstant method

Name: 'IncludedEdge', Value: 'left' or 'right'. This option is only available with 'count', 'firstvalue', 'lastvalue', 'mode', Scilab function, user function methods.

tsout

new timeseries.

Description

retime creates a new timeserie, tsout, on a new time basis defined by newTimeStep, newTimes, TimeStep or SampleRate. tsout has the same variables (columns) that tsin.

tsout = retime(tsin, newTimeStep) created a new timeseries based on newTimeStep, regular spaced time. newTimeStep can be 'yearly', 'monthly' 'daily', 'hourly', 'minutely' ou 'secondly'

Specifying the method, tsout = retime(tsin, newTimeStep, method), the results will be different:

• 'default': either 'fillwithmissing' method or uses method defined in VariableContinuity property of tsin (see ).

• 'fillwithmissing': for the times of tsout not matching to the times of tsin, the rows of tsout are filled with the default values for each type (NaN for doubles, "" for strings, NaT for datetimes, ...).

• 'fillwithconstant': this method uses 'Constant' keyword. 'Constant' is a cell of the same number of columns than tsin without the Time column. The cell content must concord with the column of tsin.

• 'linear': linear interpolation. tsin must be sorted by time and contains unique values in the time column.

• 'spline': cubic spline interpolation. tsin must be sorted by time and contains unique values in the time column.

• 'count': counts the number of values of tsin contained in each new time step defined for tsout.

• 'firstvalue': takes the first value contained in tsin for each time step defined for tsout.

• 'lastvalue': takes the last value contained in tsin for each time step defined for tsout.

• 'mode': computes the mode of the values of tsin contained in each new time step defined for tsout.

• Scilab or user function: function used to compute values of tsout (for example: mean, sum, ...).

tsout = retime(tsin, newTimes) or tsout = retime(tsin, newTimes, method) returns a new timeseries based on the data of the column vector newTimes, that may be irregular. If newTimes doesn't match with the row times of tsin, method is used to fill missing values.

tsout = retime(tsin, "regular", "TimeStep", timestep) tsout = retime(tsin, "regular", method, "TimeStep", timestep) generates a timeseries with regular time step defined by timestep.

tsout = retime(tsin, "regular", "SampleRate", sampleRate) or tsout = retime(tsin, "regular", method, "SampleRate", sampleRate) generates a timeseries with regular time step defined by sampleRate.

tsout = retime(..., method, "IncludedEdge", "right"|"left"). When IncludedEdge is equal to 'left', the computed time base (newrowTimes) will be truncated to newrowTimes(1:$-1) unless newrowTimes($) is present in the initial time basis of tsin. If IncludedEdge is equal to "right", then newrowTimes will be truncated to newrowTimes(2:$) unless newrowTimes(1) is present in the initial time basis of tsin.

Examples

retime with linear method + newTimeStep = "minutely"

// newTimeStep == "minutely"
T = datetime(["2022-12-01 08:35:00"; "2022-12-01 08:37:00"; "2022-12-01 08:39:00"; ...
"2022-12-01 08:45:17"; "2022-12-01 08:47:00"]);

AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];

ts = timeseries(T, AmbientTemperature, FlowRate, "VariableNames", ["Time", "AmbientTemp", "FlowRate"])
r = retime(ts, 'minutely')

// with linear method
r = retime(ts, 'minutely', 'linear')

retime with linear method + newTimes

// with newTimes
T = datetime(["2022-12-01 08:35:00"; "2022-12-01 08:57:15"; "2022-12-01 09:27:43"; ...
"2022-12-01 10:00:00"; "2022-12-01 10:14:56"]);

AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];

ts = timeseries(T, AmbientTemperature, FlowRate, "VariableNames", ["Time", "AmbientTemp", "FlowRate"])
newTimes = [datetime("2022-12-01 08:30:00"):minutes(15):datetime("2022-12-01 10:15:00")]'
r = retime(ts, newTimes, 'linear')

retime with linear method + TimeStep

// with TimeStep
T = datetime(["2022-12-01 08:35:00"; "2022-12-01 08:57:15"; "2022-12-01 09:27:43"; ...
"2022-12-01 10:00:00"; "2022-12-01 10:14:56"]);

AmbientTemperature = [18; 18.5; 20; 20.2; 20.5];
FlowRate = [50; 52; 53; 55; 60];

ts = timeseries(T, AmbientTemperature, FlowRate, "VariableNames", ["Time", "AmbientTemp", "FlowRate"])
timestep = hours(1)
r = retime(ts, 'regular', 'linear', 'TimeStep', timestep)

retime with scilab function + IncludedEdge

// with scilab function
monthsM = [10 * ones(31,1); 11 * ones(30,1); 12 * ones(31,1)];
daysM = [(1:31)'; (1:30)'; (1:31)'];
T = datetime(2022, monthsM, daysM);

AmbientTemperature = floor(rand(92,1)*18);
FlowRate = floor(grand(92,1, "unf", 50,60));

ts = timeseries(T, AmbientTemperature, FlowRate, "VariableNames", ["Time", "AmbientTemp", "FlowRate"])
r = retime(ts, 'monthly', mean)
r = retime(ts, 'monthly', mean, 'IncludedEdge', 'right')

See also

• timeseries — create a timeseries - table with time as index
• synchronize — synchronize several timeseries on the same time basis
• isregular — check if the time vector is regular

History