Main Content

matlab.io.datastore.sdidatastore

Datastore for Simulation Data Inspector signals

expand all in page

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. The read function loads the signal data referenced by an sdidatastore 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 a matlab.io.datastore.sdidatastore object.

Creation

Syntax

sigObj = getAsDatastore(dsrObj,arg)
ds = matlab.io.datastore.sdidatastore(signalID)

Description

sigObj = getAsDatastore(dsrObj,arg) 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.

example

ds = matlab.io.datastore.sdidatastore(signalID) creates the sdidatastore object ds for the signal corresponding to the specified signalID.

example

Input Arguments

expand all

Search criterion used to retrieve the signal in the Simulation Data Inspector run referenced by the Simulink.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

Numeric signal identifier, specified as a positive integer. The Simulation Data Inspector assigns a signal ID to each signal when a run is created. You can get the signal ID for a signal using one of these functions:

Properties

expand all

Signal name specified as a character vector.

Example: 'My Signal'

Referenced signal object associated with the sdidatastore object, specified as a Simulink.sdi.Signal object. The Signal property provides access to the Signal object data and metadata.

Object Functions

hasdata Determine whether data is available to read
resetReset datastore to initial position
readallRead all data in datastore
readRead chunk of data in datastore
preview Return subset of data from datastore

Examples

collapse all

Open Live Script

To create a run of logged signals, simulate the model sldemo_fuelsys.

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 = 16x1 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: [1x1 Simulink.SimulationData.BlockPath]
          PortType: 'outport'
         PortIndex: 1
            Values: [1x1 matlab.io.datastore.sdidatastore]


name = 
'fuel'

idx = 
7
Open Live Script

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')
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.

egoDs.Name
ans = 
'fuel'

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 =

  Mx1 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 =

  Mx1 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

    ?

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 sec
Evaluation completed in 1.2 sec

egoMean = 
1.3729

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.

Open Live Script

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
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.

speedSDIds.Name
ans = 
'speed'

You can also use the preview function to verify the first ten samples in the signal.

preview(speedSDIds)
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
latestMax = 
314.1593

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.

reset(speedSDIds)

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)
speedMax = 
314.1593

Version History

Introduced in R2017b

See Also

| | |

Topics