nca.sparse¶

Non-compartmental analysis of sparse and destructive sampling designs.

A preclinical study rarely samples one animal repeatedly: the animal is sacrificed for the sample (a destructive design, one sample per animal) or contributes a few samples out of the schedule (a batch design). There is no curve per animal then, only a mean curve over the animals of every time point, and the question is how uncertain the area under that mean curve is.

Bailer (1988) answers it: the area is a fixed linear combination of the means,

\[\widehat{\mathrm{AUC}} = \sum_j w_j \bar y_j,\]

with the trapezoid weights \(w_j\), so its variance follows from the variances of the means. With one sample per animal the means are independent and

\[\widehat{\mathrm{Var}}\left[\widehat{\mathrm{AUC}}\right] = \sum_j w_j^2 \frac{s_j^2}{n_j};\]

Nedelman, Gibiansky and Lau (1995) give the Satterthwaite degrees of freedom of that sum so the area gets a \(t\) interval. Nedelman and Jia (1998) extend the estimator to a batch design, where an animal contributes to several means, and Holder (2001), commenting on that extension, gives the variance which carries the covariance between the time points an animal is shared by.

pkpdutils computes all three from one identity. Writing the estimator per animal rather than per time point,

\[\widehat{\mathrm{AUC}} = \sum_i A_i, \qquad A_i = \sum_{j \in T_i} \frac{w_j}{n_j}\, y_{ij},\]

where \(T_i\) are the times animal \(i\) was sampled at, the animals are independent whatever the design, so the variance is the sum over the animals and is estimated batch by batch (a batch is a group of animals with the same sampling times):

\[\widehat{\mathrm{Var}}\left[\widehat{\mathrm{AUC}}\right] = \sum_b m_b\, s^2_{A,b}, \qquad \nu = \frac{\left(\sum_b c_b\right)^2}{\sum_b \frac{c_b^2}{m_b - 1}}, \quad c_b = m_b\, s^2_{A,b}.\]

With one sample per animal a batch is one time point, \(A_i = (w_j/n_j) y_{ij}\) and \(c_b = w_j^2 s_j^2 / n_j\): the formula of Bailer and the degrees of freedom of Nedelman, Gibiansky and Lau, exactly. With several samples per animal the sample variance of the \(A_i\) carries the covariances of Holder without ever forming them.

Nominal times are used, never the actual sampling times: a mean over animals only exists at a nominal time (the caution of Phoenix WinNonlin for its sparse models).

trapezoid_weights ¶

trapezoid_weights(times)

Weights of the linear trapezoid rule over a grid of times.

The area under the polygon through \((t_j, y_j)\) is \(\sum_j w_j y_j\) with

\[w_1 = \frac{t_2 - t_1}{2}, \qquad w_j = \frac{t_{j+1} - t_{j-1}}{2}, \qquad w_J = \frac{t_J - t_{J-1}}{2},\]

which is the form Bailer (1988) needs: the area is linear in the values, so its variance follows from theirs. The logarithmic trapezoid rules of pkpdutils.nca.options.AUCMethod are not linear in the values and have no such weights.

Parameters:

Name	Type	Description	Default
`times`	`ndarray`	the sampling times, strictly increasing, at least two.	required

Returns:

Type	Description
`ndarray`	One weight per time, of the shape of `times`.

point_statistics ¶

point_statistics(values)

Count, mean and standard deviation of every time point of a sparse design.

Parameters:

Name	Type	Description	Default
`values`	`ndarray`	the values `(n_animals, n_time)`, `NaN` where an animal has no sample at a time.	required

Returns:

Type	Description
`ndarray`	The number of animals sampled at every time, the mean over them and
`ndarray`	their standard deviation (`ddof=1`, `NaN` for a single animal).

area_window ¶

area_window(observed, mean)

The nominal times auc_last of a sparse design covers.

The observed time points up to the last one whose mean is positive, the \(t_\mathrm{last}\) rule of a concentration curve read on the mean curve. nca_sparse weights these points and pkpdutils.plot.plot_sparse shades them, so both read the window from here.

Parameters:

Name	Type	Description	Default
`observed`	`ndarray`	whether a nominal time carries a sample at all.	required
`mean`	`ndarray`	the mean of every nominal time, `NaN` where there is none.	required

Returns:

Type	Description
`ndarray`	The boolean mask of the covered time points; all `False` when no mean
`ndarray`	is positive.

bailer_variance ¶

bailer_variance(weights, values)

Variance of the sparse area estimate and its Satterthwaite degrees of freedom.

The estimate is written per animal, \(A_i = \sum_{j \in T_i} (w_j/n_j) y_{ij}\) with \(n_j\) the number of animals sampled at time \(j\), so that the animals are independent whatever the design and

\[\widehat{\mathrm{Var}}\left[\sum_i A_i\right] = \sum_b m_b\, s^2_{A,b}, \qquad \nu = \frac{\left(\sum_b c_b\right)^2}{\sum_b \frac{c_b^2}{m_b - 1}}, \quad c_b = m_b\, s^2_{A,b},\]

where a batch \(b\) is the group of the \(m_b\) animals with the same sampling times and \(s^2_{A,b}\) the sample variance of their \(A_i\). With one sample per animal a batch is one time point and the two formulas are \(\sum_j w_j^2 s_j^2/n_j\) of Bailer (1988) and the degrees of freedom of Nedelman, Gibiansky and Lau (1995); with several samples per animal the sample variance carries the covariance terms of the batch design of Nedelman and Jia (1998) as Holder (2001) writes them.

Parameters:

Name	Type	Description	Default
`weights`	`ndarray`	the weight of every time point, 0 for a time point which is not part of the area.	required
`values`	`ndarray`	the values `(n_animals, n_time)`, `NaN` where an animal has no sample at a time.	required

Returns:

Type	Description
`float`	The variance, the degrees of freedom and the number of batches; the
`float`	variance and the degrees of freedom are `NaN` when a batch holds a
`int`	single animal, whose contribution cannot be estimated.

sparse_mean ¶

sparse_mean(
    times,
    values,
    *,
    time_unit,
    unit,
    dose=None,
    substance="substance",
    dim="group",
    label="mean",
)

The mean curve of a sparse design, with its spread per time point.

The curve every sparse analysis is read from: the mean over the animals sampled at a nominal time, their standard deviation (ddof=1), the standard error \(s_j/\sqrt{n_j}\) and the count \(n_j\), each per time point, so that a time point sampled in fewer animals carries its own count.

Parameters:

Name	Type	Description	Default
`times`	`Any`	the nominal sampling times, one-dimensional	required
`values`	`Any`	the values `(n_animals, n_time)`, `NaN` where an animal has no sample at a time	required

Other Parameters:

Name	Type	Description
`time_unit`	`str`	unit of the times
`unit`	`str`	unit of the values
`dose`	`Dose \| None`	the dose of the animals, `None` without one
`substance`	`str`	name of the substance
`dim`	`str`	name of the sample dimension of the batch
`label`	`Any`	label of the single sample of the batch

Returns:

Type	Description
`Timecourses`	A batch of one sample carrying `value`, `sd`, `se` and `n` per time
`Timecourses`	point.

Raises:

Type	Description
`ValueError`	if the shapes do not fit or the times are not increasing.

nca_sparse ¶

nca_sparse(
    times,
    values,
    *,
    design="serial",
    options=None,
    time_unit,
    unit,
    dose=None,
)

Non-compartmental analysis of a sparse or destructive sampling design.

The area under the mean curve with the standard error of Bailer (1988), the degrees of freedom of Nedelman, Gibiansky and Lau (1995) and, for the batch design of Nedelman and Jia (1998), the covariance of Holder (2001), all three from the per-animal identity of bailer_variance:

\[\widehat{\mathrm{AUC}}_{0\text{-}t_\mathrm{last}} = \sum_j w_j \bar y_j, \qquad \mathrm{se} = \sqrt{\widehat{\mathrm{Var}}\left[\widehat{\mathrm{AUC}}\right]}, \qquad \mathrm{CI} = \widehat{\mathrm{AUC}} \pm t_{1-\alpha/2,\nu}\,\mathrm{se}.\]

\(t_\mathrm{last}\) is the last nominal time whose mean is positive, as it is for a concentration curve, and auc_all is the area over every nominal time with a sample. Both run over the nominal times as they are given, from the first of them rather than from the dose: nothing is inserted at time 0, because an inserted point has no variance and the estimator has to stay a combination of the measured means. A design whose area starts at the dose carries a nominal time 0 of its own (the value 0 after an extravascular dose). The peak of the mean curve is cmax at tmax with the standard error \(s_j/\sqrt{n_j}\) of the mean at that time, the SE_Cmax of Phoenix WinNonlin. The number of animals behind every time point is the point variable n_animals.

The estimator is a fixed linear combination of the means, so the weights are always those of the linear trapezoid rule (trapezoid_weights): a logarithmic rule is not linear in the values and has no variance formula of this kind. options.auc_method is therefore not used, and neither are the rules which read a single curve (lloq, blq, the terminal phase, the uncertainty of a group curve).

Parameters:

Name	Type	Description	Default
`times`	`Any`	the nominal sampling times, one-dimensional. Nominal, not actual: a mean over animals only exists at a nominal time.	required
`values`	`Any`	the values `(n_animals, n_time)`, `NaN` where an animal has no sample at a time	required

Other Parameters:

Name	Type	Description
`design`	`Design`	`"serial"` when every animal carries a single sample (destructive sampling, the variance of Bailer) and `"batch"` when an animal carries several (the covariance of Holder); a serial design is checked, both are estimated by the same formula
`options`	`NCAOptions \| None`	the options, defaults for `None`
`time_unit`	`str`	unit of the times
`unit`	`str`	unit of the values
`dose`	`Dose \| None`	the dose of the animals, whose amount travels into the result as the coordinate `dose_amount`; `None` without one

Returns:

Type	Description
`NCAResult`	The parameters of the mean curve without sample dimensions:
`NCAResult`	`auc_last`, `auc_last_se`, `auc_last_df`, `auc_all`, `cmax`,
`NCAResult`	`cmax_se`, `tmax` and the point variable `n_animals` over `time`.

Raises:

Type	Description
`ValueError`	if the shapes do not fit, if the times are not increasing, if the design is unknown or if a serial design holds an animal with several samples.