Superposition

superposition(df::DataFrame; kwargs...)

Compute a superposition profile from a single-dose (non-steady state) plasma profile.

This function takes a DataFrame that was produced by read_nca or read_nca_pumas and simulates repeated dosing by linear superposition using interpolation/extrapolation from the observed profile.

The output DataFrame has the same columns as the input DataFrame, plus:

• superposition_dose_number: which dose interval each row belongs to (1, 2, 3, ...).
• superposition_error: missing on success, otherwise a String describing why superposition failed for that row.
• superposition_assumed_tau: the dosing interval used by superposition (the assumed_tau keyword), or missing when complex dosing was used.

The time column in the output is time-after-dose (TAD) for each dose (i.e. it resets for each dose). The corresponding absolute time of each observation can be reconstructed as dose_time + time.

Model

Superposition assumes linear, time-invariant pharmacokinetics, so the concentration response scales proportionally with dose and concentrations from multiple doses add.

Let C_ref(t) be the single-dose concentration-time curve for a reference dose D_ref. For a dosing schedule with doses D_j administered at dose times T_j (with T_1 = 0), the predicted concentration at absolute time t is:

\[\hat C(t) = \sum_{j: T_j \le t} \frac{D_j}{D_{ref}}\, \hat C_{ref}(t - T_j)\]

In the output of superposition, time is reported as time-after-dose (TAD) within each dose interval. For dose number i and tad >= 0, the absolute time is t = T_i + tad, and the reported concentration is:

\[\hat C_i(\mathrm{tad}) = \sum_{j=1}^{i} \frac{D_j}{D_{ref}}\, \hat C_{ref}(\mathrm{tad} + T_i - T_j)\]

The reference curve \hat C_{ref}(t) is constructed from the observed profile using interpolation between observations and (when needed) terminal log-linear extrapolation using lambdaz_fit.

Failure behavior

If the computation requires terminal extrapolation but lambdaz_fit cannot be determined, then concentration is set to missing and superposition_error contains a String with the failure reason.

Dosing modes

If assumed_tau is provided, a simple repeated dosing schedule is simulated.

• assumed_tau: dosing interval.
• loading_dose (default: the profile's reference dose): dose for the first dose.
• maintenance_dose (default: the profile's reference dose): dose for subsequent doses.
• n_doses (default: Inf): number of doses. If Inf, the number of doses is chosen automatically based on the estimated half-life.
• max_auto_doses::Int (default: typemax(Int)): upper bound on the automatically determined number of doses. Only consulted when n_doses = Inf; if the heuristic (based on terminal half-life and assumed_tau) yields more than max_auto_doses doses, superposition throws a SuperpositionMaxDosesError instead of running a potentially very long simulation.

If assumed_tau is not provided, a complex dosing schedule is simulated.

• dose_times (required): vector of dose times (relative to the first dose, with the first element equal to 0).
• doses (required): vector of dose amounts, one per element in dose_times.

Additional keywords:

• outtime: vector of time points (time-after-dose) at which to generate predictions.
• method: interpolation method (e.g. :linear).
• adjr2factor, threshold: passed to the underlying lambdaz_fit.

Example

julia> using NCA, PharmaDatasets

julia> df = dataset("nca/ev_sd_example");

julia> df_r = NCA.read_nca(df);

julia> sup = NCA.superposition(df_r; assumed_tau = 12, n_doses = 5);

julia> size(sup)
(136, 14)

julia> sort(unique(sup.superposition_dose_number))
5-element Vector{Int64}:
 1
 2
 3
 4
 5

SuperpositionMaxDosesError(n_doses, max_auto_doses)

Thrown by superposition when n_doses = Inf and the heuristic based on terminal half-life and assumed_tau produces more doses than the max_auto_doses keyword allows.

Fields:

• n_doses::Int: the number of doses the heuristic would have used.
• max_auto_doses::Int: the configured upper bound.

Downstream code can catch this exception type to recover n_doses and max_auto_doses and produce a domain-specific error.