Main Content

workspaceEnsemble

Manage ensemble data stored in the MATLAB workspace using code generated by Diagnostic Feature Designer

Since R2020a

expand all in page

Description

A workspaceEnsemble object is an ensemble object specialized for use in code generated by Diagnostic Feature Designer. The workspaceEnsemble object is similar to a fileEnsembleDatastore object, as both specify the data variables, independent variables, and condition variables in the ensemble. Unlike a file ensemble datastore, however, a workspace ensemble operates on data in memory rather than in external files.

When you import a table or a cell array into the app and generate code after you have completed your interactive feature design, that code includes the creation of a workspace ensemble. This ensemble contains variables that are identical to those in your initial import, and can manage any input data sets that include the same variables. For example, suppose that you import a 20-member table into the app, extract a feature, and generate a function. The workspace ensemble in that function is compatible with a 2000-member table, as long as the table includes the same variables.

For more information about data ensembles, see Data Ensembles for Condition Monitoring and Predictive Maintenance.

Creation

Syntax

wsensemble = workspaceEnsemble(Name,Value)
wsensemble = workspaceEnsemble(data,Name,Value)

Description

wsensemble = workspaceEnsemble(Name,Value) creates an empty workspaceEnsemble object wsensemble with properties specified by name-value pair arguments.

wsensemble = workspaceEnsemble(data,Name,Value) creates a workspaceEnsemble object wsensemble from the data set data.

example

Input Arguments

expand all

Input data set, specified as a table or a cell array of tables.

  • If data is a table, each row represents the data of one ensemble member.

  • If data is a cell array of tables, each table in the cell represents the data of one ensemble member.

Properties

expand all

Data variables in the ensemble, specified as a string or cell array. Data variables are the main content of the members of an ensemble. Data variables can include measured data or derived data. For example, your data variables might include measured vibration or simulated vibration signals and derived values such mean vibration value or peak vibration frequency.

Example: outputEnsemble = workspaceEnsemble(inputData,'DataVariables',["Vibration";"Tacho"])

Independent variables in the ensemble, specified as a string or cell array. Typically, independent variables order the members of an ensemble. Examples are timestamps or the number of operating cycles.

Example: outputEnsemble = workspaceEnsemble(inputData,'IndependentVariables',"Time")

Condition variables in the ensemble, specified as a string or cell array. Condition variables label the members in an ensemble according to the fault condition or other operating condition under which the ensemble member was collected.

Example: outputEnsemble = workspaceEnsemble(inputData,'ConditionVariables',"faultCode")

Variables to read from the ensemble, specified as a string or cell array. SelectedVariables identifies which variables in data to read and operate on.

Example: outputEnsemble.SelectedVariables = ["Vibration","Tacho"]

Number of members to read from the workspace ensemble at once when you use the read command, specified as a positive integer that is smaller than the total number of members in the ensemble. By default, the read command returns a one-row table containing data from one ensemble member. To read data from multiple members in a single read operation, set this property to an integer value greater than one. For example, if ReadSize is 3, then read returns a three-row table where each row contains data from a different ensemble member. If fewer than ReadSize members are unread, then read returns a table with as many rows as there are remaining members.

Changing the ReadSize property also resets the ensemble to its unread state. For instance, suppose that you set ReadSize to 1 to read some ensemble members one at a time, and then change ReadSize to 3. The next read operation returns data from the first three ensemble members.

Object Functions

refreshUpdate a workspace ensemble with partitions of modified or added data computed in parallel processing
writeMemberWrite data to a specific workspace ensemble member
readMemberReturn ensemble member data based on the member index
findIndexFind the workspace ensemble member indices for members that match a specified variable name and value

Examples

collapse all

Open Live Script

Create a workspaceEnsemble object from an ensemble table and read its contents.

Load the ensemble table dataTable and view the first three members.

load dfd_Tutorial dataTable
head(dataTable,3)
        Vibration               Tacho           faultCode
    __________________    __________________    _________

    {6000x1 timetable}    {6000x1 timetable}        0    
    {6000x1 timetable}    {6000x1 timetable}        1    
    {6000x1 timetable}    {6000x1 timetable}        1

The table contains 16 members, each of which contain timetables with vibration and tacho data along with a scalar fault code.

Create a Workspace Ensemble

Create a workspace ensemble wensemble from dataTable.

wensemble = workspaceEnsemble(dataTable,'DataVariables',["Vibration";"Tacho"],...
           'ConditionVariables',"faultCode")
wensemble = 
  workspaceEnsemble with properties:

           DataVariables: [2x1 string]
    IndependentVariables: [0x0 string]
      ConditionVariables: "faultCode"
       SelectedVariables: [3x1 string]
                ReadSize: 1
              NumMembers: 16
          LastMemberRead: [0x0 string]

Confirm the data condition variable selections.

dv = wensemble.DataVariables
dv = 2x1 string
    "Vibration"
    "Tacho"


cv = wensemble.ConditionVariables
cv = 
"faultCode"

Read Workspace Ensemble Members

Inspect the data variables in the workspace ensemble for the first two members.

By default, reading the ensemble returns all ensemble variables. To select a subset of variables to read, specify SelectedVariables.

wensemble.SelectedVariables = ["Vibration","Tacho"];

Use read to get the contents of the next unread member. Each time you read a member, the software marks that member as read, and the next read command returns the following member. You can use a succession of read commands to loop through an ensemble. To start at the first member, use reset.

reset(wensemble)
m1 = read(wensemble)
m1=1×2 table
        Vibration               Tacho       
    __________________    __________________

    {6000x1 timetable}    {6000x1 timetable}


m2 = read(wensemble);

m1 and m2 are both tables containing vibration and tacho data. m1 contains the data for the first member. m2 contains the data for the second member.

Examine the vibration samples for both members. Extract the vibration signals from m1 and m2 and display the first three samples of each signal.

m1vib = readMemberData(m1,'Vibration');
m2vib = readMemberData(m2,'Vibration');
head(m1vib,3)
      Time         Data  
    _________    ________

    0 sec        -0.66925
    0.005 sec    -0.61623
    0.01 sec     -0.56666

head(m2vib,3)
      Time        Data  
    _________    _______

    0 sec        -1.6231
    0.005 sec    -1.5892
    0.01 sec     -1.5534

Each read command returns a unique result.

Open Live Script

This example illustrates some of the basic commands used in code that Diagnostic Feature Designer generates. The example shows how to use these commands to create a workspace ensemble from a table, perform member-by-member computations for a new feature, and create a feature table and an ensemble table from the workspace ensemble.

Interacting with a workspace ensemble is similar to interacting with a file ensemble datastore or a simulation ensemble datastore. Many of the commands are the same. Unlike the ensemble datastores, which allow interaction with external files, the workspace ensemble datastore enables interaction with data in memory.

Create a Workspace Ensemble from a Table

Load the ensemble table dataTable, which contains 16 members, each of which contain timetables with vibration and tacho data along with a scalar fault code.

load dfd_Tutorial dataTable

Create a workspace ensemble wensemble from dataTable, specifying the data variables and condition variables corresponding to the variables in dataTable.

wensemble = workspaceEnsemble(dataTable,'DataVariables',["Vibration";"Tacho"],...
           'ConditionVariables',"faultCode")
wensemble = 
  workspaceEnsemble with properties:

           DataVariables: [2x1 string]
    IndependentVariables: [0x0 string]
      ConditionVariables: "faultCode"
       SelectedVariables: [3x1 string]
                ReadSize: 1
              NumMembers: 16
          LastMemberRead: [0x0 string]

Processing the data and extracting features requires only Vibration and Tacho. Specify SelectedVariables to contain Vibration and Tacho.

wensemble.SelectedVariables = ["Vibration","Tacho"];

Compute Mean of Vibration Signal for First Ensemble Member

The mean of the vibration signal represents a scalar feature for each member. Compute this feature for the first member, using an approach that scales to a loop that processes multiple members.

Reset the ensemble and read the first member.

reset(wensemble)
m = read(wensemble)
m=1×2 table
        Vibration               Tacho       
    __________________    __________________

    {6000x1 timetable}    {6000x1 timetable}

Extract the vibration data from the member table m.

mvibd = readMemberData(m,'Vibration');

Compute the mean value of the vibration.

m_mean = mean(mvibd.Data)
m_mean = 
0.0218

Append the results to m.

m = [m,table(m_mean,'VariableNames',"Data_Mean")]
m=1×3 table
        Vibration               Tacho           Data_Mean
    __________________    __________________    _________

    {6000x1 timetable}    {6000x1 timetable}    0.021809

Add New Feature to Ensemble Variables

To incorporate the updated member into wensemble, you must first specify the new Data_Mean feature as an ensemble variable. Add Data_Mean to the set of ensemble data variables dv using dot notation.

dv = wensemble.DataVariables;
wensemble.DataVariables = [dv;"Data_Mean"];

Append Updated Member Table to Workspace Ensemble

Append the updated member table to the ensemble using the writeToLastMemberRead command. 

writeToLastMemberRead(wensemble,m)

Loop Through Remaining Ensemble Members

Perform the same member-specific steps for the remaining ensemble members.

while hasdata(wensemble)
    m = read(wensemble);
    mvibd = readMemberData(m,'Vibration');
    m_mean = mean(mvibd.Data);
    m = [m,table(m_mean,'VariableNames',"Data_Mean")];
    writeToLastMemberRead(wensemble,m)
end

Create Feature Table and Ensemble Table from Workspace Ensemble

Extract the feature table from wensemble with the readFeatureTable command. View the first three rows.

ft = readFeatureTable(wensemble);
head(ft,3)
    faultCode    Data_Mean 
    _________    __________

        0          0.021809
        1        -0.0092964
        1          -0.46431

The feature table contains the condition variable FaultCode and the data variable Data_Mean.

Set the SelectedVariables property to include all variables so that the resulting ensemble table contains all your information.

wensemble.SelectedVariables = ["Vibration";"Tacho";"Data_Mean";"faultCode"]
wensemble = 
  workspaceEnsemble with properties:

           DataVariables: [3x1 string]
    IndependentVariables: [0x1 string]
      ConditionVariables: "faultCode"
       SelectedVariables: [4x1 string]
                ReadSize: 1
              NumMembers: 16
          LastMemberRead: [0x0 string]

Use the datastore command readall to convert the workspace ensemble into an ensemble table. 

tensemble = readall(wensemble)
tensemble=16×4 table
        Vibration               Tacho           Data_Mean     faultCode
    __________________    __________________    __________    _________

    {6000x1 timetable}    {6000x1 timetable}      0.021809        0    
    {6000x1 timetable}    {6000x1 timetable}    -0.0092964        1    
    {6000x1 timetable}    {6000x1 timetable}      -0.46431        1    
    {6000x1 timetable}    {6000x1 timetable}        0.4922        1    
    {6000x1 timetable}    {6000x1 timetable}        0.3923        1    
    {6000x1 timetable}    {6000x1 timetable}      -0.12383        1    
    {6000x1 timetable}    {6000x1 timetable}       0.42548        1    
    {6000x1 timetable}    {6000x1 timetable}       -0.4598        1    
    {6000x1 timetable}    {6000x1 timetable}      0.062685        0    
    {6000x1 timetable}    {6000x1 timetable}      0.059155        0    
    {6000x1 timetable}    {6000x1 timetable}      0.037965        0    
    {6000x1 timetable}    {6000x1 timetable}       0.53982        1    
    {6000x1 timetable}    {6000x1 timetable}       0.52377        1    
    {6000x1 timetable}    {6000x1 timetable}        1.0357        1    
    {6000x1 timetable}    {6000x1 timetable}        1.0592        1    
    {6000x1 timetable}    {6000x1 timetable}      -0.94084        1

The table includes the original signals and the new feature.

Version History

Introduced in R2020a

See Also

Apps

Functions

Objects

Topics