Multivariate t probabilities#

Probabilities of boxes and critical values of max-t tests under the multivariate t distribution; Multivariate t probabilities explains them.

Probabilities and quantiles of the multivariate t distribution, each with its error.

A test that compares several correlated t-statistics at once, such as Dunnett’s test of each dose against the vehicle, refers the largest of them to the multivariate t distribution. multivariate_t_cdf() gives the probability that every coordinate of T stays below its limit, or within plus or minus its limit, and the complement, the chance that some coordinate leaves its interval, which is the adjusted p-value of a max-t test. multivariate_t_quantile() gives the equicoordinate quantile, the critical value of such a test. Each value comes with its error, and the computation stops when the error of the smaller of the probability and its complement is at most a requested fraction of it, so that a p-value of 1e-10 is as accurate, relative to its size, as one of 0.04. https://docs.nygen.io/CytePool/statistics/multiple-testing#multivariate-t-probabilities explains the method and its accuracy.

T = Z / S, with Z normal with mean 0 and covariance the correlation matrix R, and df S^2 chi-squared on df degrees of freedom, independent of Z; df = inf gives the multivariate normal distribution. df need not be an integer.

Methods

  • The complement of a box as a sum of first exceedances. With the coordinates in the order of decreasing marginal tails, the event that some T_i exceeds its limit b_i is the disjoint union of the events that coordinate r is the first to do so: 1 - P(box) = sum_r P(T_r > b_r) h_r, with h_r = P(T_j in its interval for every j < r | T_r > b_r). The marginal tails are exact (t_sf_scalar), h_1 = 1, and each h_r lies between 0 and 1, so an absolute error e in each h_r gives the complement a relative error of at most k e, at any magnitude. Estimating each term by conditioning on its rare event is importance sampling for a union of rare events, whose relative error stays bounded however small the union (Owen, Maximov and Chertkov 2019). For a box symmetric about 0, the exceedances below the lower limits mirror those above the upper limits, and the sum is doubled.

  • Each h_r by conditioning on the exceedance. S is drawn from a proposal tilted towards the tail, V / (df + tau^2) with V chi-squared on df degrees of freedom and tau = max(b_r, 0), with the weight (df / (df + tau^2))^(df / 2) exp(tau^2 S^2 / 2) Q(b_r S) / P(T_r > b_r) that makes the draw exact, Q being the normal upper tail; the weight is bounded, since exp(x^2 / 2) Q(x) is at most 1/2 for x >= 0. Z_r is drawn above b_r S by inversion, and the earlier coordinates, normal given Z_r with mean R[j, r] Z_r and covariance the Schur complement of R, by Genz’s (1992) separation of variables, with a Cholesky factor pivoted on the largest residual variance. A coordinate whose residual variance is at most 1e-10 is a linear function of the earlier random ones; its interval becomes limits of the last random coordinate it depends on, so that singular correlations, such as those of all pairwise contrasts, are integrated as accurately as others. Interval probabilities and draws use the normal tail on the side away from zero, which keeps them accurate far out.

  • Rare overlaps. When the earlier coordinates of a part exceed their limits with a total chance below 1e-3, given T_r at its threshold, that chance comes from draws deep in the tail of Z_r and near the ends of the earlier coordinates’ intervals, which few points reach. The part then draws each earlier coordinate at the point (1 - cos(pi x)) / 2 of its interval, x the lattice coordinate, which brings draws near both ends, and Z_r at the point x^2 of its conditional distribution, which moves draws towards its threshold, with weights pi sin(pi x) / 2 and 2 x of mean 1, and estimates 1 - h_r as the mean of the weights times the chance that an earlier coordinate leaves its interval, whose variance is that of the overlap, not that of the weights (own construction from these standard changes of variable and control variates).

  • The probability itself, when it is below 1/2. The same estimator conditions on the coordinate with the smallest marginal probability of its interval, and integrates the others given it. For a one-sided limit below 0, the condition is the exceedance of -T_r above -b_r, and S is tilted as above; otherwise a small box’s probability grows with S about as S^d, d the derivative of the box’s log-probability in log S at S = 1 with its coordinates taken as independent, and the tilt t = -df d / (df + d) gives S^2 the mean (df + d) / df that it has given such a box. So the requested relative error applies to the smaller of the probability and its complement, and small boxes cost about what large ones do.

  • Points and errors. Randomly shifted Kronecker points, x_n = frac(n alpha + Delta) with alpha_j the fractional part of the square root of the j-th prime, folded by the baker’s transform 1 - |2 x - 1|; 16 random shifts are drawn once per call, so the problems of one call share them and a seed gives the same values whatever the order of the problems and the number of threads. The estimate is the mean of the 16 shift estimates and its standard error their standard deviation over 4 (randomized quasi-Monte Carlo with independent shifts; Genz and Bretz 2002). Points per shift double from 4 until the standard error of the smaller of the probability and the complement is at most relative_error of it, or until 2^16 points per shift (2^20 in all); the error then shows that the limit was reached. A problem with rare overlaps, or with a coordinate correlated beyond 0.999 with the one it conditions on, takes at least 16 points per shift: both make features that 4 points per shift miss together, in a shift as in the others, so that their spread understates the error. Problems that share df share the chi-squared quantiles of the points.

  • Two coordinates without random numbers. A bivariate t vector is Z / S with Z = L u for a Cholesky factor L of R and u standard normal in the plane. In polar coordinates the angle of u is uniform and independent of its length, and (|u| / S)^2 / 2 follows the F distribution on 2 and df degrees of freedom, whose upper tail at r^2 / 2 is G(r) = (1 + r^2 / df)^(-df / 2) (exp(-r^2 / 2) for the normal). So the probability of a box is the average over the direction theta of G(rho_in) - G(rho_out), where rho_in and rho_out are the distances from the origin at which the ray in direction theta enters and leaves the box (own algebra from these two facts). The average is computed by adaptive Gauss-Kronrod quadrature (7 and 15 points; Piessens et al. 1983) between the directions where the face of the box that the ray meets changes, to a relative error of 1e-12 of the smaller of the probability and its complement, with the difference of the two rules as the error. One coordinate uses the t distribution directly.

  • Quantiles. The equicoordinate quantile solves for the limit at which the probability, or the complement for probabilities of at least 1/2, reaches its target. It lies between the univariate quantile at the probability and the one that Bonferroni’s inequality gives; the root is found by bisection between these bounds with the shifts and points held fixed, which makes the estimate a smooth function of the limit, until the estimate changes across the bracket by less than 1% of its standard error; while the standard error exceeds its target, points double and the bisection starts again from the bounds. The quantile’s error is the standard error of the probability over the slope of the estimate across the final bracket.

References

Genz A (1992). Numerical computation of multivariate normal probabilities. Journal of Computational and Graphical Statistics 1, 141-149. doi:10.1080/10618600.1992.10477010

Genz A, Bretz F (2002). Comparison of methods for the computation of multivariate t probabilities. Journal of Computational and Graphical Statistics 11, 950-971. doi:10.1198/106186002394

Owen AB, Maximov Y, Chertkov M (2019). Importance sampling the union of rare events with an application to power systems analysis. Electronic Journal of Statistics 13, 231-254. doi:10.1214/18-EJS1527

Piessens R, de Doncker-Kapenga E, Überhuber CW, Kahaner DK (1983). Quadpack. Springer, Berlin. doi:10.1007/978-3-642-61786-7

Explained in: Multiple testing

class cytepool.stats.multivariate_t.MultivariateTProbability(probability, complement, error)#

The probability of a box under a multivariate t distribution, with its error.

Variables:
  • probability – P(T_i <= upper_i for every i), or P(|T_i| <= upper_i for every i) for a two-sided box.

  • complement – 1 - probability, computed so that it keeps its relative accuracy when it is small: the chance that some T_i leaves its interval, the adjusted p-value of a max-t test.

  • error – The estimated error of both: the standard error of the Monte Carlo estimate with three or more coordinates, the error bound of the quadrature with two, and 0 with one.

Each is a float for one problem, and a read-only array of the problems’ shape otherwise.

Explained in: Multiple testing

class cytepool.stats.multivariate_t.MultivariateTQuantile(quantile, error)#

An equicoordinate quantile of a multivariate t distribution, with its error.

Variables:
  • quantile – The q with P(T_i <= q for every i) = probability, or P(|T_i| <= q for every i) = probability for a two-sided quantile.

  • error – The standard error of q.

Each is a float for one problem, and a read-only array of the problems’ shape otherwise.

Explained in: Multiple testing

cytepool.stats.multivariate_t.multivariate_t_cdf(upper, correlation, df, *, two_sided=False, relative_error=0.01, rng=None)#

Probability that every coordinate of a multivariate t vector stays within its limit, and its complement.

T has standard t marginals on df degrees of freedom and correlation matrix correlation: T = Z / S with Z normal, mean 0 and covariance correlation, and df S^2 chi-squared on df degrees of freedom; df=np.inf gives the multivariate normal distribution, and df need not be an integer, as moderated tests give. The complement is computed directly, so that it keeps its relative accuracy when it is small: it is the adjusted p-value of a max-t test, such as P(max |T_i| >= c) for a two-sided box with every limit c. With three or more coordinates, the computation is randomized and stops when the standard error of the smaller of the probability and the complement is at most relative_error times it; with two it is a deterministic quadrature, accurate to about 1e-12 relative, and with one it is the t distribution itself. https://docs.nygen.io/CytePool/statistics/multiple-testing#multivariate-t-probabilities explains the method.

The arguments broadcast over leading dimensions: the problems are those of the broadcast shape of upper[..., 0], correlation[..., 0, 0] and df. NaN in a limit, a correlation or df gives NaN.

Parameters:
  • upper – (..., k) upper limits; +inf for none. With two_sided, the box is |T_i| <= upper_i, and the limits must be at least 0.

  • correlation – (..., k, k) correlation matrices: symmetric to 1e-10, with a unit diagonal to 1e-10, and positive semidefinite (smallest eigenvalue at least -1e-10 times the largest); singular matrices, such as those of all pairwise contrasts, are allowed.

  • df – Degrees of freedom, positive; np.inf for the normal distribution.

  • two_sided – Whether the box is two-sided, -upper_i <= T_i <= upper_i.

  • relative_error – The largest standard error of the smaller of the probability and its complement, as a fraction of it, between 0 and 1; the default gives two significant digits. The computation stops at 2^20 points per problem whatever the error, which error then shows.

  • rng – A numpy random generator, a non-negative integer seed, or None. One set of 16 random shifts is drawn per call and serves every problem, so a seed gives the same values whatever the order of the problems and the number of threads. Problems of one or two coordinates use no random numbers.

Returns:

The probability, its complement and their error, as floats for one problem and as read-only arrays of the problems’ shape otherwise.

Raises:
  • ValueError – If correlation is not square, symmetric, of unit diagonal or positive semidefinite, has no coordinates or an infinite entry, the shapes do not broadcast, a two-sided limit is negative, df is not positive, or relative_error is not between 0 and 1.

  • TypeError – If an argument has the wrong type or is a numpy masked array.

Example

>>> import numpy as np
>>> correlation = np.full((3, 3), 0.5) + 0.5 * np.eye(3)
>>> result = multivariate_t_cdf([2.5, 2.5, 2.5], correlation, df=10,
...                             two_sided=True, rng=1)
>>> round(result.complement, 3)  # P(max |T_i| >= 2.5)
0.076

Explained in: Multiple testing

cytepool.stats.multivariate_t.multivariate_t_quantile(probability, correlation, df, *, two_sided=False, relative_error=0.01, rng=None)#

Equicoordinate quantile of a multivariate t distribution: the critical value of a max-t test.

The q with P(T_i <= q for every i) = probability, or, with two_sided, P(|T_i| <= q for every i) = probability, as mvtnorm’s qmvt with tail = "lower.tail" or "both.tails"; T is as in multivariate_t_cdf(). A one-sided max-t test at level alpha rejects when the largest t-statistic exceeds the quantile at 1 - alpha, and a two-sided one when the largest absolute value does. The search stops when the standard error of the smaller of the probability and its complement at q is at most relative_error times it. https://docs.nygen.io/CytePool/statistics/multiple-testing#multivariate-t-probabilities explains the method.

The arguments broadcast over leading dimensions, as in multivariate_t_cdf(). NaN in the probability, a correlation or df gives NaN.

Parameters:
  • probability – The probability of the box, between 0 and 1, exclusive.

  • correlation – (..., k, k) correlation matrices, as in multivariate_t_cdf().

  • df – Degrees of freedom, positive; np.inf for the normal distribution.

  • two_sided – Whether the box is two-sided, -q <= T_i <= q.

  • relative_error – As in multivariate_t_cdf().

  • rng – As in multivariate_t_cdf().

Returns:

The quantile and its standard error, which is 0 with one coordinate, as floats for one problem and as read-only arrays of the problems’ shape otherwise.

Raises:
  • ValueError – If a probability is not between 0 and 1, correlation is not a valid correlation matrix, the shapes do not broadcast, df is not positive, or relative_error is not between 0 and 1.

  • TypeError – If an argument has the wrong type or is a numpy masked array.

Example

>>> import numpy as np
>>> correlation = np.full((3, 3), 0.5) + 0.5 * np.eye(3)
>>> critical = multivariate_t_quantile(0.95, correlation, df=10,
...                                    two_sided=True, rng=1)
>>> round(critical.quantile, 2)
2.76

Explained in: Multiple testing