nca.uncertainty¶

Uncertainty of the NCA parameters of group timecourses.

A group timecourse is the mean curve of several subjects with the standard deviation (sd) or the standard error (se) per time point and the number of subjects n. Two methods propagate this uncertainty to the parameters:

the parametric bootstrap (Efron & Tibshirani 1993, ch. 6) draws every time point of every curve n_boot times from a normal (or log-normal) distribution with the observed mean and spread, analyses the replicates with the same vectorized code as the original curves and reduces them to the standard error (or standard deviation), the percentile confidence interval and, for log-normal parameters, the geometric mean and geometric CV;
the delta method perturbs every time point once, forms the numerical Jacobian of every parameter with respect to the values and propagates the standard errors through it: var(x) = sum_i (dx/dC_i)^2 se_i^2.

The variables of a parameter x are x_sd, x_se, x_ci_low, x_ci_high and, for log-normal parameters, x_geomean, x_geocv; n is the number of subjects per sample. x_sd and x_geocv are always on the between-subject scale (the spread of the parameter over subjects), x_se is always the uncertainty of the parameter of the mean curve, and x_ci_low/x_ci_high are always an interval of that estimate. Discrete parameters (tmax, tlast, counts) and the diagnostics of the terminal regression carry no uncertainty.

With BootstrapSpread.SD the replicates are individual curves, so their percentiles bound individuals and not the estimate; they are exported separately as x_pi_low/x_pi_high and the confidence interval is the normal approximation x +- z se (on the log scale for log-normal parameters).

Under BootstrapSpread.SE the interval is the percentile interval of the replicates, so it is not guaranteed to contain the point estimate of the mean curve: for skewed replicates (a parameter which is a strongly non-linear function of the values, such as lambda_z or mrt) the interval is asymmetric around the estimate and can exclude it.

terminal_independent ¶

terminal_independent(options)

The parameters which do not depend on the terminal phase, for these options.

TERMINAL_INDEPENDENT_PARAMETERS holds for an analysis which reads the dosing interval as it was measured. With NCAOptions.tau_tolerance above 0 the exposure of a last interval which falls short of its end is completed with the terminal regression (pkpdutils.nca.steady_state.complete_last_interval), so auc_tau and the four parameters which read the same interval depend on the terminal window and are dropped from the set: the delta method then skips the points at which the window flipped for them as well, rather than differentiating across two regressions.

Parameters:

Name	Type	Description	Default
`options`	`NCAOptions`	the options of the analysis	required

Returns:

Type	Description
`frozenset[str]`	The names of the parameters whose derivative may be taken at every
`frozenset[str]`	point, whatever the terminal window does there.

flatten_rows ¶

flatten_rows(a, n_rows)

A per row dose array of shape (*sample_shape, n_dose) as (N, n_dose).

Parameters:

Name	Type	Description	Default
`a`	`ndarray \| None`	the array, or `None`	required
`n_rows`	`int`	number of rows `N` of the batch	required

Returns:

Type	Description
`ndarray \| None`	The flattened array `(N, n_dose)`, or `None`.

repeat_block ¶

repeat_block(a, start, stop, repeats)

Repeat every row of a block of a flattened dose array, keeping the rows grouped.

Parameters:

Name	Type	Description	Default
`a`	`ndarray \| None`	the flattened array `(N, n_dose)` (`flatten_rows`), or `None`	required
`start`	`int`	first row of the block	required
`stop`	`int`	row after the last one of the block	required
`repeats`	`int`	copies per row	required

Returns:

Type	Description
`ndarray \| None`	The repeated block `((stop - start) * repeats, n_dose)`, or `None`.

repeat_rows ¶

repeat_rows(a, n_rows, repeats)

Repeat every row of a per row dose array, keeping the rows grouped.

The replicates of the bootstrap and the perturbed curves of the delta method are repeats copies of every row of the batch, in blocks; the dose arrays follow them row by row.

Parameters:

Name	Type	Description	Default
`a`	`ndarray \| None`	the array of shape `(*sample_shape, n_dose)`, or `None`	required
`n_rows`	`int`	number of rows `N` of the batch	required
`repeats`	`int`	copies per row	required

Returns:

Type	Description
`ndarray \| None`	The repeated array `(N * repeats, n_dose)`, or `None`.

resolve_spread ¶

resolve_spread(timecourses, options, *, spread=None)

The spread every time point is resampled with, (n_samples, n_time).

Parameters:

Name	Type	Description	Default
`timecourses`	`Timecourses`	the batch	required
`options`	`NCAOptions`	`bootstrap_spread` selects `se` or `sd` when `spread` is not given; the missing one is derived from the other with `n`	required

Other Parameters:

Name	Type	Description
`spread`	`BootstrapSpread \| None`	the spread to return, overriding `options.bootstrap_spread`; the delta method always propagates `se`, whatever the options say

Returns:

Type	Description
`ndarray`	The spread per point (`NaN` where the batch has none).

Raises:

Type	Description
`ValueError`	if the requested spread is neither present nor derivable.

resample_values ¶

resample_values(
    c,
    spread,
    n_boot,
    rng,
    distribution,
    *,
    clip_at_zero=True,
)

Draw bootstrap replicates of every time point of every row.

A normal draw is C_i + s_i z, clipped at 0 for concentrations; a log-normal draw has the same mean and spread, sigma^2 = ln(1 + s_i^2 / C_i^2) and mu = ln C_i - sigma^2 / 2 (Efron & Tibshirani 1993, ch. 6). A log-normal point whose mean is not positive has no such distribution and is copied unchanged.

Parameters:

Name	Type	Description	Default
`c`	`ndarray`	values `(N, n)`	required
`spread`	`ndarray`	spread per point `(N, n)`; a point without a finite positive spread is copied	required
`n_boot`	`int`	number of replicates `B`	required
`rng`	`Generator`	random generator	required
`distribution`	`BootstrapDistribution`	normal or log-normal with the same mean and spread	required
`clip_at_zero`	`bool`	whether normal draws below 0 are set to 0; `True` for concentrations, which cannot be negative, and `False` for effects, whose values are legitimately negative. Clipping biases the mean of a point whose spread is large against its value upwards, see `BootstrapDistribution.LOGNORMAL` for an alternative.	`True`

Returns:

Type	Description
`ndarray`	The replicates `(N, B, n)`.

reduce_replicates ¶

reduce_replicates(
    replicates,
    point,
    *,
    spread_kind,
    n_subjects,
    ci_level,
    usable_rows=None,
)

Reduce the bootstrap replicates of every continuous parameter to its uncertainty variables.

The spread of the replicates is the standard error of the parameter when the points were drawn with se and its standard deviation over subjects when they were drawn with sd; the other one follows from se = sd / sqrt(n).

x_ci_low/x_ci_high are always an interval of the estimate: the percentile interval of the replicates under se draws, which is asymmetric around the estimate of the mean curve for skewed replicates and is not guaranteed to contain it, and the normal approximation x +- z se (on the log scale, x exp(+- z se / x), for log-normal parameters) under sd draws, whose replicates are individual curves. Their percentiles are exported separately as x_pi_low/x_pi_high, the interval of the individuals.

x_geocv is, like x_sd, always the geometric CV over subjects, geocv = sqrt(exp(var(ln x)) - 1) (Efron & Tibshirani 1993, ch. 13): from sd draws the log variance of the replicates is used as it is, from se draws it is the log variance of the mean and is scaled by n first (NaN without n). x_geomean comes from the logarithms of the positive replicates.

Parameters:

Name	Type	Description	Default
`replicates`	`dict[str, ndarray]`	parameter name to replicates `(N, B)`	required
`point`	`dict[str, ndarray]`	parameter name to the estimate of the original curve `(N,)`	required
`spread_kind`	`BootstrapSpread`	whether the replicates were drawn with `se` (their spread is the standard error of the parameter) or `sd` (their spread is the standard deviation over subjects)	required
`n_subjects`	`ndarray \| None`	subjects per row, `None` or `NaN` when unknown	required
`ci_level`	`float`	level of the confidence interval	required
`usable_rows`	`ndarray \| None`	rows which carried a usable spread, `None` for all of them; a row without one has no uncertainty and is `NaN` everywhere	`None`

Returns:

Type	Description
`dict[str, ndarray]`	`x_sd`, `x_se`, `x_ci_low`, `x_ci_high` per parameter, `x_pi_low`,
`dict[str, ndarray]`	`x_pi_high` under `sd` draws and `x_geomean`, `x_geocv` for log-normal
`dict[str, ndarray]`	parameters.

bootstrap ¶

bootstrap(timecourses, options, point)

Bootstrap the parameters of a batch.

The curves are processed in blocks: the replicates of a block are drawn, analysed and reduced to their parameters before the next block is drawn, so the (N, B, n) array of every replicate of the batch never exists at once. The draws do not depend on the blocking, the random generator produces the same numbers in the same order.

Parameters:

Name	Type	Description	Default
`timecourses`	`Timecourses`	the batch (group curves with `sd` or `se`)	required
`options`	`NCAOptions`	`n_boot`, `seed`, `bootstrap_spread`, `bootstrap_distribution`, `ci_level`	required
`point`	`dict[str, ndarray]`	the parameters of the original curves (`run_rows` output)	required

Returns:

Type	Description
`dict[str, ndarray]`	The uncertainty variables per parameter (see `reduce_replicates`).

Raises:

Type	Description
`ValueError`	if the batch has no spread to resample with, or if log-normal draws are requested for effect timecourses.

delta ¶

delta(timecourses, options, point)

Delta method: propagate the standard errors of the points through the numerical Jacobian.

var(x) = sum_i (dx/dC_i)^2 se_i^2 with dx/dC_i from a forward difference of step options.delta_step * se_i (Efron & Tibshirani 1993, ch. 5). The method always propagates se, the uncertainty of the mean curve, so options.bootstrap_spread does not apply. The interval is the normal interval x +- z se, on the log scale for log-normal parameters; discrete parameters and the diagnostics of the terminal regression are skipped.

x_sd = x_se sqrt(n) is the spread of the parameter over subjects and x_geocv is its geometric CV, as in the bootstrap: with mu = x and sd = x_sd, the log-normal moment relation gives sigma_log² = ln(1 + (sd / mu)²) and

geocv = sqrt(exp(sigma_log²) - 1) = sd / mu,

so the geometric CV equals the arithmetic CV over subjects (Efron & Tibshirani 1993, ch. 13). Without n the between-subject scale is unknown and x_sd and x_geocv are NaN.

A perturbation which selects a different terminal window (lambda_z_n_points or lambda_z_t_first changes) makes the difference quotient a jump between two regressions instead of a derivative, which inflates the standard error of every terminal parameter. Such points are skipped for every parameter outside terminal_independent(options) and the row carries NCAFlag.DELTA_WINDOW_CHANGE, which says that the uncertainty of its terminal parameters is incomplete; use the bootstrap, which follows the window, for those rows.

Parameters:

Name	Type	Description	Default
`timecourses`	`Timecourses`	the batch (group curves with `se`, or `sd` and `n`)	required
`options`	`NCAOptions`	`delta_step`, `ci_level`	required
`point`	`dict[str, ndarray]`	the parameters of the original curves (`run_rows` output)	required

Returns:

Type	Description
`dict[str, ndarray]`	The uncertainty variables per continuous parameter and, under the key
`dict[str, ndarray]`	`"flags"`, the flags of the skipped points to be combined with the
`dict[str, ndarray]`	flags of the analysis.

Raises:

Type	Description
`ValueError`	if the batch has no `se` and it cannot be derived.