synchronize

Synchronize timetables to common time vector, and resample or aggregate data from input timetables

collapse all in page

Syntax

TT = synchronize(TT1,TT2)

TT = synchronize(TT1,TT2,newTimeBasis,method)

TT = synchronize(TT1,TT2,newTimeStep,method)

TT = synchronize(TT1,TT2,'regular',method,'TimeStep',dt)

TT = synchronize(TT1,TT2,'regular',method,'SampleRate',Fs)

TT = synchronize(TT1,TT2,newTimes,method)

TT = synchronize(TT1,TT2,newTimeBasis)

TT = synchronize(TT1,TT2,newTimeStep)

TT = synchronize(TT1,TT2,'regular','TimeStep',dt)

TT = synchronize(TT1,TT2,'regular','SampleRate',Fs)

TT = synchronize(TT1,TT2,newTimes)

TT = synchronize(TT1,TT2,___,Name,Value)

TT = synchronize(TT1,...,TTN,___)

Description

The synchronize function collects the variables from all input timetables, synchronizes them to a common time vector, and returns the result as a single timetable. The effect is similar to a horizontal concatenation, though the input timetables can have different row times. When the synchronize function synchronizes timetable variables to different times, it also resamples or aggregates the data in the variables using a method that you specify.

TT = synchronize(TT1,TT2) creates a timetable, TT, that contains all variables from both the input timetables TT1 and TT2, synchronized to a vector of row times that is the union of the row times from TT1 and TT2. The row times of TT are in sorted order with no repeated times.

In effect, synchronize horizontally concatenates the variables of TT1 and TT2, even when they have row times that differ. As a result, synchronize inserts a missing data indicator in TT wherever it has:

A row time only from TT1 but no corresponding data from the variables of TT2.
A row time only from TT2 but no corresponding data from the variables of TT1.

If TT1 and TT2 have variables with the same names, then synchronize renames them and copies both variables into TT.

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

example

TT = synchronize(TT1,TT2,newTimeBasis,method) creates TT by synchronizing the variables from TT1 and TT2 to a new time vector specified by newTimeBasis. synchronize resamples or aggregates data from the variables in TT1 and TT2 using the operation specified by method. The input argument, newTimeBasis, specifies how synchronize constructs the row times of TT from the row times of TT1 and TT2.

For example, if newTimeBasis is 'union' and method is 'linear', then TT contains the row times from TT1 and TT2, and synchronize uses linear interpolation to resample the data from the input timetables to the output row times.

example

TT = synchronize(TT1,TT2,newTimeStep,method) creates TT by synchronizing the variables from TT1 and TT2 to a new time vector that is regularly spaced by the time unit specified by newTimeStep.

For example, if newTimeStep is 'daily' and method is 'mean', then TT contains row times that are one day apart, and TT contains daily means for each variable from TT1 and TT2.

example

TT = synchronize(TT1,TT2,'regular',method,'TimeStep',dt) uses the time step dt to calculate regularly spaced row times. dt is a scalar duration or calendar duration. The row times of TT span the range of row times of TT1 and TT2.

example

TT = synchronize(TT1,TT2,'regular',method,'SampleRate',Fs) uses the sample rate Fs to calculate regularly spaced row times. Fs is a numeric scalar that specifies the number of samples per second (Hz).

TT = synchronize(TT1,TT2,newTimes,method) creates TT by synchronizing the variables from TT1 and TT2 to newTimes, a datetime or duration vector of unique, sorted times that you specify. The times in newTimes become the row times of TT.

example

TT = synchronize(TT1,TT2,newTimeBasis) creates TT by synchronizing the variables from TT1 and TT2 to a new time vector. synchronize inserts missing data indicators where needed in TT.

example

TT = synchronize(TT1,TT2,newTimeStep) creates TT by synchronizing the variables from TT1 and TT2 to a new time vector that is regularly spaced by the time unit specified by newTimeStep. The synchronize function inserts missing data indicators where needed in TT.

example

TT = synchronize(TT1,TT2,'regular','TimeStep',dt) uses the time step dt to calculate regularly spaced row times. dt is a scalar duration or calendar duration. The row times of TT span the range of row times of TT1 and TT2.

TT = synchronize(TT1,TT2,'regular','SampleRate',Fs) uses the sample rate Fs to calculate regularly spaced row times. Fs is a numeric scalar that specifies the number of samples per second (Hz).

TT = synchronize(TT1,TT2,newTimes) creates TT by synchronizing the variables from TT1 and TT2 to the time vector, newTimes. The synchronize function inserts missing data indicators where needed in TT.

TT = synchronize(TT1,TT2,___,Name,Value) synchronizes timetables 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.

TT = synchronize(TT1,...,TTN,___) creates the timetable, TT, by synchronizing the N timetables TT1,...,TTN. You can use this syntax with the input arguments of any of the previous syntaxes.

Examples

collapse all

Synchronize Timetables and Insert Missing Data Indicators

Open Live Script

Load two sample timetables from a file. Then synchronize their data to a vector of new row times.

load smallTT

Display the timetables. TT1 has row times that are out of order. TT1 and TT2 have different variables.

TT1

TT1=3×1 timetable
            Time            Temp
    ____________________    ____

    18-Dec-2015 12:00:00    42.3
    18-Dec-2015 08:00:00    37.3
    18-Dec-2015 10:00:00    39.1

TT2

TT2=3×1 timetable
            Time            Pressure
    ____________________    ________

    18-Dec-2015 09:00:00      30.1  
    18-Dec-2015 11:00:00     30.03  
    18-Dec-2015 13:00:00      29.9

Synchronize TT1 and TT2. The output timetable, TT, contains all the row times from both timetables, in sorted order. In TT, Temp contains NaN for row times from TT2, and Pressure contains NaN for row times from TT1.

TT = synchronize(TT1,TT2)

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

    18-Dec-2015 08:00:00    37.3       NaN  
    18-Dec-2015 09:00:00     NaN      30.1  
    18-Dec-2015 10:00:00    39.1       NaN  
    18-Dec-2015 11:00:00     NaN     30.03  
    18-Dec-2015 12:00:00    42.3       NaN  
    18-Dec-2015 13:00:00     NaN      29.9

Interpolate Data Values to Row Times

Open Live Script

Load two sample timetables that contain weather measurements. Synchronize their data to the union of the row times from the timetables.

load firstTT

Display the timetables.

TT1

TT1=3×1 timetable
            Time            Temp
    ____________________    ____

    06-Jun-2016 15:00:00    79.7
    06-Jun-2016 16:00:00    76.3
    06-Jun-2016 17:00:00    74.9

TT2

TT2=4×1 timetable
            Time            Humidity
    ____________________    ________

    06-Jun-2016 14:35:48      49.7  
    06-Jun-2016 15:35:48      52.2  
    06-Jun-2016 16:35:48      56.7  
    06-Jun-2016 17:35:48        60

Synchronize the timetables. To select the union of row times, specify 'union'. To resample TT1.Temp and TT2.Humidity using linear interpolation, specify 'linear'.

TT = synchronize(TT1,TT2,'union','linear')

TT=7×2 timetable
            Time             Temp     Humidity
    ____________________    ______    ________

    06-Jun-2016 14:35:48    81.071       49.7 
    06-Jun-2016 15:00:00      79.7     50.708 
    06-Jun-2016 15:35:48    77.671       52.2 
    06-Jun-2016 16:00:00      76.3     54.014 
    06-Jun-2016 16:35:48    75.464       56.7 
    06-Jun-2016 17:00:00      74.9      58.03 
    06-Jun-2016 17:35:48    74.064         60

Aggregate Data When Synchronizing Timetables

Open Live Script

Synchronize two timetables to new row times that specify time bins that each span a day. Aggregate the data from the input timetables into the daily time bins.

Load sample timetables that contain two different sets of environmental measurements, indoors and outdoors. The air quality data come from a sensor inside a building, while the weather measurements come from sensors outside. The timetables include measurements taken from November 15, 2015, to November 19, 2015.

load indoors
load outdoors

Display the first three lines of each timetable. They do not contain the same row times or variables.

indoors(1:3,:)

ans=3×2 timetable
           Time            Humidity    AirQuality
    ___________________    ________    __________

    2015-11-15 00:00:24       36           80    
    2015-11-15 01:13:35       36           80    
    2015-11-15 02:26:47       37           79

outdoors(1:3,:)

ans=3×3 timetable
           Time            Humidity    TemperatureF    PressureHg
    ___________________    ________    ____________    __________

    2015-11-15 00:00:24        49          51.3          29.61   
    2015-11-15 01:30:24      48.9          51.5          29.61   
    2015-11-15 03:00:24      48.9          51.5          29.61

Aggregate the data from the timetables into daily time bins using the synchronize function. Specify 'daily' to aggregate the data into time bins that span one day apiece. Specify 'mean' to obtain the mean values in each time bin for each variable.

TT = synchronize(indoors,outdoors,'daily','mean');
TT(1:3,:)

ans=3×5 timetable
           Time            Humidity_indoors    AirQuality    Humidity_outdoors    TemperatureF    PressureHg
    ___________________    ________________    __________    _________________    ____________    __________

    2015-11-15 00:00:00          36.5            80.05            48.931             51.394         29.607  
    2015-11-16 00:00:00         36.85            80.35            47.924             51.571         29.611  
    2015-11-17 00:00:00         36.85            79.45             48.45             51.238         29.613

Synchronize Timetables to Regular Times

Open Live Script

Synchronize two small timetables with weather measurements to a set of regular row times that span the row times in the input timetables. Specify a time step as the interval between consecutive row times in the output timetable. Use linear interpolation to resample data for times in the time vector that do not match row times from the input timetables.

First, load the two timetables.

load indoors
load outdoors

Display the first three lines of each timetable. They do not contain the same row times or variables.

indoors(1:3,:)

ans=3×2 timetable
           Time            Humidity    AirQuality
    ___________________    ________    __________

    2015-11-15 00:00:24       36           80    
    2015-11-15 01:13:35       36           80    
    2015-11-15 02:26:47       37           79

outdoors(1:3,:)

ans=3×3 timetable
           Time            Humidity    TemperatureF    PressureHg
    ___________________    ________    ____________    __________

    2015-11-15 00:00:24        49          51.3          29.61   
    2015-11-15 01:30:24      48.9          51.5          29.61   
    2015-11-15 03:00:24      48.9          51.5          29.61

Aggregate the data from the timetables into 30-minute time bins using the synchronize function. Specify a regular time step using the 'regular' input argument and the 'TimeStep' name-value pair argument. You can use these arguments to create a timetable that is regular, but whose time step is not a predefined step such as 'hourly'.

TT = synchronize(indoors,outdoors,'regular','linear','TimeStep',minutes(30));
TT(1:3,:)

ans=3×5 timetable
           Time            Humidity_indoors    AirQuality    Humidity_outdoors    TemperatureF    PressureHg
    ___________________    ________________    __________    _________________    ____________    __________

    2015-11-15 00:00:00           36               80                 49             51.299         29.61   
    2015-11-15 00:30:00           36               80             48.967             51.366         29.61   
    2015-11-15 01:00:00           36               80             48.934             51.432         29.61

Synchronize Timetables to Arbitrary Time Vector

Open Live Script

Synchronize two small timetables with weather measurements to an arbitrary time vector. Use linear interpolation to resample data for times in the time vector that do not match row times from the input timetables.

Load two small timetables, with row times for measurements taken at the half-hour mark. However, in each timetable, there is a row time for data that was not collected at the half-hour mark. Both timetables are irregular, which means that the time step is different between consecutive row times.

load halfHoursTT

Display the timetables. TT1 and TT2 have three rows and different variables.

TT1

TT1=3×1 timetable
            Time            Temp
    ____________________    ____

    18-Dec-2015 08:30:00    47.6
    18-Dec-2015 09:30:00    49.2
    18-Dec-2015 10:47:23    51.4

TT2

TT2=3×1 timetable
            Time            Pressure
    ____________________    ________

    18-Dec-2015 07:00:00      29.7  
    18-Dec-2015 09:30:00     30.03  
    18-Dec-2015 10:30:00      29.9

Specify a time vector that includes some of the row times from each timetable.

newTimes = datetime('2015-12-18 08:30:00') + hours(0:1:2)

newTimes = 1x3 datetime
   18-Dec-2015 08:30:00   18-Dec-2015 09:30:00   18-Dec-2015 10:30:00

Synchronize TT1 and TT2 to newTimes. The newTimes vector has times that are not row times of TT1 or TT2. To interpolate data values for times in newTimes that do not match row times in TT1 or TT2, specify 'linear'.

TT = synchronize(TT1,TT2,newTimes,'linear')

TT=3×2 timetable
            Time             Temp     Pressure
    ____________________    ______    ________

    18-Dec-2015 08:30:00      47.6     29.898 
    18-Dec-2015 09:30:00      49.2      30.03 
    18-Dec-2015 10:30:00    50.906       29.9

Synchronize Timetables with Intersecting Row Times

Open Live Script

Load two sample timetables and synchronize their data to a vector of row times they have in common.

load intersectTT

Display the timetables. TT1 and TT2 have three rows and different variables.

TT1

TT1=3×1 timetable
            Time            Temp
    ____________________    ____

    18-Dec-2015 08:00:00    37.3
    18-Dec-2015 10:00:00    39.1
    18-Dec-2015 12:00:00    42.3

TT2

TT2=3×1 timetable
            Time            Pressure
    ____________________    ________

    18-Dec-2015 06:00:00      30.1  
    18-Dec-2015 08:00:00     30.03  
    18-Dec-2015 10:00:00      29.9

Synchronize TT1 and TT2, specifying 'intersection' as the basis for the row times of the output timetable. TT has only two rows because TT1 and TT2 have only two row times in common.

TT = synchronize(TT1,TT2,'intersection')

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

    18-Dec-2015 08:00:00    37.3     30.03  
    18-Dec-2015 10:00:00    39.1      29.9

There is no need to interpolate or fill unmatched rows, because TT1 and TT2 both have data for the row times they have in common.

Synchronize Timetables to Hourly Times

Open Live Script

Synchronize two small timetables with weather measurements to an hourly time vector.

Load two small timetables. In each timetable, there is a row time for data that was not collected on the hour. Both timetables are irregular, which means that the time step is different between consecutive row times.

load irregularTT

Display the timetables. TT1 and TT2 have three rows and different variables.

TT1

TT1=3×1 timetable
            Time            Temp
    ____________________    ____

    18-Dec-2015 08:00:00    37.3
    18-Dec-2015 09:11:17    39.1
    18-Dec-2015 10:00:00    42.3

TT2

TT2=3×1 timetable
            Time            Pressure
    ____________________    ________

    18-Dec-2015 08:00:00      29.8  
    18-Dec-2015 09:27:23      29.7  
    18-Dec-2015 10:00:00      30.3

Synchronize TT1 and TT2, specifying 'hourly' as the time step for the row times of the output timetable. TT has data from TT1 and TT2 where they have row times that are on the hour. TT has missing data indicators where it has a row time that TT1 and TT2 do not have.

TT = synchronize(TT1,TT2,'hourly')

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

    18-Dec-2015 08:00:00    37.3      29.8  
    18-Dec-2015 09:00:00     NaN       NaN  
    18-Dec-2015 10:00:00    42.3      30.3

Synchronize Timetables Using Multiple Methods

Open Live Script

Synchronize two timetables. Apply the mean method to some timetable variables and the sum method to others.

Load two small timetables that contain weather measurements for Boston and Natick. Each timetable contains temperature and rainfall readings.

load citiesTT
Boston

Boston=6×2 timetable
           Time            Temp    Rain
    ___________________    ____    ____

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

Natick

Natick=5×2 timetable
           Time            Temp     Rain 
    ___________________    _____    _____

    2016-06-09 12:00:23     61.2    0.076
    2016-06-09 17:59:00     60.3     0.11
    2016-06-10 09:03:01     56.1     0.19
    2016-06-10 12:07:03    62.17     0.72
    2016-06-10 17:59:57     58.3      0.1

Synchronize the measurements to daily times to produce mean temperatures and the sums of the rainfall measurements. synchronize applies the specified method to all timetable variables. To apply different methods to different timetable variables, index into the timetables to select different variables, and call synchronize for each method you use.

BOS = Boston(:,'Temp');
NTK = Natick(:,'Temp');
TT1 = synchronize(BOS,NTK,'daily','mean')

TT1=2×2 timetable
           Time            Temp_BOS    Temp_NTK
    ___________________    ________    ________

    2016-06-09 00:00:00       61.4       60.75 
    2016-06-10 00:00:00     58.833      58.857

BOS = Boston(:,'Rain');
NTK = Natick(:,'Rain');
TT2 = synchronize(BOS,NTK,'daily','sum')

TT2=2×2 timetable
           Time            Rain_BOS    Rain_NTK
    ___________________    ________    ________

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

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

TT = [TT1 TT2]

TT=2×4 timetable
           Time            Temp_BOS    Temp_NTK    Rain_BOS    Rain_NTK
    ___________________    ________    ________    ________    ________

    2016-06-09 00:00:00       61.4       60.75       0.26       0.186  
    2016-06-10 00:00:00     58.833      58.857       1.35        1.01

Input Arguments

collapse all

`TT1,TT2` — Input timetables
timetables

Input timetables.

`newTimeBasis` — Basis for computing row times of output timetable
character vector

Basis for computing row times of output timetable, specified as a character vector. newTimeBasis can be any of the listed methods.

Method	Description
`'union'` (default)	Union of the row times
`'intersection'`	Intersection of the row times
`'commonrange'`	Union of the row times, but over the intersection of the time ranges
`'first'`	Row times from the first input timetable only
`'last'`	Row times from the last input timetable only

`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 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

The first row time of TT is at the beginning of the time unit that includes the earliest row time from the input timetables. The range of row times in TT covers the range of row times from TT1 and TT2. However, TT might not include any of the actual row times from TT1 or TT2, since they can have row times that are not at the beginnings of any time unit.

`Fs` — Sample rate
numeric scalar

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

`dt` — Time step
duration scalar | calendar duration scalar

Time step, specified as a duration or calendar duration scalar.

Data Types: duration | calendarDuration

`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 any of the input timetables.

`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 to adjust the data from the input timetables.

Fill Methods

Copy data from the rows of each input timetable when row times of the output timetable match row times of the corresponding input. Then, fill the remaining elements of the output timetable with missing data indicators.

To fill the remaining elements with a constant instead of a missing data indicator, use the 'Constant' name-value pair argument.

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

Nearest Neighbor Methods

Copy data from the rows of the input timetables to output timetable rows whose row times are the nearest match, according to the specified method. Input timetables must be sorted by 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 the output timetable from data values in neighboring rows of the input timetables. Input timetables must have row times that are sorted and unique. To control how the data are extrapolated beyond the first and last row times of the input timetables, 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 rows of the input timetables over time bins specified by the row times of the output timetable. Each row time of TT 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. If you specify the time basis of the output timetable as 'first' or 'last', then the row times of either the first or the last timetable 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 timetables.

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: TT = synchronize(TT1,TT2,newTimes,'fillwithconstant','Constant',-1) synchronizes the timetables TT1 and TT2 and assigns the value -1 to elements in rows of TT with row times that do not match row times in the corresponding input timetables.

`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: TT = synchronize(TT1,TT2,'hourly','fillwithconstant','Constant','NONE') fills gaps in TT with the character vector 'NONE' when all the variables in TT 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 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: TT = synchronize(TT1,TT2,'daily','previous','EndValues',1000) fills gaps in TT with previous row values where TT has row times within the range of row times from TT1 and TT2, and with the value 1000 where TT 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 TT 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: TT = synchronize(TT1,TT2,'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 synchronize function supports tall arrays with the following usage notes and limitations:

The newTimes input must be strictly increasing instead of strictly monotonic.
The 'commonrange' option for the newTimeBasis input is not supported.
Interpolation methods 'spline' and 'makima' are not supported.
The 'EndValues' name-value argument is not supported.
Synchronization 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 properties of the input timetables are not constant, then this function ignores them.
The 'weekly', 'monthly', and 'quarterly' time steps are not supported.
- If the input timetables have 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

expand all

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 timetables

If any of the input timetables have 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 timetables.

For example, this code creates two timetables with NaN values.

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

T1 =

  3×1 timetable

       Time        Var1
    ___________    ____

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


T2 =

  4×1 timetable

       Time        Var1
    ___________    ____

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

This call to synchronize replaces the NaNs with 0s. But in previous releases, this call leaves the NaNs in the output timetable.

T = synchronize(T1,T2,"daily","fillwithconstant","constant",0)

T =

  4×2 timetable

       Time        Var1_T1    Var1_T2
    ___________    _______    _______

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

synchronize

Syntax

Description

Examples

Synchronize Timetables and Insert Missing Data Indicators

Interpolate Data Values to Row Times

Aggregate Data When Synchronizing Timetables

Synchronize Timetables to Regular Times

Synchronize Timetables to Arbitrary Time Vector

Synchronize Timetables with Intersecting Row Times

Synchronize Timetables to Hourly Times

Synchronize Timetables Using Multiple Methods

Input Arguments

`TT1,TT2` — Input timetables
timetables

`newTimeBasis` — Basis for computing row times of output timetable
character vector

`newTimeStep` — Time step for spacing times in output timetable
character vector

`Fs` — Sample rate
numeric scalar

`dt` — Time step
duration scalar | calendar duration scalar

`newTimes` — New time vector
datetime vector | duration vector

`method` — Method for adjusting timetable data
character vector | string scalar | function handle

Name-Value Arguments

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

`EndValues` — Method for extrapolation when using interpolation method
`'extrap'` (default) | scalar

`IncludedEdge` — Edges to include in each time bin
`'left'` (default) | `'right'`

Extended Capabilities

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

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

Version History

R2021a: `'SamplingRate'` will be removed

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

See Also

Functions

Live Editor Tasks

Topics

synchronize

Syntax

Description

Examples

Synchronize Timetables and Insert Missing Data Indicators

Interpolate Data Values to Row Times

Aggregate Data When Synchronizing Timetables

Synchronize Timetables to Regular Times

Synchronize Timetables to Arbitrary Time Vector

Synchronize Timetables with Intersecting Row Times

Synchronize Timetables to Hourly Times

Synchronize Timetables Using Multiple Methods

Input Arguments

TT1,TT2 — Input timetables timetables

newTimeBasis — Basis for computing row times of output timetable character vector

newTimeStep — Time step for spacing times in output timetable character vector

Fs — Sample rate numeric scalar

dt — Time step duration scalar | calendar duration scalar

newTimes — New time vector datetime vector | duration vector

method — Method for adjusting timetable data character vector | string scalar | function handle

Name-Value Arguments

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

EndValues — Method for extrapolation when using interpolation method 'extrap' (default) | scalar

IncludedEdge — Edges to include in each time bin 'left' (default) | 'right'

Extended Capabilities

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

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

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

Version History

R2021a: 'SamplingRate' will be removed

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

See Also

Functions

Live Editor Tasks

Topics

`TT1,TT2` — Input timetables
timetables

`newTimeBasis` — Basis for computing row times of output timetable
character vector

`newTimeStep` — Time step for spacing times in output timetable
character vector

`Fs` — Sample rate
numeric scalar

`dt` — Time step
duration scalar | calendar duration scalar

`newTimes` — New time vector
datetime vector | duration vector

`method` — Method for adjusting timetable data
character vector | string scalar | function handle

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

`EndValues` — Method for extrapolation when using interpolation method
`'extrap'` (default) | scalar

`IncludedEdge` — Edges to include in each time bin
`'left'` (default) | `'right'`

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

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment
Run code in the background using MATLAB® `backgroundPool` or accelerate code with Parallel Computing Toolbox™ `ThreadPool`.

R2021a: `'SamplingRate'` will be removed

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