nca.steady_state¶

Steady state parameters of the last dosing interval and superposition.

At steady state under repeated dosing every dosing interval tau looks the same; the exposure over one interval, AUC(0-tau), equals the single dose AUC(0-inf) when the kinetics are linear (Gabrielsson & Weiner 2016, ch. 2.8; Rowland & Tozer 2011, ch. 11). The parameters of one interval are

AUC(0-tau) with the values at the dose and at tau interpolated, so that samples before the dose do not add area,
Ctrough = C(tau), Cmin,ss and Cmax,ss the smallest and the largest value in the interval,
Cavg = AUC(0-tau) / tau,
fluctuation = (Cmax,ss - Cmin,ss) / Cavg, swing = (Cmax,ss - Cmin,ss) / Cmin,ss, and the trough variants fluctuation_tau, swing_tau and the peak-trough ratio ptr, which read Ctrough = C(tau) where the first two read the smallest observed value,
thalf_eff, the effective half-life of the decline (compute_parameters),
CLss = Dose / AUC(0-tau) (cl_ss, cl_ss_f for an extravascular route), the clearance of a multiple dose analysis: the single dose CL, Vz, Vss, auc_inf_dn and cmax_dn are NaN there (SINGLE_DOSE_PARAMETERS),
the accumulation ratio R = 1 / (1 - exp(-lambda_z tau)) predicted from the terminal phase, and the observed ratios of the last over the first dosing interval of the protocol: accumulation_ratio_obs of the exposure and accumulation_ratio_cmax_obs, accumulation_ratio_cmin_obs and accumulation_ratio_ctrough_obs of the peak, the minimum and the trough.

compute_steady_state analyses the last dosing interval of the protocol of every row, [t_K, t_K + tau], where tau is NCAOptions.tau or the distance of the last two doses; the parameters of every interval come from pkpdutils.nca.intervals. A last interval whose last sample falls short of its end by at most NCAOptions.tau_tolerance of tau is completed with the terminal regression rather than given up (complete_last_interval). The point parameters of the same rows are computed from the last dose on: the values before it are dropped and the times are relative to it, so that cmax, tmax, the terminal phase and the extrapolated areas describe the last dosing interval and its decline; the parameters which would read that slice as a single dose curve are dropped, see compute_steady_state.

superposition predicts the multiple dose curve of a dosing protocol from a single dose curve by adding the shifted, dose-scaled single dose curves (linear superposition), which is valid for linear kinetics.

complete_last_interval ¶

complete_last_interval(
    t,
    c,
    intervals,
    values,
    *,
    last,
    t_start,
    t_end,
    route,
    options,
)

Complete a last dosing interval which falls a little short of its end.

A last sample a few minutes before the nominal end of the interval makes every steady state parameter of the profile NaN, although the missing piece of the exposure is a fraction of a percent. Phoenix WinNonlin describes the case verbatim ("if dose time=0 and tau=24, the last sample might be at 23.975 or 24.083 hours ... the program will estimate the AUC_TAU based on the estimated concentration at 24 hours") and EMA asks for the last sample within ten minutes of the nominal end precisely because it is common.

An interval whose last measurable sample lies at most NCAOptions.tau_tolerance * tau before its end is therefore analysed up to that sample and completed with the terminal regression: the tail from \(t_\mathrm{last}\) to the end of the interval of \(C(t) = C_\mathrm{last} e^{-\lambda_z (t - t_\mathrm{last})}\) is

\[\frac{C_\mathrm{last}}{\lambda_z} \left(1 - e^{-\lambda_z (t_\mathrm{end} - t_\mathrm{last})}\right),\]

the trough of the interval is the same regression at its end, \(C_\mathrm{trough} = C_\mathrm{last} e^{-\lambda_z (t_\mathrm{end} - t_\mathrm{last})}\), and the minimum of the interval is the smaller of the observed minimum and that trough. The tail is extrapolated from the observed \(C_\mathrm{last}\), which is what \(\mathrm{AUC}_{0\text{-}\infty,\mathrm{obs}}\) extrapolates from as well. The completed columns replace the NaN columns of the last interval, so every parameter which reads them follows, and the share of the exposure which was extrapolated is reported as auc_tau_extrap_fraction (Phoenix AUC_TAU_%Extrap). Beyond the tolerance nothing is completed and the profile keeps its NCAFlag.INCOMPLETE_INTERVAL.

Only a concentration analysis is completed: an effect timecourse has no terminal regression to extrapolate with.

Parameters:

Name	Type	Description	Default
`t`	`ndarray`	times `(N, n)` of the curves	required
`c`	`ndarray`	values `(N, n)`	required
`intervals`	`dict[str, ndarray]`	the per-interval variables `(N, K)` of `compute_intervals`, whose last column is patched in place for the completed rows	required
`values`	`dict[str, ndarray]`	the point parameters of the rows, which carry `tlast`, `clast` and `lambda_z` relative to the last dose	required

Other Parameters:

Name	Type	Description
`last`	`ndarray`	column index of the last interval of every row `(N,)`
`t_start`	`ndarray`	start of the last interval per row `(N,)`
`t_end`	`ndarray`	end of the last interval per row `(N,)`
`route`	`Route \| None`	route of the batch
`options`	`NCAOptions`	the options, `tau_tolerance`, `kind` and `auc_method` are used

Returns:

Type	Description
`ndarray`	The mask of the completed rows `(N,)` and the extrapolated fraction of
`ndarray`	their exposure `(N,)`, `NaN` for a row which was not completed.

compute_steady_state ¶

compute_steady_state(
    t,
    c,
    *,
    dose_amount,
    dose_time,
    dose_duration,
    route,
    options,
    lloq=None,
    windows=None,
)

Point, per-interval and steady state parameters of every row of a batch.

The dose arrays carry the dosing protocol of every row, (N, K) padded with NaN (pkpdutils.timecourse.Timecourses). The point parameters are computed from the last dose of every protocol on (the values before it are dropped), the per-interval parameters over every dosing interval (pkpdutils.nca.intervals.compute_intervals) and the steady state parameters from the last interval [t_K, t_K + tau]. A row whose last interval is not covered by the data carries NCAFlag.INCOMPLETE_INTERVAL and NaN steady state parameters.

A multiple dose analysis reports no single dose quantities: the slice after the last dose carries the exposure of every earlier dose as well, so the parameters which divide the dose by it (SINGLE_DOSE_PARAMETERS: cl, cl_f, vz, vz_f, vss, auc_inf_dn, cmax_dn) are NaN. The clearance is cl_ss (cl_ss_f for an extravascular route), the dose over the exposure of the dosing interval. auc_inf_obs, auc_inf_pred, aumc_inf and mrt are reported and are the areas of that slice extrapolated with its terminal phase, i.e. the exposure after the last dose, not the single dose exposure of the substance.

Parameters:

Name	Type	Description	Default
`t`	`ndarray`	times `(N, n)`	required
`c`	`ndarray`	values `(N, n)`	required

Other Parameters:

Name	Type	Description
`dose_amount`	`ndarray \| None`	dose amounts `(N, K)`, `None` without doses
`dose_time`	`ndarray \| None`	dose times `(N, K)`, `None` without doses (the interval of `options.tau` then starts at time 0)
`dose_duration`	`ndarray \| None`	infusion durations `(N, K)`, `None` for none
`route`	`Route \| None`	route of the batch
`options`	`NCAOptions`	the options; `tau` gives the length of the last interval when the protocol has one dose
`lloq`	`ndarray \| None`	limit of quantification per row `(N,)`, `None` for none; it applies to the point parameters, as `NCAOptions.lloq` does
`windows`	`ndarray \| None`	the terminal window of single rows `(N, 2)`, `NaN` for a row without one; it applies to the point parameters, whose times are relative to the last dose

Returns:

Type	Description
`dict[str, ndarray]`	The parameters of `pkpdutils.nca.nca.compute_parameters` plus the
`dict[str, ndarray]`	steady state parameters, the per-interval parameters (with
`dict[str, ndarray]`	`options.intervals`) and `flags`.

accumulation_ratio ¶

accumulation_ratio(steady_state, single_dose)

Accumulation and stationarity of a steady state study against a single dose study.

Both results come from analyses over the same dosing interval, so both carry auc_tau. The accumulation ratio is the exposure of the interval at steady state over the exposure of the same interval after the first dose,

\[R_\mathrm{obs} = \frac{\mathrm{AUC}_{0\text{-}\tau}^\mathrm{ss}} {\mathrm{AUC}_{0\text{-}\tau}^\mathrm{single}},\]

and the stationarity ratio compares the exposure of the interval at steady state with the total exposure of the single dose,

\[\mathrm{SR} = \frac{\mathrm{AUC}_{0\text{-}\tau}^\mathrm{ss}} {\mathrm{AUC}_{0\text{-}\infty,\mathrm{obs}}^\mathrm{single}},\]

which is 1 for time-invariant linear kinetics and says that the clearance did not change over the study (CDISC ARAUC and SRAUC; Gabrielsson & Weiner 2016, ch. 2.8). Within one multiple dose curve the ratio of the last and the first dosing interval is reported as accumulation_ratio_obs.

Parameters:

Name	Type	Description	Default
`steady_state`	`NCAResult`	result of the analysis of the steady state curve	required
`single_dose`	`NCAResult`	result of the analysis of the single dose curve	required

Returns:

Type	Description
`Dataset`	A dataset over the sample dimensions of the results with the variables
`Dataset`	`accumulation_ratio` and `stationarity_ratio`, `attrs["units"]` of both
`Dataset`	`"dimensionless"`; the stationarity ratio is `NaN` when the single dose
`Dataset`	analysis reports no `auc_inf_obs`.

Raises:

Type	Description
`ValueError`	if either result has no `auc_tau`.

superposition ¶

superposition(
    timecourse,
    dosing,
    *,
    options=None,
    t_end=None,
    grid=None,
)

Predict the multiple dose curve of a protocol from a single dose curve.

Every dose of the protocol contributes the single dose curve shifted to its time and scaled by amount_k / amount_single, the linear superposition which holds for linear kinetics (Gabrielsson & Weiner 2016, ch. 2.8). The curve is interpolated on the union of the shifted time grids, or on grid, and continued beyond its last observed point with its terminal phase.

Before the first observed point after a dose the curve runs in a straight line from the value at the dose, the back-extrapolated \(C_0\) of a bolus (c0 of the analysis) and 0 for every other route, to that point. The predicted curve carries a sample right before every dose after the first, a thousandth of the shortest dosing interval ahead of the dose time: the sample at the dose time carries the post-dose value, so without the pre-dose sample the curve of a bolus would rise to the next peak in a straight line from the last sample of the interval instead of falling to the trough and jumping. The trough of every interval is therefore in the curve, and a figure of the prediction shows the sawtooth of a bolus.

The reference amount is the dose of the single dose curve; a curve whose dose amount is 0 carries no scale, so every dose of the protocol then contributes the curve unscaled.

Parameters:

Name	Type	Description	Default
`timecourse`	`Timecourse`	the single dose curve (its dose is the reference amount)	required
`dosing`	`Dosing \| DosingRegimen`	the protocol to superpose, or a `DosingRegimen` with `n_doses`	required

Other Parameters:

Name	Type	Description
`options`	`NCAOptions \| None`	NCA options for the interpolation and the terminal phase
`t_end`	`float \| None`	end of the predicted curve, the last dose time plus the last observed time by default
`grid`	`ArrayLike \| None`	the times to predict at, from the first dose to `t_end`; by default the union of the observed times shifted to every dose, which is as sparse as the observed curve. A fine grid (`np.arange(0, 120, 0.25)`) gives a smooth curve of a figure. The pre-dose samples are added either way.

Returns:

Type	Description
`Timecourse`	The predicted curve carrying the protocol, without a label: the label
`Timecourse`	of the single dose curve describes that curve, not the prediction.

Raises:

Type	Description
`ValueError`	without `n_doses` of a regimen, without a dose of the single dose curve or without a terminal phase of the curve.