Desktop Example - Using User-Defined Functions in Expressions

Learn more about SimBiology

Desktop Example — Using User-Defined Functions in Expressions

On this page…
Prerequisites Overview Creating an M-File Function Calling the Function in a Rule Expression See Also

On this page…

Prerequisites

Overview

Creating an M-File Function

Calling the Function in a Rule Expression

Prerequisites

To work through the example, these sections assume you have a working knowledge of the following:

MATLAB desktop
Creating and saving M-files
SimBiology desktop

Overview

You can use custom defined functions in reaction rate, rule, and event expressions. When you use a function in a SimBiology expression, the solver calls the function every time the expression is evaluated during simulation.

Therefore, if you have complex reaction rate expressions you can define the reaction rate with a function.

Requirements For Using User-Defined Functions in SimBiology Expressions

Create an M-file function. To find out more about M-file functions, see function in MATLAB Function Reference. For an example of a function to be used in a SimBiology model, see Creating an M-File Function in this topic.
Change the current folder to the folder containing your M-file using the cd command or use the Current Folder field in the MATLAB desktop toolbar. Alternatively, add the path to the folder containing your M-file using addpath or see Adding Folders to the Search Pathin the MATLAB Desktop Tools and Development Environment documentation.
Call the function in a SimBiology reaction, rule, or event expression.

The requirements do not have to be executed in any specific order, but you might find it more convenient to start with the first two items before calling the function from within the SimBiology expression. This is because colored cues for model verification in the SimBiology desktop will show the expression as invalid if the function has not yet been defined, or is not on the path or the working directory.

The example below shows how to create and call user-defined functions in SimBiology expressions. More specifically, the example shows how to use a user-defined function in a rule expression. You can use user-defined functions similarly in event functions (EventFcns property), event triggers (Trigger property) and in reaction rate expressions (ReactionRate property). For example, you can define a function that gives the reaction rate expression as the output, and use the function in a reaction rate expression.

About the Example Model

This example uses the model from Modeling a G Protein Cycle in the SimBiology Model Reference documentation.

This table shows the reactions used to model the G protein cycle and the corresponding rate parameters (rate constants) for each reaction. For reversible reactions, the forward rate parameter is listed first.

No.	Name	Reaction	Rate Parameters
1	Receptor-ligand interaction	`L + R <-> RL`	`kRL`,`kRLm`
2	Heterotrimeric G protein formation	`Gd + Gbg -> G`	`kG1`
3	G protein activation	`RL + G -> Ga + Gbg + RL`	`kGa`
4	Receptor synthesis and degradation	`R <-> null`	`kRdo`, `kRs`
5	Receptor-ligand degradation	`RL -> null`	`kRD1`
6	G protein inactivation	`Ga -> Gd`	`kGd`

Assumptions

For the purpose of this example, assume that:

An inhibitor (Inhib) slows the inactivation of the active G protein (reaction 6 above, Ga –> Gd).
The variation in the amount of Inhib is defined in a function.
The effect on the reaction is through a change in the rate parameter kGd.

Creating an M-File Function

In the MATLAB desktop, select File > New > M-File, to open a new M-file in the MATLAB Editor.

Copy and paste the following function declaration:

% inhibvalex.m
function Cp = inhibvalex(t, Cpo, kel)

% This function takes the input arguments t, Cpo, and kel 
% and returns the value of the inhibitor Cp.
% You can define the input arguments in a 
% SimBiology rule expression. 
% For example in the rule, define:
% t as time (a keyword recognized as simulation time), 
% Cpo as a parameter that represents the initial 
% amount of inhibitor and kel as a parameter 
% that governs the amount of inhibitor.

if  t < 400   
    Cp = Cpo*exp(-kel*(t));
else
    Cp = Cpo*exp(-kel*(t-400));
end

Save the M-file (name the file inhibvalex.m) in a directory that you can access, or that is on the path.
If the location of the M-file is not on the path, change the working directory to the M-file location.

Calling the Function in a Rule Expression

Opening and Saving the Example Model

Load the example project by typing the following at the command line:
```
sbioloadproject gprotein
```
The model is stored in a variable called m1.
Open the SimBiology desktop with the model loaded by typing:
```
simbiology(m1)
```
The desktop opens with Model Session-Heterotrimeric_G_Protein_wt.
Select File > Save Project As. The Save SimBiology Project dialog box opens.
Specify a name (for example, gprotein_ex) and location for your project, and click Save.

Adding User-Defined Functions to the Example Model

The previously defined function inhibvalex in Creating an M-File Function lets you specify how the inhibitor amount changes over time. This section shows you how to specify the input values for the function in a rule expression. As defined in the function, the output value is the amount of inhibitor.

Define a new rule to assign the inhibitor value.

In the Project Explorer, expand SimBiology Model and click Rules to open the Rules pane.
In the Enter Rule box, type the following expression and press Enter:
```
Inhib = inhibvalex(time, Cpo, Kel)
```
The Rule Variables dialog box opens for you to define the rule variables.

From the Type list, select species for Inhib, and parameter for Cpo and Kel. The SimBiology desktop creates the two species and the parameter.

Note If inhibvalex is on the list of undefined variables in the Rule Variables dialog box, this means that you have not yet put the M-file on the path or changed the working directory to the location of the M-file.

Leave inhibvalex undefined in the Rule Variables dialog box and click OK. In the MATLAB desktop, change the Current Directory field to the location of the M-file.

Click OK.
In the Rules pane from the RuleType list, select repeatedAssignment.
In the Settings tab, in Parameters being used by Rule, find the row containing the parameter Kel. Double-click the Value column, type 0.01, and press Enter.
Find the row containing the parameter Cpo. Double-click the Value column, type 250 and press Enter.
Save the project by selecting File > Save Project.

Defining a Rule to Affect Parameter Value

As described in About the Example Model , the parameter kGd should be affected by the amount of inhibitor present in the system. Add a rule to describe this action, but first change the Scope and ConstantValue properties of the parameter kGd so that it can be varied by a rule.

Note Although the model has a previously defined parameter called kGd, this parameter's scope is currently at the kinetic law level. The parameter must be scoped to the model for it to be varied by a rule or an event.

In the Project Explorer, expand SimBiology Model and click Parameters to open the Parameters pane.
Select the row containing the parameter kGd.
Right-click and select Change Parameter Scope. Notice that the Scope column now shows the model name for this parameter.
In the Settings tab, clear the ConstantValue check box for kGd, as this parameter is being varied by a rule.
In the Project Explorer, click Rules to open the Rules pane.
In the Enter Rule box, type the following expression and press Enter:
```
kGd = 1/Inhib
```
In the Settings tab you should see a green square indicating that the rule variables have been previously defined, and that there are no other warnings or errors associated with this rule.
For the new rule, in the Rules pane from the RuleType list, select repeatedAssignment.
Save the project by selecting File > Save Project.

Simulating the Modified Model

In the Project Explorer, right-click SimBiology Model and select Run Simulation.
The simulation runs to completion and plots the result in a figure. The plot does not show the species of interest due to a wide range in species amounts/concentrations. Follow the next steps to view the species of interest.
In the Project Explorer, under Simulation, click Data to open the Data pane for the most recent simulation run.
Click the Plots tab.
In the Arguments section, click . The Select Values for y dialog box opens.
Clear the check box for the following species:
```
RL
L
R
Gbg
```
In the Plot Type box, select Time and click Add Plot Type.
Select the row containing the new plot, and then in the Arguments section, click . The Select Values for y dialog box opens.
Click Clear All, and then select the check box for the species Inhib.
Click OK.
Click Plot. Your plots should resemble the following:

Notice the change in profile of species Ga at time = 400 seconds (simulation time) when the inhibitor amount is changed to reflect the re-addition of inhibitor to the model.

To learn about...	Refer to...
The SimBiology desktop	Getting Started in the SimBiology Desktop in the SimBiology Getting Started Guide.
M-file functions	`function` in the MATLAB Function Reference.
Changing the working directory to the directory containing your M-file	`cd` command in the MATLAB Function Reference.
Adding the directory containing your M-files to the MATLAB search path	`addpath` in the MATLAB Function Reference or Adding Folders to the Search Path in MATLAB Desktop Tools and Development Environment.