Main Content

matlab.io.datastore.sdidatastore class

Package: matlab.io.datastore

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 method 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 does 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 the matlab.io.datastore.sdidatastore.

Construction

ds = dsrObj.getAsDatastore(arg) creates the sdidatastore, ds, for the signal in the Simulink.sdi.DatasetRef object selected by the search criterion arg. You can specify arg as an integer representing the index of the desired signal within the Simulink.sdi.DatasetRef object, or as a character vector containing the name of the signal.

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

Input Arguments

expand all

Search criterion used to retrieve the element from the Simulink.sdi.DatasetRef object. For name-based searches, specify arg as a character vector. For index-based searches, arg is an integer, representing the index of the desired element.

Example: 'MySignal'

Example: 3

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

Properties

expand all

Name of the signal specified as a character vector.

Example: 'My Signal'

Simulink.sdi.Signal object associated with the sdidatastore. The Signal property provides access to the signal data and metadata.

Methods

hasdata Determine if data is available to read
preview Return preview of data in sdidatstore
read Read a chunk of data from an sdidatastore
readall Read all data from an sdidatastore
reset Reset the read position

Copy Semantics

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

Examples

collapse all

Open Live Script

This example shows how to create a tall timetable for a signal in the Simulation Data Inspector repository. You can create the tall timetable using a Simulink.sdi.Signal object or by first creating a matlab.io.datastore.sdidatastore for the signal. You can use a matlab.io.datastore.sdidatastore 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 your 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')

Then, use the Simulation Data Inspector programmatic interface to access the signal ID for a signal of interest. 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 a Tall Timetable Using a matlab.io.datastore.sdidatastore

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 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.209
    0.00056199 sec     1.209
    0.0033719 sec      1.209
    0.01 sec          1.1729
    0.02 sec          1.1409
    0.03 sec          1.1124
    0.04 sec          1.0873
    0.05 sec          1.0652
          :             :
          :             :

Create a Tall Timetable Using a Simulink.sdi.Signal Object

The Simulink.sdi.Signal class has a method 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 method to create the tall timetable.

egoSig = Simulink.sdi.getSignal(egoSigID);

egoTt = egoSig.getAsTall
egoTt =

  Mx1 tall timetable

         Time          Data 
    ______________    ______

    0 sec              1.209
    0.00056199 sec     1.209
    0.0033719 sec      1.209
    0.01 sec          1.1729
    0.02 sec          1.1409
    0.03 sec          1.1124
    0.04 sec          1.0873
    0.05 sec          1.0652
          :             :
          :             :

Use the Tall Timetable to Process Your 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 0.99 sec
Evaluation completed in 1.1 sec

egoMean = 1.3292

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 references signal data in the Simulation Data Inspector repository. When the signal is too large to fit into memory, you can use the matlab.io.datastore.sdidatastore to incrementally process the data manually or to create a tall timetable for the signal that handles the incremental processing for you. This example shows how to process data using a matlab.io.datastore.sdidatastore.

Create a matlab.io.datastore.sdidatastore for a Signal

Simulate the sldemo_fuelsys model, which is configured to log several signals, to create data in the Simulation Data Inspector repository.

sim('sldemo_fuelsys')

Use the Simulation Data Inspector programmatic interface to get the signal ID for the signal.

runCount = Simulink.sdi.getRunCount;

latestRunID = Simulink.sdi.getRunIDByIndex(runCount);

latestRun = Simulink.sdi.getRun(latestRunID);

speedSigID = latestRun.getSignalIDByIndex(4);

Use the signal ID to create a matlab.io.datastore.sdidatastore for the speed signal.

speedSDIds = matlab.io.datastore.sdidatastore(speedSigID);

Verify the Contents of the Datastore

Check the Name property of the matlab.io.datastore.sdidatastore to verify that it matches your expectations.

speedSDIds.Name
ans = 
'map'

You can also use the preview method to check that the first ten samples in the signal look correct.

speedSDIds.preview
ans=10×1 timetable
         Time          Data  
    ______________    _______

    0 sec               0.589
    0.00056199 sec    0.58772
    0.0033719 sec     0.58148
    0.01 sec          0.56765
    0.02 sec          0.54897
    0.03 sec          0.53264
    0.04 sec          0.51837
    0.05 sec          0.50594
    0.055328 sec          0.5
    0.055328 sec          0.5

Process Signal Data with the matlab.io.datastore.sdidatastore

When your signal is too large to fit into memory, you can use the readData method to read chunks of data from the Simulation Data Inspector repository to incrementally process your data. Use the hasdata method as the condition for a while loop to incrementally process the whole signal. For example, find the maximum signal value.

latestMax = [];

while speedSDIds.hasdata
    
    speedChunk = speedSDIds.read;
    speedChunkData = speedChunk.Data;
    latestMax = max([speedChunkData; latestMax]);
    
end

latestMax
latestMax = 0.8897

On each read operation, the read method updates the read position for the start of the next read operation. After reading some or all of the matlab.io.datastore.sdidatastore, you can reset the read position to start again from the beginning of the signal.

speedSDIds.reset

Process Signal Data in Memory

When the signal referenced by your matlab.io.datastore.sdidatastore fits into memory, you can use the readall method to read all the signal data into memory for processing, rather than reading and processing the data incrementally with the read method. The readall method returns a timetable with all the signal data.

speedTimetable = speedSDIds.readall;

speedMax = max(speedTimetable.Data)
speedMax = 0.8897

Version History

Introduced in R2017b

See Also

| | |

Topics