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.

@dosecontrol

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