find

Get element or collection of elements from Simulink.SimulationData.Dataset object

Syntax

[dsOut,idx]=find(dsIn,prop,val,...)

[dsOut,idx]=find(dsIn,prop,val,logical,...prop,val,...)

[dsOut,idx]=find(dsIn,'-regexp',prop,val,...)

Description

[dsOut,idx]=find(dsIn,prop,val,...) returns a Simulink.SimulationData.Dataset object containing the elements in the Dataset object dsIn that match one or more property type and value pairs specified by prop and val. The function also returns the indices of those elements in the Dataset object dsIn.

[dsOut,idx]=find(dsIn,prop,val,logical,...prop,val,...) applies the logical operator logical to connect multiple property and value pairs. You can combine multiple logical operators.

[dsOut,idx]=find(dsIn,'-regexp',prop,val,...) matches elements using regular expressions as if the value of the property is passed to the regexp function as

regexp(element.prop,val)

The find function applies regular expression matching to the prop and val arguments that appear after -regexp. If the find function contains no -regexp argument, then the function matches elements as if the value of the property is passed as

isequal(element.prop,val)

Examples

Find Elements in Dataset Object

Use the find function to access an element or collection of elements in a Simulink.SimulationData.Dataset object. The model sldemo_clutch, which models a rotating clutch system, logs ten signals in Dataset format. For more information about the model, see Building a Clutch Lock-Up Model.

Simulate the model.

sim("sldemo_clutch");

The logged signal data is contained in a Dataset object named sldemo_clutch_output.

ds = sldemo_clutch_output

ds = 
Simulink.SimulationData.Dataset 'sldemo_clutch_output' with 10 elements

                         Name          BlockPath                         
                         ____________  _________________________________ 
    1  [1x1 Signal]      Fn            sldemo_clutch/Clutch Pedal       
    2  [1x1 Signal]      Tin           sldemo_clutch/Engine Torque      
    3  [1x1 Signal]      LockedFlag    sldemo_clutch/Friction Mode Logic
    4  [1x1 Signal]      LockupFlag    sldemo_clutch/Friction Mode Logic
    5  [1x1 Signal]      UnlockFlag    sldemo_clutch/Friction Mode Logic
    6  [1x1 Signal]      Tfmaxk        sldemo_clutch/Friction Model     
    7  [1x1 Signal]      Tfmaxs        sldemo_clutch/Friction Model     
    8  [1x1 Signal]      ShaftSpeed    sldemo_clutch/Locked             
    9  [1x1 Signal]      EngineSpeed   sldemo_clutch/Unlocked           
   10  [1x1 Signal]      VehicleSpeed  sldemo_clutch/Unlocked           

  - Use braces { } to access, modify, or add elements using index.

Use the find function to return a Dataset object containing the element named EngineSpeed.

engSpeed = find(ds,"Name","EngineSpeed")

engSpeed = 
Simulink.SimulationData.Dataset 'sldemo_clutch_output' with 1 element

                         Name         BlockPath              
                         ___________  ______________________ 
    1  [1x1 Signal]      EngineSpeed  sldemo_clutch/Unlocked

  - Use braces { } to access, modify, or add elements using index.

You can also use the find function to return a Dataset object that contains a collection of elements. For example, use the find function to return all the elements in ds that are logged output signals from the Friction Mode Logic block and get the corresponding indices in the Dataset object ds for these elements.

[dsFml,idx] = find(ds,"BlockPath","sldemo_clutch/Friction Mode Logic")

dsFml = 
Simulink.SimulationData.Dataset 'sldemo_clutch_output' with 3 elements

                         Name        BlockPath                         
                         __________  _________________________________ 
    1  [1x1 Signal]      LockedFlag  sldemo_clutch/Friction Mode Logic
    2  [1x1 Signal]      LockupFlag  sldemo_clutch/Friction Mode Logic
    3  [1x1 Signal]      UnlockFlag  sldemo_clutch/Friction Mode Logic

  - Use braces { } to access, modify, or add elements using index.

idx = 1×3

     3     4     5

Use multiple property type and value pairs to narrow your results. For example, find the element logged from the first port of the Friction Mode Logic block.

dsFmlp1 = find(ds,"BlockPath","sldemo_clutch/Friction Mode Logic","PortIndex",1)

dsFmlp1 = 
Simulink.SimulationData.Dataset 'sldemo_clutch_output' with 1 element

                         Name        BlockPath                         
                         __________  _________________________________ 
    1  [1x1 Signal]      LockedFlag  sldemo_clutch/Friction Mode Logic

  - Use braces { } to access, modify, or add elements using index.

Use Logical Operator to Find Elements in Dataset Object

Use the find function to access a collection of elements in a Simulink.SimulationData.Dataset object using the logical operator '-or'. The model sldemo_clutch, which models a rotating clutch system, logs ten signals in Dataset format. For more information about the model, see Building a Clutch Lock-Up Model.

Simulate the model.

sim("sldemo_clutch");

The logged signal data is contained in a Dataset object named sldemo_clutch_output.

ds = sldemo_clutch_output

ds = 
Simulink.SimulationData.Dataset 'sldemo_clutch_output' with 10 elements

                         Name          BlockPath                         
                         ____________  _________________________________ 
    1  [1x1 Signal]      Fn            sldemo_clutch/Clutch Pedal       
    2  [1x1 Signal]      Tin           sldemo_clutch/Engine Torque      
    3  [1x1 Signal]      LockedFlag    sldemo_clutch/Friction Mode Logic
    4  [1x1 Signal]      LockupFlag    sldemo_clutch/Friction Mode Logic
    5  [1x1 Signal]      UnlockFlag    sldemo_clutch/Friction Mode Logic
    6  [1x1 Signal]      Tfmaxk        sldemo_clutch/Friction Model     
    7  [1x1 Signal]      Tfmaxs        sldemo_clutch/Friction Model     
    8  [1x1 Signal]      ShaftSpeed    sldemo_clutch/Locked             
    9  [1x1 Signal]      EngineSpeed   sldemo_clutch/Unlocked           
   10  [1x1 Signal]      VehicleSpeed  sldemo_clutch/Unlocked           

  - Use braces { } to access, modify, or add elements using index.

Use the find function to return a Dataset object that contains all the elements in ds that are logged output signals from either the Unlocked subsystem or the Locked subsystem.

find(ds,"BlockPath","sldemo_clutch/Unlocked",'-or',"BlockPath","sldemo_clutch/Locked")

ans = 
Simulink.SimulationData.Dataset 'sldemo_clutch_output' with 3 elements

                         Name          BlockPath              
                         ____________  ______________________ 
    1  [1x1 Signal]      ShaftSpeed    sldemo_clutch/Locked  
    2  [1x1 Signal]      EngineSpeed   sldemo_clutch/Unlocked
    3  [1x1 Signal]      VehicleSpeed  sldemo_clutch/Unlocked

  - Use braces { } to access, modify, or add elements using index.

Use Regular Expressions to Find Elements in Dataset Object

Use the find function to access a collection of elements in a Simulink.SimulationData.Dataset object using regular expressions. The model sldemo_clutch, which models a rotating clutch system, logs ten signals in Dataset format. For more information about the model, see Building a Clutch Lock-Up Model.

Simulate the model.

sim("sldemo_clutch");

The logged signal data is contained in a Dataset object named sldemo_clutch_output.

ds = sldemo_clutch_output

ds = 
Simulink.SimulationData.Dataset 'sldemo_clutch_output' with 10 elements

                         Name          BlockPath                         
                         ____________  _________________________________ 
    1  [1x1 Signal]      Fn            sldemo_clutch/Clutch Pedal       
    2  [1x1 Signal]      Tin           sldemo_clutch/Engine Torque      
    3  [1x1 Signal]      LockedFlag    sldemo_clutch/Friction Mode Logic
    4  [1x1 Signal]      LockupFlag    sldemo_clutch/Friction Mode Logic
    5  [1x1 Signal]      UnlockFlag    sldemo_clutch/Friction Mode Logic
    6  [1x1 Signal]      Tfmaxk        sldemo_clutch/Friction Model     
    7  [1x1 Signal]      Tfmaxs        sldemo_clutch/Friction Model     
    8  [1x1 Signal]      ShaftSpeed    sldemo_clutch/Locked             
    9  [1x1 Signal]      EngineSpeed   sldemo_clutch/Unlocked           
   10  [1x1 Signal]      VehicleSpeed  sldemo_clutch/Unlocked           

  - Use braces { } to access, modify, or add elements using index.

Use the find function to return a Dataset object that contains all the elements in ds with a name that contains the word Speed.

The regular expression "\w*Speed\w*" indicates that the Name property must contain the word Speed, but the name can have any alphanumeric expression or underscore character before or after the specified text.

find(ds,"-regexp","Name","\w*Speed\w*")

ans = 
Simulink.SimulationData.Dataset 'sldemo_clutch_output' with 3 elements

                         Name          BlockPath              
                         ____________  ______________________ 
    1  [1x1 Signal]      ShaftSpeed    sldemo_clutch/Locked  
    2  [1x1 Signal]      EngineSpeed   sldemo_clutch/Unlocked
    3  [1x1 Signal]      VehicleSpeed  sldemo_clutch/Unlocked

  - Use braces { } to access, modify, or add elements using index.

Input Arguments

dsIn — Dataset object

Simulink.SimulationData.Dataset object

Dataset object in which to search for matching elements, specified as a Simulink.SimulationData.Dataset object.

prop — Type of property to search

string | character vector

Type of property to search, specified as a string or character vector.

Each element in a Dataset object is an object. The type of each object depends on the data it contains. An element must have the property type defined by prop to be included in the Dataset object returned by the find function. For example, you can find Simulink.SimulationData.Signal object elements in a Dataset object using any of the properties of a Signal object:

• Name — Name of element

• PropagatedName — Propagated signal name

• BlockPath — Block path

• PortIndex — Port index

• PortType — Type of port logged

• Values — Logged time and data

The results returned by the find function are not limited to one object type. The find function can return a Dataset object containing elements of any object type that have the specified property type with the specified value. For example, suppose a Dataset object contains two elements with the name myName, where one element is a Signal object and the other element is a timeseries object. You can use the find function to search for both elements by specifying the property type as Name and the property value as myName.

dsName = find(ds,"Name","myName")

dsName = 

Simulink.SimulationData.Dataset 'myDataset' with 2 elements

                             Name    BlockPath 
                             ______  _________ 
    1  [1x1 timeseries]      myName  ''       
    2  [1x1 Signal    ]      myName  ''       

  - Use braces { } to access, modify, or add elements using index.

val — Property value to search for

string | character vector

Property value to search for, specified as a string or character vector. The property value can be a regular expression when using the '-regexp' argument.

logical — Logical operator

'-and' | '-or'

Logical operator connecting multiple property type and value pairs, specified as '-and' or '-or'.

If you do not specify an operation, the function assumes '-and'.

Output Arguments

dsOut — Dataset object

Simulink.SimulationData.Dataset object

Dataset object that contains the elements that match one or more property type and value pairs, returned as a Simulink.SimulationData.Dataset object. If no elements match the specified property type and value, the returned Dataset object is empty.

idx — Indices

vector

Indices in the Dataset object dsIn of the elements that match the specified property name and property value, returned as a vector. If no elements match the specified property type and value, then idx is empty.

Alternatives

You can use curly braces to streamline the indexing syntax to access an element in a Dataset object instead of using the find function. The index must be a positive integer that is not greater than the number of elements in the variable. For example, find the second element of the logsout dataset.

logsout{2}

You can also use the get function to get an element or collection of elements from a dataset.

Version History

Introduced in R2015b