*! version 1.7 03 Jan 2019

Title

Title

mvt -- Multivariate t Distribution

Syntax

mvt, [options]

Main
lower(numlist miss) Vector of lower integration limits.

upper(numlist miss) Vector of upper integration limits.

delta(numlist) Vector of non-centrality parameters.

sigma(string) Covariance matrix.

df(#) Degrees of freedom.

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

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.

alpha(#) Value of the Monte Carlo confidence factor.

Description

mvt computes the distribution function of the multivariate t distribution. Arbitrary integration limits, non-centrality parameters, scale matrices, and degrees of freedom are supported.

For one-dimensional multivariate 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).
Note that unlike pmvnormal, mvt is not yet vectorised, which may make its run time long compared to the corresponding multivariate normal command.

Options

Required

lower(numlist miss) A numlist (vector) giving the lower integration limits.
Missing values are allowed, as . can be used to indicate a value is -Infinity.

upper(numlist miss) A numlist (vector) giving the upper integration limits.
Its length must be equal to the length of lower, and the elements of upper must be strictly greater than the corresponding elements in lower.
Missing values are allowed, as . can be used to indicate a value is +Infinity.

Optional

delta(numlist) A numlist (vector) giving the non-centrality parameters of the multivariate t distribution under consideration.
If specified, its length must be equal to the length of option lower.
If left unspecified, it will default internally to the zero vector of the correct length.

sigma(string) A string (matrix) giving the scale matrix of the multivariate t distribution under consideration.
If specified, it must be symmetric positive-definite, and its number of rows (equivalently columns) must be equal to the length of option lower.
If left unspecified, it will default internally to the identity matrix of the correct dimension.

df(#) A real giving the number of degrees of freedom of the multivariate t distribution under consideration.
It must be either greater than or equal to zero, or missing.
Multivariate normal distribution functions will be computed when it is equal to zero or is missing, using the method of pmvnormal or mvnormalcv depending on the value of integrator.
It defaults to 1.

integrator(string) Only used when df is equal to zero or is missing.
It is then a string giving the method for evaluating the required multivariate normal distribution function.
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(#) Not used when df is equal to zero or missing and integrator is equal to mvnormalcv.
It is 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 integral.
It defaults to 12.

samples(#) Not used when df is equal to zero or missing and integrator is equal to mvnormalcv.
It is an integer giving the number of samples to use in each shift of the Quasi-Monte Carlo integration algorithm.
It must be greater than or equal to 1.
Theoretically, increasing samples will increase run-time but reduce the error in the returned value of the integral.
It defaults to 1000.

alpha(#) Not used when df is equal to zero or missing and integrator is equal to mvnormalcv.
It is a real giving the value of the Monte Carlo confidence factor, used to provide an estimate of the error in returned integral value.
It must be strictly positive.
Defaults to 3.

Examples

/// Example 1: Without specifying delta or sigma

mvt, lower(-2, -2, -2) upper(2, 2, 2)

/// Example 2: Specifying delta and sigma

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

mvt, lower(-2, -2, -2) upper(2, 2, 2) delta(0, 0, 0) sigma(Sigma)

/// Example 3: Reducing the error using samples

mvt, lower(-2, -2, -2) upper(2, 2, 2) delta(0, 0, 0) sigma(Sigma) samples(10000)

/// Example 4: Requesting multivariate normal distribution function

mvt, lower(-2, -2, -2) upper(2, 2, 2) delta(0, 0, 0) sigma(Sigma) df(0)

pmvnormal, lower(-2, -2, -2) upper(2, 2, 2) mean(0, 0, 0) sigma(Sigma)

Stored results

mvt stores the following in r():

scalars:

r(integral) Computed integral.

r(error) Estimated error in the computed integral.

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:

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.

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

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)