# Dose Control Parameters (DCP)

`using Pumas`

The `@dosecontrol`

part of a `PumasModel`

allows for specifying special pre-processed parameters known as the Dose Control Parameters (DCP). Unlike standard parameters which are for use in the proceeding blocks, the DCP are used to modify the internal event handling of Pumas. The DCP are defined as follows:

`lags`

: the lag of the dose. A dose with a lag will take place at time`t = dosetime + lag`

. Default is zero.`bioav`

: the bioavailability of the dose. For bolus doses, the effective dose is equal to`bioav * amt`

where`amt`

is the dose amount from the dosage regimen. Default is`1`

. For infusions, Pumas currently follows NONMEM and applies the bioavailability to the`duration`

such that the effective duration is`bioav * duration`

from the dosage regimen. If you wish to keep the duration and only modify the effective dose it is possible to adjust the`rate`

dose control parameter instead.`rate`

: the rate of the dosing.`duration`

: the duration of the dose.

`rate`

and `duration`

handling are intertwined and always satisfy the relation `amt = rate * duration`

. Any two of the values are given, the third is automatically defined. If both `rate`

and `duration`

are specified, then an error will be given unless `amt = rate * duration`

is satisfied.

## Input Definition

If a DCP is defined as a scalar, then it applies to all doses.

`Pumas.@dosecontrol`

— Macro@dosecontrol

defines dose control parameters as a function of fixed and random effects. Options include `bioav`

, `duration`

, `lag`

, and `rate`

. Must be used in an `@model`

block. For example:

```
@model begin
@dosecontrol begin
bioav = (Depot1 = max(0, θ[5]), Depot2 = clamp(1 - θ[5], 0.0, 1.0), Central = 1)
lags = (Depot1 = 0, Depot2 = max(0.1, θ[6]), Central = 0)
end
end
```

For example, if a `@dosecontrol`

block contains the definition:

```
@dosecontrol begin
lags = θ
end
```

and `θ`

is a scalar, then every dose will be lagged by the parameter `θ`

. If there are several dynamic variables (compartments) they can have individual lags associated with dosing into them like the following:

```
@pre begin
lags = (; Depot1 = θ, Depot2 = 0.5)
end
```

where the lag of dosing into `Depot1`

is controlled by `θ`

and the lag of dosing into `Depot2`

is fixed at `0.5`

. Omitting dynamic variables in this way of specifying DCPs implicitly sets the value of the missing variables to the default value as specified at the top. Likewise, if a DCP is defined as a collection, then the value of the collection corresponding to the `cmt`

-index of the dose specifies the DCP. For example:

```
@pre begin
lags = [2, 0]
end
```

implies that any dose into `cmt=1`

will have a lag of `2`

, while any dose into `cmt=2`

will have a lag of `0`

.

## Timing and Dose Control Parameters

It is important to understand when dose control parameters affect dosage regimens. For example, let us consider a dosage regimen consisting of two bolus doses:

```
dr1 = DosageRegimen(10; time = 1, cmt = :Central)
dr5 = DosageRegimen(10; time = 5, cmt = :Central)
dr = DosageRegimen(dr1, dr5)
```

If the model has the following `@dosecontrol`

block:

```
@dosecontrol begin
bioav = (; Central = 1 / t)
end
```

Then the effective bolus doses will be `amt * bioav = 10 * 1 / 1 = 10`

for the first dose and `amt * bioav = 10 * 1 / 5 = 2`

for the second dose. However, if the dose is an oral dose, and we want to use a first order absorption model the following does not affect the transfer from the `Depot`

to the `Central`

compartment continually throughout time

```
# doses
dr1 = DosageRegimen(10; time = 1, cmt = :Depot)
dr5 = DosageRegimen(10; time = 5, cmt = :Depot)
dr = DosageRegimen(dr1, dr5)
# dose control specification
@model begin
# ...
@dosecontrol begin
bioav = (; Depot = 0.5, Central = 1 / t)
end
# ...
end
```

The behavior of the above doses and model specification means that we get an effective dose of `amt * bioav = 10 * 0.5 = 5`

at both time 1 and time 5 into `Depot`

, and then the absorption from the gut to the blood stream follows whatever dynamic model we specified in the omitted sections indicated by `...`

.

Another important thing to know and notice is that we follow NONMEM's behavior when it comes to bioavailability and infusions. Consider the following:

```
# doses
dr1 = DosageRegimen(10; rate = 0.5, time = 1, cmt = :Central)
dr5 = DosageRegimen(10; rate = 0.5, time = 5, cmt = :Central)
dr = DosageRegimen(dr1, dr5)
# dose control specification
@model begin
# ...
@dosecontrol begin
bioav = (; Central = 1 / t)
end
# ...
end
```

This model will alter the *duration* to ensure that `duration * rate == amt`

. As a result, we get `duration = bioav * av / rate`

. To keep the duration constant and have the rate adjust instead, you should not use `bioav`

, but rather apply the bioavailability fraction directly to the rate. The above will then effectively have two infusions: one starting at `t=1.0`

and lasting for `bioav * amt / rate = (1 / 1) * 10 / 0.5 = 20`

units of time and one starting at `t=5`

and lasting `bioav * amt / rate = (1 / 5) * 10 / 0.5 = 4`

time units.