Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

retime

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

Syntax

TT2 = retime(TT1,newTimeStep,method)
TT2 = retime(TT1,newTimes,method)
TT2 = retime(TT1,newTimeStep)
TT2 = retime(TT1,newTimes)
TT = retime(___,Name,Value)

Description

example

TT2 = retime(TT1,newTimeStep,method) creates a timetable that contains the variables from TT1 and row times that are regularly spaced by the time step specified by newTimeStep. retime resamples or aggregates data from 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.

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 resample or aggregate data from multiple timetables, see synchronize.

example

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

example

TT2 = retime(TT1,newTimeStep) creates a timetable 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,newTimes) creates a timetable using the 'fillwithmissing' method. TT2 contains missing data indicators wherever newTimes does not match row times in TT1.

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

TT = retime(___,Name,Value) creates a timetable with 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

collapse all

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  

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

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   

Create a regular time vector and interpolate the data based on it. To resample the data from TT1 using linear interpolation, specify 'linear'.

newTimes = [datetime('2015-12-18 07:30:00'):minutes(30):datetime('2015-12-18 09:30:00')];
TT2 = retime(TT1,newTimes,'linear')
TT2 = 5×2 timetable
            Time             Temp     Pressure
    ____________________    ______    ________

    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  

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>  

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(fullfile(matlabroot,'examples','matlab','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

Input Arguments

collapse all

Input timetable.

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

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

New time vector, specified as a datetime vector or a duration vector. The new time vector must be a column vector. newTimes can have a different number of rows than TT1.

Method for adjusting timetable data, specified as a character vector or a 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' parameter.

Method

Description

'fillwithmissing' (default)

Fill gaps with missing data indicators (for example, NaN for numeric variables).

'fillwithconstant'

Fill gaps with the value of the 'Constant' parameter. 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' parameter.

Method

Description

'linear'

Use linear interpolation.

'spline'

Use piecewise cubic spline interpolation.

'pchip'

Use shape-preserving piecewise cubic 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' parameter.

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.

'mean'

Calculate the mean of the values in each time bin.

'prod'

Calculate the product 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.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: TT2 = retime(TT1,newTimes,'Constant',0) creates the timetable TT2 and fills its rows with zeroes where TT2 has row times that are not row times in TT1.

collapse all

Constant to fill missing values, specified as a numeric scalar.

Method for extrapolation when using interpolation method, specified as the comma-separated pair consisting of 'EndValues' and either 'extrap', or a constant scalar value.

Method

Description

'extrap' (default)

Extrapolate using the method specified by the method input argument

scalar value

Extrapolate by filling with a constant value (numeric, datetime, or duration value only)

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.

Introduced in R2016b

Was this topic helpful?