Main Content

Simulink.sdi.Run.create

Import data into a run in the Simulation Data Inspector

Description

example

runObj = Simulink.sdi.Run.create creates the empty Simulink.sdi.Run object, runObj. You can add signals to the Run object using the add function or the Simulink.sdi.addToRun function.

example

runObj = Simulink.sdi.Run.create(runName) creates an empty run named runName.

example

runObj = Simulink.sdi.Run.create(var) creates a run that contains the data in the scalar workspace variable var. The run is named according to the input variable. For example, when var is a timeseries object, the run name comes from the Name property of the timeseries object.

example

runObj = Simulink.sdi.Run.create(runName,'file',filename) creates a run that contains the data in the file specified by filename.

runObj = Simulink.sdi.Run.create(runName,'file',filename,reader) uses the file reader, reader, to create a run that contains the data in the file, filename. Use this syntax when multiple file readers that support the file with data to import are registered with the Simulation Data Inspector. To determine which readers are available for your file, use the io.reader.getSupportedReadersForFile function.

example

runObj = Simulink.sdi.Run.create(runName,'namevalue',sourceNames,sigValues) creates a run that contains the data in the cell array sigValues. The cell array sourceNames specifies the source names used to set the RootSource, TimeSource, and DataSource properties for the signals imported from the sigValues cell array.

Examples

collapse all

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

To view the runs you create in each section, open the Simulation Data Inspector by entering Simulink.sdi.view in the MATLAB™ Command Window.

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');

This example shows how to create a run, add data to it, and then view the data in the Simulation Data Inspector.

Create Data for the Run

Create timeseries objects to contain data for a sine signal and a cosine signal. Give each timeseries object a descriptive name.

time = linspace(0,20,100);

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';

Create a Run and Add Data

Use the Simulink.sdi.view function to open the Simulation Data Inspector.

Simulink.sdi.view

To import data into the Simulation Data Inspector from the workspace, create a Simulink.sdi.Run object using the Simulink.sdi.Run.create function. Add information about the run to its metadata using the Name and Description properties of the Run object.

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

Use the add function to add the data you created in the workspace to the empty run.

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

Plot the Data in the Simulation Data Inspector

Use the getSignalByIndex function to access Simulink.sdi.Signal objects that contain the signal data. You can use the Simulink.sdi.Signal object properties to specify the line style and color for the signal and plot it in the Simulation Data Inspector. Specify the LineColor and LineDashed properties for each signal.

sine_sig = getSignalByIndex(sinusoidsRun,1);
sine_sig.LineColor = [0 0 1];
sine_sig.LineDashed = '-.';

cos_sig = sinusoidsRun.getSignalByIndex(2);
cos_sig.LineColor = [0 1 0];
cos_sig.LineDashed = '--';

Use the Simulink.sdi.setSubPlotLayout function to configure a 2-by-1 subplot layout in the Simulation Data Inspector plotting area. Then use the plotOnSubplot function to plot the sine signal on the top subplot and the cosine signal on the lower subplot.

Simulink.sdi.setSubPlotLayout(2,1);

plotOnSubPlot(sine_sig,1,1,true);
plotOnSubPlot(cos_sig,2,1,true);

Close the Simulation Data Inspector and Save Your Data

When you have finished inspecting the plotted signal data, you can close the Simulation Data Inspector and save the session to an MLDATX file.

Simulink.sdi.close('sinusoids.mldatx')

Input Arguments

collapse all

Name for run in the Simulation Data Inspector, specified as a character vector or string.

Example: 'Baseline Simulation'

Variable in the base workspace that contains the data you want to import into a run in the Simulation Data Inspector. The Simulation Data Inspector supports time-based data in which sample values are associated with sample times. The Simulation Data Inspector supports all loading and logging data formats, including timeseries and Simulink.SimulationData.Dataset.

Example: myData

Source names for imported data, specified as a cell array of character vectors. The source name is used to set the RootSource, TimeSource, and DataSource properties of the Simulink.sdi.Signal objects created from the data specified by the sigValues input.l

Provide a sourceNames input when you specify 'namevalue' for the second argument.

Example: {'sig1','sig2'}

Data to import, specified as a cell array of workspace variables.

Provide a sigValues input when you specify 'namevalue' for the second argument.

Example: {var1,var2}

Name of file with data to import, specified as a character vector. Provide a filename input when you specify 'file' for the second argument.

You can create a run from these types of files using file readers built into the Simulation Data Inspector:

When you need to import data from a file that the built-in readers do not support, you can write your own reader using the io.reader class. You can also write a custom reader to use instead of the built-in reader for any file extension. For an example, see Import Data Using a Custom File Reader.

Example: 'simulation.mat'

File reader to use for importing data from a file, specified as a character array. The Simulation Data Inspector prioritizes using a registered custom reader when one is available for the file. When you do not specify a reader, the Simulation Data Inspector uses the first custom reader registered for the file. If no custom readers are registered, the data is imported using the built-in reader.

Specify the reader input when:

  • You want to use the built-in reader to import data for a file that is also supported by a custom reader.

  • Multiple registered custom readers support the file.

To determine which readers are available to import your file, use the io.reader.getSupportedReadersForFile function.

Example: 'MyExcelReader'

Example: 'built-in'

Output Arguments

collapse all

Imported data, returned as a Simulink.sdi.Run object. When you create an empty Run object, import data from the base workspace or a file using the add function or the Simulink.sdi.addToRun function.

Introduced in R2017b