retime

Resample or aggregate data in timetable, and resolve duplicate or irregular times

Syntax

TT2 = retime(TT1,newTimeStep,method)

TT2 = retime(TT1,'regular',method,'TimeStep',dt)

TT2 = retime(TT1,'regular',method,'SampleRate',Fs)

TT2 = retime(TT1,newTimes,method)

TT2 = retime(TT1,newTimeStep)

TT2 = retime(TT1,'regular','TimeStep',dt)

TT2 = retime(TT1,'regular','SampleRate',Fs)

TT2 = retime(TT1,newTimes)

TT2 = retime(___,Name,Value)

Description

TT2 = retime(TT1,newTimeStep,method) returns a timetable that contains the variables from TT1 and row times that are regularly spaced by the time step newTimeStep. The retime function resamples or aggregates data in the variables of TT1 using the function specified by method. You can use retime to:

• Interpolate data values from TT1 at different times.

• Aggregate data into time bins (for example, to create a timetable containing quarterly means from monthly data).

• Remove rows from TT1 that have duplicate row times.

• Make an irregular timetable into a regular timetable, since newTimeStep specifies regular row times.

The newTimeStep input argument is a character vector or string that specifies a predefined time step. For example, when newTimeStep is 'daily', and method is 'mean', then TT2 contains the daily means of the data from TT1.

The first row time of TT2 is on the time step before the earliest row time from TT1. The row times in TT2 cover the range of row times from TT1. However, TT2 might not include any of the actual row times from TT1, since TT1 might not have any row times that fall on any of the regular row times of TT2.

To interpolate or fill in values in TT2 using different methods for different variables, specify the VariableContinuity property of TT1. For more information, see Retime and Synchronize Timetable Variables Using Different Methods.

To resample or aggregate data from multiple timetables, see synchronize.

TT2 = retime(TT1,'regular',method,'TimeStep',dt) calculates regularly spaced row times using the time step dt. The dt input argument is a scalar duration or calendar duration, specifying a time step of any size. The row times of TT2 span the range of row times of TT1.

Use this syntax when the time step is not one of the predefined time steps you can specify as a character vector or string.

TT2 = retime(TT1,'regular',method,'SampleRate',Fs) calculates regularly spaced row times using the sample rate Fs. The Fs input argument is a numeric scalar that specifies the number of samples per second (Hz).

TT2 = retime(TT1,newTimes,method) adjusts the timetable variables data to the time vector newTimes, using the method specified by method. The newTimes time vector can be irregular, but it must be a sorted datetime or duration vector and contain unique values. The times in newTimes become the row times of TT2.

TT2 = retime(TT1,newTimeStep) adjusts timetable data using the 'fillwithmissing' method. TT2 has missing data indicators wherever TT2 has a row time that does not match any row time in TT1.

If TT1 has rows with duplicate row times and TT2 has row times that match the duplicates, then TT2 contains the first row from each group of rows in TT1 with duplicate row times that match.

TT2 = retime(TT1,'regular','TimeStep',dt) calculates regularly spaced row times using the time step dt and, where needed, inserts missing data indicators.

TT2 = retime(TT1,'regular','SampleRate',Fs) calculates regularly spaced row times using the sample rate Fs and, where needed, inserts missing data indicators.

TT2 = retime(TT1,newTimes) returns a timetable containing missing data indicators wherever newTimes does not match row times in TT1.

TT2 = retime(___,Name,Value) adjusts timetable data using additional options specified by one or more Name,Value pairs. You can use this syntax with the input arguments of any of the previous syntaxes.

Examples

Interpolate Irregular Timetable Data at Hourly Times

Create timetable data that are approximately hourly, but with some irregularity in the times. Interpolate the data so that the output timetable has regular hourly row times.

Time = datetime({'2015-12-18 07:02:12';'2015-12-18 08:00:47';...
                 '2015-12-18 09:01:37';'2015-12-18 10:03:10';...
                 '2015-12-18 10:59:34'});
Temp = [37.3;41.9;45.7;42.3;39.8];
Pressure = [30.1;29.9;30.03;29.9;29.8];
TT = timetable(Time,Temp,Pressure)

TT=5×2 timetable
            Time            Temp    Pressure
    ____________________    ____    ________

    18-Dec-2015 07:02:12    37.3      30.1  
    18-Dec-2015 08:00:47    41.9      29.9  
    18-Dec-2015 09:01:37    45.7     30.03  
    18-Dec-2015 10:03:10    42.3      29.9  
    18-Dec-2015 10:59:34    39.8      29.8  

To resample with cubic spline interpolation, specify 'spline'.

TT2 = retime(TT,'hourly','spline')

TT2=5×2 timetable
            Time             Temp     Pressure
    ____________________    ______    ________

    18-Dec-2015 07:00:00    37.228     30.124 
    18-Dec-2015 08:00:00    41.824     29.899 
    18-Dec-2015 09:00:00    45.694     30.029 
    18-Dec-2015 10:00:00    42.552      29.91 
    18-Dec-2015 11:00:00    39.808       29.8 

Aggregate Timetable Data and Calculate Mean Values

Create a timetable with temperature and pulse readings taken every fifteen minutes.

Time = [minutes(0):minutes(15):minutes(105)]';
Temp = [98;97.5;97.9;98.1;97.9;98;98.3;97.8];
Pulse = [80;75;73;68;69;65;72;71];
TT = timetable(Time,Temp,Pulse)

TT=8×2 timetable
     Time      Temp    Pulse
    _______    ____    _____

    0 min        98     80  
    15 min     97.5     75  
    30 min     97.9     73  
    45 min     98.1     68  
    60 min     97.9     69  
    75 min       98     65  
    90 min     98.3     72  
    105 min    97.8     71  

Calculate the mean for each reading over hourly time bins. When you aggregate data over time bins, the row times of the output timetable are the left edges of the time bins.

TT2 = retime(TT,'hourly','mean')

TT2=2×2 timetable
     Time      Temp     Pulse
    ______    ______    _____

    0 min     97.875       74
    60 min        98    69.25

Specify Time Step of Your Own

Create a timetable that contains times, temperature, and pressure readings taken approximately at the half-hour mark, but with one measurement from 9:00 AM missing.

Time = datetime({'2015-12-18 07:29:53';'2015-12-18 08:00:00';...
                 '2015-12-18 08:31:02';'2015-12-18 09:30:00'});
Temp = [37.3;41.9;45.7;39.8];
Pressure = [30.1;29.9;30.03;29.8];
TT1 = timetable(Time,Temp,Pressure)

TT1=4×2 timetable
            Time            Temp    Pressure
    ____________________    ____    ________

    18-Dec-2015 07:29:53    37.3      30.1  
    18-Dec-2015 08:00:00    41.9      29.9  
    18-Dec-2015 08:31:02    45.7     30.03  
    18-Dec-2015 09:30:00    39.8      29.8  

Specify a 30 minute time step. Since 30 minutes is not a predefined time step, you must specify it as a duration value, using the 'TimeStep' name-value pair argument. Resample the data from TT1 using linear interpolation.

dt = minutes(30);
TT2 = retime(TT1,'regular','linear','TimeStep',dt)

TT2=6×2 timetable
            Time             Temp     Pressure
    ____________________    ______    ________

    18-Dec-2015 07:00:00    32.736     30.298 
    18-Dec-2015 07:30:00    37.318     30.099 
    18-Dec-2015 08:00:00      41.9       29.9 
    18-Dec-2015 08:30:00    45.573     30.026 
    18-Dec-2015 09:00:00    42.802     29.917 
    18-Dec-2015 09:30:00      39.8       29.8 

Specify Sample Rate

Create a timetable using column vectors of data. The row times are between 10 and 50 milliseconds.

Intensity = [100 98.7 95.2 101.4 99.1]';
Time = milliseconds([11 20 34 40.3 49.9])';
TT1 = timetable(Time,Intensity)

TT1=5×1 timetable
       Time       Intensity
    __________    _________

    0.011 sec         100  
    0.02 sec         98.7  
    0.034 sec        95.2  
    0.0403 sec      101.4  
    0.0499 sec       99.1  

Resample the data in TT1 using a sample rate of 100 Hz.

TT2 = retime(TT1,'regular','linear','SampleRate',100)

TT2=5×1 timetable
      Time      Intensity
    ________    _________

    0.01 sec     100.14  
    0.02 sec       98.7  
    0.03 sec       96.2  
    0.04 sec      101.1  
    0.05 sec     99.076  

Interpolate Timetable Data to Time Vector

Create a timetable that contains times, temperature, and pressure readings.

Time = datetime({'2015-12-18 07:29:53';'2015-12-18 08:00:00';...
                 '2015-12-18 08:31:02';'2015-12-18 09:30:00'});
Temp = [37.3;41.9;45.7;39.8];
Pressure = [30.1;29.9;30.03;29.8];
TT1 = timetable(Time,Temp,Pressure)

TT1=4×2 timetable
            Time            Temp    Pressure
    ____________________    ____    ________

    18-Dec-2015 07:29:53    37.3      30.1  
    18-Dec-2015 08:00:00    41.9      29.9  
    18-Dec-2015 08:31:02    45.7     30.03  
    18-Dec-2015 09:30:00    39.8      29.8  

Create a time vector and interpolate the timetable data at the times in the vector. This time vector starts at 8:00 AM. If you instead use the 'TimeStep' name-value pair argument, then the output timetable would start at 7:00 AM. One reason to use a time vector is to ensure that the output timetable starts, and ends, with times you specify.

newTimes = [datetime('2015-12-18 08:00:00'):minutes(30):datetime('2015-12-18 09:30:00')];
TT2 = retime(TT1,newTimes,'linear')

TT2=4×2 timetable
            Time             Temp     Pressure
    ____________________    ______    ________

    18-Dec-2015 08:00:00      41.9       29.9 
    18-Dec-2015 08:30:00    45.573     30.026 
    18-Dec-2015 09:00:00    42.802     29.917 
    18-Dec-2015 09:30:00      39.8       29.8 

Adjust Timetable by Inserting Missing Data Indicators

Create a timetable that contains times and measurements of wind speed and direction.

Time = datetime({'2015-12-18 07:00:00';'2015-12-18 08:03:47';...
                 '2015-12-18 09:00:00';'2015-12-18 10:00:00';...
                 '2015-12-18 10:59:34'});
WindSpeed = [13.4;6.5;7.3;8.5;2.3];
WindDirection = categorical({'NE';'N';'NE';'NW';'W'});
TT1 = timetable(Time,WindSpeed,WindDirection)

TT1=5×2 timetable
            Time            WindSpeed    WindDirection
    ____________________    _________    _____________

    18-Dec-2015 07:00:00      13.4            NE      
    18-Dec-2015 08:03:47       6.5            N       
    18-Dec-2015 09:00:00       7.3            NE      
    18-Dec-2015 10:00:00       8.5            NW      
    18-Dec-2015 10:59:34       2.3            W       

Adjust the data to an hourly time vector. Insert missing data indicators in TT2 where TT1 does not have data on the hourly time vector.

TT2 = retime(TT1,'hourly')

TT2=5×2 timetable
            Time            WindSpeed    WindDirection
    ____________________    _________    _____________

    18-Dec-2015 07:00:00      13.4        NE          
    18-Dec-2015 08:00:00       NaN        <undefined> 
    18-Dec-2015 09:00:00       7.3        NE          
    18-Dec-2015 10:00:00       8.5        NW          
    18-Dec-2015 11:00:00       NaN        <undefined> 

Apply Multiple Methods to Timetable

Load a timetable. Adjust the timetable variables using the retime function and different methods for different variables.

Load a timetable with temperature, wind speed, and rainfall measurements for Boston.

load bostonTT
Boston

Boston=6×3 timetable
           Time            Temp    WindSpeed    Rain
    ___________________    ____    _________    ____

    2016-06-09 06:03:00    59.5       0.1       0.05
    2016-06-09 12:00:23      63       2.3       0.08
    2016-06-09 18:02:57    61.7       3.1       0.13
    2016-06-10 06:01:47    55.4       5.7       0.15
    2016-06-10 12:06:00    62.3       2.6       0.87
    2016-06-10 18:02:57    58.8       6.2       0.33

Adjust the data to produce daily mean temperatures and wind speeds, and daily sums of the rainfall. retime applies the same method to all timetable variables. To apply different methods, index into the timetable to select variables, and call retime for each method you use.

BOS = Boston(:,{'Temp','WindSpeed'});
TT1 = retime(BOS,'daily','mean')

TT1=2×2 timetable
           Time             Temp     WindSpeed
    ___________________    ______    _________

    2016-06-09 00:00:00      61.4     1.8333  
    2016-06-10 00:00:00    58.833     4.8333  

BOS = Boston(:,'Rain');
TT2 = retime(BOS,'daily','sum')

TT2=2×1 timetable
           Time            Rain
    ___________________    ____

    2016-06-09 00:00:00    0.26
    2016-06-10 00:00:00    1.35

To combine all results in one timetable, concatenate TT1 and TT2.

TT = [TT1 TT2]

TT=2×3 timetable
           Time             Temp     WindSpeed    Rain
    ___________________    ______    _________    ____

    2016-06-09 00:00:00      61.4     1.8333      0.26
    2016-06-10 00:00:00    58.833     4.8333      1.35

Include Right Edges of Time Bins

Bin timetable data into hourly bins. Specify the right edges, or end times, of the time bins as row times. By default, the left edges, or start times of the time bins, are row times.

Create a timetable with temperature and pulse readings taken at fifteen minutes intervals.

Time = [minutes(15):minutes(15):minutes(105)]';
Temp = [97.5;97.9;98.1;97.9;98;98.3;97.8];
Pulse = [75;73;68;69;65;72;71];
TT = timetable(Time,Temp,Pulse)

TT=7×2 timetable
     Time      Temp    Pulse
    _______    ____    _____

    15 min     97.5     75  
    30 min     97.9     73  
    45 min     98.1     68  
    60 min     97.9     69  
    75 min       98     65  
    90 min     98.3     72  
    105 min    97.8     71  

Calculate the mean for each reading over hourly time bins. Specify that the row times of the output timetable are the right edges of the time bins. Since the right edges are included, the reading at 60 minutes is included in the first time bin.

TT2 = retime(TT,'hourly','mean','IncludedEdge','right')

TT2=2×2 timetable
     Time       Temp     Pulse 
    _______    ______    ______

    60 min      97.85     71.25
    120 min    98.033    69.333

Calculate the means, with the left edges as the row times. The mean values are different from those in TT2, because the reading at 60 minutes is now in the second time bin.

TT3 = retime(TT,'hourly','mean')

TT3=2×2 timetable
     Time      Temp     Pulse
    ______    ______    _____

    0 min     97.833       72
    60 min        98    69.25

Input Arguments

TT1 — Input timetable

timetable

Input timetable.

newTimeStep — Time step for spacing times in output timetable

character vector

Time step for spacing times in the output timetable, specified as a character vector. newTimeStep can be any of the predefined time steps in the table.

Time Step	Description
'yearly'	One year
'quarterly'	One quarter
'monthly'	One month
'weekly'	One week
'daily'	One day
'hourly'	One hour
'minutely'	One minute
'secondly'	One second

dt — Time step of any size

duration scalar | calendar duration scalar

Time step of any size, specified as a duration or calendar duration scalar.

Data Types: duration | calendarDuration

Fs — Sample rate

numeric scalar

Sample rate, specified as a numeric scalar. Fs specifies the number of samples per second (Hz).

newTimes — New time vector

datetime vector | duration vector

New time vector, specified as a datetime vector or a duration vector. The new time vector can be irregular, but it must be sorted and contain unique values. The vector can have a different number of rows than TT1.

method — Method for adjusting timetable data

character vector | string scalar | function handle

Method for adjusting timetable data, specified as a character vector, string scalar, or function handle. You can use any of the listed methods listed to adjust the data from TT1.

Fill Methods

Copy data from the rows of TT1 when row times of TT2 match row times of TT1. Then, fill the remaining rows of TT2 with missing data indicators.

To fill the remaining rows with a constant instead of a missing data indicator, specify method as 'fillwithconstant' and use the 'Constant' name-value pair argument.

Method	Description
'fillwithmissing'	Fill gaps with missing data indicators (for example, NaN for numeric variables).
'fillwithconstant'	Fill gaps with the value of the 'Constant' name-value pair argument. The default value is 0.

Nearest Neighbor Methods

Copy data from the rows of TT1 to the rows of TT2 whose row times are the nearest match, according to the specified method. TT1 must be sorted by its row times.

Method	Description
'previous'	Copy data from the nearest preceding neighbor in the input timetable, proceeding from the end of the vector of row times. If there are duplicate row times, then 'previous' indicates the last of the duplicates.
'next'	Copy data from the nearest following neighbor in the input timetable, proceeding from the beginning of the vector of row times. If there are duplicate row times, then 'next' indicates the first of the duplicates.
'nearest'	Copy data from the nearest neighbor in the input timetable.

Interpolation Methods

Interpolate data values in TT2 from data values in neighboring rows of TT1. The input timetable must have row times that are sorted and unique. To control how the data are extrapolated beyond the first and last row times of TT1, use the 'EndValues' name-value pair argument.

Method	Description
'linear'	Use linear interpolation.
'spline'	Use piecewise cubic spline interpolation.
'pchip'	Use shape-preserving piecewise cubic interpolation.
'makima'	Use modified Akima cubic Hermite interpolation.

Aggregation Methods

Aggregate data from the rows of TT1 over time bins specified by the row times of TT2. Each row time of TT2 is the left edge of a time bin, with the next consecutive row time being the right edge. By default, the left edges are included in the time bins. To control whether the left or the right bin edges are included in the time bins, use the 'IncludedEdge' name-value pair argument.

If you specify the time vector newTimes, then newTimes must be sorted in ascending order.

All the listed methods omit NaNs, NaTs, and other missing data indicators, except for func. To include missing data indicators, specify func as a function handle to a function that includes them when aggregating data.

Method	Description
'sum'	Sum the values in each time bin.
'prod'	Calculate the product of the values in each time bin.
'mean'	Calculate the mean of the values in each time bin.
'median'	Calculate the median of the values in each time bin.
'mode'	Calculate the mode of the values in each time bin.
'min'	Calculate the minimum of the values in each time bin.
'max'	Calculate the maximum of the values in each time bin.
'count'	Count the number of values in each time bin.
'firstvalue'	Use the first value in each time bin.
'lastvalue'	Use the last value in each time bin.
@func	Use the function specified by the function handle (for example, @std to calculate the standard deviation for the values in each time bin). func must return an output argument that is a scalar or a row vector, and must accept empty inputs.

Default Method

The default method is equivalent to leaving method unspecified.

Method	Description
'default' (default)	Either fill gaps with missing data indicators, or use per-variable methods if they are specified by the VariableContinuity property of the input timetable.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: TT2 = retime(TT1,newTimes,'Constant',-1) creates the timetable TT2 and assigns the value -1 to elements in rows of TT2 with row times that do not match row times from TT1.

Constant — Value for filling gaps when method is 'fillwithconstant'

array

Value for filling gaps when the method is 'fillwithconstant', specified as the comma-separated pair consisting of 'Constant' and an array. The default value is 0. The data type of the value specified by 'Constant' must be compatible with the data types of the timetable variables.

Example: TT2 = retime(TT1,'hourly','fillwithconstant','Constant','NONE') fills gaps in TT2 with the character vector 'NONE' when all the variables in TT2 contain text.

EndValues — Method for extrapolation when using interpolation method

'extrap' (default) | scalar

Method for extrapolation when using an interpolation method, specified as the comma-separated pair consisting of 'EndValues' and either 'extrap' or a scalar. If you specify a scalar, then its data type must be compatible with all the timetable variables.

Method	Description
'extrap' (default)	Extrapolate using the method specified by the method input argument
scalar	Extrapolate by filling gaps outside the range of input row times with a scalar

Example: TT2 = retime(TT1,'daily','previous','EndValues',1000) fills gaps in TT2 with previous row values where TT2 has row times within the range of row times from TT1, and with the value 1000 where TT2 has row times outside that range.

IncludedEdge — Edges to include in each time bin

'left' (default) | 'right'

Edges to include in each time bin, specified as the comma-separated pair consisting of 'IncludedEdge' and either 'left' or 'right'. Each row time of TT2 is the left edge of a time bin, with the next consecutive row time being the right edge.

Edges to Include	Description
'left' (default)	All bins include the left bin edge, except for the last bin, which includes both edges
'right'	All bins include the right bin edge, except for the first bin, which includes both edges

If you specify 'left', then the time bins include the left edges except for the last bin, which includes both edges. If you specify 'right', then the time bins include the right edges except for the first bin, which includes both edges.

Example: TT2 = retime(TT1,'hourly','mean','IncludedEdge','right') includes the right bin edge of each time bin.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The retime function supports tall arrays with the following usage notes and limitations:

• Interpolation methods 'spline' and 'makima' are not supported.

• The 'EndValues' name-value argument is not supported.

• Retiming to 'regular' spaced row times is not supported.

• All variables in input timetables must support missing values (floating point, categorical, datetime, duration, or text) for the methods 'nearest', 'next', and 'previous'.

For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The row times of the output timetable are considered to be irregular, even when synchronized to row times that have a regular time step.

• The 'makima' interpolation method is not supported.

• If the VariableContinuity property of the input timetable is not constant, then this function ignores it.

• The 'weekly', 'monthly', and 'quarterly' time steps are not supported.

  • If the input timetable has row times that are datetime values, then the 'daily' and 'yearly' time steps also are not supported.

For more information, see Code Generation for Timetables (MATLAB Coder) and Timetable Limitations for Code Generation (MATLAB Coder).

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2016b

R2021a: 'SamplingRate' will be removed

The 'SamplingRate' name-value argument will be removed in a future release. Use 'SampleRate' instead. The corresponding timetable property is also named SampleRate.

For backward compatibility, you still can specify 'SamplingRate' as the name of the name-value argument. However, the value is assigned to the SampleRate property.

R2021a: 'fillwithconstant' method replaces missing data in rows taken from input timetable

If the input timetable has rows with missing data values, such as NaNs, and any of those rows are included in the output timetable, then using the 'fillwithconstant' method replaces those missing values with a constant. In previous releases the 'fillwithconstant' method does not replace missing values in rows taken from the input timetable.

For example, this code creates a timetable with a NaN in the second row.

T = timetable(datetime("today") + [1 2 3]', [1 nan 2]')

T =

  3×1 timetable

       Time        Var1
    ___________    ____

    20-Jan-2022      1 
    21-Jan-2022    NaN 
    22-Jan-2022      2 

This call to retime replaces the NaN with 0. But in previous releases, this call leaves the NaN in the output timetable.

T1 = retime(T,"daily","fillwithconstant","constant",0)

T1 =

  3×1 timetable

       Time        Var1
    ___________    ____

    20-Jan-2022     1  
    21-Jan-2022     0  
    22-Jan-2022     2