addElement

Class: Simulink.SimulationData.Dataset
Package: Simulink.SimulationData

Add element to end of a Dataset object

Syntax

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


Description

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

dataset = addElement(dataset,element,name) adds an element to the Simulink.SimulationData.Dataset data set and gives the element the name that you specify with the name argument. If the object already has a name, the element instead uses the name you specify by using the name argument.

Input Arguments

dataset — Data set

SimulationData.Dataset object

The data set to which to add the element.

element — Element to add

Simulink.SimulationData.Signal object | Simulink.SimulationData.State object | Simulink.SimulationData.DataStoreMemory object | timeseries object | matlab.io.datastore.SimulationDatastore object

Element to add to the data set, specified as a Simulink.SimulationData.Signal, Simulink.SimulationData.DataStoreMemory, or matlab.io.datastore.SimulationDatastore object.

name — Name for element

character vector

Name for element, specified as a character vector.

Output Arguments

dataset — Data set

character vector

The data set to which you add the element, returned as a character vector. The new element is added to the end of the data set.

Examples

Create a Data Set

Create a data set and add three elements to it.

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

ds = 

Simulink.SimulationData.Dataset '' with 3 elements

                         Name  BlockPath 
                         ____  _________ 
    1  [1x1 Signal]      A     ''       
    2  [1x1 Signal]      B     ''       
    3  [1x1 Signal]      C     ''       

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

Create a Run in the Simulation Data Inspector

You can programmatically import data into the Simulation Data Inspector by creating a run from data in the base workspace or a file. This example creates data in the workspace and then illustrates several methods of creating a Simulation Data Inspector run containing the data.

Create Data

Create data in the workspace. The Simulation Data Inspector supports time series data in many formats. This example creates data using the timeseries and Simulink.SimulationData.Dataset formats and saves the data in a MAT-file.

Create a sine signal and a cosine signal, and store the data for each signal in a timeseries object with a descriptive name.

time = 0:0.2:20;

sine_vals = sin(2*pi/5*time);
sine_ts = timeseries(sine_vals,time);
sine_ts.Name = 'Sine, T=5';

cos_vals = cos(2*pi/8*time);
cos_ts = timeseries(cos_vals,time);
cos_ts.Name = 'Cosine, T=8';

You can use the Dataset format to group related signal data together in a single object. The Dataset format is the default format for logged data and is supported for loading simulation input data. Create a Dataset object that contains the sinusoid timeseries data.

sinusoids_ds = Simulink.SimulationData.Dataset;
sinusoids_ds = addElement(sinusoids_ds,cos_ts);
sinusoids_ds = addElement(sinusoids_ds,sine_ts);

Scale each signal by a factor of 2 and create a Dataset object to contain the signal data for the results.

doubSine = 2*sine_ts;
doubCos = 2*cos_ts;

doubSinusoids_ds = Simulink.SimulationData.Dataset;
doubSinusoids_ds = addElement(doubSinusoids_ds,doubSine);
doubSinusoids_ds = addElement(doubSinusoids_ds,doubCos);

Finally, save the timeseries data to a MAT-file.

save sinusoids.mat sine_ts cos_ts

Open the Simulation Data Inspector

Open the Simulation Data Inspector so you can see the runs you create in each section.

Simulink.sdi.view

Create a Run Using a Simulink.sdi.Run Object

You can import your data into a run in the Simulation Data Inspector by creating an empty run and then adding data to the run from the workspace or a file. Depending on your task, you can use the Simulink.sdi.Run.create function or the Simulink.sdi.createRun function to create the empty run. The Simulink.sdi.Run.create function returns the Simulink.sdi.Run object for the new run, and the Simulink.sdi.createRun function returns the run ID for the new run.

This example creates an empty run using the Simulink.sdi.Run.create function, gives the run a meaningful name and description, and then adds the sine and cosine timeseries data using the add function.

sinusoidsRun = Simulink.sdi.Run.create;
sinusoidsRun.Name = 'Sinusoids';
sinusoidsRun.Description = 'Sine and cosine signals of different frequencies';

add(sinusoidsRun,'vars',sine_ts,cos_ts)

This example uses the Simulink.sdi.createRun function to create a new run in the Simulation Data Inspector called My Waves and then uses the Simulink.sdi.addToRun function to add the sine and cosine timeseries data to the run.

runID = Simulink.sdi.createRun('My Waves');
signalID = Simulink.sdi.addToRun(runID,'vars',sine_ts,cos_ts);

Create a Run from a Workspace Variable

You can create a run from a single variable in the workspace. After creating the run, you can add additional data, or you can create another run to contain your other data. The variable you use to create the run can be a timeseries object with data that corresponds to only one signal, or it can be a Dataset object that contains several signals.

When you use this syntax to create a run from a single workspace variable, the run takes the same name as the object used to create it.

runID = Simulink.sdi.createRun(sine_ts);

The Simulink.sdi.createRun function returns the run ID for the run it creates. You can use the Simulink.sdi.getRun function to access the Run object for the run.

sineRun = Simulink.sdi.getRun(runID);
sineRun.Name

ans = 
'Sine, T=5'

Create a Run from Multiple Workspace Variables

When your data exists in multiple variables in your workspace, you can use the Simulink.sdi.createRun function with the vars option to import the data from multiple variables into a single run in the Simulation Data Inspector. You can also use this syntax to create a run for a single variable that uses a name you specify.

This example creates a run called My Sinusoids that contains data for the sine and cosine timeseries objects.

runID = Simulink.sdi.createRun('My Sinusoids','vars',sine_ts,cos_ts);

Create a Run and Specify Source Names

You can use the namevalue option of the Simulink.sdi.createRun function to create a run and specify names for the signals in the run. This syntax can be particularly helpful when you import individual leaf signals from hierarchical data.

This example creates a run containing the data for both the Dataset objects. Each Dataset object contains data for more than one signal, so the imported run data has hierarchy. The name-value syntax in this example specifies a name for the hierarchical node that corresponds to each Dataset object.

runID = Simulink.sdi.createRun('Waves','namevalue',{'Sinusoids',...
    'BigSinusoids'},{sinusoids_ds,doubSinusoids_ds});

Create a Run from Data in a File

You can also use the Simulink.sdi.createRun function to import data into the Simulation Data Inspector from a file. Use the file option to import the data in the simusoids.mat file.

runID = Simulink.sdi.createRun('Wave Data','file','sinusoids.mat');

Alternative

To streamline indexing syntax, you can use curly braces ({}) to add an element to a dataset, instead of using addElement. For the index, use a scalar that is greater than the number of elements by one. The new element becomes the last element of the dataset.

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