Main Content

add

Import data into existing run in Simulation Data Inspector using Simulink.sdi.Run object

Description

Import Data from Workspace

add(runObj,var) imports the data in the variable var into the Simulation Data Inspector by adding a signal to the run that corresponds to the specified Simulink.sdi.Run object.

To import data into a new run, use the Simulink.sdi.Run.create function or the Simulink.sdi.createRun function.

example

add(runObj,'vars',var,var2,...,varn) imports data from one or more variables into the Simulation Data Inspector by adding one or more signals to the run that corresponds to the specified Run object.

add(runObj,'namevalue',sourceNames,sigValues) imports data from one or more variables into the Simulation Data Inspector by adding one or more signals to the run that corresponds to the specified Run object. The sourceNames argument specifies values to use for the data source in the metadata for the signals added to the run.

Import Data from File

add(runObj,'file',filename) imports data from a file into the Simulation Data Inspector by adding one or more signals to the run that corresponds to the specified Run object. You can use a built-in file reader to import data from a MAT file, CSV file, Microsoft® Excel® file, 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.

add(runObj,'file',filename,Name=Value) imports data from a file into the Simulation Data Inspector by adding one or more signals to the run that corresponds to the specified Run object. For example, sheets=["sheet1" "sheet2"] specifies the sheets from which to import data when importing data from an Excel file.

Examples

collapse all

Create a run, add data to it, and then view the data in the Simulation Data Inspector.

Create Data for 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 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 Data in 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 the signal 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 = [1 0 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);

The sine wave and cosine wave signals plotted in the Simulation Data Inspector. There are two vertically aligned subplots. In the upper subplot, the Sine, T=5 signal is plotted in blue with a dash-dotted line style. In the lower subplot, Cosine, T=8 signal is plotted in red with a dashed line style.

Close Simulation Data Inspector and Save Your Data

When you finish 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

Run to which you want to add imported data, specified as a Simulink.sdi.Run object.

Data to import, specified as a variable. 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.

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

Example: {"sig1","sig2"}

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}

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.

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

  • 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"]

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

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"

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. Use the sheets name-value argument when you do not want to import data from all sheets in the Excel file.

When the data in the file does not include simulation numbers and source information, the data on each sheet is imported 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: ["sheet1" "sheet2"]

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

When you load data from an Excel file that defines signal data types using user-defined data types, such as enumerations, buses, or aliases, the Simulation Data Inspector needs 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 more information on formatting data to import from an Excel file, see Microsoft Excel Import, Export, and Logging Format.

Example: "myModel.slx"

Version History

Introduced in R2017b