SimBiology.ScheduleDose

Define drug dosing protocol

Description

A SimBiology.ScheduleDose object defines a series of doses to the amount of a species during a simulation. The TargetName property defines the species that receives the dose.

Each dose can have a different amount, as defined by an amount array in the Amount property. Each dose can be given at specified times, as defined by a time array in the Time property. A rate array in the Rate property defines how fast each dose is given. At each time point in the time array, a dose is given with the corresponding amount and rate.

To use a dose object in a simulation you must add the dose object to a model object and set the Active property of the dose object to true. Set the Active property to true if you always want the dose to be applied before simulating the model.

Warning

The Active property of the ScheduleDose object will be removed in a future release. Explicitly specify a dose or an array of doses as an input argument when you simulate a model using sbiosimulate.

When there are multiple active ScheduleDdose objects on a model, and there are duplicate specifications for a property value, the simulation uses the last occurrence for the property value in the array of doses. You can find out which dose you applied last by looking at the indices of the dose objects stored on the model.

You can parameterize the LagParameterName and DurationParameterName properties by setting the property value to the name of a model-scoped parameter (as a character vector or string). Parameterizing dose properties provides more flexibility for different dosing applications, such as scaling the dose amount by body weight. For details, see Parameterized and Adaptive Doses.

Tip

You can create a combination of bolus and infusion doses by setting the rate property of a ScheduleDose object to a vector containing zeros and non-zeros.

Creation

You can create a SimBiology.ScheduleDose object using any of the following functions.

• adddose (model) — Creates a dose object and adds it to a model. You must set its Active property to true to apply the dose the model during simulation.

• 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 the dose as a dosing input. Update TargetName and other properties as appropriate when you are applying to different models.

For details, see Doses in SimBiology Models.

Properties

Active — Flag to use dose object during simulation

false or 0 (default) | true or 1

Flag to use the dose object during simulation, specified as a numeric or logical 1 (true) or 0 (false).

Data Types: double | logical

Amount — Dose amount

empty column vector (default) | numeric column vector

Dose amount, specified as a numeric column vector. The property defines an increase in the amount of a SimBiology^® species that receives a dose.

A ScheduleDose object defines a series of doses. Each dose can have a different amount, as defined by an amount array in the Amount property, and given at specified times, as defined by a time array in the Time property. A rate array in the Rate property defines how fast each dose is given. At each time point in the time array, a dose is given with the corresponding amount and rate.

Data Types: double | char | string

AmountUnits — Dose amount units

empty character vector (default) | character vector | string scalar

Dose amount units, specified as a character vector or string scalar.

This property defines units for the Amount property.

If the TargetName property defines a species, then AmountUnits for a dose must be a chemical amount (for example, milligram, mole, or molecule), not a concentration. To get a list of the defined units in the library, use the sbioshowunits function. To add a user-defined unit to the list, see sbioaddtolibrary.

Note

SimBiology uses units including empty units in association with DimensionalAnalysis and UnitConversion features.

• When DimensionalAnalysis and UnitConversion are both false, units are not used. However, SimBiology still performs a minimum level of dimensional analysis to decide whether a reaction rate is in dimensions of amount/time or concentration/time.

• When DimensionalAnalysis is true and UnitConversion is false, units (if not empty) must have consistent dimensions so that SimBiology can perform dimensional analysis. However, the units are not converted.

• When UnitConversion is set to true (which requires DimensionalAnalysis to be true), SimBiology performs a dimensional analysis and converts everything to consistent units. Hence, you must specify consistent units, and no units can be empty. If you have a dimensionless parameter, you must still set its unit to dimensionless.

Data Types: char | string

DurationParameterName — Parameter specifying length of time to administer a dose

empty character vector (default) | character vector | string scalar

Parameter specifying length of time to administer a dose, specified as a character vector or string scalar.

Specify the name of a parameter object that is scoped to a model. This parameter defines the length of time it takes to administer a dose.

You can parameterize the property by setting it to the name of a model-scoped parameter that is not being modified by a repeated assignment rule, an algebraic rule, or a rate rule. However, the parameter can be modified by an event.

Data Types: char | string

EventMode — Flag to determine whether to continue in-progress dosing

"stop" (default) | "continue"

Flag to determine whether to continue the in-progress dosing when an event changes a parameter that is referenced by a dose property, specified as "stop" or "continue".

If EventMode is set to "continue", the ongoing dose continues to completion when the event changes dose parameters, and updated parameters affect only subsequent doses. If EventMode is set to "stop", the ongoing dose stops immediately when dose parameters change, and subsequent doses use the updated parameters.

To decide whether a parameter has been changed, SimBiology compares the old value of a parameter to the new value. For instance, the following event does not change the doseStartTime parameter value: addevent(model,'time >= 5','doseStartTime = doseStartTime * 1').

Any change in dose parameters affects the schedule of doses generated. If an event changes dose parameters, SimBiology updates the dose schedule, ignores any doses scheduled before the current simulation time, and applies only the subsequent doses. Suppose that you have parameterized the StartTime property of a dose. Updating the parameter with an event causes to regenerate the dose schedule. If there are any previously-scheduled doses before the current simulation time, they are ignored.

By default, SimBiology uses the following MATLAB^® expression to generate a list of dose times (dose schedule) whenever an event changes any dose parameter, using the updated parameter values:

$$scheduledDoseTimes\text{ = }StartTime\text{ + (0:}RepeatCount\text{) * }Interval\text{ + }Lag$$,

where StartTime, RepeatCount, and Interval are properties of the dose object. Lag is the time lag parameter for a dose, referenced by the LagParameterName property.

Data Types: char | string

LagParameterName — Parameter specifying time lag for dose

empty character vector (default) | character vector | string

Parameter specifying time lag for the dose, specified as a character vector or string scalar.

Specify the name of a parameter object that is scoped to a model. The parameter defines the length of time it takes for the dose to reach its target after being introduced.

You can parameterize the property by setting it to the name of a model-scoped parameter that is not being modified by a repeated assignment rule, an algebraic rule, or a rate rule. However, the parameter can be modified by an event.

Data Types: char | string

Name — SimBiology.ScheduleDose object name

character vector | string

SimBiology.ScheduleDose object name, specified as a character vector or string.

For details on requirements and recommendations for naming SimBiology components, see Guidelines for Naming Model Components.

Data Types: char | string

Notes — Additional information

empty character array (default) | character vector | string

Additional information that you can add for SimBiology.ScheduleDose, specified as a character vector or string.

Data Types: char | string

Parent — Parent object

Read-only: SimBiology.Model object

This property is read-only.

Parent object, specified as a SimBiology.Model object.

The Parent property indicates accessibility of the object. The object is accessible to the Parent object and other objects within the Parent object.

Rate — Rate of dose

empty column vector (default) | numeric column vector

Rate of a dose, specified as a numeric column vector.

This property defines how fast a dose is given. By default, the rate is an empty column vector, which means the dose is interpreted as a bolus (instantaneous) dose.

Note

If you set the Rate property of a dose, you must also specify the Amount property of the dose, and set the DurationParameterName property to ''. This is because the duration is calculated from the amount and rate.

Tip

You can create a combination of bolus and infusion doses by setting the rate property of a ScheduleDose object to a vector containing zeros and non-zeros.

Data Types: double | char | string

RateUnits — Units for dose rate

empty character vector (default) | character vector | string scalar

Units for the dose rate, specified as a character vector or string scalar.

You can use units from the units library with dimensions of amount divided by time, such as mole/second. You cannot use units of concentration divided by time, such as mole/liter/second.

Note

SimBiology uses units including empty units in association with DimensionalAnalysis and UnitConversion features.

• When DimensionalAnalysis and UnitConversion are both false, units are not used. However, SimBiology still performs a minimum level of dimensional analysis to decide whether a reaction rate is in dimensions of amount/time or concentration/time.

• When DimensionalAnalysis is true and UnitConversion is false, units (if not empty) must have consistent dimensions so that SimBiology can perform dimensional analysis. However, the units are not converted.

• When UnitConversion is set to true (which requires DimensionalAnalysis to be true), SimBiology performs a dimensional analysis and converts everything to consistent units. Hence, you must specify consistent units, and no units can be empty. If you have a dimensionless parameter, you must still set its units to dimensionless.

Data Types: char | string

Tag — Object label

empty character array (default) | character vector | string

Object label, specified as a character vector or string.

Tip

Use this property to group objects and then use sbioselect to retrieve. For example, use the Tag property of reaction objects to group synthesis or degradation reactions. You can then retrieve all synthesis reactions using sbioselect. Similarly, for species objects you can enter and store classification information, for example, membrane protein, transcription factor, enzyme classifications, or whether a species is an independent variable. You can also enter the full form of the name of the species.

Data Types: char | string

TargetName — Name of species receiving dose

empty character vector (default) | character vector | string

Name of species receiving the dose, specified as a character vector or string scalar.

The dose amount increases the species amount at each time point or time interval defined by the dose.

The value of TargetName is the name of a species. If the model has more than one species with the same name, TargetName is defined as compartmentName.speciesName, where compartmentName is the name of the compartment containing the species.

Data Types: char | string

Time — Schedule dose times

empty numeric vector (default) | numeric column vector

Schedule dose times, specified as a numeric column vector.

This property defines the times to give a dose. Each dose can have a different amount, as defined by an amount array in the Amount property, and given at specified times, as defined by a time array in the Time property. A rate array in the Rate property defines how fast each dose is given. At each time point in the time array, a dose is given with the corresponding amount and rate.

Data Types: double

TimeUnits — Time units for dosing

empty character vector (default) | character vector | string scalar

Time units for dosing, specified as a character vector or string scalar. This property specifies the units for the Time property.

If you change the value of the TimeUnits property, make sure that you update the values of the Time property accordingly.

Data Types: char | string

Type — Object type

Read-only: 'repeatdose' (default)

This property is read-only.

Object type, specified as 'repeatdose'. When you create a SimBiology object, the value of Type is automatically defined.

Data Types: char

UserData — Data to associate with object

scalar | vector | string | ...

Data to associate with the object, specified as a numeric scalar, vector, string, or any other MATLAB data type.

The object does not use this data directly, but you can access it using dot notation or get.

Object Functions

copyobj	Copy SimBiology object and its children
delete	Delete SimBiology object
display	Display summary of SimBiology object
get	Get SimBiology object properties
getTable(ScheduleDose,RepeatDose)	Return data from SimBiology dose object as table
rename	Rename SimBiology model component and update expressions
set	Set SimBiology object properties
setTable(ScheduleDose,RepeatDose)	Set dosing information from table to dose object

Examples

Scale Dose Amount by Body Weight

Parameterize the Amount property of a dose to scale it by the body weight of a patient.

Create a simple model with linear elimination and an amount parameter.

model                      = sbiomodel('simple model');
compartment                = addcompartment(model,'Central',1);
compartment.CapacityUnits  = 'liter';
species                    = addspecies(model,'drug');
species.InitialAmountUnits = 'milligram';

% Elimination rate
elimParam                  = addparameter(model,'kel',0.1);
elimParam.ValueUnits       = '1/hour';

% Elimination reaction
reaction                   = addreaction(model,'drug -> null');
reaction.ReactionRate      = 'kel*drug';
amountParam                = addparameter(model,'A',50);
amountParam.ConstantValue  = false;
amountParam.ValueUnits     = 'milligram'

amountParam = 
   SimBiology Parameter Array

   Index:    Name:    Value:    Units:   
   1         A        50        milligram

Create a dose with its Amount property set to the amount parameter 'A'.

dose                       = adddose(model,'adaptive dose','repeat');
dose.Amount                = 'A';

Set other dose properties.

dose.TargetName            = 'drug';
dose.StartTime             = 0;
dose.TimeUnits             = 'hour';
dose.Interval              = 24;
dose.RepeatCount           = 7;

Add a parameter to represent the body weight.

weightParam            = addparameter(model,'weight', 80);
weightParam.ValueUnits = 'kilogram';

Scale the dose amount by the body weight using an initial assignment rule.

scaleParam             = addparameter(model,'doseAmountPerWeight',0.6);
scaleParam.ValueUnits  = 'milligram/kilogram';
rule                   = addrule(model,'A = weight*doseAmountPerWeight','initialAssignment');

Simulate the model for 7 days and plot the results.

configset               = getconfigset(model);
configset.StopTime      = 7*24;
configset.TimeUnits     = 'hour';
[time, drugAndAmount]   = sbiosimulate(model,dose);
plot(time, drugAndAmount);
legend('drug','A');

Change Dose Behavior In Response to Changes in Model Parameters

Create a simple model with linear elimination, an amount parameter, and a rate parameter.

model                      = sbiomodel('simple model');
compartment                = addcompartment(model,'Central',1);
compartment.CapacityUnits  = 'liter';
species                    = addspecies(model,'drug');
species.InitialAmountUnits = 'milligram';

% Elimination rate
elimParam                  = addparameter(model,'kel',0.1);
elimParam.ValueUnits       = '1/hour';

% Elimination reaction
reaction                   = addreaction(model,'drug -> null');
reaction.ReactionRate      = 'kel*drug';

% Add amount and rate parameters
amountParam                = addparameter(model,'A',50);
amountParam.ConstantValue  = false;
amountParam.ValueUnits     = 'milligram'

amountParam = 
   SimBiology Parameter Array

   Index:    Name:    Value:    Units:   
   1         A        50        milligram

rateParam                  = addparameter(model,'R',10);
rateParam.ValueUnits       = 'milligram/hour'

rateParam = 
   SimBiology Parameter Array

   Index:    Name:    Value:    Units:        
   1         R        10        milligram/hour

Create a dose with its Amount and Rate properties set to the amount and rate parameters 'A' and 'R', respectively.

dose                       = adddose(model,'adaptive dose','repeat');
dose.Amount                = 'A';
dose.Rate                  = 'R';

Set other dose properties.

dose.TargetName            = 'drug';
dose.StartTime             = 0;
dose.TimeUnits             = 'hour';
dose.Interval              = 24;
dose.RepeatCount           = 7;

Prepare the configuration set to simulate the model for 7 days.

configset           = getconfigset(model);
configset.StopTime  = 7*24;
configset.TimeUnits = 'hour';

Add an event to reset the dose amount to 10 at time >= 26.

event = addevent(model,'time >= 26','A = 10');

Set the EventMode property to 'stop'. This setting causes any ongoing dose event to stop at 26 hours.

dose.EventMode = 'stop';

Simulate the model. The second dose event stops at 26 hours, and the subsequent dose events continue with the new dose amount of 10.

[time, drugAndAmount] = sbiosimulate(model,dose);
figure
plot(time, drugAndAmount); 
legend('drug','A');

Alternatively, you can allow the ongoing dose event to finish before applying the new dose amount by setting EventMode to 'continue'.

dose.EventMode = 'continue';

Simulate the model. In this case, the second dose event continues to 26 hours.

[time, drugAndAmount] = sbiosimulate(model,dose);
figure
plot(time, drugAndAmount); 
legend('drug','A');

Change Dose Behavior In Response to Changes in Model Parameters

Create a simple model with linear elimination, an amount parameter, and a rate parameter.

model                      = sbiomodel('simple model');
compartment                = addcompartment(model,'Central',1);
compartment.CapacityUnits  = 'liter';
species                    = addspecies(model,'drug');
species.InitialAmountUnits = 'milligram';

% Elimination rate
elimParam                  = addparameter(model,'kel',0.1);
elimParam.ValueUnits       = '1/hour';

% Elimination reaction
reaction                   = addreaction(model,'drug -> null');
reaction.ReactionRate      = 'kel*drug';

% Add amount and rate parameters
amountParam                = addparameter(model,'A',50);
amountParam.ConstantValue  = false;
amountParam.ValueUnits     = 'milligram'

amountParam = 
   SimBiology Parameter Array

   Index:    Name:    Value:    Units:   
   1         A        50        milligram

rateParam                  = addparameter(model,'R',10);
rateParam.ValueUnits       = 'milligram/hour'

rateParam = 
   SimBiology Parameter Array

   Index:    Name:    Value:    Units:        
   1         R        10        milligram/hour

Create a dose with its Amount and Rate properties set to the amount and rate parameters 'A' and 'R', respectively.

dose                       = adddose(model,'adaptive dose','repeat');
dose.Amount                = 'A';
dose.Rate                  = 'R';

Set other dose properties.

dose.TargetName            = 'drug';
dose.StartTime             = 0;
dose.TimeUnits             = 'hour';
dose.Interval              = 24;
dose.RepeatCount           = 7;

Prepare the configuration set to simulate the model for 7 days.

configset           = getconfigset(model);
configset.StopTime  = 7*24;
configset.TimeUnits = 'hour';

Add an event to reset the dose amount to 10 at time >= 26.

event = addevent(model,'time >= 26','A = 10');

Set the EventMode property to 'stop'. This setting causes any ongoing dose event to stop at 26 hours.

dose.EventMode = 'stop';

Simulate the model. The second dose event stops at 26 hours, and the subsequent dose events continue with the new dose amount of 10.

[time, drugAndAmount] = sbiosimulate(model,dose);
figure
plot(time, drugAndAmount); 
legend('drug','A');

Alternatively, you can allow the ongoing dose event to finish before applying the new dose amount by setting EventMode to 'continue'.

dose.EventMode = 'continue';

Simulate the model. In this case, the second dose event continues to 26 hours.

[time, drugAndAmount] = sbiosimulate(model,dose);
figure
plot(time, drugAndAmount); 
legend('drug','A');

Estimate Time Lag and Duration of a Dose

This example shows how to estimate the time lag before a bolus dose was administered and the duration of the dose using a one-compartment model.

Load a sample data set.

load lagDurationData.mat

Plot the data.

plot(data.Time,data.Conc,'x')
xlabel('Time (hour)')
ylabel('Conc (milligram/liter)')

Convert to groupedData.

gData = groupedData(data);
gData.Properties.VariableUnits = {'hour','milligram/liter'};

Create a one-compartment model.

pkmd                    = PKModelDesign;
pkc1                    = addCompartment(pkmd,'Central');
pkc1.DosingType         = 'Bolus';
pkc1.EliminationType    = 'linear-clearance';
pkc1.HasResponseVariable = true;
model                   = construct(pkmd);
configset               = getconfigset(model);
configset.CompileOptions.UnitConversion = true;

Add two parameters that represent the time lag and duration of a dose. The lag parameter specifies the time lag before the dose is administered. The duration parameter specifies the length of time it takes to administer a dose.

lagP = addparameter(model,'lagP');
lagP.ValueUnits = 'hour';
durP = addparameter(model,'durP');
durP.ValueUnits = 'hour';

Create a dose object. Set the LagParameterName and DurationParameterName properties of the dose to the names of the lag and duration parameters, respectively. Set the dose amount to 10 milligram which was the amount used to generate the data.

dose                = sbiodose('dose');
dose.TargetName     = 'Drug_Central';
dose.StartTime      = 0;
dose.Amount         = 10;
dose.AmountUnits    = 'milligram';
dose.TimeUnits      = 'hour';
dose.LagParameterName = 'lagP';
dose.DurationParameterName = 'durP';

Map the model species to the corresponding data.

responseMap = {'Drug_Central = Conc'};

Specify the lag and duration parameters as parameters to estimate. Log-transform the parameters. Initialize them to 2 and set the upper bound and lower bound.

paramsToEstimate    = {'log(lagP)','log(durP)'};
estimatedParams     = estimatedInfo(paramsToEstimate,'InitialValue',2,'Bounds',[1 5]);

Perform parameter estimation.

fitResults = sbiofit(model,gData,responseMap,estimatedParams,dose,'fminsearch')

fitResults = 
  OptimResults with properties:

                   ExitFlag: 1
                     Output: [1×1 struct]
                  GroupName: One group
                       Beta: [2×4 table]
         ParameterEstimates: [2×4 table]
                          J: [11×2 double]
                       COVB: [2×2 double]
           CovarianceMatrix: [2×2 double]
                          R: [11×1 double]
                        MSE: 0.0024
                        SSE: 0.0213
                    Weights: []
              LogLikelihood: 18.7511
                        AIC: -33.5023
                        BIC: -32.7065
                        DFE: 9
             DependentFiles: {1×2 cell}
                       Data: [11×2 groupedData]
    EstimatedParameterNames: {'lagP'  'durP'}
             ErrorModelInfo: [1×3 table]
         EstimationFunction: 'fminsearch'

Display the result.

fitResults.ParameterEstimates

ans=2×4 table
      Name      Estimate    StandardError    Bounds
    ________    ________    _____________    ______

    {'lagP'}     1.986        0.0051568      1    5
    {'durP'}     1.527         0.012956      1    5

plot(fitResults)

Version History

Introduced in R2010a

R2024a: Having duplicate model component names is no longer allowed

• When you load a model that contains duplicate names, SimBiology automatically updates those names. SimBiology disambiguates the duplicate names by adding a suffix "_N", where N is the first positive integer that results in a unique name. If there is an existing suffix, N will be incremented from that suffix. For example, if there are two model components named x_3, the function updates one of the names to x_4. If the existing suffix has leading zeros, the function omits the zeros in the new name. For instance, if x_003 is a duplicate name, it gets renamed to x_4. However, the function assumes that names with leading zeros and without leading zeros are different. For instance, x_005 and x_5 are considered to be different names.

• SimBiology issues an error if multiple model components (model, compartment, species, parameter, reaction, rule, event, observable, dose, and variant) have the same name. Within a single model, these components are required to have unique names even when they are of different types with the following two exceptions:

  • Species in different compartments can have the same name.

  • Parameters can have the same name if they are scoped to different parents. Specifically, you can use the same name for a model-scoped parameter and reaction-scoped parameters, where each reaction-scoped parameter belongs to a different reaction.

  For details on how to reference model component names in expressions, see Guidelines for Referencing Names in Expressions.

R2022b: Having duplicate model component names issues a warning

SimBiology issues a warning if multiple model components have the same name.

R2022a: Having duplicate model component names will not be allowed in a future release

SimBiology will not allow you to have duplicate names for model components within a model.

R2019b: Value of the Amount, Rate, and Time properties is a column vector

The value of the Amount, Rate, and Time properties is a column vector instead of a row vector. The default value for each property is 0x1 empty double column vector, instead of [].