Main Content

synchronize

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

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.

example

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.

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

example

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.

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

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  

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 

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

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

Input timetables.

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

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.

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

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

Data Types: datetime | duration | calendarDuration

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

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.

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.

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.

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

Version History

Introduced in R2016b

expand all