Documentation

createSimFunction (model)

Create SimFunction object

Syntax

  • F = createSimFunction(model,params,observables,dosed) example
  • F = createSimFunction(___,Name,Value)

Description

example

F = createSimFunction(model,params,observables,dosed) creates a SimFunction object F that you can execute like a function handle. The params and observables arguments define the inputs and outputs of the function F when it is executed, and dosed defines the dosing information of species. See SimFunction object for details on how to execute F.

F = createSimFunction(___,Name,Value) uses additional options specified by one or more Name,Value pair arguments.

    Note:  

    • Active doses and variants of the model are ignored when F is executed.

    • F is immutable after it is created.

    • F is automatically accelerated at the first function execution. However, manually accelerate the object if you want it accelerated in your deployment applications.

Input Arguments

collapse all

model — SimBiology modelSimBiology model object

SimBiology model, specified as a SimBiology model object.

params — Inputs of SimFunction Fstring | cell array of strings

Inputs of SimFunction F, specified as a string or cell array of strings. The strings represent the names of model quantities (species, compartments, or parameters) that define the inputs of F.

To unambiguously name a model quantity, use the qualified name, which includes the name of the compartment. To name a reaction-scoped parameter, use the reaction name to qualify the parameter. If the name is not a valid MATLAB® variable name, surround it by square brackets such as [reaction 1].[parameter 1].

observables — Outputs of SimFunction Fstring | cell array of strings

Outputs of SimFunction F, specified as a string or cell array of strings. The strings represent the names of model quantities (species, compartments, or parameters) that define the outputs of F.

dosed — Dosed species or dose objectsstring | cell array of strings | vector of dose objects | []

Dosed species or dose objects, specified as a string, cell array of strings, vector of dose objects, or empty array []. If it is a vector, it must be 1-by-N vector, where N is the number of dosed species. Use [] to specify no species are dosed.

If dose objects contain any data for Time, Value, or Rate properties, they are ignored and a warning is issued. Only TargetName, DurationParameterName, and LagParameterName properties of each dose object are used.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'UseParallel',true specifies to execute the SimFunction F in parallel.

'UseParallel' — Flag to execute SimFunction F in parallelfalse (default) | true

Flag to execute SimFunction F in parallel, specified as the comma-separated pair consisting of 'UseParallel' and true or false. If true and Parallel Computing Toolbox™ is available, the SimFunction F is executed in parallel.

Example: 'UseParallel',true

'SensitivityOutputs' — Sensitivity output factors{} (default) | cell array of strings | 'all'

Sensitivity output factors, specified as the comma-separated pair consisting of 'SensitivityOutputs' and a cell array of strings. The strings are the names of model quantities (species and parameters) for which you want to compute the sensitivities. The default is {} meaning there is no output factors. Output factors are the numerators of time-dependent derivatives explained in Sensitivity Calculation.

Use the keyword 'all' to specify all model quantities listed in the observables argument as sensitivity outputs. However, {'all'} means a model quantity named all in the model.

You must specify both 'SensitivityOutputs' and 'SensitivityInputs' name-value pair arguments for sensitivity calculations.

Example: 'SensitivityOutputs','all'

'SensitivityInputs' — Sensitivity input factors{} (default) | cell array of strings | 'all'

Sensitivity input factors, specified as the comma-separated pair consisting of 'SensitivityInputs' and a cell array of strings. The strings are the names of model quantities (species, compartments, and parameters) with respect to which you want to compute the sensitivities. The default is {} meaning no input factors. Input factors are the denominators of time-dependent derivatives explained in Sensitivity Calculation.

Use the keyword 'all' to specify all model quantities listed in the params argument as sensitivity inputs. However, {'all'} means a model quantity named all in the model.

You must specify both 'SensitivityOutputs' and 'SensitivityInputs' name-value pair arguments for sensitivity calculations.

Example: 'SensitivityInputs',{'Reaction1.c1','Reaction1.c2'}

'SensitivityNormalization' — Normalization for calculated sensitivities'None' (default) | 'Half | 'Full'

Normalization for calculated sensitivities, specified as the comma-separated pair consisting of 'SensitivityNormalization' and 'None', 'Half', or 'Full'.

  • 'None' — No normalization (default)

  • 'Half' — Normalization relative to the numerator only

  • 'Full' — Full dedimensionalization

For details, see Normalization.

Example: 'SensitivityNormalization','Full'

Output Arguments

collapse all

F — SimFunctionSimFunction object | SimFunctionSensitivity object

SimFunction, returned as a SimFunction object or SimFunctionSensitivity object. You can execute F like a function handle.

F is a SimFunctionSensitivity object if you specify non-empty 'SensitivityOutputs' and 'SensitivityInputs' name-value pair arguments.

Examples

collapse all

Create a SimFunction Object

This example uses a radioactive decay model with the first-order reaction dzdt=c·x, where x and z are species and c is the forward rate constant.

Load the sample project containing the radioactive decay model m1.

sbioloadproject radiodecay;

Create a SimFunction object, specifying the parameter Reaction1.c to be scanned, and species x as the output of the function with no dosed species.

f = createSimFunction(m1, 'Reaction1.c','x', [])
f = 

SimFunction

Parameters:

        Name         Value       Type          Units   
    _____________    _____    ___________    __________

    'Reaction1.c'    0.5      'parameter'    '1/second'

Observables: 

    Name      Type         Units   
    ____    _________    __________

    'x'     'species'    'molecule'

Dosed: None

If the UnitConversion option was set to false when the SimFunction object f was created, the table does not display the units of the model quantities.

To illustrate this, first set the UnitConversion option to false.

m1.getconfigset.CompileOptions.UnitConversion = false;

Create the SimFunction object as before and note that the variable named Units disappears.

f = createSimFunction(m1, {'Reaction1.c'},{'x'}, [])
f = 

SimFunction

Parameters:

        Name         Value       Type    
    _____________    _____    ___________

    'Reaction1.c'    0.5      'parameter'

Observables: 

    Name      Type   
    ____    _________

    'x'     'species'

Dosed: None

If any of the species in the model is being dosed, specify the names of dosed species as the last argument. For example, if the species x is being dosed, specify it as the last argument.

f = createSimFunction(m1, {'Reaction1.c'},{'x'}, 'x')
f = 

SimFunction

Parameters:

        Name         Value       Type    
    _____________    _____    ___________

    'Reaction1.c'    0.5      'parameter'

Observables: 

    Name      Type   
    ____    _________

    'x'     'species'

Dosed: 

    TargetName
    __________

    'x'  

Once the SimFunction object is created, you can execute it like a function handle and perform parameter scans (in parallel if Parallel Computing Toolbox is available), Monte Carlo simulations, and scans with multiple or vectorized doses. See SimFunction object for more examples.

Create a SimFunction Object with Dosing Information

This example creates a SimFunction object with dosing information using a RepeatDose or ScheduleDose object or a vector of these objects. However, if any dose object contains data such as StartTime, Amount, and Rate, such data are ignored, and a warning is issued. Only data, if available, used are TargetName, LagParameterName, and DurationParameterName of the dose object.

Load the sample project containing the radioactive decay model m1.

sbioloadproject radiodecay;

Create a RepeatDose object and specify its properties.

rdose = sbiodose('rd');
rdose.TargetName = 'x';
rdose.StartTime = 5;
rdose.TimeUnits = 'second';
rdose.Amount = 300;
rdose.AmountUnits = 'molecule';
rdose.Rate = 1;
rdose.RateUnits = 'molecule/second';
rdose.Interval = 100;
rdose.RepeatCount = 2;

Add a lag parameter and duration parameter to the model.

lagPara = addparameter(m1,'lp');
lagPara.Value = 1;
lagPara.ValueUnits = 'second';
duraPara = addparameter(m1,'dp');
duraPara.Value = 1;
duraPara.ValueUnits = 'second';

Set these parameters to the dose object.

rdose.LagParameterName = 'lp';
rdose.DurationParameterName = 'dp';

Create a SimFunction object f using the RepeatDose object rdose that you just created.

f = createSimFunction(m1,{'Reaction1.c'},{'x','z'},rdose)
Warning: Some Dose objects in DOSED had data. This data
will be ignored. 
> In SimFunction>SimFunction.SimFunction at 847
  In SimFunction>SimFunction.createSimFunction at 374 

f = 

SimFunction

Parameters:

        Name         Value       Type          Units   
    _____________    _____    ___________    __________

    'Reaction1.c'    0.5      'parameter'    '1/second'

Observables: 

    Name      Type         Units   
    ____    _________    __________

    'x'     'species'    'molecule'
    'z'     'species'    'molecule'

Dosed: 

    TargetName            TargetDimension        
    __________    _______________________________

    'x'           'Amount(e.g. mole or molecule)'


    DurationParameterName    DurationParameterValue
    _____________________    ______________________

    'dp'                     1                     


    DurationParameterUnits    LagParameterName
    ______________________    ________________

    'second'                  'lp'            


    LagParameterValue    LagParameterUnits
    _________________    _________________

    1                    'second'         

A warning message appears because the rdose object contains data (StartTime, Amount, Rate) that are ignored by the createSimFunction method.

Scan Parameters of the Lotka-Volterra Model

This example shows how to execute different signatures of the SimFunction object to simulate and scan parameters of the Lotka-Volterra (predator-prey) model described by Gillespie [1].

Load the sample project containing the model m1.

sbioloadproject lotka;

Create a SimFunction object f with c1 and c2 as input parameters to be scanned, and y1 and y2 as the output of the function with no dose.

f = createSimFunction(m1,{'Reaction1.c1', 'Reaction2.c2'},{'y1', 'y2'}, [])
f = 

SimFunction

Parameters:

         Name         Value       Type    
    ______________    _____    ___________

    'Reaction1.c1'      10     'parameter'
    'Reaction2.c2'    0.01     'parameter'

Observables: 

    Name      Type   
    ____    _________

    'y1'    'species'
    'y2'    'species'

Dosed: None

Define an input matrix that contains values for each parameter (c1 and c2) for each simulation. The number of rows indicates the total number of simulations, and each simulation uses the parameter values specified in each row.

phi = [10 0.01; 10 0.02];

Run simulations until the stop time is 5 and plot the simulation results.

sbioplot(f(phi, 5));

You can also specify a vector of different stop times for each simulation.

t_stop = [3;6];
sbioplot(f(phi, t_stop));

Next, specify the output times as a vector.

t_output = 0:0.1:5;
sbioplot(f(phi,[],[],t_output));

Specify output times as a cell array of vectors.

t_output = {0:0.01:3, 0:0.2:6};
sbioplot(f(phi, [], [], t_output));

Calculate Sensitivities Using SimFunctionSensitivity Object

This example shows how to calculate sensitivities of some species in the Lotka-Volterra model using the SimFunctionSensitivity object.

Load the sample project.

sbioloadproject lotka;

Define the input parameters.

params = {'Reaction1.c1', 'Reaction2.c2'};

Define the observed species, which are the outputs of simulation.

observables  = {'y1', 'y2'};

Create a SimFunctionSensitivity object. Set the sensitivity output factors to all species (y1 and y2) specified in the observables argument and input factors to those in the params argument (c1 and c2) by using the keyword 'all'.

f = createSimFunction(m1,params,observables,[],'SensitivityOutputs','all','SensitivityInputs','all','SensitivityNormalization','Full')
f = 

SimFunction

Parameters:

         Name         Value       Type    
    ______________    _____    ___________

    'Reaction1.c1'      10     'parameter'
    'Reaction2.c2'    0.01     'parameter'

Observables: 

    Name      Type   
    ____    _________

    'y1'    'species'
    'y2'    'species'

Dosed: None

Sensitivity Input Factors: 

         Name            Type    
    ______________    ___________

    'Reaction1.c1'    'parameter'
    'Reaction2.c2'    'parameter'

Sensitivity Output Factors: 

    Name      Type   
    ____    _________

    'y1'    'species'
    'y2'    'species'

Sensitivity Normalization: 

Full

Calculate sensitivities by executing the object with c1 and c2 set to 10 and 0.1 respectively. Set the output times from 1 to 10. t contains time points, y contains simulation data, and sensMatrix is the sensitivity matrix containing sensitivities of y1 and y2 with respect to c1 and c2.

[t,y,sensMatrix] = f([10,0.1],[],[],1:10);

Retrieve the sensitivity information at simulation time = 5.

temp = sensMatrix{:};
sensMatrix2 = temp(t{:}==5,:,:);
sensMatrix2 = squeeze(sensMatrix2)
sensMatrix2 =

   35.5735   -5.8617
  -39.7255    5.7080

The rows of sensMatrix2 represent output factors (y1 and y2). The columns represent the input factors (c1 and c2).

$$sensMatrix2 = \left[ {\begin{array}{*{20}{c}}
{\begin{array}{*{20}{c}} {\frac{{\partial y1}}{{\partial c1}}}\\ {}\\
{\frac{{\partial y2}}{{\partial c1}}}
\end{array}}&{\begin{array}{*{20}{c}} {\frac{{\partial y1}}{{\partial
c2}}}\\ {}\\ {\frac{{\partial y2}}{{\partial c2}}} \end{array}}
\end{array}} \right]$$

Set the stop time to 15, without specifying the output times. In this case, the output times are the solver time points by default.

sd = f([10,0.1],15);

Retrieve the calculated sensitivities from the SimData object sd.

[t,y,outputs,inputs] = getsensmatrix(sd);

Plot the sensitivities of species y1 and y2 with respect to c1.

figure;
plot(t,y(:,:,1));
legend(outputs);
title('Sensitivites of species y1 and y2 with respect to parameter c1');
xlabel('Time');
ylabel('Sensitivity');

Plot the sensitivities of species y1 and y2 with respect to c2.

figure;
plot(t,y(:,:,2));
legend(outputs);
title('Sensitivites of species y1 and y2 with respect to parameter c2');
xlabel('Time');
ylabel('Sensitivity');

Alternatively, you can use sbioplot. Expand Run1 to select which simulation or sensitivity data to display.

sbioplot(sd);

You can also plot the sensitivity matrix using the time integral for the calculated sensitivities of y1 and y2. The plot indicates y1 and y2 are more sensitive to the parameter c1 than c2.

[~, in, out] = size(y);
result = zeros(in, out);
for i = 1:in
    for j = 1:out
        result(i,j) = trapz(t(:),abs(y(:,i,j)));
    end
end
figure;
hbar = bar(result);
haxes = hbar(1).Parent;
haxes.XTick = 1:length(outputs);
haxes.XTickLabel = outputs;
legend(inputs,'Location','NorthEastOutside');
ylabel('Sensitivity');

References

[1] Gillespie, D.T. (1977). Exact Stochastic Simulation of Coupled Chemical Reactions. The Journal of Physical Chemistry. 81(25), 2340–2361.

Was this topic helpful?