mahalDist: Mahalanobis distance of statistics
In mbaaske/qle: Simulation-Based Quasi-Likelihood Estimation

Description Usage Arguments Details Value Author(s) Examples

Compute the Mahalanobis distance (MD) based on the kriging models of statistics

1
2
3

mahalDist(points, qsd, Sigma = NULL, ..., cvm = NULL, obs = NULL,
  inverted = FALSE, check = TRUE, value.only = FALSE, na.rm = TRUE,
  cl = NULL, verbose = FALSE)

`points`	either matrix or list of points or a vector of parameters (but then considered as a single point)
`qsd`	object of class `QLmodel`
`Sigma`	either a constant variance matrix estimate or an pre-specified value
`...`	further arguments passed to `covarTx` for variance average approximation
`cvm`	list of fitted cross-validation models (see `prefitCV`)
`obs`	numeric vector of observed statistics (this overwrites '`qsd$obs`')
`inverted`	logical, `FALSE` (default), whether '`Sigma`' is already inverted when used as constant variance matrix
`check`	logical, `TRUE` (default), whether to check all input arguments
`value.only`	only return the value of the MD
`na.rm`	logical, if `TRUE` (default) remove 'Na' values from the results
`cl`	cluster object, `NULL` (default), of class "`MPIcluster`", "`SOCKcluster`", "`cluster`"
`verbose`	if `TRUE`, then print intermediate output

The function computes the Mahalanobis distance of the given statistics T(X)\in R^p with different options how to approximate the variance matrix. The Mahalanobis distance can be used as an alternative criterion function for estimating the unknown parameter during the main estimation function qle.

There are several options how to estimate or choose the variance matrix of the statistics Σ. First, in case of a given constant variance matrix estimate 'Sigma', the Mahalanobis distance reads

(T(x)-E_{θ}[T(X)])^tΣ^{-1}(T(x)-E_{θ}[T(X)])

and 'Sigma' is directly used.

As a second option, the variance matrix Σ can be estimated by the average approximation

\bar{V}=\frac{1}{n}∑_{i=1}^n V_i

based on the simulated variance matrices V_i=V(θ_i) of statistics over all sample points θ_1,...,θ_n (see vignette). Unless 'qsd$var.type' equals "const" additional prediction variances are added as diagonal terms to account for the kriging approximation error of the statistics using kriging with calculation of kriging variances if 'qsd$krig.type' equal to "var". Otherwise no additional variances are added. A weighted version of the these average approximation types is also available (see covarTx).

As a continuous version of variance approximation we use a kriging approach (see [1]). Then

Σ(θ) = Var_{θ}(T(X))

denotes the variance matrix which depends on the parameter θ\in R^q, which corresponds to the formal function argument 'points'. Each time a value of the criterion function is calculated for any parameter 'point' this matrix is estimated by the correpsonding kriging model defined in 'qsd$covL' either with or without using prediction variances as explained above. Note that in this case the argument 'Sigma' is ignored.

Either a vector of MD values or a list of lists, where each contains the following elements:

`value`	Mahalanobis distance value
`par`	parameter estimate
`I`	approximate variance matrix of the parameter estimate
`score`	gradient of MD (for fixed '`Sigma`')
`jac`	Jacobian of sample average statistics
`varS`	estimated variance of the gradient '`score`'

and, if applicable, the following attributes:

`Sigma`	estimate of variance matrix (if '`Sigma`' is computed or was set as a constant matrix)
`inverted`	whether '`Sigma`' was inverted

M. Baaske

 data(normal)
 # (weighted) least squares
 mahalDist(c(2,1), qsd, Sigma=diag(2))
 
 # generalized LS with variance average approximation 
	# here: same as quasi-deviance
 mahalDist(c(2,1), qsd)