matlab.io.datastore.sdidatastore - Datastore for Simulation Data Inspector signals - MATLAB (original) (raw)
Datastore for Simulation Data Inspector signals
Description
A matlab.io.datastore.sdidatastore
object provides access to signals logged to the Simulation Data Inspector that are too large to fit into memory. An sdidatastore
object references the data for a single signal. Theread
function loads the signal data referenced by ansdidatastore
object in a chunk-wise manner such that each chunk always fits into memory. You can use an sdidatastore
object to create a tall timetable for your signal data. For more information about working with tall arrays, see Tall Arrays.
Note
matlab.io.datastore.sdidatastore
objects do not support parallel computations. If you have a Parallel Computing Toolbox™ license, use mapreducer(0)
to set the execution environment to the local MATLAB® client before creating a tall timetable from amatlab.io.datastore.sdidatastore
object.
Creation
Syntax
Description
`sigObj` = getAsDatastore(`dsrObj`,[arg](#d126e690392))
creates an sdidatastore
object in the Values
property of the returned Simulink.SimulationData.Signal object sigObj
for the signal specified by the search criterion arg
in the Simulation Data Inspector run referenced by the Simulink.sdi.DatasetRef object dsrObj
. Use the search criterion arg
to specify a signal by index or by name.
`ds` = matlab.io.datastore.sdidatastore([signalID](#d126e690433))
creates the sdidatastore
object ds
for the signal corresponding to the specified signalID
.
Input Arguments
Search criterion used to retrieve the signal in the Simulation Data Inspector run referenced by theSimulink.sdi.DatasetRef
object, specified as one of these values:
- Positive integer — For index-based searches, specify
arg
as a positive integer representing the index of the desired signal. - String or character vector — For name-based searches, specify
arg
as a string or character vector containing the name of the desired signal.
Example: "MySignal"
Example: 3
Properties
Signal name specified as a character vector.
Example: 'My Signal'
Referenced signal object associated with thesdidatastore
object, specified as a Simulink.sdi.Signal object. The Signal
property provides access to theSignal
object data and metadata.
Object Functions
hasdata | Determine whether data is available to read |
---|---|
reset | Reset datastore to initial position |
readall | Read all data in datastore |
read | Read chunk of data in datastore |
preview | Return subset of data from datastore |
Examples
To create a run of logged signals, simulate the model sldemo_fuelsys
.
open_system('sldemo_fuelsys') Simulink.sdi.clear; sim("sldemo_fuelsys")
Use the Simulink.sdi.Run.getLatest
function to get the latest run.
fuelRun = Simulink.sdi.Run.getLatest;
Create a Simulink.sdi.DatasetRef
object that references fuelRun
.
DSRef_fuelRun = getDatasetRef(fuelRun);
Get the names of the elements in the DatasetRef
object.
DSRnames = getElementNames(DSRef_fuelRun)
DSRnames = 16×1 cell {'CheckRange' } {'air_fuel_ratio' } {'speed' } {'map' } {'ego' } {'throttle' } {'fuel' } {'EGO Fault Switch:1' } {'Engine Speed Fault Switch:1' } {'MAP Fault Switch:1' } {'Throttle Angle Fault Switch:1'} {'ego_sw' } {'engine_speed' } {'speed_sw' } {'map_sw' } {'throttle_sw' }
Get an sdidatastore
object for the fuel
signal. The sdidatastore
object exists in the Values
property of the returned Simulink.SimulationData.Signal
object.
[fuel_ds,name,idx] = getAsDatastore(DSRef_fuelRun,"fuel")
fuel_ds = Simulink.SimulationData.Signal Package: Simulink.SimulationData
Properties: Name: 'fuel' PropagatedName: '' BlockPath: [1×1 Simulink.SimulationData.BlockPath] PortType: 'outport' PortIndex: 1 Values: [1×1 matlab.io.datastore.sdidatastore]
Methods, Superclasses
Create a tall timetable for a signal in the Simulation Data Inspector repository. You can create a tall timetable for a signal in the Simulation Data Inspector repository using a Simulink.sdi.Signal object or by first creating a matlab.io.datastore.sdidatastore
object for the signal. You can use a matlab.io.datastore.sdidatastore
object to incrementally read and process signal data for signals that do not fit into memory. A tall timetable handles the data chunking and processing in the background. In general, you can work with tall timetables very similarly to how you work with in-memory data.
Create Data and Access Signal ID
Whether you create a tall timetable using a Simulink.sdi.Signal
object or a matlab.io.datastore.sdidatastore
, start by creating data and accessing the signal ID for a signal of interest. The sldemo_fuelsys
model is configured to log signals which stream to the Simulation Data Inspector repository when you simulate the model.
open_system('sldemo_fuelsys') Simulink.sdi.clear sim('sldemo_fuelsys')
Use the Simulation Data Inspector programmatic interface to access a signal ID. For example, access the ego
signal.
runCount = Simulink.sdi.getRunCount; latestRunID = Simulink.sdi.getRunIDByIndex(runCount); latestRun = Simulink.sdi.getRun(latestRunID);
egoSigID = latestRun.getSignalIDByIndex(7);
Create Tall Timetable Using matlab.io.datastore.sdidatastore
Object
In general, tall timetables are backed by datastores. Create a matlab.io.datastore.sdidatastore
object to reference the signal data in the Simulation Data Inspector repository.
egoDs = matlab.io.datastore.sdidatastore(egoSigID);
Check the name of the datastore to verify you have the signal you expect.
Create a tall timetable from the matlab.io.datastore.sdidatastore
object to use for processing the signal data. When you have a Parallel Computing Toolbox™ license, you need to explicitly set the execution environment to the local MATLAB® session using mapreducer
before creating the tall timetable. The matlab.io.datastore.sdidatastore
object does not support parallel computations.
mapreducer(0);
egoTt = tall(egoDs)
egoTt =
M×1 tall timetable
Time Data
______________ ______
0 sec 1.2855
0.00056195 sec 1.2855
0.0033717 sec 1.2855
0.01 sec 1.2398
0.02 sec 1.199
0.03 sec 1.1628
0.04 sec 1.1309
0.043098 sec 1.1309
: :
: :
Create Tall Timetable Using Simulink.sdi.Signal
Object
The Simulink.sdi.Signal
object has a function to create a tall timetable directly, allowing you to skip the step of creating a datastore by creating it behind the scenes. Use the signal ID to access the Simulink.sdi.Signal
object for the ego
signal. Then, use the getTable
function to create the tall timetable.
egoSig = Simulink.sdi.getSignal(egoSigID);
egoTt = egoSig.getAsTall
egoTt =
M×1 tall timetable
Time Data
______________ ______
0 sec 1.2855
0.00056195 sec 1.2855
0.0033717 sec 1.2855
0.01 sec 1.2398
0.02 sec 1.199
0.03 sec 1.1628
0.04 sec 1.1309
0.043098 sec 1.1309
: :
: :
Use Tall Timetable to Process Signal Data
When you use the tall timetable egoTt
, its underlying datastore reads chunks of data and passes them to the tall timetable to process. Neither the datastore nor the tall timetable retain any of the data in memory after processing. Also, the tall timetable defers processing for many operations. For example, calculate the mean value of the signal.
egoMean = mean(egoTt.Data)
egoMean =
tall double
?
Preview deferred. Learn more.
You can use the gather
function to evaluate a variable and write its value to the workspace, or you can use the write
function to write the results to disc. When you use gather
, be sure the results fit into memory.
egoMean = gather(egoMean)
Evaluating tall expression using the Local MATLAB Session:
- Pass 1 of 1: Completed in 1.2 sec Evaluation completed in 1.4 sec
When you perform multiple operations on a tall timetable, evaluation of the results for each step is deferred until you explicitly request the results with write
or gather
. During evaluation, MATLAB optimizes the number of passes it makes through the tall timetable, which can significantly speed up processing time for analyzing very large signals. For more information about working with tall arrays, see Tall Arrays for Out-of-Memory Data.
A matlab.io.datastore.sdidatastore
object references signal data in the Simulation Data Inspector repository. When the signal is too large to fit into memory, you can use the sdidatastore
object to incrementally process the data manually or to create a tall timetable for the signal that handles the incremental processing for you.
Create sdidatastore
for Signal
Simulate the sldemo_fuelsys
model, which is configured to log several signals, to create data in the Simulation Data Inspector repository.
mdl = "sldemo_fuelsys"; sim(mdl);
Logged signal data is returned in a Simulink.SimulationData.Dataset
object named sldemo_fuelsys_output
.
sldemo_fuelsys_output = Simulink.SimulationData.Dataset 'sldemo_fuelsys_output' with 10 elements
Name BlockPath
______________ ________________________________________
1 [1x1 Signal] '' sldemo_fuelsys/EGO Fault Switch
2 [1x1 Signal] air_fuel_ratio sldemo_fuelsys/Engine Gas Dynamics
3 [1x1 Signal] '' sldemo_fuelsys/Engine Speed Fault Switch
4 [1x1 Signal] speed sldemo_fuelsys/Engine_Speed_Selector
5 [1x1 Signal] '' sldemo_fuelsys/MAP Fault Switch
6 [1x1 Signal] map sldemo_fuelsys/MAP_Selector
7 [1x1 Signal] ego sldemo_fuelsys/O2_Voltage_Selector
8 [1x1 Signal] '' ...o_fuelsys/Throttle Angle Fault Switch
9 [1x1 Signal] throttle sldemo_fuelsys/Throttle_Angle_Selector
10 [1x1 Signal] fuel sldemo_fuelsys/To Plant
- Use braces { } to access, modify, or add elements using index.
Use the Simulation Data Inspector programmatic interface to get the signal ID for the signal named speed
.
runCount = Simulink.sdi.getRunCount; latestRunID = Simulink.sdi.getRunIDByIndex(runCount); latestRun = Simulink.sdi.getRun(latestRunID); speedSigID = getSignalIDsByName(latestRun,"speed");
Use the signal ID to create an sdidatastore
object for the speed
signal.
speedSDIds = matlab.io.datastore.sdidatastore(speedSigID);
Verify Contents of Datastore
Check the Name
property of the sdidatastore
object to verify that it matches your expectations.
You can also use the preview
function to verify the first ten samples in the signal.
ans=10×1 timetable Time Data ______________ ______
0 sec 314.16
0.00056195 sec 314.16
0.0033717 sec 314.16
0.01 sec 314.16
0.02 sec 314.16
0.03 sec 314.16
0.04 sec 314.16
0.043098 sec 314.16
0.043098 sec 314.16
0.043098 sec 314.16
Process Signal Data with sdidatastore
Object
When your signal is too large to fit into memory, you can use the read
function to read chunks of data from the Simulation Data Inspector repository to incrementally process your data. Use the hasdata
function as the condition for a while loop to incrementally process the whole signal. For example, find the maximum signal value.
latestMax = [];
while hasdata(speedSDIds) speedChunk = read(speedSDIds); speedChunkData = speedChunk.Data; latestMax = max([speedChunkData; latestMax]); end
latestMax
On each read operation, the read
function updates the read position for the start of the next read operation. After reading some or all of the sdidatastore
object, you can reset the read position to start again from the beginning of the signal.
Process Signal Data in Memory
When the signal referenced by your sdidatastore
object fits into memory, you can use the readall
function to read all the signal data into memory for processing rather than reading and processing the data incrementally with the read
function. The readall
function returns a timetable
with all the signal data.
speedTimetable = readall(speedSDIds); speedMax = max(speedTimetable.Data)
Version History
Introduced in R2017b