Main Content

RepeatDose object

Define drug dosing protocol

Description

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

Each dose is the same amount, as defined by the Amount property, and given at equally spaced times, as defined by the Interval property. The RepeatCount property defines the number of injections in the series, excluding the initial injection. The Rate property defines how fast each dose is given.

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 RepeatDose 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 RepeatDose objects on a model and if there are duplicate specifications for a property value, the last occurrence for the property value in the array of dose, is used during simulation. You can find out which dose is applied last by looking at the indices of the dose objects stored on the model.

You can set these dose properties to model parameters: Amount, Interval, Rate, RepeatCount, StartTime, LagParameterName and DurationParameterName. You can set these properties, except LagParameterName and DurationParameterName, to either a numeric value or 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.

Constructor Summary

sbiodoseConstruct dose object

Method Summary

Methods for RepeatDose objects

copyobjCopy SimBiology object and its children
deleteDelete SimBiology object
displayDisplay summary of SimBiology object
getGet SimBiology object properties
getTable(ScheduleDose,RepeatDose)Return data from SimBiology dose object as table
renameRename SimBiology model component and update expressions
setSet SimBiology object properties
setTable(ScheduleDose,RepeatDose)Set dosing information from table to dose object

Property Summary

Properties for RepeatDose objects

ActiveIndicate object in use during simulation
AmountAmount of dose
AmountUnitsDose amount units
DurationParameterNameParameter specifying length of time to administer a dose
EventModeDetermine how events that change dose parameters affect in-progress dosing
IntervalTime between doses
LagParameterNameParameter specifying time lag for dose
NameSpecify name of object
NotesHTML text describing SimBiology object
ParentIndicate parent object
RateRate of dose
RateUnitsUnits for dose rate
RepeatCountDose repetitions
StartTimeStart time for initial dose time
TagSpecify label for SimBiology object
TargetNameSpecies receiving dose
TimeUnitsShow time units for dosing and simulation
TypeDisplay SimBiology object type
UserDataSpecify data to associate with object

Examples

collapse all

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');

Figure contains an axes object. The axes object contains 2 objects of type line. These objects represent drug, A.

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');

Figure contains an axes object. The axes object contains 2 objects of type line. These objects represent 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');

Figure contains an axes object. The axes object contains 2 objects of type line. These objects represent drug, A.

Version History

Introduced in R2010a