Main Content

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

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

ObjSimBiology® object or array of objects to search. If an object is not specified, sbioselect searches the root.
PropertyNameAny property of the object being searched.
PropertyValueSpecify PropertyValue to include in the selection criteria.
TypeValueType of object to include in the selection, for example, sbiomodel, species, reaction, or kineticlaw.
ConditionThe search condition. See the table under Description for a list of conditions.
PropertyNameConditionSearch condition that applies only to the name property. See the table listing “Conditions for Names” below.
PropertyNamePatternCharacter vector or string used to select the property name according to the condition imposed by PropertyNameCondition.
DepthValueSpecify 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 PropertiesExample 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])

~betweenSearch 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 NamesExample 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.

ConditionExample 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); 

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.

ConditionExample 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))

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

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

See Also