Simulink.sdi.createRun

R2026b

Import data into new run in Simulation Data Inspector and return run ID

Syntax

runID = Simulink.sdi.createRun

runID = Simulink.sdi.createRun(runName)

runID = Simulink.sdi.createRun(var)

runID = Simulink.sdi.createRun(runName,"vars",var1,var2,...,varn)

runID = Simulink.sdi.createRun(runName,"namevalue",sourceNames,sigValues)

runID = Simulink.sdi.createRun(runName,"file",filename)

runID = Simulink.sdi.createRun(runName,"file",filename,Name=Value)

[runID,runIndex] = Simulink.sdi.createRun(___)

[runID,runIndex,sigIDs] = Simulink.sdi.createRun(___)

Description

Create Empty Run

runID = Simulink.sdi.createRun creates an empty, unnamed run in the Simulation Data Inspector and returns the run ID for the created run.

You can use the Simulink.sdi.getRun function to access the Simulink.sdi.Run object that corresponds to the run. To add metadata to the run, set the properties on the Run object. Use the Simulink.sdi.addToRun function or the add function to add data to the run.

runID = Simulink.sdi.createRun(runName) creates an empty run named runName.

Import Data from Workspace

runID = Simulink.sdi.createRun(var) imports data from the scalar variable var into a new run in the Simulation Data Inspector. The function names the run according to the input variable. For example, when var is a timeseries object, the run name comes from the Name property on the timeseries object.

runID = Simulink.sdi.createRun(runName,"vars",var1,var2,...,varn) imports data from one or more variables into a new run in the Simulation Data Inspector named runName.

Use this syntax to import data from multiple variables or from a variable that represents an array of objects, such as an array of Simulink.SimulationOutput or Simulink.SimulationData.Dataset objects.

runID = Simulink.sdi.createRun(runName,"namevalue",sourceNames,sigValues) imports data from one or more variables into a new run in the Simulation Data Inspector named runName. The cell array sourceNames specifies the names used to set the RootSource, TimeSource, and DataSource properties for the signals imported from the sigValues cell array.

Import Data from File

runID = Simulink.sdi.createRun(runName,"file",filename) imports data from a file into a new run in the Simulation Data Inspector. You can use a built-in file reader to import data from a MAT file, CSV file, Microsoft^® Excel^® file, Parquet file (since R2026b), or MDF file.

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.

runID = Simulink.sdi.createRun(runName,"file",filename,Name=Value) imports data from a file into a new run in the Simulation Data Inspector according to options specified using one or more name-value arguments. For example, sheets=["sheet1" "sheet2"] specifies the sheets from which to import data when importing data from an Excel file.

Return Additional Run Information

[runID,runIndex] = Simulink.sdi.createRun(___) returns the run ID and the run index in the Simulation Data Inspector for the created run.

[runID,runIndex,sigIDs] = Simulink.sdi.createRun(___) returns the run ID, run index in the Simulation Data Inspector, and the signal IDs for the signals in the created run.

Examples

Create Run in 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 timeseries 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 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 Run Using 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, 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. 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 Run from Workspace Variable

You can create a run from a single variable in the workspace. After creating the run, you can add additional data or 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 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 the function 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 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 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 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 Run from File Data

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 sinusoids.mat file.

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

Create Simulation Data Inspector Run and Access Signal Data

You can create a run in the Simulation Data Inspector using data from the workspace.

Generate Data for Run

Create timeseries data for sine and cosine signals. Give each signal a descriptive name.

time = linspace(0, 20, 101);

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 Run and Return Signal IDs

Use the Simulink.sdi.createRun function to create a run for the sinusoid data. You can use multiple return arguments to get the run ID, run index, and signal IDs directly. If you do not return the signal ID using the Simulink.sdi.createRun function, you can access the signal IDs through the Simulink.sdi.Run object.

[runID,runIndex,sigIDs] = Simulink.sdi.createRun("Sinusoids","vars",...
    sine_ts,cos_ts);

Modify Signal Properties and View in Simulation Data Inspector

Use the second signal ID in the returned sigIDs vector to get the Simulink.sdi.Signal object corresponding to the cosine wave.

cosID = sigIDs(2);
cosSig = Simulink.sdi.getSignal(cosID);

You can view and modify the signal properties for a Simulink.sdi.Signal object. For example, set the Checked property of cosSig to true to plot the signal in the Simulation Data Inspector. Then, open the Simulation Data Inspector to view the signal data.

cosSig.Checked = true;
Simulink.sdi.view

Input Arguments

runName — Name for run

string | character vector

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

Example: "Baseline Simulation"

var — Variable to import

variable

Variable to import. 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: myVar

var1,var2,...,varn — Data to import

variables

Data to import, specified as one or more variables. The Simulation Data Inspector supports time-based data in which sample values correspond to sample times. The Simulation Data Inspector supports all loading and logging data formats, including timeseries and Simulink.SimulationData.Dataset.

Example: myData

sourceNames — Source names for imported data

cell array of character vectors

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.

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

Example: {'sig1','sig2'}

sigValues — Data to import

cell array of variables

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

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

Example: {var1,var2}

filename — Name of file with data to import

character vector

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:

• MAT file.

• CSV file that contains data formatted according to CSV File Format for Simulation Data.

• Microsoft Excel file that contains data formatted according to Microsoft Excel Import, Export, and Logging Format.

• Parquet file that contains data formatted according to Parquet File Format for Simulation Data.

• MDF file with one of these extensions:

  • .mdf

  • .mf4

  • .mf3

  • .data

  • .dat

• ULG file. Flight log data import requires a UAV Toolbox license.

• ROS Bag file version 1.1 or 2.0. Bag file import requires a ROS Toolbox license.

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 Custom File Reader.

Example: 'simulation.mat'

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: Sheets=["sheet1" "sheet2"]

Reader — File reader to use to import data

string | character vector

File reader to use to import data, specified as a string or character vector.

The Simulation Data Inspector prioritizes using a registered custom reader if one is available for the file. If 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 Simulation Data Inspector imports the data 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: Reader="MyExcelReader"

Example: Reader="built-in"

Sheets — Sheets in Excel file from which to import data

string array | cell array of character vectors

Sheets in Excel file from which to import data, specified as a string array or a cell array of character vectors. By default, the Simulation Data Inspector imports data from all sheets. Specify Sheets to limit the import to specific sheets.

If the data in the file does not include simulation numbers and source information, the Simulation Data Inspector imports the data on each sheet into a separate run. For more information about formatting data to import from an Excel file, see Microsoft Excel Import, Export, and Logging Format.

Example: Sheets=["sheet1" "sheet2"]

Model — Model with definitions of user-defined data types

string | character vector

Model with definitions of user-defined data types, specified as a string or character vector.

If you load data from a CSV or Excel file that defines signal data types using user-defined data types, such as enumerations, buses, or aliases, the Simulation Data Inspector requires access to the type definition to import the data. You can provide access to the type definitions by:

• Loading the associated object into the MATLAB^® workspace.

• Specifying the Model name-value argument to use type definitions saved in the model workspace or a data dictionary.

For information about formatting data to import, see CSV File Format for Simulation Data or Microsoft Excel Import, Export, and Logging Format.

Example: Model="myModel.slx"

SignalNames — Names of signals to import from Parquet file

string | string array | character vector | cell array of character vectors

Names of signals to import from a Parquet file, specified as a string, string array, character vector, or cell array of character vectors. By default, the Simulation Data Inspector imports all signals from the file. To selectively import specific signals, use the SignalNames or ColumnIndices name-value argument.

Signal names must match exactly and are case-sensitive. To identify the signal names available in a Parquet file, use Simulink.sdi.Parquet.getSignalMetadata.

To import all elements of a bus, specify the bus parent name. For example, to import all elements from a bus named VehicleBus, specify SignalNames="VehicleBus". To import only some elements of a bus, use dot notation. For example, SignalNames="VehicleBus.Velocity" imports only the Velocity element.

Example: SignalNames=["Sine" "Cosine"]

ColumnIndices — Column indices of signals to import from Parquet file

positive integer | vector of positive integers

Column indices of signals to import from a Parquet file, specified as a positive integer or vector of positive integers. By default, the Simulation Data Inspector imports all signals from the file. To selectively import specific signals, use the SignalNames or ColumnIndices name-value argument.

Column indices refer to data columns only. The Simulation Data Inspector automatically imports time columns with the corresponding data columns. To identify the column indices for signals in a Parquet file, use Simulink.sdi.Parquet.getSignalMetadata.

Example: ColumnIndices=[1 3 5]

Output Arguments

runID — Run ID for run that contains imported data

positive integer | vector of positive integers

Run ID for the run that contains imported data, returned as one of these values:

• positive integer — If you create an empty run, import data from the workspace, or import data from a file that contains only one run, then runID is a scalar.

• vector of positive integers — If you import data from a file that contains multiple runs, then runID is a vector.

runIndex — Index of run in Simulation Data Inspector

positive integer | vector of positive integers

Index of run in the Simulation Data Inspector that contains imported data, returned as one of these values:

• positive integer — If you create an empty run, import data from the workspace, or import data from a file that contains only one run, then runIndex is a scalar.

• vector of positive integers — If you import data from a file that contains multiple runs, then runIndex is a vector.

sigIDs — Signal IDs for signals created from imported data

integer | vector of integers

Signal IDs for signals created from imported data, returned as an integer or vector of integers.

Version History

Introduced in R2011b

R2026b: Import additional data types and metadata from CSV files

You can import CSV files that contain complex and multidimensional signals, function-call signals, simulation parameters, and user-defined data types such as alias, fixed-point, and bus types. The expanded import also supports additional signal metadata and multiple runs in a single file. To resolve user-defined data types when importing a CSV file, specify the Model name-value argument.

R2026b: Import data from Parquet files

You can import simulation data from Parquet files into the Simulation Data Inspector. To selectively import specific signals, specify the SignalNames or ColumnIndices name-value argument. When a JSON sidecar file accompanies the Parquet file, the import preserves signal metadata such as data types, units, and run grouping. When the Parquet file contains multiple runs, this function creates separate runs and returns a vector of run IDs. For more information about the file format, see Parquet File Format for Simulation Data.