stats¶

The member of an enumeration given as the member itself or as its string.

Every public function of pkpdutils.stats takes its options either way, so compare(a, b, scale="log") is the analysis of compare(a, b, scale=Scale.LOG) and an unknown string is rejected instead of falling through to a default.

Parameters:

Returns:

Raises:

Log-scale moments of a log-normal distribution with the given mean and standard deviation.

\(\sigma^2 = \ln(1 + \mathrm{sd}^2 / \mathrm{mean}^2)\), \(\mu = \ln \mathrm{mean} - \sigma^2 / 2\).

Parameters:

Returns:

Raises:

Log-scale moments from a geometric mean and a geometric coefficient of variation.

\(\mu = \ln \mathrm{geomean}\), \(\sigma = \sqrt{\ln(1 + \mathrm{geocv}^2)}\).

Parameters:

Returns:

Raises:

Arithmetic mean and standard deviation of a log-normal distribution.

\(\mathrm{mean} = e^{\mu + \sigma^2/2}\), \(\mathrm{sd} = \mathrm{mean}\sqrt{e^{\sigma^2} - 1}\).

Parameters:

Returns:

The logarithms of an array which must be positive.

Parameters:

Returns:

Raises:

Small sample correction of the standardized mean difference.

\(J = 1 - 3 / (4N - 9)\) (Hedges 1981, the approximation of the exact gamma expression), with \(N\) the total number of values.

Parameters:

Returns:

Pooled standard deviation of two samples.

\(s_p = \sqrt{((n_a - 1) s_a^2 + (n_b - 1) s_b^2) / (n_a + n_b - 2)}\).

Parameters:

Returns:

Cohen's d and Hedges' g from the moments of two samples.

\(d = (\bar a - \bar b) / s_p\) with the pooled standard deviation, \(g = J d\) with the small sample correction of hedges_correction (Hedges 1981).

Parameters:

Returns:

Standard error of the difference of two means with unequal variances.

\(\mathrm{se} = \sqrt{s_a^2/n_a + s_b^2/n_b}\).

Parameters:

Returns:

Welch-Satterthwaite degrees of freedom.

\(\nu = (s_a^2/n_a + s_b^2/n_b)^2 / ((s_a^2/n_a)^2/(n_a-1) + (s_b^2/n_b)^2/(n_b-1))\).

A sample of a single value has no variance to propagate and two samples without variance have no scale, both give NaN.

Parameters:

Returns:

The exponentiated two-sided t interval of an estimate on the log scale.

\(\exp(\hat\theta \pm t_{1-\alpha/2, df}\,\mathrm{se})\), the interval of a geometric mean or of a geometric mean ratio (FDA 2001).

Parameters:

Returns:

Whether both samples are individual, labelled and share an individual.

Which values are finite does not enter, so a missing value does not turn a paired design into an unpaired one.

Parameters:

Returns:

The indices of the matched pairs of two samples of individual data.

When both samples carry labels the pairs are matched by label: a label which only one sample carries is dropped, so a missing individual does not break the pairing. Without labels on both samples (also when only one of them is labelled) the pairs are matched by position and the samples must have the same length. A pair is dropped when either of its two values is not finite; dropped pairs are logged at debug level.

Parameters:

Returns:

Raises:

The raw values of two samples as matched pairs, see paired_indices.

Parameters:

Returns:

Raises:

Summary statistics of a parameter sample.

The arithmetic statistics, the geometric mean and the geometric CV, the quantiles of individual data, and a t interval: of the mean on the LINEAR scale, \(\bar x \pm t_{1-\alpha/2, n-1}\,\mathrm{sd}/\sqrt{n}\), and of the geometric mean on the LOG scale, \(\exp(\mu \pm t_{1-\alpha/2, n-1}\,\sigma/\sqrt{n})\). The interval and the spread are NaN with a single value. On LOG a non-positive value raises ValueError; on LINEAR it is tolerated and geomean/geocv come back as NaN instead.

Parameters:

Returns:

Raises:

Compare two samples of a parameter.

AUTO runs the paired t test for paired=True and the Welch t test otherwise; summary data is compared with the Welch t test from its moments. On the log scale the tests run on the logarithms and the effect is the ratio of the geometric means with the exponentiated t interval. The paired tests need individual data of both samples and match it with paired_values, by label when both samples carry labels and by position otherwise; a pair with a missing value is dropped, and so is an individual only one of the samples holds. Every field of the result is computed from the values the test runs on, the finite values of each sample or the remaining pairs: the effect (the medians of the rank tests included), its interval, Cohen's d, Hedges' g and the counts describe the same individuals as the p value. The permutation test permutes the group labels (or the signs of the paired differences) of the difference of the means, with n_perm resamples (Efron & Tibshirani 1993, ch. 15). A sample of one value or two samples without variance give NaN for statistic, p_value, df, the interval and the effect sizes; a sample without a finite value gives a NaN effect as well, unpaired, and raises on the paired path, where no pair remains. test, scale and alternative are taken as the enumeration member or as its string.

Parameters:

Returns:

Raises:

The Hodges-Lehmann estimate of the median difference with a distribution free interval.

The estimator of Hodges & Lehmann (1963) is the median of the Walsh averages of the paired differences,

for paired data and the median of the \(n_a n_b\) pairwise differences \(a_i - b_j\) for two independent samples. Its confidence interval is a pair of order statistics of the same quantities: with \(w\) the smallest value of the null statistic whose cumulative probability reaches \(\alpha/2\), the interval runs from the \(w\)-th smallest to the \(w\)-th largest, which is the interval R reports for wilcox.test. The null distribution is enumerated exactly up to EXACT_MAX_N values per sample (the subsets of the signed ranks, the partitions of the Mann-Whitney statistic) and approximated by the normal distribution of its mean and variance above, where the exact enumeration no longer changes the answer. The p value is the matching two-sided rank test of scipy, the Wilcoxon signed rank test for paired and the Mann-Whitney U test for independent samples.

The analysis runs on the values as they are, not on their logarithms: it is the comparison of \(t_\mathrm{max}\) the EMA asks for when a rapid onset is claimed to be clinically relevant ("no apparent difference in median \(t_\mathrm{max}\) and its variability"), a parameter which is read from the sampling grid, is not log-normal and is no acceptance parameter of bioequivalence. Exposure parameters are analysed with tost instead, which both the EMA and the FDA require for \(\mathrm{AUC}\) and \(C_\mathrm{max}\).

Ties are kept as they are: the estimate and the interval are well defined, while the exact null distribution assumes no ties, so the p value of a sample with ties is scipy's tie-corrected one and the interval is conservative.

The null distribution is discrete, so an interval of order statistics rarely has exactly the requested coverage: the ci_level of the result is the level the interval achieves, \(1 - 2 P(W \le w - 1)\), which is what R reports as the conf.level of wilcox.test. A sample too small for the requested level gets the two extreme order statistics, and ci_level then says how little they cover (four pairs at a requested 0.90 achieve 0.875); above EXACT_MAX_N, where the exact distribution is not enumerated, the requested level is reported as it is.

Parameters:

Other Parameters:

Returns:

Raises:

Adjust p values for multiple comparisons.

Bonferroni: \(\min(1, m p_i)\). Holm (step-down): sort ascending, \(\tilde p_{(i)} = \max_{j \le i} \min(1, (m - j + 1) p_{(j)})\). Benjamini-Hochberg (step-up): \(\tilde p_{(i)} = \min_{j \ge i} \min(1, m p_{(j)} / j)\).

Parameters:

Other Parameters:

Returns:

Raises:

Geometric mean ratio of a parameter, test over reference, with a t interval.

Paired (crossover design): \(d_i = \ln t_i - \ln r_i\), \(\ln \mathrm{GMR} = \bar d\), \(\mathrm{se} = s_d / \sqrt{n}\), \(n - 1\) degrees of freedom. Unpaired (parallel groups): the Welch t interval of \(\bar{\ln t} - \bar{\ln r}\). The interval of the ratio is the exponentiated interval (FDA 2001; Schuirmann 1987). Summary data uses the log moments of ParameterSample.log_moments. Paired samples are matched with paired_values, by label when both samples carry labels and by position otherwise; a pair with a missing value is dropped. A sample of one value or two samples without variance give NaN for se_log, df and the interval, the gmr stays finite; an unpaired sample without a finite value gives NaN throughout, a paired one raises, as no pair remains.

Parameters:

Returns:

Raises:

The ratio table of a publication: one row per parameter, formatted.

The table a bioequivalence, food effect or special population study reports: the geometric mean ratio of every parameter with its confidence interval, as percentages of the reference (percent, the convention of the regulatory guidances: 93.1 % rather than 0.931) or as plain ratios. A pkpdutils.stats.BEResult adds the within-subject coefficient of variation and the verdict of the acceptance limits.

Parameters:

Returns: