sbioselect

Search for objects with specified constraints

Syntax

Out = sbioselect('PropertyName', PropertyValue) Out = sbioselect('Where', 'PropertyName', 'Condition', PropertyValue) Out = sbioselect(Obj, 'PropertyName', PropertyValue) Out = sbioselect(Obj, 'Type', 'TypeValue', 'PropertyName', PropertyValue) Out = sbioselect(Obj, 'Where', 'PropertyName', 'Condition', PropertyValue) Out = sbioselect(Obj, 'Where', 'PropertyNameCondition', 'PropertyNamePattern', 'Condition', PropertyValue) Out = sbioselect(Obj, 'Where', 'PropertyName1', 'Condition1', PropertyValue1, 'Where', 'PropertyName2', 'Condition2', PropertyValue2,...) Out = sbioselect(Obj, 'Where', 'PropertyName1', 'Condition1', PropertyValue1,Bool_Operator, 'Where', 'PropertyName2', 'Condition2', PropertyValue2,...) Out = sbioselect(Obj, 'Depth', DepthValue,...)

Arguments

`Out`	Object or array of objects returned by the `sbioselect` function. `Out` might contain a mixture of object types (for example, species and parameters), depending on the selection you specify. If `PropertyValue` is a cell array, then the function returns all objects with the property `'PropertyName'` that matches any element of `PropertyValue`.
`Obj`	SimBiology^® object or array of objects to search. If an object is not specified, `sbioselect` searches the root.
`PropertyName`	Any property of the object being searched.
`PropertyValue`	Specify `PropertyValue` to include in the selection criteria.
`TypeValue`	Type of object to include in the selection, for example, `sbiomodel`, `species`, `reaction`, or `kineticlaw`.
`Condition`	The search condition. See the table under Description for a list of conditions.
`PropertyNameCondition`	Search condition that applies only to the name property. See the table listing “Conditions for Names” below.
`PropertyNamePattern`	Character vector or string used to select the property name according to the condition imposed by `PropertyNameCondition`.
`DepthValue`	Specify the depth number to search. Valid numbers are positive integer values and `inf`. If `DepthValue` is `inf`, `sbioselect` searches `Obj` and all of its children. If `DepthValue` is `1`, `sbioselect` only searches `Obj` and not its children. By default, `DepthValue` is `inf`.

Description

sbioselect searches for objects with specified constraints.

Out = sbioselect('PropertyName', PropertyValue) searches the root object (including all model objects contained by the root object) and returns the objects with the property name (PropertyName) and property value (PropertyValue) contained by the root object.

Out = sbioselect('Where', 'PropertyName', 'Condition', PropertyValue) searches the root object and finds objects that have a property name (PropertyName) and value (PropertyValue) that matches the condition (Condition).

Out = sbioselect(Obj, 'PropertyName', PropertyValue) returns the objects with the property name (PropertyName) and property value (PropertyValue) found in any object (Obj). If the property name in a property-value pair contains either a '?' or '*', then the name is automatically interpreted as a wildcard expression, equivalent to the where clause ('Where', 'wildcard', 'PropertyName', '==', PropertyValue).

Out = sbioselect(Obj, 'Type', 'TypeValue', 'PropertyName', PropertyValue) finds the objects of type (TypeValue), with the property name (PropertyName) and property value (PropertyValue) found in any object (Obj). TypeValue is the type of SimBiology object to be included in the selection, for example, species, reaction, or kineticlaw.

Out = sbioselect(Obj, 'Where', 'PropertyName', 'Condition', PropertyValue) finds objects that have a property name (PropertyName) and value (PropertyValue) that match the condition (Condition).

If you search for a character vector property value without specifying a condition, you must use the same format as get returns. For example, if get returns the Name as 'MyObject', sbioselect will not find an object with a Name property value of 'myobject'. Therefore, for this example, you must specify:

modelObj = sbioselect ('Name', 'MyObject')

Instead, if you use a condition, you can specify:

modelObj = sbioselect ('Where', 'Name', '==i', 'myobject')

Thus, conditions let you control the specificity of your selection.

sbioselect searches for model objects on the root in both cases.

Out = sbioselect(Obj, 'Where', 'PropertyNameCondition', 'PropertyNamePattern', 'Condition', PropertyValue) finds objects with a property name that matches the pattern in (PropertyNamePattern) with the condition (PropertyNameCondition) and matches the value (PropertyValue) with the condition (Condition). Use this syntax when you want search conditions on both property names and property values.

The conditions, with examples of property names and corresponding examples of property values that you can use, are listed in the following tables. This table shows you conditions for numeric properties.

Conditions for Numeric Properties	Example Syntax
`==`	Search in the model object (`modelObj`), and return parameter objects that have `Value` equal to `0.5`. `sbioselect` returns parameter objects because only parameter objects have a property called `Value`. parameterObj = sbioselect (modelObj,... 'Where', 'Value', '==', 0.5) In the case of `==`, this is equivalent to omitting the condition as shown: parameterObj = sbioselect (modelObj,... 'Value', 0.5) Search in the model object (`modelObj`), and return parameter objects that have `ConstantValue` `false` (nonconstant parameters). parameterObj = sbioselect (modelObj,... 'Where', 'ConstantValue', '==', false)
`~=`	Search in the model object (`modelObj`), and return parameter objects that do not have `Value` equal to `0.5`. parameterObj = sbioselect (modelObj,... 'Where', 'Value', '~=', 0.5)
`>`,`<`,`>=`,`<=`	Search in the model object (`modelObj`), and return species objects that have an initial amount (`InitialAmount`) greater than `50`. speciesObj = sbioselect (modelObj, ... 'Where', 'InitialAmount', '>', 50) Search in the model object (`modelObj`), and return species objects that have an initial amount (`InitialAmount`) less than or equal to `50`. speciesObj = sbioselect (modelObj,... 'Where', 'InitialAmount', '<=', 50)
`between`	Search in the model object (`modelObj`), and return species objects that have an initial amount (`InitialAmount`) between `200` and `300`. speciesObj = sbioselect (modelObj,... 'Where', 'InitialAmount',... 'between', [200 300])
`~between`	Search in the model object (`modelObj`), and return species objects that have an initial amount (`InitialAmount`) that is not between `200` and `300`. speciesObj = sbioselect (modelObj,... 'Where', 'InitialAmount',... '~between', [200 300])
equal_and_same_type	Similar to `==`, but in addition requires the property value to be of the same type. Search in the model object (`modelObj`), and return all objects containing a property of type `double` and a value equal to `0`. (Using `'=='` would also select objects containing a property with a value of false.) zeroObj = sbioselect(modelObj, ... 'Where', '*', 'equal_and_same_type', 0);
unequal_and_same_type	Similar to `~=`, but in addition requires the property value to be of the same type. Select all objects containing a property of type double and value not equal to 0. (Using `'~='` would also select objects containing a property with a value of true.) nonzeroObj = sbioselect(modelObj, ... 'Where', '*', 'unequal_and_same_type', 0);

The following table shows you conditions for the name property or for properties whose values are character vectors.

Conditions for Names	Example Syntax
`==`	Search in the model object (`modelObj`), and return species objects named `'Glucose'`. speciesObj = sbioselect (modelObj,... 'Type', 'species', 'Where',... 'Name', '==', 'Glucose')
`~=`	Search in the model object (`modelObj`), and return species objects that are not named `'Glucose'`. speciesObj = sbioselect (modelObj,... 'Type', 'species', 'Where',... 'Name', '~=', 'Glucose')
`==i`	Same as `==`; in addition, this is case insensitive.
`~=i`	Search in the model object (`modelObj`), and return species objects that are not named `'Glucose'`, ignoring case. speciesObj = sbioselect (modelObj,... 'Type', 'species', 'Where',... 'Name', '~=i', 'glucose')
`regexp`. Supports expressions supported by the functions `regexp` and `regexpi`.	Search in the model object (`modelObj`), and return objects that have `'ese'` or `'ase'` anywhere within the name. Obj = sbioselect (modelObj, 'Where',... 'Name', 'regexp', '[ea]se') Search in the root, and return objects that have `kinase` anywhere within the name. Obj = sbioselect ('Where',... 'Name', 'regexp', 'kinase') Note that this query could result in a mixture of object types (for example, species and parameters).
`regexpi`	Same as `regexp`; in addition, this is case insensitive.
`~regexp`	Search in the model object (`modelObj`), and return objects that do not have `kinase` anywhere within the name. Obj = sbioselect (modelObj, 'Where',... 'Name', '~regexp', 'kinase')
`~regexpi`	Same as `~regexp`; in addition, this is case insensitive.
`wildcard`	Supports `DOS-style` wildcards ('`?`' matches any single character, '`*`' matches any number of characters, and the pattern must match the entire character vector). See `regexptranslate` for more information.
`wildcardi`	Same as `wildcard`; in addition, this is case insensitive.
`~wildcard`	Search in the model object (`modelObj`), and return objects that have names that do not begin with `kin`. Obj = sbioselect (modelObj, 'Where',... 'Name', '~wildcard', 'kin')
`~wildcardi`	Same as `~wildcard`; in addition, this is case insensitive.

Use the condition type function for any property. The specified value should be a function handle that, when applied to a property value, returns a boolean indicating whether there is a match. The following table shows an example of using function.

Condition Example Syntax

Condition	Example Syntax
`'function'`	Search in the model object and return reaction objects whose `Stoichiometry` property contains the specified stoichiometry. Out = sbioselect(modelObj, 'Where',... 'Stoichiometry', 'function',... @(x)any(x>2)) Select all objects with a numeric value that is even. iseven = @(x) isnumeric(x)... && isvector(x) && mod(x, 2) == 0; evenValuedObj = sbioselect(modelObj, ... 'where', 'Value', 'function', iseven);

'function'

Search in the model object and return reaction objects whose Stoichiometry property contains the specified stoichiometry.

Out = sbioselect(modelObj, 'Where',...
'Stoichiometry', 'function',...
 @(x)any(x>2))

Select all objects with a numeric value that is even.

iseven = @(x) isnumeric(x)...
 && isvector(x) && mod(x, 2) == 0; 
evenValuedObj = sbioselect(modelObj, ...
'where', 'Value', 'function', iseven);

The condition 'contains' can be used only for those properties whose values are an array of SimBiology objects. The following table shows an example of using contains.

Condition Example Syntax

Condition	Example Syntax
`'contains'`	Search in the model object and return reaction objects whose `Reactant` property contains the specified species. Out = sbioselect(modelObj, 'Where',... 'Reactants', 'contains',... modelObj.Species(1))

'contains'

Search in the model object and return reaction objects whose Reactant property contains the specified species.

Out = sbioselect(modelObj, 'Where',...
'Reactants', 'contains',...
 modelObj.Species(1))

Out = sbioselect(Obj, 'Where', 'PropertyName1', 'Condition1', PropertyValue1, 'Where', 'PropertyName2', 'Condition2', PropertyValue2,...) finds objects contained by Obj that matches all the conditions specified.

You can combine any number of property name/property value pairs and conditions in the sbioselect command.

Out = sbioselect(Obj, 'Where', 'PropertyName1', 'Condition1', PropertyValue1,Bool_Operator, 'Where', 'PropertyName2', 'Condition2', PropertyValue2,...) finds objects contained by Obj that matches all the conditions specified. Supported character vectors for Bool_Operator are as follows.

`'and'`	True if ( `'Where'`, `'PropertyName1'`,`'Condition1'`,`PropertyValue1`) and ( `'Where'`, `'PropertyName2'`,`'Condition2'`,`PropertyValue2`) are both true.
`'or'`	True if either ( `'Where'`, `'PropertyName1'`,`'Condition1'`,`PropertyValue1`) or ( `'Where'`, `'PropertyName2'`,`'Condition2'`,`PropertyValue2`) is true.
`'xor'`	True if exactly one of ( `'Where'`, `'PropertyName1'`,`'Condition1'`,`PropertyValue1`) or ( `'Where'`, `'PropertyName2'`,`'Condition2'`,`PropertyValue2`) is true.
`'not'`	True if ( `'Where'`, `'PropertyName1'`,`'Condition1'`,`PropertyValue1`) is true and ( `'Where'`, `'PropertyName2'`,`'Condition2'`,`PropertyValue2`) is not true.

Compound expressions with multiple boolean operators are supported. Precedence of the operators follows the order of operations for boolean algebra not –> and –> xor –> or.

Out = sbioselect(Obj, 'Depth', DepthValue,...) finds objects using a model search depth of DepthValue.

Note

The order of results from sbioselect is not guaranteed. Hence, it is not recommended to depend on the order of results.

Examples

collapse all

Find Species from a SimBiology Model

Open Live Script

Import a model.

modelObj = sbmlimport('oscillator');

Find and return an object named pA.

pA = sbioselect(modelObj, 'Name', 'pA')

pA = 
   SimBiology Species Array

   Index:    Compartment:    Name:    Value:    Units:
   1         unnamed         pA       100

Find and return species objects whose Name starts with p and have A or B as the next letter in the name.

speciesObjs = sbioselect(modelObj, 'Type', 'species', 'Where',...
                        'Name', 'regexp', '^p[AB]')

speciesObjs = 
   SimBiology Species Array

   Index:    Compartment:    Name:        Value:    Units:
   1         unnamed         pA           100             
   2         unnamed         pB           0               
   3         unnamed         pA_OpB1      0               
   4         unnamed         pB_OpC1      0               
   5         unnamed         pA_OpB_pA    20              
   6         unnamed         pA_OpB2      0               
   7         unnamed         pB_OpC2      0               
   8         unnamed         pB_OpC_pB    0

Find a cell array. Note how cell array values must be specified inside another cell array.

modelObj.Species(2).UserData = {'a' 'b'}; 
Obj = sbioselect(modelObj, 'UserData', {{'a' 'b'}})

Obj = 
   SimBiology Species Array

   Index:    Compartment:    Name:    Value:    Units:
   1         unnamed         pB       0

Find and return objects that do not have their units set.

unitlessObj = sbioselect(modelObj, 'Where', 'wildcard', '*Units', '==', '');

Alternatively, you can do the following.

unitlessObj = sbioselect(modelObj, '*Units', '');

Version History

Introduced before R2006a