*! version 1.6 03 Jan 2019

Title

invtmvnormal -- Quantiles of the Truncated Multivariate Normal Distribution

Syntax

invtmvnormal, [options]

Required
p(#) Probability.

lowertruncation(numlist miss) Vector of lower truncation points.

uppertruncation(numlist miss) Vector of upper truncation points.

Optional
mean(numlist) Mean vector.

sigma(string) Covariance matrix.

tail(string) Which type of quantile should be computed.

max_iter(string) Maximum number of allowed iterations in the root-finding algorithm.

tolerance(string) Desired tolerance in the root-finding algorithm.

integrator(string) Method for evaluating required multivariate normal distribution functions.

shifts(#) Number of shifts of the Quasi-Monte Carlo integration algorithm.

samples(#) Number of samples in each shift of the Quasi-Monte Carlo integration algorithm.

Description

invtmvnormal computes equicoordinate quantiles of a specified truncated multivariate normal distribution through Brent's root finding algorithm (Brent, 1973).
Arbitrary means, covariance matrices, and truncation points are supported.

For one- and two-dimensional multivariate normal distributions it makes use of the functionality provided by invnormal and binormal respectively. For multivariate normal distributions of dimension three or more, support is available to evaluate requisite multivariate normal distribution functions using the approaches of both pmvnormal and mvnormalcv (see option integrator).

Options

Required

p(#) A real giving the desired tail probability. It must be between zero and one inclusive.

lowertruncation(numlist miss) A numlist (vector) giving the lower truncation points for the truncated multivariate normal distribution under consideration.
Its length must be equal to the length of option lower.
Missing values are allowed, as . can be used to indicated a value is -Infinity.

uppertruncation(numlist miss) A numlist (vector) giving the upper truncation points for the truncated multivariate normal distribution under consideration.
Its length must be equal to the length of option lower, and the elements of uppertruncation must be strictly greater than the corresponding elements in lowertruncation.
Missing values are allowed, as . can be used to indicated a value is +Infinity.

Optional

mean(numlist) A numlist (vector) giving the mean of the non-truncated multivariate normal distribution from which the truncated multivariate normal distribution under consideration is constructed.
If specified, its length must be equal to the length of option lowertruncation.
If left unspecified, it will default internally to the zero vector of the correct length.

sigma(string) A string (matrix) giving the covariance matrix of the non-truncated multivariate normal distribution from which the truncated multivariate normal distribution under consideration is constructed.
If specified, It must be symmetric positive-definite, and its number of rows (equivalently columns) must be equal to the length of option lowertruncation.
If left unspecified, it will default internally to the identity matrix of the correct dimension.

tail(string) A string specifying which type of quantile should be computed.
It must be either lower, upper, or both.
lower gives the x such that P(X <= x) = p, upper such that P(X >= x) = p, and both such that P(-x <= X <= x) = p.
It left unspecified, it defaults internally to lower.

max_iter(#) An integer giving the maximum allowed number of iterations in the root-finding algorithm.
It must be greater than or equal to one.
It defaults to 1000000.

tolerance(#) A real giving the desired tolerance in the root-finding algorithm.
It must be strictly positive.
It defaults to 0.000001.

integrator(string) A string giving the method for evaluating the required multivariate normal distribution functions.
It must be either pmvnormal (to use the method from pmvnormal) or mvnormal (to use mvnormalcv as released in Stata 15).
If left unspecified, it will default internally to pmvnormal.

shifts(#) Only used when integrator is set to pmvnormal.
It is then an integer giving the number of shifts to use in the Quasi-Monte Carlo integration algorithm.
It must be strictly positive.
Theoretically, increasing shifts will increase run-time but reduce the error in the returned value of the quantile.
It defaults to 12.

samples(#) Only used when integrator is set to pmvnormal.
It is then an integer giving the number of samples to use in each shift of the Quasi-Monte Carlo integration algorithm.
It must be strictly positive.
Theoretically, increasing samples will increase run-time but reduce the error in the returned value of the quantile.
It defaults to 1000.

Examples

/// Example 1: Without specifying mean or sigma

invtmvnormal, p(0.95) lowertruncation(-2, -2, -2) uppertruncation(2, 2, 2)

/// Example 2: Specifying mean, sigma, and tail

mat Sigma = (1, 0.5, 0.5 \ 0.5, 1, 0.5 \ 0.5, 0.5, 1)

invtmvnormal, p(0.95) lowertruncation(-2, -2, -2) uppertruncation(2, 2, 2) mean(1, 1, 1) sigma(Sigma) tail(upper)

Stored results

invtmvnormal stores the following in r():

scalars:

r(quantile) Computed quantile.

r(error) Estimated error in the computed quantile.

r(flag) Flag indicating the progress of the root-finding algorithm. Non-zero values indicate a potential problem.

r(fquantile) Value of the objective function at the computed quantile.

r(iterations) Number of iterations used by the root-finding algorithm.

Authors

Dr Michael J Grayling
Population Health Sciences Institute, Newcastle University, UK
Email: michael.grayling@newcastle.ac.uk

Prof Adrian P Mander
Centre for Trials Research, Cardiff University, Cardiff, UK

See also

References:

Brent R (1973) Algorithms for minimization without derivatives. Prentice-Hall: New Jersey, US.

Genz A, Bretz F (2009) Computation of multivariate normal and t probabilities. Lecture Notes in Statistics, Vol 195. Springer-Verlag: Heidelberg, Germany.

Gibson GJ, Glasbey CA, Elston DA (1994) Monte Carlo evaluation of multivariate normal integrals and sensitivity to variate ordering.
In Advances in numerical methods and applications, ed Dimov IT, Sendov B, Vassilevski PS, 120-6. River Edge: World Scientific Publishing.

Grayling MJ, Mander AP (2018) Calculations involving the multivariate normal and multivariate t distributions with and without truncation. Stata J 18(4):826-43.

Tong YL (2012) The multivariate normal distribution. Springer-Verlag: New York, US.

Related commands:

mvtnorm (for an overview of the functionality provided by mvtnorm)

Multivariate normal distribution

drawnorm (an official Stata command for multivariate normal random deviates)
invmvnormal (mvtnorm command for multivariate normal quantiles)
lnmvnormalden (an official Stata command for multivariate normal densities)
mvnormalcv (an official Stata command for the multivariate normal distribution function)
mvnormalden (mvtnorm command for multivariate normal densities)
pmvnormal (mvtnorm command for the multivariate normal distribution function)
rmvnormal (mvtnorm command for multivariate normal random deviates)

Multivariate t distribution

invmvt (mvtnorm command for multivariate t quantiles)
mvtden (mvtnorm command for multivariate t densities)
mvt (mvtnorm command for the multivariate t distribution function)
rmvt (mvtnorm command for multivariate t random deviates)

Truncated multivariate normal distribution

invtmvnormal (mvtnorm command for truncated multivariate normal quantiles)
rtmvnormal (mvtnorm command for truncated multivariate normal random deviates)
tmvnormal (mvtnorm command for the truncated multivariate normal distribution function)
tmvnormalden (mvtnorm command for truncated multivariate normal densities)

Truncated multivariate t distribution

invtmvt (mvtnorm command for truncated multivariate t quantiles)
rtmvt (mvtnorm command for truncated multivariate t random deviates)
tmvt (mvtnorm command for the truncated multivariate t distribution function)
tmvtden (mvtnorm command for truncated multivariate t densities)