getElement

Copy signal data from Simulation Data Inspector run to workspace

collapse all in page

Syntax

[element, name, idx] = getElement(dsr,searchIdx)
[element, name, idx] = getElement(dsr,searchName)

Description

[element, name, idx] = getElement(dsr,searchIdx) copies data for the signal with the index searchIdx within the Simulation Data Inspector run referenced by the Simulink.SimulationData.DatasetRef object dsr into the variable element in the workspace.

Use the getElement function to work with a copy of data for a signal in the Simulation Data Inspector in the workspace. The function loads the data for the signal into memory. Simulation data logs to a temporary file on disk. The Simulation Data Inspector accesses data in the temporary file, loading data into memory only as needed.

A Simulink.sdi.DatasetRef object references the data for a run in the Simulation Data Inspector, allowing you to work with signal data in the run while controlling when and how the signal data is loaded into memory. To access signal data in the repository without loading the signal data into memory, use the getSignal function.

example

[element, name, idx] = getElement(dsr,searchName) copies data for the signal searchName into the workspace variable element.

  • If only one signal has the name searchName, the function returns the data to the workspace as a scalar object matching the way the data is logged to the workspace in Dataset format.

  • If multiple signals have the name searchName, the function returns a Dataset object that contains those elements.

  • If searchName is a cell array containing one character vector, the function returns a Dataset object containing the signal data for one or more signals corresponding to the name searchName.

example

Examples

collapse all

Open Live Script

When you have data that is stored in the Simulation Data Inspector repository, but not in the workspace, you can use the getElement function to return a copy of the signal data to the workspace. In this example, a Simulation Data Inspector session file is used to add run data to the repository. The data is not loaded to the workspace. The session file contains data for four simulations of an aircraft longitudinal controller. For more information about the model used to create the data, see Aircraft Longitudinal Flight Control.

Use the Simulink.sdi.load function to load the Simulation Data Inspector session. When you load the session file, run data is saved to the Simulation Data Inspector repository. 

Simulink.sdi.load("AircraftExample.mldatx");

To view the data, open the Simulation Data Inspector and select signals to plot. Note that the data from the Simulation Data Inspector session file is not recorded in the workspace. 

Simulink.sdi.view

Get the run ID for the first run saved in the session file.

allIDs = Simulink.sdi.getAllRunIDs;
aircraftRun1ID = allIDs(end-3);

Create a Simulink.sdi.DatasetRef object that references that run.

dsr = Simulink.sdi.DatasetRef(aircraftRun1ID);

Get the names of all the elements in the DatasetRef object.

getElementNames(dsr)
ans = 3×1 cell
    {'q, rad/sec'}
    {'alpha, rad'}
    {'Stick'     }

Use the getElement function to pull a copy of the q, rad/sec signal data that is located in the Simulation Data Inspector repository into the workspace using the index 1. 

qSig = getElement(dsr,1)
qSig = 
  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

  Properties:
              Name: 'q, rad/sec'
    PropagatedName: ''
         BlockPath: [1×1 Simulink.SimulationData.BlockPath]
          PortType: 'outport'
         PortIndex: 3
            Values: [1×1 timeseries]


  Methods, Superclasses
Open Live Script

The model GetDatasetElements logs data generated by three source blocks using the Dataset format. In the model, the signals coming from the Sine Wave block and the Constant block share the same name. The signal coming from the Pulse Generator block has a unique name. 

open_system("GetDatasetElements")

Simulate the model.

out = sim("GetDatasetElements");

Use the Simulink.sdi.Run.getLatest function to get the latest run in the Simulation Data Inspector repository.

GDERun = Simulink.sdi.Run.getLatest;

Create a Simulink.sdi.DatasetRef object that references GDERun.

DSRef = getDatasetRef(GDERun);

Use the getElement function to return a copy of the data from the signal with the name DifName to the workspace. Because the name DifName is unique, the function returns a Simulink.SimulationData.Signal object for that signal.

[el,difName,difIndex] = getElement(DSRef,"DifName")
el = 
  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

  Properties:
              Name: 'DifName'
    PropagatedName: ''
         BlockPath: [1×1 Simulink.SimulationData.BlockPath]
          PortType: 'inport'
         PortIndex: 1
            Values: [1×1 timeseries]


  Methods, Superclasses

difName = 
'DifName'

difIndex = 
2

You can also use the getElement function when a signal name is not unique within a run. For example, because SameName is not a unique name, the function returns a copy of the data for the signals with that name to the workspace in a Simulink.SimulationData.Dataset object.

ds = getElement(DSRef,"SameName")
ds = 
Simulink.SimulationData.Dataset '' with 2 elements

                         Name      BlockPath               
                         ________  _______________________ 
    1  [1x1 Signal]      SameName  GetDatasetElements/Out1
    2  [1x1 Signal]      SameName  GetDatasetElements/Out2

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

The model GetDatasetElements logs data generated by three source blocks using the Dataset format. In the model, the signals coming from the Sine Wave block and the Constant block share the same name. The signal coming from the Pulse Generator block has a unique name. 

open_system("GetDatasetElements")

Simulate the model.

out = sim("GetDatasetElements");

Use the Simulink.sdi.Run.getLatest function to get the latest run. 

GDERun = Simulink.sdi.Run.getLatest;

Create a Simulink.sdi.DatasetRef object that references GDERun.

DSRef = getDatasetRef(GDERun);

Use the getElement function with a cell array containing a character vector to return a Simulink.SimulationData.Dataset object in the workspace that corresponds to a Simulink.sdi.Signal object in the Simulation Data Inspector repository. If the element name is unique, the getElement function returns a Dataset object containing one element. If the element name is not unique, the getElement function returns a Dataset object containing all elements with that name. For example, create a Dataset object containing the element named DifName.

ds = get(DSRef,{'DifName'})
ds = 
Simulink.SimulationData.Dataset '' with 1 element

                         Name     BlockPath               
                         _______  _______________________ 
    1  [1x1 Signal]      DifName  GetDatasetElements/Out3

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

Input Arguments

collapse all

Run from which to get signal data, specified as a Simulink.sdi.DatasetRef object.

Index of signal to get in the Simulation Data Inspector run referenced by dsr, specified as a positive integer.

Name of signal to get in the Simulation Data Inspector run referenced by dsr, specified as:

  • A string reflecting the name of the signal.

  • A character array reflecting the name of the signal.

  • A cell array containing one character vector reflecting the name of the signal. To return a Dataset object containing one element, use this format.

Output Arguments

collapse all

Copy of signal data, specified as an object containing logged simulation results. This output can be a Simulink.SimulationData.Dataset object or a Dataset object element, such as a Simulink.Simulationdata.Signal, Simulink.SimulationData.State, or Simulink.SimulationData.DataStoreMemory object.

Element name, specified as a character vector.

Element index in the Run object, specified as a positive integer.

Alternatives

To access signal data in the repository without loading the signal data into memory, use the getSignal function.

Version History

Introduced in R2017b

See Also

Objects

Functions

Tools

Topics