*! version 1.1 03 Jan 2019

Title

tmvtden -- Truncated Multivariate t Density

Syntax

tmvtden, [options]

Required
x(numlist) Vector of quantiles.

lowertruncation(numlist miss) Vector of lower truncation points.

uppertruncation(numlist miss) Vector of upper truncation points.

Optional
delta(numlist) Vector of non-centrality parameters.

sigma(string) Scale matrix.

df(#) Degrees of freedom.

logdensity Print the log of the density.

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.

Description

tmvtden evaluates the probability density function of a specified truncated multivariate t distribution at a given vector of quantiles.
Arbitrary quantiles, non-centrality parameters, scale matrices, degrees of freedom, and truncation points are supported.

The requisite multivariate t distribution function is evaluated using the method of tmvt.

Options

Required

x(numlist) A numlist (vector) of quantiles at which to evaluate the density.

lowertruncation(numlist miss) A numlist (vector) giving the lower truncation points for the truncated multivariate t distribution under consideration.
Its length must be equal to the length of option x.
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 t distribution under consideration.
Its length must be equal to the length of option x, 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

delta(numlist) A numlist (vector) giving the non-centrality parameters of the non-truncated multivariate t distribution from which the truncated multivariate t distribution under consideration is constructed.
If specified, its length must be equal to the length of option x.
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 non-truncated multivariate t distribution from which the truncated multivariate t 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 x.
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 non-truncated multivariate t distribution from which the truncated multivariate t distribution under consideration is constructed.
It must be either greater than or equal to zero, or missing.
Truncated multivariate normal densities will be computed when it is equal to zero or is missing, using the method of tmvnormalden.
It defaults to 1.

logdensity If specified, this indicates that the log of the density (rather than the density itself) should be printed.

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(#) Only used when df is equal to zero or is missing, and 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 density.
It defaults to 12.

samples(#) Only used when df is equal to zero or is missing, and 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 density.
It defaults to 1000.

Examples

/// Example 1: Without specifying delta or sigma

tmvtden, x(0, 0, 0) lowertruncation(-2, -2, -2) uppertruncation(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)

tmvtden, x(0, 0, 0) lowertruncation(-2, -2, -2) uppertruncation(2, 2, 2) delta(0.5, 1, 1.5) sigma(Sigma)

/// Example 3: Requesting the log of the density with logdensity

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

tmvtden, x(1, 1) lowertruncation(-3, -3) uppertruncation(3, 3) delta(2, 2) sigma(Sigma) log

/// Example 4: Requesting a truncated multivariate normal density

tmvtden, x(1, 1) lowertruncation(-3, -3) uppertruncation(3, 3) delta(2, 2) sigma(Sigma) df(0) log

tmvnormalden, x(1, 1) lowertruncation(-3, -3) uppertruncation(3, 3) mean(2, 2) sigma(Sigma) log

Stored results

tmvtden stores the following in r():

scalars:

r(density) Computed density.

r(log_density) Log of the computed density.

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:

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)