Doses

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

Representing Doses

There are two types of dose objects.

SimBiology dose objects support the following dosing types.

Dosing StrategyDescriptionDose Object Properties Configuration
BolusInstantaneous increase in the amount of drug in the compartmentTo create a bolus dose, set the Amount and TargetName properties of a dose object. You might also need to configure other properties such as RepeatCount, Interval, or scheduled dose times (Time) if you are applying a series of doses. For details on these properties, see ScheduleDose object and RepeatDose object .
InfusionIncrease of the drug at a fixed rate over a period of time, which is calculated from the dose amountUnlike a bolus dose, you also need to specify the infusion rate (Rate property) of the dose object.
Zero-orderIncrease of the drug at a fixed rate calculated from the dose amount and dose durationUnlike a bolus dose, you also need to create a zero-order duration parameter and specify the duration parameter name (DurationParameterNameproperty) of the dose object.
First-orderIncrease of the drug via first-order absorption kineticsUnlike bolus, infusion, or zero-order, you need to create an additional reaction for the drug absorption.

Creating Doses Programmatically

There are two common ways to create dose objects using the command-line interface. One way is to create a dose object using the sbiodose or 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.

Create a Dose Object Using sbiodose or adddose

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 sbiofit or sbiofitmixed.

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

The following examples show how to add a dose object to a one-compartment PK model using 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.

Create Dose Objects from Dosing Data

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 groupedData 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 sbiofit or sbiofitmixed. For a complete workflow, see Modeling the Population Pharmacokinetics of Phenobarbital in Neonates.

Creating Doses Graphically

You can interactively create and add doses using the SimBiology desktop. For details, see Diagram View.

Parameterized and Adaptive Doses

You can specify some of the properties of RepeatDose and 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: Amount, Rate, Interval, StartTime, RepeatCount, LagParameterName, and DurationParameterName. ScheduleDose properties that can be parameterized are LagParameterName and DurationParameterName. You can set these RepeatDose properties, except LagParameterName and 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 setting the EventMode property of the dose object to 'stop'.

  • Continue the ongoing dose to completion, and updated parameter values affect only subsequent doses by setting EventMode to 'continue'.

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.

Units Validation on Parameterized Dose Properties

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 desktop, 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 properties.

Simulation Solvers for Models Containing Doses

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.

See Also

| | |

Related Topics