qle (version 0.18)

mahalDist: Mahalanobis distance of statistics

Description

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

Usage

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

Arguments

points

either matrix or list of points or a vector of parameters (but then considered as a single (multidimensional) point)

qsd

object of class QLmodel

Sigma

either a constant variance matrix estimate or an prespecified 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 (overwrites `qsd$obs` if given)

inverted

logical, FALSE (default), whether `Sigma` is already inverted when used as constant variance matrix only

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

Value

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 constant `Sigma`)

jac

Jacobian of sample mean values of statistics

varS

estimated variance matrix of `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

Details

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

There are several options how to estimate or choose the variance matrix of the statistics \(\Sigma\). First, in case of a given constant variance matrix estimate `Sigma`, the Mahalanobis distance reads $$ (T(x)-E_{\theta}[T(X)])^t\Sigma^{-1}(T(x)-E_{\theta}[T(X)]) $$ and `Sigma` is used as given.

As a second option, the variance matrix \(\Sigma\) can be estimated by the average approximation $$\bar{V}=\frac{1}{n}\sum_{i=1}^n V_i $$ based on the simulated variance matrices \(V_i=V(\theta_i)\) of statistics over all sample points \(\theta_1,...,\theta_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 these average approximation types is also available (see covarTx).

As a continuous version of variance approximation we use a kriging approach (see [1]). Then $$\Sigma(\theta) = Var_{\theta}(T(X))$$ denotes the variance matrix which depends on the parameter \(\theta\in R^q\) and corresponds to the formal function argument `points`. Each time a value of the criterion function is calculated at any parameter `points` the variance matrix is estimated by the correpsonding approach either with or without using prediction variances as explained above. Note that in this case the argument `Sigma` is ignored.

Examples

# NOT RUN {
 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)  
 
# }