Simulink.sdi.Signal class

Package: Simulink.sdi

Access signal data and metadata

Description

A Simulink.sdi.Signal object provides access to signal data and metadata. The metadata includes properties for visualizing and comparing signals.

Construction

signal = Simulink.sdi.getSignal(signalID) returns a Simulink.sdi.Signal object corresponding to the signalID.

signal = runObj.getSignal(signalID) returns a Simulink.sdi.Signal object corresponding to the signalID.

signal = runObj.getSignalByIndex(index) returns a Simulink.sdi.Signal object corresponding to the signalID at the index specified by index in the Run object runObj.

Input Arguments

expand all

Numeric signal identifier for the signal generated by the Simulation Data Inspector. You can get the signal ID for a signal using methods of the Simulink.sdi.Run object or using the Simulink.sdi.getSignal function.

Index of the signal within the run.

Example: 1

Properties

expand all

Signal Properties

Unique number identifying the signal. The Simulation Data Inspector assigns a unique numeric ID to each run and signal.

Run identifier for the run that contains the signal. The Simulation Data Inspector assigns a unique numeric ID to each run and signal. You can access the run ID for a signal using the Simulink.sdi.getAllRunIDs function.

Name of the signal.

Example: 'fuel'

Description of the signal, specified as a character array or a string. You can use the Description property to annotate the signal or identify the signal content beyond the Name. When you log Simscape™ data to the Simulation Data Inspector, the Description property is populated automatically for each node.

Signal units of measure.

Example: 'g/s'

Data type of signal data.

Example: 'double'

Specifies whether signal data is real or complex.

Example: 'real'

Signal sample time. A value of 'Continuous' indicates a variable-step simulation.

Example: 'Continuous'

Example: 0.1

Name of the model that produced the signal.

Example: 'sldemo_fuelsys'

The path to the block that produced the signal.

Example: 'sldemo_fuelsys/Engine Gas Dynamics'

Path to the block that generates the signal including the full model hierarchy. For signals within reference models, FullBlockPath is a cell array containing the full path. For other signals, FullBlockPath is identical to BlockPath.

Example: 'sldemo_fuelsys/Engine Gas Dynamics/Mixing & Combustion/MinMax'

Index of the output port that defines the signal.

Example: 1

Dimensions of the matrix that contains the signal.

Example: [1]

Indices of the signal for signals that are part of a vector or matrix.

Time and data values for the signal. For buses, Values is a structure.

Name of the high-level logging structure containing the signal, for signals imported from the MATLAB workspace.

Name of the variable containing the signal time data for signals imported from the MATLAB workspace.

Name of the array containing the signal data for signals imported from the MATLAB workspace.

Visualization Properties

Complex format specifying how to display complex signal data in the Simulation Data Inspector.

  • "real-imaginary" — The real and imaginary components of the signal display together when you plot the signal. The imaginary component of the signal is plotted with a different shade of the Line Color.

  • "magnitude" — The magnitude of the signal displays when you plot the signal.

  • "magnitude-phase" — The magnitude and phase of the signal display together when you plot the signal.

  • "phase" — The phase of the signal displays when you plot the signal. The phase is plotted with a different shade of the Line Color.

Data Types: char | string

Logical value indicating whether the signal is plotted on any subplot. Setting Checked to false clears the signal from all subplots. Setting Checked to true plots the signal on the active subplot.

Data Types: logical

Color of signal in plots, specified as a 1-by-3 RGB vector.

Example: [0 114 189]

Data Types: double

Signal line style.

  • '-' specifies a solid line style.

  • '--' specifies a dashed line style.

  • ':' specifies a dotted line style.

  • '-.' specifies a dash-dot line style.

Interpolation method used in data visualization and synchronization. 'zoh' specifies zero-order hold interpolation, 'linear' specifies linear interpolation, and 'none' specifies no interpolation. For more information about the interpolation options, see How the Simulation Data Inspector Compares Data.

Comparison Properties

Positive-valued absolute tolerance of the signal used for signal comparisons. The Simulation Data Inspector uses tolerances specified in the signal properties of the baseline signal when Override Global Tol is set to yes. For more information about tolerances in the Simulation Data Inspector, see How the Simulation Data Inspector Compares Data.

Example: 0.1

Data Types: double

Positive-valued relative tolerance for the signal used for signal comparisons. The Simulation Data Inspector uses tolerances specified in the signal properties of the baseline signal when Override Global Tol is set to yes. The relative tolerance is expressed as a fractional multiplier. For example, 0.1 specifies a 10 percent tolerance. For more information about tolerances in the Simulation Data Inspector, see How the Simulation Data Inspector Compares Data.

Example: 0.05

Data Types: double

Positive-valued time tolerance for the signal used in signal comparisons. The Simulation Data Inspector uses tolerances specified in the signal properties of the baseline signal when Override Global Tol is set to yes. Specify the time tolerance in seconds. For more information about tolerances in the Simulation Data Inspector, see How the Simulation Data Inspector Compares Data.

Example: 0.1

Data Types: double

Method used to synchronize signal time data for comparison. For more information about the synchronization options, see How the Simulation Data Inspector Compares Data.

Methods

convertUnits Convert signal units
export Export signal object to MATLAB timeseries
getAsTall Return tall timetable with time and data values
plotOnSubPlot Plot signal on specified sub-plot

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects (MATLAB).

Examples

collapse all

You can change tolerance values on a signal-by-signal basis to evaluate the effect of a model parameter change. This example uses the slexAircraftExample model and the Simulation Data Inspector to evaluate the effect of changing the time constant for the low-pass filter following the control input.

Setup

Load the model, and mark the q, rad/sec and alpha, rad signals for logging. Then, simulate the model to create the baseline run.

% Load example model
load_system('slexAircraftExample')

% Mark the q, rad/sec and alpha, rad signals for logging
Simulink.sdi.markSignalForStreaming('slexAircraftExample/Aircraft Dynamics Model',3,'on')
Simulink.sdi.markSignalForStreaming('slexAircraftExample/Aircraft Dynamics Model',4,'on')

% Simulate system
out_1 = sim('slexAircraftExample');

Modify Model Parameter

Modify the model parameter Ts in the model workspace to change the time constant of the input low-pass filter.

% Change input filter time constant
modelWorkspace = get_param('slexAircraftExample','modelworkspace');
assignin(modelWorkspace,'Ts',1)

% Simulate again
out_2 = sim('slexAircraftExample');

Compare Runs and Inspect Results

Use the Simulink.sdi.compareRuns function to compare the data from the simulations. Then, inspect the match property of the signal result to see whether the signals fell within the default tolerance of 0.

% Get run data
runIDs = Simulink.sdi.getAllRunIDs;
runID1 = runIDs(end - 1);
runID2 = runIDs(end);

% Compare runs
diffRun1 = Simulink.sdi.compareRuns(runID1,runID2);

% Get signal result
sig1Result1 = getResultByIndex(diffRun1,1);
sig2Result1 = getResultByIndex(diffRun1,2);

% Check whether signals matched
sig1Result1.Status
ans = 
OutOfTolerance
sig2Result1.Status
ans = 
OutOfTolerance

Compare Runs with Signal Tolerances

The signals did not match within the default tolerance of 0. To further analyze the effect of the time constant change, add signal tolerances to the comparison with the baseline signal properties to determine the tolerance required for a pass. This example uses a combination of time and absolute tolerances.

% Get signal object for sigID1
run1 = Simulink.sdi.getRun(runID1);
sigID1 = getSignalIDByIndex(run1,1);
sigID2 = getSignalIDByIndex(run1,2);

sig1 = Simulink.sdi.getSignal(sigID1);
sig2 = Simulink.sdi.getSignal(sigID2);

% Set tolerances for q, rad/sec
sig1.AbsTol = 0.1;
sig1.TimeTol = 0.6;

% Set tolerances for alpha, rad
sig2.AbsTol = 0.2;
sig2.TimeTol = 0.8;

% Run the comparison again
diffRun2 = Simulink.sdi.compareRuns(runID1,runID2);
sig1Result2 = getResultByIndex(diffRun2,1);
sig2Result2 = getResultByIndex(diffRun2,2);

% Check the result
sig1Result2.Status
ans = 
WithinTolerance
sig2Result2.Status
ans = 
WithinTolerance

This example shows how to obtain a Simulink.sdi.Signal object and modify its properties using the Simulation Data Inspector programmatic interface.

Acquire a Simulink.sdi.Signal Object

First, run a simulation to create a run. This example uses example model slexAircraftExample. Then, use the Simulation Data Inspector programmatic interface to get the Simulink.sdi.Signal object for your signal of interest.

% Configure model "slexAircraftExample" for logging and simulate
simOut = sim('slexAircraftExample','SaveOutput','on',...
                   'SaveFormat','StructureWithTime');
 
% Use Simulink.sdi.createRun to create a run and return the list of signal IDs for signals 
% contained in the run
[~,~,signalIDs] = Simulink.sdi.createRun('My Run','base',{'simOut'});

% Get the signal object corresponding to the first signal ID
signalObj = Simulink.sdi.getSignal(signalIDs(1));

Modify the Signal Properties

The Simulink.sdi.Signal object has several comparison and visualization properties that you can modify.

% Define comparison and visualization properties for this signal
signalObj.syncMethod = 'intersection';
signalObj.lineColor = [1,0.4,0.6];
signalObj.lineDashed = '-';
signalObj.checked = true;

View the Signal Properties

You can view the signal properties in the command window and in the Simulation Data Inspector to verify that the signal has its properties defined how you want them.

signalObj
signalObj = 
  Signal with properties:

               ID: 22670
            RunID: 22656
             Name: 'Integrate:CSTATE'
      Description: ""
            Units: ''
         DataType: 'double'
       Complexity: "real"
    ComplexFormat: "real-imaginary"
       SampleTime: ''
            Model: 'slexAircraftExample'
        BlockPath: 'slexAircraftExample/Aircraft Dynamics Model/Vertical Channel/Integrate'
    FullBlockPath: 'slexAircraftExample/Aircraft Dynamics Model/Vertical Channel/Integrate'
        PortIndex: 0
       Dimensions: 1
          Channel: [1x0 int32]
          Checked: 1
        LineColor: [1 0.4000 0.6000]
       LineDashed: '-'
     InterpMethod: 'linear'
           AbsTol: 0
           RelTol: 0
          TimeTol: 0
       SyncMethod: 'intersection'
           Values: [1x1 timeseries]
       RootSource: 'simOut.get('xout')'
       TimeSource: 'simOut.get('xout').time'
       DataSource: 'simOut.get('xout').signals(1).values'

Simulink.sdi.view

This example uses the slexAircraftExample model to demonstrate the comparison of the input and output signals for a control system. The example marks the signals for streaming then gets the run object for a simulation run. Signal IDs from the run object specify the signals to be compared.

% Load model slexAircraftExample and mark signals for streaming
load_system('slexAircraftExample')
Simulink.sdi.markSignalForStreaming('slexAircraftExample/Pilot',1,'on')
Simulink.sdi.markSignalForStreaming('slexAircraftExample/Aircraft Dynamics Model',4,'on')

% Simulate model slexAircraftExample
out = sim('slexAircraftExample');

% Get run IDs for most recent run
allIDs = Simulink.sdi.getAllRunIDs;
runID = allIDs(end);

% Get Run object
aircraftRun = Simulink.sdi.getRun(runID);

% Get signal IDs
signalID1 = getSignalIDByIndex(aircraftRun,1);
signalID2 = getSignalIDByIndex(aircraftRun,2);

if (isValidSignalID(aircraftRun,signalID1))
    % Change signal tolerance
    signal1 = Simulink.sdi.getSignal(signalID1);
    signal1.AbsTol = 0.1;
end

if (isValidSignalID(aircraftRun,signalID1) && isValidSignalID(aircraftRun,signalID2))
    % Compare signals
    sigDiff = Simulink.sdi.compareSignals(signalID1,signalID2);

    % Check whether signal result status
    match = sigDiff.Status
end
match = 
OutOfTolerance

This example demonstrates how to access the Simulink.sdi.Run object for a Simulation Data Inspector run created by logging signals. From the Simulink.sdi.Run object you can get Simulink.sdi.Signal objects that you can use to plot the data.

Create a Simulation Run and Access the Run Object

The sldemo_fuelsys model includes several signals that are marked for logging. To create a simulation run containing the logged data, simulate the model.

sim('ex_vdp');

The Simulation Data Inspector keeps track of runs by assigning each run created by simulation, importing data, or opening a session a unique numeric ID. To access the run object for the simulation just performed, use the Simulink.sdi.getAllRunIDs function and take the last run ID in the returned vector.

runIDs = Simulink.sdi.getAllRunIDs;
runID = runIDs(end);

Once you have the run ID for the run of interest, you can use the Simulink.sdi.getRun function to get the Simulink.sdi.Run object corresponding to the run. You can use the Run object to check metadata associated with the run, including the number of signals in the run.

vdpRun = Simulink.sdi.getRun(runID);

vdpRun.SignalCount
ans = int32
    2

Plot Data Using Signal Objects

Use the getSignalByIndex function to access signals of interest from the Run object, fuelRun.

signal1 = getSignalByIndex(vdpRun,1);
signal2 = getSignalByIndex(vdpRun,2);

Use the Simulink.sdi.setSubPlotLayout function to specify a 3-by-1 layout.

Simulink.sdi.setSubPlotLayout(2,1)

Before plotting the data, use the Simulink.sdi.clearAllSubPlots function to clear any data that is already plotted.

Simulink.sdi.clearAllSubPlots

Plot one signal on each subplot. To plot signals on the first subplot, you can set the checked property for the signal. To plot signals on subplots other than the first subplot, use the plotOnSubPlot function.

signal1.Checked = true;
plotOnSubPlot(signal2,2,1,true);

View the Plotted Data

To view the plots you just created, open the Simulation Data Inspector using the Simulink.sdi.view function.

Alternatives

Use the Simulation Data Inspector UI to view and modify signals and signal properties.

Introduced in R2012b