Convert Data to Dataset Format

Why Convert to Dataset Format?

You can use the Simulink.SimulationData.Dataset constructor to convert a MATLAB^® workspace variable that contains data that was logged in one of these formats to Dataset format:

• Array

• Structure

• Structure with time

• MATLAB timeseries object

Converting data from other logging formats to Dataset format simplifies writing scripts to post-process data logged. For example, a model with multiple To Workspace blocks can use different data formats. Converting the logged data to Dataset format avoids the need to write special code to handle different formats.

Different simulation modes have different levels of support for data logging formats. Switching between normal and accelerator modes can require changes to the logging formats used.

The conversion to Dataset format also makes it easier to take advantage of features that require Dataset format. You can easily convert data logged in earlier releases that used a format other than Dataset to work well with Dataset data in a more recent release.

The Dataset format:

• Uses MATLAB timeseries objects to store logged data, which allows you to work with logging data in MATLAB without a Simulink^® license. For example, to manipulate the logged data, you can use MATLAB timeseries object functions such as filter, detrend, and resample.

• Supports logging multiple data values for a given time step, which is important for Iterator subsystem and Stateflow^® signal logging.

By default, the resulting Dataset object uses the variable name as the object name. You can use a name-value argument to specify a Dataset name.

You can also use the concat function to combine Dataset objects into one concatenated Dataset object.

Results of Conversion

Dataset objects hold data as elements. To display the elements of a Dataset object variable, enter the variable name at the MATLAB command prompt. Each element is an object. The type of the object depends on the data each element contains. For example, signal logging stores data as Simulink.SimulationData.Signal elements, and state logging in Dataset format stores data as Simulink.SimulationData.State elements. Each element holds data as a MATLAB timeseries object. At conversion, the elements and timeseries field populate as much as possible from the converted object.

Format	Conversion Result Notes
MATLAB timeseries object	If you log nonbus data, during conversion, the software first adds the data as a Simulink.SimulationData.Signal object. The software then adds that object as an element of the newly created Dataset. If you log bus data in timeseries format, one timeseries object corresponds to each element of a bus. Converting arranges the logged data as a structure with timeseries objects as leaf nodes where the structure hierarchy matches the bus hierarchy. Conversion of this type of structure adds the structure to a Signal object. Then, the Signal object is added as an element to the Dataset object. timeseries objects hold relevant information such as block path and timestamps. The conversion tries to preserve this information.
Structure and structure with time	Structure and structure with time formats do not always contain as much information as if you log in Dataset format. However, before converting structure and structure with time formats, the data structure must have time and signals fields. Conversion populates a Simulink.SimulationData.Signal object with the structure and adds it as an element of the Dataset object. If other information is available, converting also adds that information to the element or timeseries object values. For example, if the structure has a field called blockName, converting adds the block name to the block path. Otherwise, the block path is empty. When scope data is logged in structure format, the logged structure has a PlotStyle field. The software uses this field to set the interpolation in the Dataset object.
Array	Arrays contain little information. For example, there is no block path information. Conversion adds the array to a Simulink.SimulationData.Signal object, then adds the Signal object as an element of the Dataset object. The conversion treats unavailable information such as block path and timestamp fields as empty or uses default values.

Convert timeseries Object to Dataset Object

Convert data from timeseries format to Dataset format. The model vdpConvert is the vdp model with two To Workspace blocks that log data to variables named simout and simout1.

Simulate the model. By default, To Workspace blocks log data as timeseries objects.

out = sim("vdpConvert")

out = 
  Simulink.SimulationOutput:

                 simout: [1x1 timeseries] 
                simout1: [1x1 timeseries] 

     SimulationMetadata: [1x1 Simulink.SimulationMetadata] 
           ErrorMessage: [0x0 char] 

Use the Simulink.SimulationData.Dataset constructor to convert the timeseries objects to Dataset format.

ds = Simulink.SimulationData.Dataset(out.simout)

ds = 
Simulink.SimulationData.Dataset '' with 1 element

                         Name  BlockPath 
                         ____  _________ 
    1  [1x1 Signal]      x1    ''       

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

ds1 = Simulink.SimulationData.Dataset(out.simout1)

ds1 = 
Simulink.SimulationData.Dataset '' with 1 element

                         Name  BlockPath 
                         ____  _________ 
    1  [1x1 Signal]      x2    ''       

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

You can use the concat function to combine the two Dataset objects into one concatenated Dataset object.

dsFinal = concat(ds,ds1)

dsFinal = 
Simulink.SimulationData.Dataset '' with 2 elements

                         Name  BlockPath 
                         ____  _________ 
    1  [1x1 Signal]      x1    ''       
    2  [1x1 Signal]      x2    ''       

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

Convert Structure to Dataset Object

Convert a structure to Dataset format. The model vdpConvert is the vdp model with two To Workspace blocks that log data to variables named simout and simout1.

By default, To Workspace blocks log data as timeseries objects. Set the To Workspace block that saves data to the variable simout to log data as a structure with time. Set the To Workspace block that saves data to the variable simout1 to log data as a structure without time.

mdl = "vdpConvert";
load_system(mdl)
set_param("vdpConvert/To Workspace","SaveFormat","Structure With Time")
set_param("vdpConvert/To Workspace1","SaveFormat","Structure")

Simulate the model.

out = sim(mdl);

Data from the To Workspace blocks is contained in the single SimulationOutput object out. To access this data, use dot notation.

simout = out.simout

simout = struct with fields:
         time: [64×1 double]
      signals: [1×1 struct]
    blockName: 'vdpConvert/To Workspace'

simout1 = out.simout1

simout1 = struct with fields:
         time: []
      signals: [1×1 struct]
    blockName: 'vdpConvert/To Workspace1'

Convert the structure data from both To Workspace blocks to Dataset format.

ds = Simulink.SimulationData.Dataset(simout);
ds1 = Simulink.SimulationData.Dataset(simout1);

Access the time values for the element ds.

get(ds,1).Values.time

ans = 64×1

         0
    0.0001
    0.0006
    0.0031
    0.0157
    0.0785
    0.2844
    0.5407
    0.8788
    1.2788
    1.6788
    2.0788
    2.4788
    2.8788
    3.2138
      ⋮

Notice that the time field for simout1 is an empty array. When a structure without time or an array is converted to a Dataset object, the conversion inserts a time vector that starts at 0 and increments by 1.

Get the time values of the element in ds1. Because a time vector is not included in the structure simout1, the time steps for the Dataset object ds1 do not match the simulation time steps.

get(ds1,1).Values.Time

ans = 64×1

     0
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
      ⋮

Dataset Conversion Limitations

• Converting logged data to Dataset format results in a Dataset object that contains all the information that the original logged data included. However, if no corresponding information is available for the other Dataset properties, the conversion uses default values for that information.

• When you convert data for a variable-size signal logged using the To Workspace block, the information in the valueDimensions field of the structure is lost in the conversion.

• When you log a bus in array, structure, or structure with time formats, the logged data is organized with:

  • The first column containing the data for the first signal in the bus

  • The second column containing data for the second bus signal, and so on

  When you convert that data to Dataset format, the Dataset object preserves that organization. However, if you log the bus in Dataset format without conversion, the conversion captures the bus data as a structure of timeseries objects.

• If the logged data does not include a time vector, when you convert that data to Dataset format, the conversion inserts a time vector. The time vector has one time step for each data value. However, the simulation time steps and the Dataset time steps can vary.

• Dataset format ignores the specification of frame signals. Conversion of structure or structure with time data to Dataset format reshapes the data for logged frame signals.