Main Content

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

  • ModelDataLogs

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.

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

ModelDataLogs

Converts data from ModelDataLogs format to Dataset format.

Note

The ModelDataLogs format is no longer used for signal logging.

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.

Model of the van der Pol equation.

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 vdpConvertStructure is the vdp model with two To Workspace blocks that log data to variables named simout and simout1 in structure format.

Model of the van der Pol equation.

Simulate the model.

out = sim("vdpConvertStructure");

The To Workspace block that saves data to the variable simout logs data as a structure with time. The To Workspace block that saves data to the variable simout1 logs data as a structure without time.

simout = out.simout
simout = struct with fields:
         time: [64x1 double]
      signals: [1x1 struct]
    blockName: 'vdpConvertStructure/To Workspace'

simout1 = out.simout1
simout1 = struct with fields:
         time: []
      signals: [1x1 struct]
    blockName: 'vdpConvertStructure/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
      ⋮

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
      ⋮

Migrate Legacy Code That Uses ModelDataLogs

For scripts that simulate a model created in a release earlier than R2016a that uses ModelDataLogs format for logging, update the code to log in Dataset format.

If you have already logged signal data in the ModelDataLogs format, you can use the convertToDataset function to update the ModelDataLogs signal logging data to use Dataset format. For example, update the older_model_data from ModelDataLogs format to Dataset format.

new_dataset = convertToDataset(logsout,"older_model_data")

Converting a model from using ModelDataLogs format to using Dataset format can require that you modify your existing models and code in callbacks, functions, scripts, or tests. This table identifies possible issues to address after converting to Dataset format.

Possible Issue After Conversion to Dataset FormatSolution

Code in existing callbacks, functions, scripts, or tests that used the ModelDataLogs programmatic interface to access data can result in an error.

Check for code that uses ModelDataLogs format access methods. Update that code to use Dataset format access methods.

For example, suppose that existing code includes this line.

logsout.('Subsystem Name').X.data

Replace that code with a Dataset access function.

get(logsout,"x").Values.data

Mux block signal names are lost.

The Dataset format treats Mux block signals as a vector. To identify signals by signal names, replace Mux blocks with Bus Creator blocks.

Signal Viewer cannot be used for signal logging.

The software does not log signal logging data in the Signal Viewer.

Use the signal logging output variable to view the logged data.

The unpack function generates an error.

The unpack function, which is supported for Simulink.ModelDataLogs and Simulink.SubsysDataLogs objects, is not supported for Simulink.SimulationData.Dataset objects.

For example, suppose the data in mlog has three fields: x, y, and z.

  • For ModelDataLogs format data, the mlog.unpack function creates three variables in the base workspace.

  • For Dataset format data, the get function accesses data by name.

    x = get(logsout,"x").Values

The ModelDataLogs and Dataset formats have different naming rules for unnamed signals.

If necessary, add signal names.

In ModelDataLogs format, for an unnamed signal coming from a block, the software assigns a name in the form SL_BlockName+<portIndex>, for example, SL_Gain1.

In Dataset format, elements do not need a name, so the software leaves the signal name empty.

For both ModelDataLogs and Dataset formats, the software assigns the same name to unnamed signals that come from Bus Selector blocks.

Test points in referenced models are not logged.

Consider enabling signal logging for test points in a referenced model.

Script uses who or whos functions.

Consider using find instead.

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

See Also

Objects

Functions

Related Topics