{smcl}
{* 07jul2005}{...}
{cmd:help mata mvnlattice()}
{hline}

{title:Title}

{p 4 8 2}
{bf: mvnlattice() -- Lattice rule approximation of the MVN probability function}


{title:Syntax}

{p 8 8 2}
{it:real rowvector}{bind:}
{cmd:mvnlattice(}{it:real vector a}, {it:b}, {it:real matrix R} [, {it:real scalar maxn}
[, {it:eps}]]{cmd:)}


{title:Description}

{p 4 4 2}
This routine numerically approximates the integral of the multivariate normal
(MVN) density function using a rank-1 lattice rule, a form of constant weight
quadrature.
The lower and upper bounds of integration are contained in the
vectors {it:a} and {it:b}, respectively.  Missing values denote minus infinity in
{it:a} and plus infinity in {it:b}.  The matrix {it:R} contains either the MVN
variance-covariance or its correlation matrix.  The optional scalar {it:maxn}
sets the maximum number of points to use in the lattice rule, default 1.0e4, and scalar 
{it:eps} sets the targeted absolute error of the quadrature, default 1.0e-4.

{title:Remarks}

{p 4 4 2}
Efficient implementation of the rank-1 lattice rule is carried out by first
transforming the original integral into an integral over the unit hypercube as
described by Genz (1992).  Further techniques outlined by Genz and Bretz (2002)
are used to estimate the absolute error of the integral which involves shifting
the lattice using pseudo-uniform random numbers.  The method of good
lattice points described by Sloan and Joe (1994), Chapter 4, are used to compute
the coefficients of the Korobov rank-1 lattice generator.

{title:Conformability}

    {cmd:mvnlattice(}{it:a}, {it:b}, {it:R}, {it:maxn}, {it:eps}{cmd:):}
	{it:input:}
		{it:a}:  {it:1 x n}, or {it:n x 1}
		{it:b}:  {it:1 x n}, or {it:n x 1}
		{it:R}:  {it:n x n}
	     {it:maxn}:  {it:1 x 1}
	      {it:eps}:  {it:1 x 1}
       {it:output:}
           {it:result}:  {it:1 x 3}
		 

{title:Diagnostics}

{p 4 4 2}
{cmd:mvnlattice(}{it:a}, {it:b}, {it:R}{cmd:)}
returns a vector of length 3 in which the first element is the estimated
integral, the second element its estimated absolute error of the
integral, and the last element contains the number of points used.

{p 4 4 2}
Use {cmd:setseed()} in order to reproduce the results.

{title:Examples}

: R = (1,.2,.3,-.4\.2,1,-.2, .5\.3,-.2,1,.3\-.4,.5,.3,1)
: mvnlattice((-.5,-.6,-1,-1.5),(2,0,1,.5),R)
                 1             2             3
    +-------------------------------------------+
  1 |  .0914858347   .0000361571          4630  |
    +-------------------------------------------+
: mvnlattice((-.5,-.6,-1,-1.5),(2,0,1,.5),R)

                 1             2             3
    +-------------------------------------------+
  1 |  .0914863778   .0000382281          4630  |
    +-------------------------------------------+


{title:References}

{p 4 6 2}
Genz, A. 1992. Numerical computation of multivariate normal probabilities.
Journal of Computational and Graphical Statistics, 1:141-149.

{p 4 6 2}
Genz, A. and F. Bretz 2002. Comparison of methods fot the computation of 
multivariate t probabilities.  Journal of Computational and Graphical Statistics
11:950-971.

{p 4 6 2}
Sloan, I.H. and S. Joe 1994. Lattice Methods for multiple Integration.
Oxford University Press 

{title:Source code}

{p 4 4 2}
{view mvnlattice.mata}

{title:Also see}

{p 4 13 2}
{hi: rank1coef()}

{p 4 13 2}
Online:  help for 
{bf:{help rank1coef: rank1coef()}}
{p_end}