Main Content

extractTimetable

Extract data from Simulink.SimulationData.Dataset or Simulink.SimulationData.Signal objects into timetables

Since R2021b

collapse all in page

Syntax

TT = extractTimetable(ds)
TT = extractTimetable(ds,Name=Value)

Description

TT = extractTimetable(ds) extracts data from multiple elements of ds into a timetable. The input argument ds is a Simulink.SimulationData.Dataset or Simulink.SimulationData.Signal object.

example

TT = extractTimetable(ds,Name=Value) extracts data into one or more timetables according to options that are specified by one or more name-value arguments. For example, the SignalNames argument specifies the names of the signals to extract from ds.

You can return the data as:

  • A single timetable that includes all elements that contain time series data, synchronized to the union of the time stamps of all signals.

  • A cell array of timetables that each contain data for signals that share the same sample time.

  • A cell array of timetables that each contain time series data for a single signal.

example

Examples

collapse all

Open Live Script

Extract signals from a Simulink.SimulationData.Dataset object into a timetable.

First, create a Dataset object and add two signals to it. To calculate data for the signals, use the sin and cos functions. Each signal is in its own timeseries object. These signals both have a 0.1-second time step.

Time = 0.1*(0:99)';
ds = Simulink.SimulationData.Dataset;

element1 = Simulink.SimulationData.Signal;
element1.Name = "Sine";
element1.Values = timeseries(sin(Time),Time);
ds = addElement(ds,element1);

element2 = Simulink.SimulationData.Signal;
element2.Name = "Cosine";
element2.Values = timeseries(cos(Time),Time);
ds = addElement(ds,element2)
ds = 
Simulink.SimulationData.Dataset '' with 2 elements

                         Name    BlockPath 
                         ______  _________ 
    1  [1x1 Signal]      Sine    ''       
    2  [1x1 Signal]      Cosine  ''       

  - Use braces { } to access, modify, or add elements using index.

Next, extract data from ds and put the data into a timetable. The timetable TT has two variables, Sine and Cosine, that contain data from both elements of ds.

TT = extractTimetable(ds)
TT=100×2 timetable
     Time        Sine       Cosine 
    _______    ________    ________

    0 sec             0           1
    0.1 sec    0.099833       0.995
    0.2 sec     0.19867     0.98007
    0.3 sec     0.29552     0.95534
    0.4 sec     0.38942     0.92106
    0.5 sec     0.47943     0.87758
    0.6 sec     0.56464     0.82534
    0.7 sec     0.64422     0.76484
    0.8 sec     0.71736     0.69671
    0.9 sec     0.78333     0.62161
    1 sec       0.84147      0.5403
    1.1 sec     0.89121      0.4536
    1.2 sec     0.93204     0.36236
    1.3 sec     0.96356      0.2675
    1.4 sec     0.98545     0.16997
    1.5 sec     0.99749    0.070737
      ⋮

Add a third signal to ds with a time vector that has a 0.05-second time step.

Time2 = 0.05*(0:149)';
element3 = Simulink.SimulationData.Signal;
element3.Name = "Tangent";
element3.Values = timeseries(tan(Time2),Time2);
ds = addElement(ds,element3)
ds = 
Simulink.SimulationData.Dataset '' with 3 elements

                         Name     BlockPath 
                         _______  _________ 
    1  [1x1 Signal]      Sine     ''       
    2  [1x1 Signal]      Cosine   ''       
    3  [1x1 Signal]      Tangent  ''       

  - Use braces { } to access, modify, or add elements using index.

Extract the data from the three elements of ds. The elements have timeseries objects whose time vectors do not match. Thus, the vector of row times of TT is the union of the time vectors of the three timeseries objects. Then, the extractTimetable function synchronizes data from the three signals to its row times. the function fills in missing values for the row times where Sine and Cosine do not provide data.

TT2 = extractTimetable(ds)
TT2=175×3 timetable
      Time        Sine      Cosine     Tangent 
    ________    ________    _______    ________

    0 sec              0          1           0
    0.05 sec         NaN        NaN    0.050042
    0.1 sec     0.099833      0.995     0.10033
    0.15 sec         NaN        NaN     0.15114
    0.2 sec      0.19867    0.98007     0.20271
    0.25 sec         NaN        NaN     0.25534
    0.3 sec      0.29552    0.95534     0.30934
    0.35 sec         NaN        NaN     0.36503
    0.4 sec      0.38942    0.92106     0.42279
    0.45 sec         NaN        NaN     0.48306
    0.5 sec      0.47943    0.87758      0.5463
    0.55 sec         NaN        NaN     0.61311
    0.6 sec      0.56464    0.82534     0.68414
    0.65 sec         NaN        NaN      0.7602
    0.7 sec      0.64422    0.76484     0.84229
    0.75 sec         NaN        NaN      0.9316
      ⋮
Open Live Script

Extract data from signals that have time vectors with different sample times. To avoid returning a timetable that contains NaNs, return the data in a cell array of timetables. Then, synchronize the output timetables by using linear interpolation to fill gaps in the data.

Create a Dataset object that has three elements. The first two elements have the same time vector and sample time. The third element has a time vector with a different sample time.

Time1 = 0.1*(0:99)';
ds = Simulink.SimulationData.Dataset;

element1 = Simulink.SimulationData.Signal;
element1.Name = "Sine";
element1.Values = timeseries(sin(Time1),Time1);
ds = addElement(ds,element1);

element2 = Simulink.SimulationData.Signal; 
element2.Name ="Cosine"; 
element2.Values = timeseries(cos(Time1),Time1); 
ds = addElement(ds,element2);

Time2 = 0.05*(0:149)';

element3 = Simulink.SimulationData.Signal;
element3.Name = "Tangent";
element3.Values = timeseries(tan(Time2),Time2);
ds = addElement(ds,element3)
ds = 
Simulink.SimulationData.Dataset '' with 3 elements

                         Name     BlockPath 
                         _______  _________ 
    1  [1x1 Signal]      Sine     ''       
    2  [1x1 Signal]      Cosine   ''       
    3  [1x1 Signal]      Tangent  ''       

  - Use braces { } to access, modify, or add elements using index.

Extract data from the signals into timetables. To avoid NaNs in the output, extract signals by sample time.

TT = extractTimetable(ds,OutputFormat="cell-by-sampletime")
TT=1×2 cell array
    {150x1 timetable}    {100x2 timetable}

Display the first timetable. The timetable contains the data from ds{3} and has a sample time of 0.05 seconds.

TT{1}
ans=150×1 timetable
      Time      Tangent 
    ________    ________

    0 sec              0
    0.05 sec    0.050042
    0.1 sec      0.10033
    0.15 sec     0.15114
    0.2 sec      0.20271
    0.25 sec     0.25534
    0.3 sec      0.30934
    0.35 sec     0.36503
    0.4 sec      0.42279
    0.45 sec     0.48306
    0.5 sec       0.5463
    0.55 sec     0.61311
    0.6 sec      0.68414
    0.65 sec      0.7602
    0.7 sec      0.84229
    0.75 sec      0.9316
      ⋮

Display the second timetable. The variables from the second timetable contain the data from ds{1} and ds{2} because those two elements of ds have the same sample time, 0.1 seconds.

TT{2}
ans=100×2 timetable
     Time        Sine       Cosine 
    _______    ________    ________

    0 sec             0           1
    0.1 sec    0.099833       0.995
    0.2 sec     0.19867     0.98007
    0.3 sec     0.29552     0.95534
    0.4 sec     0.38942     0.92106
    0.5 sec     0.47943     0.87758
    0.6 sec     0.56464     0.82534
    0.7 sec     0.64422     0.76484
    0.8 sec     0.71736     0.69671
    0.9 sec     0.78333     0.62161
    1 sec       0.84147      0.5403
    1.1 sec     0.89121      0.4536
    1.2 sec     0.93204     0.36236
    1.3 sec     0.96356      0.2675
    1.4 sec     0.98545     0.16997
    1.5 sec     0.99749    0.070737
      ⋮

Combine the two timetables in TT into one timetable by using the timetable synchronize method. To avoid filling gaps with NaNs, use linear interpolation as the fill method.

combinedTT = synchronize(TT{2},TT{1},"union","linear")
combinedTT=175×3 timetable
      Time        Sine      Cosine     Tangent 
    ________    ________    _______    ________

    0 sec              0          1           0
    0.05 sec    0.049917     0.9975    0.050042
    0.1 sec     0.099833      0.995     0.10033
    0.15 sec     0.14925    0.98754     0.15114
    0.2 sec      0.19867    0.98007     0.20271
    0.25 sec     0.24709     0.9677     0.25534
    0.3 sec      0.29552    0.95534     0.30934
    0.35 sec     0.34247     0.9382     0.36503
    0.4 sec      0.38942    0.92106     0.42279
    0.45 sec     0.43442    0.89932     0.48306
    0.5 sec      0.47943    0.87758      0.5463
    0.55 sec     0.52203    0.85146     0.61311
    0.6 sec      0.56464    0.82534     0.68414
    0.65 sec     0.60443    0.79509      0.7602
    0.7 sec      0.64422    0.76484     0.84229
    0.75 sec     0.68079    0.73077      0.9316
      ⋮
Open Live Script

A Dataset object can have some elements that contain timetables and other elements that contain timeseries objects. The extractTimetable function extracts data from both sets of elements and returns all data in one timetable.

Create a Dataset object with one element that has a timetable.

ds = Simulink.SimulationData.Dataset;
element1 = Simulink.SimulationData.Signal;
element1.Name = "TrigFuncs";
element1.Values = timetable(seconds(0:99)',sin(0:99)',cos(0:99)',...
                            VariableNames=["Sine","Cosine"])
element1 = 
  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

  Properties:
              Name: 'TrigFuncs'
    PropagatedName: ''
         BlockPath: [1x1 Simulink.SimulationData.BlockPath]
          PortType: 'inport'
         PortIndex: 1
            Values: [100x2 timetable]


ds = addElement(ds,element1);

Add another element that has a timeseries object.

element2 = Simulink.SimulationData.Signal; 
element2.Name ="Tangent"; 
element2.Values = timeseries(tan(0:99),0:99)
element2 = 
  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

  Properties:
              Name: 'Tangent'
    PropagatedName: ''
         BlockPath: [1x1 Simulink.SimulationData.BlockPath]
          PortType: 'inport'
         PortIndex: 1
            Values: [1x1 timeseries]


ds = addElement(ds,element2);

Extract all the data and return one timetable.

TT = extractTimetable(ds)
TT=100×3 timetable
     Time     TrigFuncs.Sine    TrigFuncs.Cosine    Tangent 
    ______    ______________    ________________    ________

    0 sec               0                  1               0
    1 sec         0.84147             0.5403          1.5574
    2 sec          0.9093           -0.41615          -2.185
    3 sec         0.14112           -0.98999        -0.14255
    4 sec         -0.7568           -0.65364          1.1578
    5 sec        -0.95892            0.28366         -3.3805
    6 sec        -0.27942            0.96017        -0.29101
    7 sec         0.65699             0.7539         0.87145
    8 sec         0.98936            -0.1455         -6.7997
    9 sec         0.41212           -0.91113        -0.45232
    10 sec       -0.54402           -0.83907         0.64836
    11 sec       -0.99999          0.0044257         -225.95
    12 sec       -0.53657            0.84385        -0.63586
    13 sec        0.42017            0.90745         0.46302
    14 sec        0.99061            0.13674          7.2446
    15 sec        0.65029           -0.75969        -0.85599
      ⋮

Add another element that has a timeseries object with a different sample time. When you extract the timetable, it has many NaN values filled in.

element3 = Simulink.SimulationData.Signal; 
element3.Name ="Mini-Tangent"; 
element3.Values = timeseries(tan(0.5*(0:99)),0.5*(0:99));
ds = addElement(ds,element3);
TT = extractTimetable(ds)
TT=150×4 timetable
     Time      TrigFuncs.Sine    TrigFuncs.Cosine    Tangent     Mini-Tangent
    _______    ______________    ________________    ________    ____________

    0 sec                0                  1               0             0  
    0.5 sec            NaN                NaN             NaN        0.5463  
    1 sec          0.84147             0.5403          1.5574        1.5574  
    1.5 sec            NaN                NaN             NaN        14.101  
    2 sec           0.9093           -0.41615          -2.185        -2.185  
    2.5 sec            NaN                NaN             NaN      -0.74702  
    3 sec          0.14112           -0.98999        -0.14255      -0.14255  
    3.5 sec            NaN                NaN             NaN       0.37459  
    4 sec          -0.7568           -0.65364          1.1578        1.1578  
    4.5 sec            NaN                NaN             NaN        4.6373  
    5 sec         -0.95892            0.28366         -3.3805       -3.3805  
    5.5 sec            NaN                NaN             NaN      -0.99558  
    6 sec         -0.27942            0.96017        -0.29101      -0.29101  
    6.5 sec            NaN                NaN             NaN       0.22028  
    7 sec          0.65699             0.7539         0.87145       0.87145  
    7.5 sec            NaN                NaN             NaN         2.706  
      ⋮

To extract all data from elements with a one-second sample time, you must use different name-value arguments because one element has a timetable and the others have timeseries objects.

  • To extract data from timetables with a one-second sample time, use the TimeStep argument. Specify the sample time as a duration value.

  • To extract data from timeseries objects with a one-second sample time, use the SampleTime argument. Specify the sample time as a numeric value.

TT = extractTimetable(ds,TimeStep=seconds(1),SampleTime=1)
TT=100×3 timetable
     Time     TrigFuncs.Sine    TrigFuncs.Cosine    Tangent 
    ______    ______________    ________________    ________

    0 sec               0                  1               0
    1 sec         0.84147             0.5403          1.5574
    2 sec          0.9093           -0.41615          -2.185
    3 sec         0.14112           -0.98999        -0.14255
    4 sec         -0.7568           -0.65364          1.1578
    5 sec        -0.95892            0.28366         -3.3805
    6 sec        -0.27942            0.96017        -0.29101
    7 sec         0.65699             0.7539         0.87145
    8 sec         0.98936            -0.1455         -6.7997
    9 sec         0.41212           -0.91113        -0.45232
    10 sec       -0.54402           -0.83907         0.64836
    11 sec       -0.99999          0.0044257         -225.95
    12 sec       -0.53657            0.84385        -0.63586
    13 sec        0.42017            0.90745         0.46302
    14 sec        0.99061            0.13674          7.2446
    15 sec        0.65029           -0.75969        -0.85599
      ⋮

If you use only the SampleTime argument, then you extract data only from elements that have a timeseries object. Similarly, if you specify only TimeStep, you extract data only from elements that have a timetable.

TT = extractTimetable(ds,SampleTime=1)
TT=100×1 timetable
     Time     Tangent 
    ______    ________

    0 sec            0
    1 sec       1.5574
    2 sec       -2.185
    3 sec     -0.14255
    4 sec       1.1578
    5 sec      -3.3805
    6 sec     -0.29101
    7 sec      0.87145
    8 sec      -6.7997
    9 sec     -0.45232
    10 sec     0.64836
    11 sec     -225.95
    12 sec    -0.63586
    13 sec     0.46302
    14 sec      7.2446
    15 sec    -0.85599
      ⋮
Open Live Script

Create a Dataset object that has elements with different time vectors.

Time1 = 0.1*(0:99)';
ds = Simulink.SimulationData.Dataset;

element1 = Simulink.SimulationData.Signal;
element1.Name = "Sine";
element1.Values = timeseries(sin(Time1),Time1);
ds = addElement(ds,element1);

Time2 = 0.05*(0:99)';
element2 = Simulink.SimulationData.Signal; 
element2.Name ="Cosine"; 
element2.Values = timeseries(cos(Time2),Time2); 
ds = addElement(ds,element2);

Time3 = (0:99)';
element3 = Simulink.SimulationData.Signal;
element3.Name = "Tangent";
element3.Values = timeseries(tan(Time3),Time3);
ds = addElement(ds,element3)
ds = 
Simulink.SimulationData.Dataset '' with 3 elements

                         Name     BlockPath 
                         _______  _________ 
    1  [1x1 Signal]      Sine     ''       
    2  [1x1 Signal]      Cosine   ''       
    3  [1x1 Signal]      Tangent  ''       

  - Use braces { } to access, modify, or add elements using index.

If you have data stored in another Dataset object, then you can use one of its elements as a template. You can extract data from elements of ds whose time properties match the time properties of the template.

Create a second Dataset object with one element.

ds2 = Simulink.SimulationData.Dataset;
templ = Simulink.SimulationData.Signal;
templ.Name = "Template";
templ.Values = timeseries(randi(100,1),(0:99)');
ds2 = addElement(ds2,templ)
ds2 = 
Simulink.SimulationData.Dataset '' with 1 element

                         Name      BlockPath 
                         ________  _________ 
    1  [1x1 Signal]      Template  ''       

  - Use braces { } to access, modify, or add elements using index.

Return data from the elements of ds that match the time properties of ds2{1}. The template matches the time properties of the third element of ds, named "Tangent".

TT = extractTimetable(ds,Template=ds2{1})
TT=100×1 timetable
     Time     Tangent 
    ______    ________

    0 sec            0
    1 sec       1.5574
    2 sec       -2.185
    3 sec     -0.14255
    4 sec       1.1578
    5 sec      -3.3805
    6 sec     -0.29101
    7 sec      0.87145
    8 sec      -6.7997
    9 sec     -0.45232
    10 sec     0.64836
    11 sec     -225.95
    12 sec    -0.63586
    13 sec     0.46302
    14 sec      7.2446
    15 sec    -0.85599
      ⋮

Input Arguments

collapse all

Object that contains time series data, specified as a Simulink.SimulationData.Dataset or Simulink.SimulationData.Signal object.

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.

Example: TT = extractTimetable(ds,OutputFormat="cell-by-sampletime")

Arguments for All Inputs

collapse all

Output format and grouping of time series data, specified as one of the values described in the table.

Value

Output Format

"timetable"

Timetable that contains the synchronized union of all signal data, padded with missing values.

"cell-by-signal"

Cell array that contains a timetable for each signal found in the input.

"cell-by-sampletime"

"cell-by-timestep"

Cell array that contains a timetable for each sample time found in the input.

Example: TT = extractTimetable(ds,OutputFormat="cell-by-signal") returns a cell array where each element is a timetable that contains data from a corresponding element of ds.

Names of signals to extract the timetable, specified as a string array or a pattern object.

Example: TT = extractTimetable(ds,SignalNames=["Sensor1","Sensor2"]) extracts data from signals named "Sensor1" or "Sensor2".

Example: TT = extractTimetable(ds,SignalNames="Sensor" + wildcardPattern) extracts data from signals whose names start with "Sensor".

Template to match to time properties of input signals, specified as a timeseries object, timetable, Simulink.SimulationData.Signal object, or the name of a signal in ds.

  • If the template is or contains a timeseries object, then extractTimetable matches it only to elements of ds that contain timeseries objects.

  • If the template is or contains a timetable, then extractTimetable matches it only to elements of ds that contain timetables.

Example: TT = extractTimetable(ds,Template=ds{1}) extracts data from all elements of ds whose time properties match the time properties of the first element of ds.

Arguments for Inputs with Signals That Contain timeseries Objects

collapse all

Sample time, specified as one or more positive numeric values. When you specify the value of SampleTime, this function extracts data from all signals in ds that have timeseries objects whose time vectors have the specified sample time. The sample time is interpreted as a time interval in seconds.

If you provide multiple sample times in a numeric array, then the output is a timetable synchronized to the union of all signals that have timeseries objects with any of the specified sample times, unless you also specify the value of OutputFormat.

Example: TT = extractTimetable(ds,SampleTime=0.5) extracts data from any signals that have timeseries objects where the sample time is 0.5 seconds and returns the data in one timetable.

Example: TT = extractTimetable(ds,SampleTime=[0.5,1.0],OutputFormat="cell-by-sampletime") extracts data from signals that have timeseries objects where the sample time is either 0.5 or 1.0 seconds and returns a cell array that contains two timetables.

Time vector, specified as a datetime vector or duration vector.

The output timetable contains data from all signals in ds that have timeseries objects whose time vector matches the value of TimeVector.

Example: TT = extractTimetable(ds,TimeVector=seconds(0:99)) extracts data from signals that have timeseries objects whose time vector is an array spanning 0–99 seconds with a sample time of one second.

Arguments for Inputs with Signals That Contain Timetables

collapse all

Sample rate, specified as one or more positive numeric values. When you specify the value of SampleRate, this function extracts data from all signals in ds that have timetables with the specified sample rate. The sample rate is interpreted as a rate in Hertz (Hz).

If you provide multiple sample rates in a numeric array, then the output is a timetable synchronized to the union of all signals that have timetables with any of the specified sample rates, unless you also specify the value of OutputFormat.

You can use this argument in combination with the StartTime name-value argument.

Example: TT = extractTimetable(ds,SampleRate=100) extracts data from any signals that have timetables where the sample rate is 100 Hz and returns the data in one timetable.

Example: TT = extractTimetable(ds,SampleRate=[100,200],OutputFormat="cell-by-sampletime") extracts data from signals that have timetables where the sample rate is either 100 or 200 Hz and returns a cell array that contains two timetables.

Example: TT = extractTimetable(ds,SampleRate=100,StartTime=seconds(25)) extracts data from any signals that have timetables where the sample rate is 100 Hz and the signal starts at 25 seconds.

Time step, specified as a duration array. When you specify the value of TimeStep, this function extracts the timetable that contains data from all signals in ds that have timetables with the specified time step.

If you provide multiple time steps in an array, then the output is a timetable synchronized to the union of all signals that have timetables with any of the specified time steps, unless you also specify the value of OutputFormat.

You can use this argument in combination with the StartTime name-value argument.

Example: TT = extractTimetable(ds,TimeStep=seconds(0.5)) extracts data from any signals that have timetables where the time step is 0.5 seconds and returns the data in one timetable.

Example: TT = extractTimetable(ds,TimeStep=seconds([0.5,1.0]),OutputFormat="cell-by-sampletime") extracts data from signals that have timetables where the time step is either 0.5 or 1.0 seconds and returns a cell array that contains two timetables.

Example: TT = extractTimetable(ds,TimeStep=seconds(0.5),StartTime=seconds(10)) extracts data from any signals that have timetables where the time step is 0.5 seconds and the signal starts at 10 seconds.

Time vector, specified as a datetime vector or duration vector.

The output timetable contains data from all the signals in ds that have timetables whose row times are in a time vector that matches the vector specified by RowTimes.

Example: TT = extractTimetable(ds,RowTimes=seconds(0:99)) extracts data from any signals that have timetables whose time vector is an array spanning 0–99 seconds with a time step of one second.

Start time, specified as a datetime scalar or duration scalar.

The output timetable contains data from all the signals in ds that have timetables whose row times start with a value matches the value specified by StartTime.

You can use StartTime in combination with either the SampleRate or TimeStep name-value arguments.

Example: TT = extractTimetable(ds,StartTime=seconds(50)) extracts data from any signals that have timetables where the signal starts at 50 seconds.

Example: TT = extractTimetable(ds,SampleRate=100,StartTime=seconds(25)) extracts data from any signals that have timetables where the sample rate is 100 Hz and the signal starts at 25 seconds.

Example: TT = extractTimetable(ds,TimeStep=seconds(0.5),StartTime=seconds(10)) extracts data from any signals that have timetables where the time step is 0.5 seconds and the signal starts at 10 seconds.

Version History

Introduced in R2021b

See Also

| | |

Topics