Documentation Center

  • Trial Software
  • Product Updates

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.

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

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 an empty string.

Specify a name when you want to easily distinguish one dataset from another. For example, if you have signal logging in model reference hierarchy, name the signal logging dataset for each model to make the output easier to analyze.

The following example shows how to give a dataset the name of Dataset1.

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

Data Type

string

Access

RW

Methods

addElement

Purpose

Add element to end of 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 = ds.addElement(element1);
element2 = Simulink.SimulationData.Signal;
element2.Name = 'B';
element2.Values = timeseries(2*sin(time), time);
ds = ds.addElement(element2);
element3 = Simulink.SimulationData.Signal;
element3.Name = 'C';
element3.Values = timeseries(3*sin(time), time);
ds = ds.addElement(element3) 

The output is:

ds = 

  Simulink.SimulationData.Dataset
  Package: Simulink.SimulationData

  Characteristics:
              Name: 'topOut'
    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 shares the same syntax and behavior as the get method.

Syntax

element = dataset.get(search_arg)
element = dataset.get(search_arg,'-blockpath')

Input Arguments

search_arg

The index, name, or block path that identifies the element to access. To access an element by:

  • Index — Set search_arg to a scalar numeric value.

  • Name — Set search_arg to a character array.

  • Block path — Specify a Simulink.SimulationData.BlockPath object. For signal logging, specify the blockpath for the source block for the element.

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

'-blockpath'

Specify a block path directly. Set search_arg to a character array representing the full block path to the element, followed by '-blockpath'.

Output Arguments

element

The element that the getElement method adds to the dataset. The returned value depends on the search_arg format.

search_arg Argument ValueReturned Value
Single-character array or Simulink.SimulationData.BlockPath objectSingle element if only one element is found; dataset if more than one element with the specified name exists
Cell array containing one string or Simulink.SimulationData.BlockPath objectDataset

Description

element = Simulink.SimulationData.Dataset.get(search_arg) returns the element corresponding the index, name, or block path that you specify with search_arg.

element = Simulink.SimulationData.Dataset.get(search_arg, '-blockpath') returns the element corresponding the search_arg character array that identifies the block path for the element that you want to access.

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 = topOut.get(1)

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

element2 = topOut.get({'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 = topOut.get(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 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.

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

See Also

| | |

Was this topic helpful?