Syntax

Description

F = createSimFunction(model,params,observables,dosed) creates
a SimFunction objectF 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.

model — SimBiology modelSimBiology model object

Inputs of SimFunction F, specified as a
character vector, cell array of character vectors, or an empty cell
array {}. The character vectors represent the names
of model quantities (species, compartments, or parameters) that define
the inputs of F. Use an empty cell array {} to
create a SimFunction object that
has no parameters.

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

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

Dosed species or dose objects, specified as a character vector, cell array of character
vectors, vector of dose objects, or empty array []. Use
[] to specify no species are dosed during
simulation.

If it is a cell array of character vectors, it must be
1-by-N array, where N is the
number of dosed species names. You can use duplicate species names if you
plan to use multiple doses for the same
species when you run the SimFunction F. Using only
dosed species names contains no information on the dose properties. If you
have a dose object that contains parameterized properties such as Amount, use
the dose object as input instead of just species names to transfer such
parameter information to the created SimFunction
F.

If it is a vector of dose objects, it must be 1-by-N
vector, where N is the number of dose objects. If dose
objects have properties with nondefault numeric values, these values are
ignored and a warning is issued. Only TargetName,
DurationParameterName,
LagParameterName, and parameterized properties are used to create the SimFunction
object F, that is, to define the
Dosed property of F. For
details on how the Dosed property table is populated,
see Property Summary.

The number of dosed species defined here, that is, the
Dosed property of the created SimFunction object
F, must be consistent with the dose input argument
u of the SimFunction F
when you execute the object. In other words, the number of elements
(N) in the Dosed property of
F must be equal to the number of elements (columns)
in the cell array u. The order of dosed species in
Dosed must also match the order of dose tables in
u.

Alternate model values, specified as a variant or vector of
variant objects. These values are applied as the model baseline values
when the SimFunction object is created. If there
are multiple variants referring to the same model element, the last
occurrence is 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 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.

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.

Sensitivity output factors, specified as the comma-separated
pair consisting of 'SensitivityOutputs' and a cell
array of character vectors. The character vectors 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.

Sensitivity input factors, specified as the comma-separated
pair consisting of 'SensitivityInputs' and a cell
array of character vectors. The character vectors 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.

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.

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.

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

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.

Select a dose that represents a single meal of 78 grams of glucose at the start of the simulation.

singleMeal = sbioselect(m1,'Name','Single Meal');

Convert the dosing information to the table format.

mealTable = getTable(singleMeal);

Simulate the glucose-insulin response for a normal subject for 24 hours.

sbioplot(normSim([],24,mealTable));

Simulate the glucose-insulin response for a diabetic subject for 24 hours.

sbioplot(diabSim([],24,mealTable));

Perform a scan using variants

Suppose you want to perform a parameter scan using an array of variants that contain different initial conditions for different insulin impairments. For example, the model m1 has variants that correspond to the low insulin sensitivity and high insulin sensitivity. You can simulate the model for both conditions via a single call to the SimFunction object.