SimBiology.Parameter

Parameter and scope information

Description

The SimBiology.Parameter object represents a parameter, which is a quantity that can change or can be constant. SimBiology^® parameters are generally used to define rate constants. You can add parameter objects to a model object or a kinetic law object. The scope of a parameter depends on where you add the parameter object: If you add the parameter object to a model object, the parameter is available to all reactions in the model and the Parent property of the parameter object is SimBiology.Model. If you add the parameter object to a kinetic law object, the parameter is available only to the reaction for which you are using the kinetic law object and the Parent property of the parameter object is SimBiology.KineticLaw.

Use dot notation to query the object properties or change properties that are not read-only. You can also use the get and set commands.

The SimBiology Model Builder app also enables you to add reactions and parameters to your model and edit them. For an example, see Incorporate Inhibitor PK by Adding and Configuring Reactions.

Creation

Use addparameter to create and add a parameter to a SimBiology model.

Properties

Constant — Flag to set parameter value as constant

true or 1 (default) | false or 0

Flag to set a parameter value as a constant, specified as a numeric or logical 1 (true) or 0 (false). Constant is identical to ConstantValue.

In other words, the Constant property indicates whether the value of a parameter can change during a simulation.

You can allow the value of the parameter to change during a simulation by specifying a rule that changes the Value property of the parameter object.

As an example, consider feedback inhibition of an enzyme such as aspartate kinase by threonine. Aspartate kinase has three isozymes that are independently inhibited by the products of downstream reactions (threonine, homoserine, and lysine). Although threonine is made through a series of reactions in the synthesis pathway, for illustration, the reactions are simplified as follows:

$$\begin{array}{l}Aspartic\text{ acid }\stackrel{\text{aspartate kinase}}{\to }\beta -Aspartylphosphate\\ \beta -Aspartylphosphate\stackrel{}{\to }Threonine\end{array}$$

To model inhibition of aspartate kinase by threonine, you could use a rule like the algebraic rule, such as k_aspartate_kinase - (1/threonine), to vary the rate of the above reaction and simulate inhibition. In the rule, the rate constant for the above reaction is denoted by k_aspartate_kinase and the quantity of threonine is threonine.

Data Types: double | logical

ConstantValue — Flag to set parameter value as constant

true or 1 (default) | false or 0

Flag to set the parameter value as a constant, specified as a numeric or logical 1 (true) or 0 (false). ConstantValue is identical to Constant.

Data Types: double | logical

Name — SimBiology.Parameter object name

character vector | string

SimBiology.Parameter object name, specified as a character vector or string.

For details on requirements and recommendations for naming SimBiology components, see Guidelines for Naming Model Components.

Data Types: char | string

Notes — Additional information

empty character array (default) | character vector | string

Additional information that you can add for SimBiology.Parameter, specified as a character vector or string.

Data Types: char | string

Parent — Parent object

SimBiology.Model object | SimBiology.KineticLaw object

This property is read-only.

Parent object, specified as a SimBiology.Model or SimBiology.KineticLaw object.

Tag — Object label

empty character array (default) | character vector | string

Object label, specified as a character vector or string.

Tip

Use this property to group objects and then use sbioselect to retrieve. For example, use the Tag property of reaction objects to group synthesis or degradation reactions. You can then retrieve all synthesis reactions using sbioselect. Similarly, for species objects you can enter and store classification information, for example, membrane protein, transcription factor, enzyme classifications, or whether a species is an independent variable. You can also enter the full form of the name of the species.

Data Types: char | string

Type — Object type

'parameter' (default)

This property is read-only.

Object type, specified as 'parameter'. When you create a SimBiology object, the value of Type is automatically defined.

Data Types: char

Units — Units for parameter value

empty character array (default) | character vector | string scalar

Units for the parameter value, specified as a character vector or string scalar.

The Units property indicates the unit definition of the Value property of a parameter object. Units is identical to ValueUnits.

The default value (empty character array) means an unspecified unit. Unspecified units are permitted during dimensional analysis, but not during unit conversion. Use 'dimensionless' to specify dimensionless units.

Units can be one of the built-in units or you can create your own units. To get a list of the built-in units, use sbioshowunits. To create a custom unit, use sbiounit. If Units changes from one unit definition to another, the Value property does not automatically convert to the new units. sbioconvertunits does this conversion.

Note

SimBiology uses units including empty units in association with DimensionalAnalysis and UnitConversion features.

• When DimensionalAnalysis and UnitConversion are both false, units are not used. However, SimBiology still performs a minimum level of dimensional analysis to decide whether a reaction rate is in dimensions of amount/time or concentration/time.

• When DimensionalAnalysis is true and UnitConversion is false, units (if not empty) must have consistent dimensions so that SimBiology can perform dimensional analysis. However, the units are not converted.

• When UnitConversion is set to true (which requires DimensionalAnalysis to be true), SimBiology performs a dimensional analysis and converts everything to consistent units. Hence, you must specify consistent units, and no units can be empty. If you have a dimensionless parameter, you must still set its unit to dimensionless.

Example: '1/second'

Data Types: char | string

UserData — Data to associate with object

scalar | vector | string | ...

Data to associate with the object, specified as a numeric scalar, vector, string, or any other MATLAB data type.

The object does not use this data directly, but you can access it using dot notation or get.

Value — Parameter value

1.0 (default) | nonnegative scalar

Parameter value, specified as a nonnegative scalar.

Data Types: double

ValueUnits — Units for parameter value

empty character array (default) | character vector | string scalar

Units for the parameter value, specified as a character vector or string scalar. This property is identical to Units.

Data Types: char | string

Object Functions

copyobj	Copy SimBiology object and its children
delete	Delete SimBiology object
display	Display summary of SimBiology object
findUsages	Find out how a species, parameter, or compartment is used in a model
get	Get SimBiology object properties
move	Move SimBiology species or parameter object to new parent
rename	Rename SimBiology model component and update expressions
set	Set SimBiology object properties

Examples

Construct a Simple Model

This example shows you how to construct a simple model with two species (A and B) and a reaction. The reaction is A -> B, which follows mass action kinetics with the forward rate parameter k. Hence the rate of change is $dA/dt=-k*A$.

Create a SimBiology model named simpleModel.

m1 = sbiomodel('simpleModel');

Add a reaction that involves two species A and B, where A is converted to B.

r1 = addreaction(m1,'A -> B');

SimBiology automatically add species A and B to the model.

m1.species

ans = 
   SimBiology Species Array

   Index:    Compartment:    Name:    Value:    Units:
   1         unnamed         A        0               
   2         unnamed         B        0               

Set the initial amount of the first species (A) to 10.

m1.species(1).InitialAmount = 10;

Define the kinetic law of the reaction to follow mass action kinetics. You can achieve this by adding a kinetic law object to the reaction r1.

kineticLaw = addkineticlaw(r1,'MassAction');

Add a rate constant parameter to the mass action kinetic law. You must set the ParameterVariableNames property of the kinetic law object to the name of the parameter 'k' so that the reaction rate can be determined.

p1 = addparameter(kineticLaw,'k',0.5);
kineticLaw.ParameterVariableNames = 'k';

Simulate the model.

sd = sbiosimulate(m1);

Plot the simulation results.

sbioplot(sd);

Create a Rate Rule for an Exponential Rate of Change

This example shows how to change the amount of a species similar to a first-order reaction using the first-order rate rule. For example, suppose the species x decays exponentially. The rate of change of species x is:

$dx/dt=-k*x$

The analytical solution is:

$C_t=C_0*e^{-kt}$

where $C_t$ is the amount of species at time t, and $C_0$ is the initial amount. Use the following commands to set up a SimBiology model accordingly and simulate it.

m = sbiomodel('m');
c = addcompartment(m,'comp');
s = addspecies(m,'x','InitialAmount',2);
p = addparameter(m,'k','Value',1);
r = addrule(m,'x = -k * x','RuleType','rate');
[t,sd,species] = sbiosimulate(m);
plot(t,sd);
legend(species);
xlabel('Time');
ylabel('Species Amount');

If the amount of a species x is determined by a rate rule and x is also in a reaction, x must have its BoundaryCodition property set to true. For example, with a reaction a -> x and a rate rule $$\frac{dx}{dt}=k*x$$, set the BoundaryCodition property of species x to true so that a differential rate term is not created from the reaction. The amount of x is determined solely by a differential rate term from the rate rule. If the BoundaryCodition property is set to false, you will get the following error message such as Invalid rule variable 'x' in rate rule or reaction.

Create a Rate Rule for the Rate of Change That Is Determined by Another Species

This example shows how to create a rate rule where a species from one reaction can determine the rate of another reaction if it is in the second reaction rate equation. Similarly, a species from a reaction can determine the rate of another species if it is in the rate rule that defines that other species. Suppose you have a SimBiology model with three species (a, b, and c), one reaction (a -> b), and two parameters (k1 and k2). The rate equation is defined as $$b=-k_1*a$$, and rate rule is $$dc/dt=k_2*a$$. The solution for the species in the reaction are:

$$a=a_o{e}^{-k_{1}t}$$, $$b=a_o(1-e^{-k_{1}t})$$.

Since the rate rule $$dc/dt=k_2*a$$ is dependent on the reaction, $$dc/dt=k_2(a_o{e}^{-k_{1}t})$$. The solution is:

$$c=c_o+k_2{a}_o/k_1(1-e^{-k_{1}t})$$

Enter the following commands to set up a SimBiology model accordingly and simulate it.

m = sbiomodel('m');
c = addcompartment(m,'comp');
s1 = addspecies(m,'a','InitialAmount',10,'InitialAmountUnits','mole');
s2 = addspecies(m,'b','InitialAmount',0,'InitialAmountUnits','mole');
s3 = addspecies(m,'c','InitialAmount',5,'InitialAmountUnits','mole');
rxn = addreaction(m,'a -> b');
kl = addkineticlaw(rxn,'MassAction');
p1 = addparameter(kl,'k1','Value',1,'ValueUnits','1/second');
rule = addrule(m,'c = k2 * a','RuleType','rate');
kl.ParameterVariableNames = 'k1';
p2 = addparameter(m,'k2','Value',1,'ValueUnits','1/second');
[t,sd,species] = sbiosimulate(m);
plot(t,sd);
legend(species);
xlabel('Time');
ylabel('Species Amount');

Version History

Introduced in R2006b

R2024a: Having duplicate model component names is no longer allowed

• When you load a model that contains duplicate names, SimBiology automatically updates those names. SimBiology disambiguates the duplicate names by adding a suffix "_N", where N is the first positive integer that results in a unique name. If there is an existing suffix, N will be incremented from that suffix. For example, if there are two model components named x_3, the function updates one of the names to x_4. If the existing suffix has leading zeros, the function omits the zeros in the new name. For instance, if x_003 is a duplicate name, it gets renamed to x_4. However, the function assumes that names with leading zeros and without leading zeros are different. For instance, x_005 and x_5 are considered to be different names.

• SimBiology issues an error if multiple model components (model, compartment, species, parameter, reaction, rule, event, observable, dose, and variant) have the same name. Within a single model, these components are required to have unique names even when they are of different types with the following two exceptions:

  • Species in different compartments can have the same name.

  • Parameters can have the same name if they are scoped to different parents. Specifically, you can use the same name for a model-scoped parameter and reaction-scoped parameters, where each reaction-scoped parameter belongs to a different reaction.

  For details on how to reference model component names in expressions, see Guidelines for Referencing Names in Expressions.

R2022b: Having duplicate model component names issues a warning

SimBiology issues a warning if multiple model components have the same name.

R2022a: Having duplicate model component names will not be allowed in a future release

SimBiology will not allow you to have duplicate names for model components within a model.