adddose

Add dose object to model

Syntax

outDose = adddose(modelObj,doseName)

outDose = adddose(modelObj,doseName,doseType)

outDose = adddose(modelObj,doseName,inDose)

Description

outDose = adddose(modelObj,doseName) creates a SimBiology.RepeatDose object outDose, assigns doseName to the dose property Name, adds the dose object to the SimBiology^® model object modelObj, and assigns modelObj to the dose property Parent. To apply the dose in your simulation, set the Active property of outDose to true.

Note

Alternatively, you can create a dose object using sbiodose as a standalone dose object, which you can apply to different models. For details, see Creating Doses Programmatically.

outDose = adddose(modelObj,doseName,doseType) also specifies the type of dose to create and add to the model.

outDose = adddose(modelObj,doseName,inDose) adds an existing dose object inDose to the model, copies the dose object to the second dose object outDose, and assigns modelObj to the outDose property Parent.

Examples

Add an Infusion Dose

This example shows how to add a constant-rate infusion dose to a one-compartment model.

Background

Suppose you have a one-compartment model with a species named drug that represents the total amount of drug in the body. The drug is removed from the body via the first-order elimination represented by the reaction drug -> null, with the elimination rate constant ke. In other words, the drug concentration versus the time profile follows the monoexponential decline $$C_t=C_0{e}^{-k_{e}t}$$, where $$C_t$$ is the drug concentration at time t, $$C_0$$ is the initial concentration, and ke is the elimination rate constant. This example shows how to set up such a one-compartment model and add an infusion dose at a constant rate of 10 mg/hour for the total dose amount of 250 mg.

Create a One-Compartment Model

Create a SimBiology model named onecomp.

m1 = sbiomodel('onecomp');

Define the elimination of the drug from the system by adding a reaction drug -> null to the model.

r1 = addreaction(m1,'drug -> null');

The species drug is automatically created and added to the compartment. The null species is a reserved species that acts as a sink in this reaction.

Add a mass action kinetic law to the reaction. This kinetic law defines the drug elimination to follow the first-order kinetics.

k1 = addkineticlaw(r1,'MassAction');

Define the elimination rate parameter ke and add it to the kinetic law.

p1 = addparameter(k1,'ke','Value',1.0,'ValueUnits','1/hour');

Specify the rate parameter ke as the forward rate parameter of the reaction by setting the ParameterVariableNames property of kinetic law object k1. This allows SimBiology to determine the reaction rate for drug -> null reaction.

k1.ParameterVariableNames = 'ke';

Set Up an Infusion Dose

Add a dose object to the model using the adddose method. Specify the amount of the dose (Amount), the dose target (TargetName), and the infusion rate (Rate). You also need to set the Active property of the dose object to true so that the dose is applied to the model during simulation.

d1 = adddose(m1,'InfusionDose');
d1.Amount = 250;
d1.TargetName = 'drug';
d1.Rate = 10;
d1.RateUnits = 'milligram/hour';
d1.Active = true;

Simulate the Model

Change the simulation stop time to 48 hours to see the complete time course. Set the compartment unit to liter.

cs = getconfigset(m1);
cs.StopTime = 48;
cs.TimeUnits = 'hour';
c1 = m1.Compartments;
c1.Units = "liter";
sd = sbiosimulate(m1);

Plot Results

Plot the concentration versus the time profile of the drug in the system.

sbioplot(sd);

Input Arguments

modelObj — SimBiology model

Model object

SimBiology model, specified as a Model object.

doseName — Name of dose

character vector | string scalar

Name of the dose object to add to the model, specified as a character vector or string scalar.

Data Types: char | string

doseType — Type of dose

"repeat" (default) | "schedule"

Type of the dose object, specified as "repeat" or "schedule". By default, the function creates and adds a SimBiology.RepeatDose object. Use "schedule" to add a SimBiology.ScheduleDose object instead.

Data Types: char | string

inDose — Dose to add

SimBiology.RepeatDose | SimBiology.ScheduleDose

Dose to add to the model, specified as a SimBiology.RepeatDose or SimBiology.ScheduleDose object.

Output Arguments

outDose — Added dose

SimBiology.RepeatDose | SimBiology.ScheduleDose

Added dose, returned as a SimBiology.RepeatDose or SimBiology.ScheduleDose object.

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.