Documentation

Simulink.SimulationData.Dataset

Container for logged data using MATLAB timeseries objects

Description

Simulink® creates Simulink.SimulationData.Dataset objects to store data elements when:

  • Performing signal logging, if you use the default signal logging format of Dataset

  • Logging a data store

Using the Dataset format for signal logging offers several advantages, compared to the ModelDataLogs format. For a discussion of those advantages, see Signal logging format.

Simulink.SimulationData.Dataset provides a getElement method for accessing individual elements in the dataset. You can specify an element by index, name, or block path.

To select the Dataset format for signal logging, use one of these approaches:

  • Set the Configuration Parameters > Data Import/Export > Signal logging format parameter to Dataset. For details, see Signal logging format.

  • From the MATLAB® command line, set the SignalLoggingSaveFormat parameter to Dataset.

Unlike the handle-based ModelDataLogs class, Simulink.SimulationData.Dataset is a value class. For details, see Handle Versus Value Classes.

If you have logged signal data in the ModelDataLogs format, you can use the Simulink.ModelDataLogs.convertToDataset function to update the ModelDataLogs data to Dataset format.

Simulink checks signal logging data format consistency for certain model referencing configurations. For details, see Model Reference Signal Logging Format Consistency. You can use the Upgrade Advisor (with the upgradeadvisor function) to upgrade a model to use Dataset format.

An alternative approach for handling reported inconsistencies is to use the Simulink.SimulationData.updateDatasetFormatLogging function to update the models to use Dataset format. This approach sets the Model Configuration Parameters > Data Import/Export > Signal logging format parameter to Dataset for each referenced model and each variant.

For details about migrating an existing model that uses ModelDataLogs format to use Dataset format, see Migrate from ModelDataLogs to Dataset Format.

Property Summary

Name

Description

Name

Logged dataset name.

Method Summary

Name

Description

addElement

Add an element to the end of a dataset.

get

The getElement method uses the same syntax and behavior as the get method

Get element or collection of elements from the dataset based on index, name, or block path.

getElementNames

Get the names of dataset elements.

numElements

Get number of elements in the dataset.

setElement

Change the element stored at the specified index

Properties

Name

Description

The name of the dataset. The default is the same as the logging variable (for example, logsout for signal logging).

Specify a name when you want to easily distinguish one dataset from another. For example, you could reset the name when comparing multiple simulations.

ds = Simulink.SimulationData.Dataset
ds.Name = 'Dataset1'

Data Type

string

Access

RW

Methods

addElement

Purpose

Add element to a dataset.

Syntax

dataset = dataset.addElement(element)
dataset = dataset.addElement(element,name)

Input Arguments

element

The element to add to the dataset. The element must be one of the following:

  • Simulink.SimulationData.Signal object

  • Simulink.SimulationData.DataStoreMemory object

name

A string specifying a name for the element.

Output Arguments

dataset

The dataset to which you add the element. The new element is added to the end of the dataset.

Description

dataset = Simulink.SimulationData.Dataset.addElement(element) adds an element to the Simulink.SimulationData.Dataset dataset.

dataset = Simulink.SimulationData.Dataset.addElement(element, name) adds an element to the Simulink.SimulationData.Dataset dataset. This element receives the name that you specify with the name argument. You can use name to identify an element that does not have a name. If an object that already has a name (for example, a Simulink.SimulationData.Signal object to which you assigned a name), the element uses that name unless you specify a different name by using with the name argument.

Examples

Create a dataset and add three elements to that dataset.

time = 0.1*(0:100)';
ds = Simulink.SimulationData.Dataset;
element1 = Simulink.SimulationData.Signal;
element1.Name = 'A';
element1.Values = timeseries(sin(time), time);
ds = addElement(ds,element1);
element2 = Simulink.SimulationData.Signal;
element2.Name = 'B';
element2.Values = timeseries(2*sin(time), time);
ds = addElement(ds,element2);
element3 = Simulink.SimulationData.Signal;
element3.Name = 'C';
element3.Values = timeseries(3*sin(time), time);
ds = addElement(ds,element3) 
ds = 

  Simulink.SimulationData.Dataset
  Package: Simulink.SimulationData

  Characteristics:
              Name: 'logsout'
    Total Elements: 3

  Elements:
    1: 'A'
    2: 'B'
    3: 'C'

get

Purpose

Get element or collection of elements from dataset, based on index, name, or block path

The getElement method uses the same syntax and behavior as the get method.

Syntax

element = dataset.get(index)
element = dataset.get(name)
element = dataset.get(blockpath,'-blockpath')

Input Arguments

index

The index is a scalar numeric value reflecting the index value of a dataset element

  • Index — Set search_arg to a scalar numeric value.

  • Name — Set search_arg to a character array.

  • Block path — Specify a

When specifying a name or block path for search_arg in cases where there could be duplicate names or block paths, use a cell array to consistently return a Simulink.SimulationData.Dataset object. (Such duplication could occur, for example, in a model reference hierarchy.)

name

A character array reflecting the name of the dataset element

blockpath -blockpat

A Simulink.SimulationData.BlockPath object or a character array representing the full block path to the element. For signal logging, specify the block path for the source block for the element. Follow the block path with the string -blockpath (with no comma between the path and the string).

Output Arguments

element

The element that the get or getElement method finds. Returns a dataset if more than one element with the specified name or block path exists, or if a cell array containing one string or Simulink.SimulationData.BlockPath object.

Description

element = Simulink.SimulationData.Dataset.get(index) returns the element corresponding to the index.

element = Simulink.SimulationData.Dataset.get(name) returns the element whose name matches name.

element = Simulink.SimulationData.Dataset.get(blockpath, '-blockpath') returns the element corresponding to the specified block path.

Examples

Access dataset elements in the top model of the ex_bus_logging model. The signal logging dataset is topOut.

open_system(docpath(fullfile(docroot,'toolbox','simulink',...
'examples','ex_mdlref_counter_bus')));
open_system(docpath(fullfile(docroot,'toolbox','simulink',...
'examples','ex_bus_logging')));
sim('ex_bus_logging')
topOut
topOut = 

  Simulink.SimulationData.Dataset
  Package: Simulink.SimulationData

  Characteristics:
              Name: 'topOut'
    Total Elements: 4

  Elements:
    1: 'COUNTERBUS'
    2: 'OUTPUTBUS'
    3: 'INCREMENTBUS'
    4: 'inner_bus'

  -Use get or getElement to access elements by index, name or 
   block path.
  -Use addElement or setElement to add or modify elements.

  Methods, Superclasses

Access the first element of the dataset, by specifying an index for search_arg.

element1 = getElement(topOut,1)

Access the second element of the dataset, by using a cell array to specify the name for search_arg.

element2 = getElement(topOut,{'OUTPUTBUS'})

Access the third element of the dataset by block path. In the Simulink Editor, select the IncrementBusCreator block. At the MATLAB command line, use gcb for search_arg and use the '-blockpath' argument.

element3 = getElement(topOut,gcb,'-blockpath')
close_system('ex_bus_logging');
close_system('ex_mdlref_counter_bus');

getElementNames

Purpose

Return the names of all of the elements in the dataset.

Syntax

element_list = dataset.getElementNames

Input Arguments

None

Output Arguments

element_list

A cell array of the strings containing names of all of the elements of the dataset.

Description

element_list = Simulink.SimulationData.Dataset.getElementNames(element) returns the names of all of the elements in the Simulink.SimulationData.Dataset object.

Examples

Return the names of the elements for the topOut dataset (the signal logging data).

open_system(docpath(fullfile(docroot,'toolbox','simulink',...
'examples','ex_mdlref_counter_bus')));
open_system(docpath(fullfile(docroot,'toolbox','simulink',...
'examples','ex_bus_logging')));
sim('ex_bus_logging')
el_names = topOut.getElementNames
el_names = 

    'COUNTERBUS'
    'OUTPUTBUS'
    'INCREMENTBUS'
    'inner_bus'
close_system('ex_bus_logging');
close_system('ex_mdlref_counter_bus');

numElements

Purpose

Get number of elements in dataset.

Syntax

length = Simulink.SimulationData.Dataset.numElements()

Description

length = Simulink.SimulationData.Dataset.numElements() Get the number of elements in the top-level dataset. To get the number of elements of a nested dataset, use numElements with the nested dataset.

Example

Get the number of elements in the signal logging dataset for the ex_bus_logging.

length = topOut.numElements()

setElement

Purpose

Change element stored at specified index.

Syntax

dataset = Simulink.SimulationData.Dataset.setElement(index,...
element)
dataset = Simulink.SimulationData.Dataset.setElement(index,...
element,name)

Input Arguments

index

A scalar numeric value specifying the index for the added element. The value must be between 1 and the number of elements plus 1.

element

The element to replace an existing element or to add to the dataset. The element must be one of the following:

  • Simulink.SimulationData.Signal object

  • Simulink.SimulationData.DataStoreMemory object

name

A string specifying a name for the element.

Output Arguments

dataset

The dataset in which you change or add an element.

Description

dataset = Simulink.SimulationData.Dataset.setElement(index, element) Change the element stored at the specified index, for an existing index. If index is one greater than the number of elements in the dataset, the element is added at the end of the dataset.

dataset = Simulink.SimulationData.Dataset.setElement(index, element, name) changes the element stored at the specified index and gives it the name that you specify with the name argument. You can use name to identify an element that does not have a name. If signal that already has a name (for example, a Simulink.SimulationData.Signal object to which you assigned a name), the element uses that name unless you specify a different name by using with the name argument.

Example

ds = Simulink.SimulationData.Dataset
element1 = Simulink.SimulationData.Signal
element1.Name = 'A'
ds = ds.addElement(element1)
element2 = Simulink.SimulationData.Signal
element2.Name = 'B'
elementNew = Simulink.SimulationData.Signal
ds = ds.setElement(2,elementNew,'B1')
ds
ds = 

  Simulink.SimulationData.Dataset
  Package: Simulink.SimulationData

  Characteristics:
              Name: 'topOut'
    Total Elements: 2

  Elements:
    1: 'A'
    2: 'B1'
    
  Use getElement to access elements by index, name or 
  block path.

  Methods, Superclasses
Was this topic helpful?