*! version 1.0 03 Jan 2019

Title

mvtnorm -- Module to work with the multivariate normal and multivariate t distributions, with and without variable truncation

Description

mvtnorm provides a set of rclass commands for working with the multivariate normal and multivariate t distributions, with and without truncation.
Specifically, commands are available to: (1)
evaluate probability density functions, (2)
generate random deviates, (3)
evaluate distribution functions, and (4)
compute equicoordinate quantiles.

The best place to start to learn about the available commands is the associated Stata J article, Grayling and Mander (2018), which contains examples on how to (1)
compare the probability density functions of multivariate normal and multivariate t distributions, (2)
compare the familywise error-rates provided by Bonferroni and Dunnett's multiple comparison corrections, (3)
visualise the value of orthont probabilities in the presence of truncation.

However, the available functionality is highly motivated by the established R package of the same name (Genz et al, 2018), and the R package tmvtnorm (Wilhelm and Manjunath, 2015).
Thus, their associated texts, Genz and Bretz (2009) and Wilhelm and Manjunath (2010), will also likely contain useful background information.

Note that some equivalent functionality is present in Stata for the multivaraite normal distribution via the built-in commands lnmvnormalden, drawnorm, and mvnormalcv.
See below for further details.

Finally, note that the file "mvtnorm_mata.do" contains a set of equivalent Mata functions, to allow utilisation in Stata to be bypassed if desired.

Available commands

Multivariate normal distribution

invmvnormal: A command for computing equicoordinate quantiles of the multivariate normal distribution,
based on inversion of integrals evaluated using pmvnormal or mvnormalcv in combination with Brent's root-finding algorithm (Brent, 1973).

mvnormalden: A command for evaluating the probability density function of the multivariate normal distribution.
Provided only for completeness; in general lnmvnormalden should be preferred.

pmvnormal: A command for evaluating the distribution function of the multivariate normal distribution.
For one- and two-dimensional multivariate normal distributions it makes use of the functionality provided by normal and binormal respectively.
For multivariate normal distributions of dimension three or more it utilises a Stata implementation of the algorithm given on page 50 of Genz and Bretz (2009):
a quasi-Monte Carlo integration algorithm over a randomised lattice after separation-of-variables has been performed.
In addition, it employs variable re-ordering in order to improve efficiency as suggested by Gibson et al (1994).
As of v1.7, pmvnormal is also vectorised, which will make it run to completion substantially faster than previous versions.
As of the release of Stata 15, the built in command mvnormalcv is available that provides equivalent functionality via numerical quadrature.
The limitations of quadrature mean that pmvnormal may well have smaller run-time for high-dimensional multivariate normal distributions (roughly of dimension greater than four).
However, for low-dimensional problems, mvnormalcv should in general be preferred.

rmvnormal: A command for generating random deviates of the multivariate normal distribution.
Provided only for completeness; in general drawnorm should be preferred.

Multivariate t distribution

invmvt: A command for computing equicoordinate quantiles of the multivariate t distribution,
based on inversion of integrals evaluated using mvt in combination with Brent's root-finding algorithm (Brent, 1973).

mvtden: A command for evaluating the probability density function of the multivariate t distribution.

mvt: A command for evaluating the distribution function of the multivariate t distribution.
For one-dimensional multivariate t distributions (i.e., univariate t distributions) it makes use of the functionality provided by t.
For multivariate t distributions of dimension two or more it utilises a Stata implementation of the algorithm given on page 50 of Genz and Bretz (2009):
a quasi-Monte Carlo integration algorithm over a randomised lattice after separation-of-variables has been performed.
In addition, it employs variable re-ordering in order to improve efficiency as suggested by Gibson et al (1994).
However, note that unlike pmvnormal, mvt is not yet vectorised, which may make its run time long compared to the corresponding multivariate normal commands.

rmvt: A command for generating random deviates of the multivariate t distribution.

Truncated multivariate normal distribution

invtmvnormal: A command for computing equicoordinate quantiles of the truncated multivariate normal distribution,
based on inversion of integrals evaluated using tmvnormal in combination with Brent's root-finding algorithm (Brent, 1973).

tmvnormalden: A command for evaluating the probability density function of the truncated multivariate normal distribution.

tmvnormal: A command for evaluating the distribution function of the truncated multivariate normal distribution,
using the method of pmvnormal or mvnormalcv for evaluating the requisite multivariate normal distribution functions.

rtmvnormal: A command for generating random deviates of the truncated multivariate normal distribution, based on accept/reject sampling of the corresponding multivariate normal distribution.

Truncated multivariate t distribution

invtmvt: A command for computing equicoordinate quantiles of the truncated multivariate t distribution,
based on inversion of integrals evaluated using tmvt in combination with Brent's root-finding algorithm (Brent, 1973).

tmvtden: A command for evaluating the probability density function of the truncated multivariate t distribution.

tmvt: A command for evaluating the distribution function of the truncated multivariate t distribution, using the method of mvt for evaluating the requisite multivariate t distribution functions.

rtmvt: A command for generating random deviates of the truncated multivariate t distribution, based on accept/reject sampling of the corresponding multivariate t distribution.

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

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.

Genz A, Bretz F, Miwa T, Mi X, Leisch F, Scheipl F, Hothorn T (2018). mvtnorm: Multivariate normal and t distributions. R package version 1.0-8. URL:http://CRAN.R-project.org/package=mvtnorm.

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.

Kotz S, Nadarajah S (2004) Multivariate t distributions and their applications. Cambridge University Press: Cambridge, UK.

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

Wilhelm S, Manjunath BG (2010) tmvtnorm: A package for the truncated multivariate normal distribution. R J 2(1):25-9.

Wilhelm S, Manjunath BG (2015) tmvtnorm: Truncated multivariate normal and student t distribution. R package version 1.4-10. URL:https://cran.r-project.org/package=tmvtnorm.