Simulink.sdi.Signal
Access signal data and metadata
Description
A Simulink.sdi.Signal
object contains data and
metadata for a signal in the Simulation Data
Inspector. You can use the Signal
object properties to
inspect signal metadata, visualize signals on time plots, and compare signals using the
Simulink.sdi.compareSignals
function.
Creation
A Simulink.sdi.Signal
object is created for each signal you log in a
model simulation or import into the Simulation Data Inspector. You can access
Signal
objects in the Simulation Data Inspector several ways.
Generally, to access a Signal
object, you first need to get the Simulink.sdi.Run
object that contains the signal.
The
Simulink.sdi.getSignal
function returns aSignal
object that corresponds to the signal ID you provide.The
getSignal
function returns theSignal
object with the specified signal ID inside the specifiedRun
object.The
getSignalByIndex
function returns theSignal
object at the specified index within the specifiedRun
object.
Properties
Signal Properties
ID
— Signal identifier
integer
This property is read-only.
Unique number identifying the signal, returned as an integer. The Simulation Data Inspector assigns a unique numeric ID to each run and signal.
RunID
— Run identifier
integer
This property is read-only.
Run identifier for the run that contains the signal, returned as an integer. The Simulation Data Inspector assigns a unique numeric ID to each run and signal.
Name
— Signal name
character vector | string
Name of the signal, specified as a character vector or a string. When
the Signal
object contains data logged from a
simulation, the name matches the name specified for the signal in the
model. If the model does not specify the name, the signal name is the
block path to the block that produces the signal.
Example: 'fuel'
Domain
— Signal type
'Signals'
| 'Outports'
| 'States'
| 'Data Store Memory'
| 'Parameters'
| ...
This property is read-only.
Signal type, specified as an option such as:
'Signals'
— Signal logging data'Outports'
— Output logging data'States'
— States logging data'Data Store Memory'
— Data store memory logging data'Parametrs'
— Logged parameter data'Stateflow'
— Stateflow® data'Simscape'
— Simscape™ data'Assessments'
— Simulink® Test™ assessment data'Profiling'
— Execution profiling data
The Domain
property is empty for data not created
by logging simulation data.
Description
— Signal description
''
(default) | character vector | string
Description of the signal, specified as a character vector 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.
Stored Units
— Units of signal data stored on disk
character vector | string
This property is read-only.
Units of signal data stored on disk, specified as a character vector
or a string. For signals generated from simulating a model, the stored
units of the Signal
objects use the units specified in
the model. When you specify display units for a signal without units,
the same units are used to set the stored units. To analyze a signal
alongside another that uses different units, modify the display units
for the signal. The Simulation Data Inspector performs the conversion to
plot the data using the display units.
You can convert the stored units for a signal using the convertUnits
function. Stored unit conversion does not
support undo and may result in precision loss.
Example: 'g/s'
Display Units
— Units used to display signal data in Simulation Data Inspector
character vector | string
Units used to display signal data in the Simulation Data Inspector, specified as a character vector or a string. The display units for a signal may differ from the stored units that reflect the data stored on disk. Modify signal display units to analyze data in the Simulation Data Inspector. Unit preferences in the Simulation Data Inspector may change the display units for logged and imported signal data. For more information, see Signal Display Units.
Example: 'm/s'
Data Type
— Data type for signal data
character vector | string
This property is read-only.
Data type of signal data, returned as a character vector or string.
Example: 'double'
Complexity
— Complexity of signal data
"real"
| "complex"
This property is read-only.
Complexity of signal data, returned as "real"
or
"complex"
.
Example: "real"
SampleTime
— Signal sample time
character vector
Signal sample time, returned as a character vector or scalar. A value
of 'Continuous'
indicates a variable-step
simulation.
Example: 'Continuous'
Example: '0.1'
Model
— Name of model that produced signal
character vector
This property is read-only.
Name of the model that produced the signal, returned as a character
vector. The Model
property is empty for
Signal
objects that contain data that was not
produced by simulating a model.
Example: 'sldemo_fuelsys'
BlockPath
— Block path for block that produced signal
character vector
This property is read-only.
Block path for the block that produced the signal, returned as a
character array. The BlockPath
property is a relative
path that does not include model hierarchy. The
BlockPath
property is empty for
Signal
objects that contain data that was not
produced by simulating a model.
Example: 'sldemo_fuelsys/Engine Gas
Dynamics'
FullBlockPath
— Complete block path for block that produced signal
character vector | cell array
This property is read-only.
Complete block path for the block that produced the signal, including
the full model hierarchy, returned as a character vector. For signals
within referenced models, FullBlockPath
is a cell
array that contains the full path. For other signals,
FullBlockPath
is identical to
BlockPath
. The FullBlockPath
property is empty for Signal
objects that contain data
that was not produced by simulating a model.
BlockName
— Name of block that produced signal
character vector
This property is read-only.
Name of the block that produced the signal, returned as a character
vector. The BlockName
property is empty for
Signal
objects that contain data that was not
produced by simulating a model.
Example: 'Engine Gas Dynamics'
PortIndex
— Block port index
integer
Index of the output port connected to the signal on the block that
produces the signal. The PortIndex
property is empty
for Signal
objects that contain data that was not
produced by simulating a model.
Example: 1
Dimensions
— Signal dimensions
integer | integer array
This property is read-only.
Signal dimensions, returned as an integer or integer array.
Example: [1 2]
Channel
— Index of signal within matrix
integer array
This property is read-only.
Index of the signal within a matrix, returned as an integer array.
NumPoints
— Number of samples in signal
integer
This property is read-only.
Number of samples in the signal, returned as an integer.
Values
— Signal values
timeseries
| structure
Time and data values for the signal, returned as a
timeseries
object for non-bus signals or
structure matching the bus hierarchy for bus signals.
RootSource
— High-level structure that contains imported signal
character vector
This property is read-only.
Name of the high-level structure containing the signal, returned as a
character vector. The RootSource
property only has
value for imported signals.
Example: When you import the Simulink.SimulationOutput
object simOut
containing structure
xout
, the RootSource
is
'simOut.get('xout')'
TimeSource
— Source of imported signal time data
character vector
This property is read-only.
Path to the signal time data, returned as a character vector. The
TimeSource
property only has value for imported
signals.
Example: When you import the Simulink.SimulationOutput
object simOut
containing structure
xout
, the TimeSource
is
'simOut.get('xout').time'
DataSource
— Source of imported signal data
character vector
This property is read-only.
Path to the signal sample values, returned as a character array. The
DataSource
property only has value for imported
signals.
Example: When you import the Simulink.SimulationOutput
object simOut
containing structure
xout
, the DataSource
is
'simOut.get('xout').signals(1).values'
Children
— Signals contained by composite signal
Simulink.sdi.Signal
vector
This property is read-only.
Signals contained by the composite signal, returned as
Simulink.sdi.Signal
objects. The
Children
property is empty for scalar
signals.
Display Scaling
— Scaling used to display signal data in Simulation Data Inspector
1
(default) | scalar
Scaling used to display signal data in the Simulation Data Inspector, specified as a real non-zero scalar. Display Scaling acts as a multiplier, allowing you to scale the appearance of an individual signal in the Simulation Data Inspector. Scaling the display does not change the data values of the signal. Signals scale differently depending on the visualization type.
Visualization | Scaling |
---|---|
Time Plot | Scale an individual signal display in the y direction. |
Sparklines | Scale an individual signal display in the y direction. |
XY | Scale signal display in the y direction and x direction independently. |
Array | Scale each element of the multidimensional signal display in the same manner in the y direction. |
Map | Scale signal display in the longitudinal and latitudinal directions independently. Note that this allows you to convert other units to longitude and latitude. |
Display Offset
— Offset used to display signal data in Simulation Data Inspector
1
(default) | scalar
Offset used to display signal data in the Simulation Data Inspector, specified as a real scalar. Display Offset allows you to shift the appearance of an individual signal in the Simulation Data Inspector. Offsetting the display does not change the data values of the signal. Signals shift differently depending on the visualization type.
Visualization | Scaling |
---|---|
Time Plot | Shift an individual signal display in the y direction. |
Sparklines | Shift an individual signal display in the y direction. |
XY | Shift signal display in the y direction and x direction independently. |
Array | Shift each element of the multidimensional signal display in the same manner in the y direction. |
Map | Shift signal display in the longitudinal and latitudinal directions independently. |
Visualization Properties
ComplexFormat
— Display format for complex signals
"real-imaginary"
| "magnitude"
| "magnitude-phase"
| "phase"
Complex format used to display complex signal data in the Simulation
Data Inspector, specified as one of the following values. You can modify
the ComplexFormat
property for a
Signal
object to change how the Simulation Data
Inspector displays the signal data when the object contains data for a
complex signal.
"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
Checked
— Whether signal is plotted
0
or
false
(default) | 1
or true
Whether the signal is plotted, specified as a logical value. Setting
Checked
to false
clears the
signal from all subplots. Setting Checked
to
true
plots the signal on the active
subplot.
Data Types: logical
LineColor
— Signal line color
1
-by-3
vector
Color of signal in plots, specified as a
1
-by-3
RGB vector with values
between 0
and 1
.
Example: [0 0.5 0.5]
Data Types: double
LineDashed
— Signal line style
'-'
| '--'
| ':'
| '-.'
Signal line style used when the signal is plotted in the Simulation Data Inspector, specified as one of these options:
'-'
— Solid'--'
— Dashed':'
— Dotted'-.'
— Dash-dotted
LineWidth
— Signal line width
1
(default) | integer between 1
and
20
Signal line width used when the signal is plotted in the Simulation
Data Inspector, specified as an integer between 1
and
20
, inclusive.
InterpMethod
— Interpolation method
'linear'
(default) | 'zoh'
| 'none'
Interpolation method used in data visualization and the synchronization step of comparisons, specified as one of the following values:
'zoh'
— Zero-order hold interpolation'linear'
— Linear interpolation'none'
— No interpolation
For more information about the interpolation options, see How the Simulation Data Inspector Compares Data.
Comparison Properties
AbsTol
— Absolute tolerance
0
(default) | scalar
Absolute tolerance to use in signal comparisons, specified as a positive-valued scalar.
The Simulation Data Inspector uses tolerances specified in the signal
properties of the baseline signal when the
OverrideGlobalTol
property is set to
1
or true
. For more
information about tolerances in the Simulation Data Inspector, see How the Simulation Data Inspector Compares Data.
The Simulation Data Inspector applies the absolute tolerance only to comparisons of numeric signals and ignores the absolute tolerance for any nonnumeric signal comparisons, such as those that contain enumerated or Boolean data.
Example: 0.1
Data Types: double
RelTol
— Relative tolerance
0
(default) | scalar
Relative tolerance to use in signal comparisons, specified as a
positive-valued scalar. The relative tolerance is expressed as a
fractional multiplier. For example, 0.1
specifies a
10 percent tolerance.
The Simulation Data Inspector uses tolerances specified in the signal
properties of the baseline signal when the
OverrideGlobalTol
property is set to
1
or true
. For more
information about tolerances in the Simulation Data Inspector, see How the Simulation Data Inspector Compares Data.
The Simulation Data Inspector applies the relative tolerance only to comparisons of numeric signals and ignores the relative tolerance for any nonnumeric signal comparisons, such as those that contain enumerated or Boolean data.
Example: 0.05
Data Types: double
TimeTol
— Time tolerance
0
(default) | scalar
Time tolerance for the signal used in signal comparisons, specified as a positive-valued scalar. Specify the time tolerance in seconds.
The Simulation Data Inspector uses tolerances specified in the signal
properties of the baseline signal when the
OverrideGlobalTol
property is set to
1
or true
. For more
information about tolerances in the Simulation Data Inspector, see How the Simulation Data Inspector Compares Data.
Example: 0.1
Data Types: double
OverrideGlobalTol
— Whether comparisons use signal tolerance
0
or
false
(default) | 1
or true
Whether comparisons use signal tolerance values instead of global
tolerance values, specified as a logical value. Set the
OverrideGlobalTol
property to
1
or true
to use the tolerance
values defined in the Signal
object properties. Set the
property to 0
or false
to use
global tolerance values.
For more information about tolerances in the Simulation Data Inspector, see How the Simulation Data Inspector Compares Data.
Data Types: logical
SyncMethod
— Synchronization method
'union'
(default) | 'intersection'
Method used to synchronize signals in comparisons, specified as
'union'
or 'intersection'
. For
more information about the synchronization options, see How the Simulation Data Inspector Compares Data.
Object Functions
convertUnits | Convert units of Simulink.sdi.Signal object |
export | Export data for signal in Simulation Data Inspector to workspace or file |
getAsTall | Create tall timetable from Simulink.sdi.Signal
object |
plotOnSubPlot | Plot Simulink.sdi.Signal object on Simulation Data Inspector
subplot |
Examples
Analyze Simulation Data Using Signal Tolerances
You can programmatically specify signal tolerance values to use in comparisons performed using the Simulation Data Inspector. In this example, you compare data collected by simulating a model of an aircraft longitudinal flight control system. Each simulation uses a different value for the input filter time constant and logs the input and output signals. You analyze the effect of the time constant change by comparing results using the Simulation Data Inspector and signal tolerances.
First, load the session file that contains the simulation data.
Simulink.sdi.load('AircraftExample.mldatx');
The session file contains four runs. In this example, you compare data from the first two runs in the file. Access the Simulink.sdi.Run
objects for the first two runs loaded from the file.
runIDs = Simulink.sdi.getAllRunIDs; runIDTs1 = runIDs(end-3); runIDTs2 = runIDs(end-2);
Compare the two runs without specifying any tolerances.
noTolDiffResult = Simulink.sdi.compareRuns(runIDTs1,runIDTs2);
Use the getResultByIndex
function to access the comparison results for the q
and alpha
signals.
qResult = getResultByIndex(noTolDiffResult,1); alphaResult = getResultByIndex(noTolDiffResult,2);
Check the Status
property of each signal result to see whether the comparison result falls within or out of tolerance.
qResult.Status
ans = ComparisonSignalStatus enumeration OutOfTolerance
alphaResult.Status
ans = ComparisonSignalStatus enumeration OutOfTolerance
The comparison uses a value of 0
for all tolerances, so the OutOfTolerance
result means the signals are not identical.
You can further analyze the effect of the time constant by specifying tolerance values for the signals. Specify the tolerances by setting the properties for the Simulink.sdi.Signal
objects that correspond to the signals being compared. Comparisons use tolerances specified for the baseline signals. This example specifies a time tolerance and an absolute tolerance.
To specify a tolerance, first access the Signal
objects from the baseline run.
runTs1 = Simulink.sdi.getRun(runIDTs1); qSig = getSignalsByName(runTs1,'q, rad/sec'); alphaSig = getSignalsByName(runTs1,'alpha, rad');
For the q
signal, specify an absolute tolerance of 0.1
and a time tolerance of 0.6
using the AbsTol
and TimeTol
properties, respectively.
qSig.AbsTol = 0.1; qSig.TimeTol = 0.6;
For the alpha
signal, specify an absolute tolerance of 0.2
and a time tolerance of 0.8
.
alphaSig.AbsTol = 0.2; alphaSig.TimeTol = 0.8;
Compare the results again. Access the results from the comparison and check the Status
property for each signal.
tolDiffResult = Simulink.sdi.compareRuns(runIDTs1,runIDTs2); qResult2 = getResultByIndex(tolDiffResult,1); alphaResult2 = getResultByIndex(tolDiffResult,2); qResult2.Status
ans = ComparisonSignalStatus enumeration WithinTolerance
alphaResult2.Status
ans = ComparisonSignalStatus enumeration WithinTolerance
Define Comparison and Visualization Properties for a Signal
This example shows how to obtain a Simulink.sdi.Signal
object and modify its properties using the Simulation Data Inspector programmatic interface.
Create Data in the Simulation Data Inspector
When you simulate a model that logs data, a run is created in the Simulation Data Inspector to contain the logged data. You can also create a run in the Simulation Data Inspector by importing data. This example simulates the slexAircraftExample
model and logs the data in Dataset
format.
simOut = sim('slexAircraftExample','SaveFormat','Dataset');
Get a Simulink.sdi.Signal
Object
The programmatic simulation returns the logged data in the workspace variable simOut
. You can access the logged data in that variable. However, to use the Simulation Data Inspector programmatic interface, you need to access the logged data in Simulink.sdi.Run
and Simulink.sdi.Signal
objects.
First, use the Simulink.sdi.getCurrentSimulationRun
to get the Run
object that was created when you simulated the slexAircraftExample
model.
aircraftRun = Simulink.sdi.getCurrentSimulationRun('slexAircraftExample');
You can use the getAllSignals
function to access the Signal
objects for all the signals in the run. From the returned array of Signal
objects, select the first signal.
signals = getAllSignals(aircraftRun); sig = signals(1);
Modify the Signal Properties
The Simulink.sdi.Signal
object has properties that specify options for comparing and visualizing the signal. Specify a line style and color for the signal. Then, use the Simulink.sdi.setSubPlotLayout
to configure the Simulation Data Inspector to show a single subplot, and use the plotOnSubPlot
function to plot the signal.
sig.LineColor = [1 0.4 0.6];
sig.LineDashed = '-';
Simulink.sdi.setSubPlotLayout(1,1)
plotOnSubPlot(sig,1,1,true)
Use the Simulink.sdi.view
function to open the Simulation Data Inspector and view the plotted signal.
Compare Two Signals in the Same Run
You can use the Simulation Data Inspector programmatic interface to compare signals within a single run. This example compares the input and output signals of an aircraft longitudinal flight controller.
Load the Simulation Data Inspector session file that contains the flight control data.
Simulink.sdi.load("AircraftExample.mldatx");
To access the latest run, use the Simulink.sdi.Run.getLatest
function.
aircraftRun = Simulink.sdi.Run.getLatest;
Use the Simulink.sdi.getSignalsByName
function to access the Stick
signal, which represents the input to the controller, and the alpha, rad
signal, which represents the output.
stick = getSignalsByName(aircraftRun,"Stick"); alpha = getSignalsByName(aircraftRun,"alpha, rad");
Use the signal IDs to compare the Stick
and alpha, rad
signals using the Simulink.sdi.compareSignals
function. The Stick
signal is the baseline. The alpha, rad
signal is the signal to compare against the baseline.
comparisonResults = Simulink.sdi.compareSignals(stick.ID,alpha.ID); match = comparisonResults.Status
match = ComparisonSignalStatus enumeration OutOfTolerance
The comparison result is out of tolerance. You can use the Simulink.sdi.view
function to open the Simulation Data Inspector to view and analyze the comparison results.
Simulink.sdi.view
You can specify time and magnitude tolerance values to use for the comparison. Comparisons use tolerance values specified for the baseline signal in the comparison. To account for the phase shift, set a time tolerance of 1
on the Stick
signal. To account for magnitude differences, set an absolute tolerance value of 0.1
on the Stick
signal.
stick.TimeTol = 1; stick.AbsTol = 0.1;
Compare the signals again. This time, because of the absolute and time tolerances, the signal comparison passes.
comparisonResults = Simulink.sdi.compareSignals(stick.ID,alpha.ID); match = comparisonResults.Status
match = ComparisonSignalStatus enumeration WithinTolerance
Plot Signals from Simulation Run
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 contain the logged signal data and metadata. You can use the Signal
objects and the plotOnSubPlot
function to plot the data in the Simulation Data Inspector.
Create a Simulation Run and Access the Run
Object
The vdp
model logs two signals. To create a simulation run containing the logged data, simulate the model.
mdl = "vdp";
sim(mdl);
The Simulation Data Inspector keeps track of runs by assigning a unique numeric run ID to each run created by simulation, importing data, or opening a session. To access the run object for the simulation you 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, you can use the Simulink.sdi.getRun
function to get the Simulink.sdi.Run
object that corresponds to the run. You can use the Run
object to check the 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 from the Run
object, vdpRun
.
signal1 = getSignalByIndex(vdpRun,1); signal2 = getSignalByIndex(vdpRun,2);
Use the Simulink.sdi.setSubPlotLayout
function to specify a 2-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.
Version History
Introduced in R2012b
MATLAB 명령
다음 MATLAB 명령에 해당하는 링크를 클릭했습니다.
명령을 실행하려면 MATLAB 명령 창에 입력하십시오. 웹 브라우저는 MATLAB 명령을 지원하지 않습니다.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)