Doses let you increase the amount of a species in a SimBiology® model during simulation, either at specific time points or regular intervals. For example, you can use a dose object to model an instantaneous supply of a drug regimen during the simulation of a model. The increase in the amount of a species occurs only during simulation and does not alter the species value permanently (that is, the value in the model is not changed).
There are two types of dose objects.
SimBiology dose objects support the following dosing types.
|Dosing Strategy||Description||Dose Object Properties Configuration|
|Bolus||Instantaneous increase in the amount of drug in the compartment||To create a bolus dose, set the |
|Infusion||Increase of the drug at a fixed rate over a period of time, which is calculated from the dose amount||Unlike a bolus dose, you also need to specify the infusion
|Zero-order||Increase of the drug at a fixed rate calculated from the dose amount and dose duration||Unlike a bolus dose, you also need to create a zero-order
duration parameter and specify the duration parameter name
|First-order||Increase of the drug via first-order absorption kinetics||Unlike bolus, infusion, or zero-order, you need to create an additional reaction for the drug absorption.|
There are two common ways to create dose objects using the command-line interface.
One way is to create a dose object using the
adddose function. Another is to
create dose objects automatically from data containing dosing information. This
first approach is useful when you want to explore different dosing strategies
through simulation. The second approach is useful if you already have a data set
with dosing information and plan to use this dosing information in your simulation
or parameter estimation.
sbiodose creates a standalone
dose object that is not attached to any model. You can apply a standalone dose
to different models during simulation by specifying it as a dosing argument for
sbiosimulate, or attach it to
any model using
adddose. You can also use it
during parameter estimation using
adddose creates a dose object
and adds it to a model. You must set its
Active property to
true to apply the dose to the model during
The following examples show how to add a dose object to a one-compartment PK
sbiodose and set up the dose properties
manually. Alternatively, you can use the built-in PK models with different
dosing types. For details, see Create Pharmacokinetic Models.
|Bolus||Add a Series of Bolus Doses to a One-Compartment Model|
|Infusion||Add an Infusion Dose to a One-Compartment Model|
|Zero-order||Increase Drug Concentration in a One-Compartment Model via Zero-order Dosing|
|First-order||Increase Drug Concentration in a One-Compartment Model via First-order Dosing|
If you already have dosing data for one or more subjects or patients that you
would like to use in your parameter estimation, first create a
object from your data set. Use
createDoses function to
automatically generate an array of dose objects. You can then use the dose array
during parameter estimation using
sbiofitmixed. For a complete
workflow, see Modeling the Population Pharmacokinetics of Phenobarbital in Neonates.
You can interactively create and add doses using the SimBiology app. For details, see Diagram View.
You can specify some of the properties of
ScheduleDose objects by using model parameters. This
parameterization of dose properties gives you more flexibility in modeling different
dosing applications, such as scaling the dose amount by body weight.
RepeatDose properties that you can parameterize are:
ScheduleDose properties that can be parameterized are
DurationParameterName. You can set
RepeatDose properties, except
DurationParameterName, to either a numeric value or the name of a
model-scoped parameter (as a character vector or string).
You can make doses adaptive to events, such as increasing the dose amount when the drug concentration drops below some threshold. This adaptive feature of doses is useful for doses that are not instantaneous. Consider an IV infusion for a drug being added at a fixed rate over a fixed duration. If an event modifies a dose parameter while this dose is in progress, you have two options:
Stop the ongoing dose if any relevant parameter values change by
EventMode property of the dose object
Continue the ongoing dose to completion, and updated parameter values
affect only subsequent doses by setting
For details, see the
EventMode property. For illustrated examples, see Scale Dose Amount by Body Weight and Change Dose Behavior In Response to Changes in Model Parameters.
If you parameterize a dose property and enable dimensional analysis, the unit
of the dose property (dose unit) is validated. The dose unit is valid either if
it is empty or if it exactly matches the unit of the parameter. If the dose unit
is invalid, SimBiology issues a warning in the command line and uses the unit of
the parameter instead. To remove the warning, set the dose unit to empty
'') or to the same unit as the parameter unit.
In the SimBiology app, the text
(unused) appears next to
the corresponding unit field in the Block Property Editor
or Doses tab, meaning that SimBiology is using the
parameter unit instead of the dose unit during simulation. For example, this
figure shows the details of the repeat dose object param_dose
in the Block Property Editor. The
TimeUnits option is designated as
unused. Instead, SimBiology uses the unit of the
parameter StartTimeParam during simulation. The
Amount and Rate properties are not
parameterized, and hence the selected AmountUnits and
RateUnits options are used. To see the units of
referenced parameters, click the indicator next to the corresponding property.
The TimeUnits option corresponds to both the
StartTime and Interval
To simulate models containing doses, use a deterministic (ODE or SUNDIALS) solver. Stochastic solvers do not support doses. For details, see Choosing a Simulation Solver.