getConfEll: Confidence ellipse

Description

Calculates the confidence ellipse for the true mean of shot coordinates under the assumption of multivariate normality. Also includes the ellipse based on a robust estimate for the covariance matrix of the shot coordinates.

Usage

getConfEll(xy, level = 0.5, dstTarget, conversion,
          center = FALSE, doRob=TRUE)
# S3 method for data.frame
getConfEll(xy, level = 0.5, dstTarget, conversion,
          center = FALSE, doRob=TRUE)
# S3 method for default
getConfEll(xy, level = 0.5, dstTarget, conversion,
          center = FALSE, doRob=TRUE)

Value

A list with the confidence ellipse measures.

ctr: coordinates group center.
ctrRob: coordinates robust estimate of group center.
cov: covariance matrix.
covRob: robust estimate of covariance matrix.
size: a numerical matrix with the lengths of the semi-axes of the ellipse (in original measurement units, MOA, SMOA, milliradian).
sizeRob: a numerical matrix with the lengths of the semi-axes of the ellipse based on a robust estimate for the covariance matrix of shot coordinates (in original measurement units, MOA, SMOA, milliradian).
shape: a numerical vector with the angle, the aspect ratio of the ellipse (square root of condition index kappa), its flattening (1 - inverse aspect ratio) as well as the trace and determinant of the covariance matrix.
shapeRob: a numerical vector with the aspect ratio and the flattening of the ellipse as well as the trace and determinant based on a robust estimate for the covariance matrix of shot coordinates.
magFac: magnification factor used to turn the error ellipse into the confidence ellipse as determined by the F(p, n-1)-distribution.

Arguments

xy: Shot coordinates of n points: either a numerical (n x p)-matrix (1 row of p coordinates per point), or a data frame with either the variables x, y or point.x, point.y (optionally z or point.z).
level: a numerical value with the coverage for the confidence ellipse.
dstTarget: a numerical value giving the distance to the target - used in MOA calculation. Acts as override if variable distance is already included in xy. See getMOA.
conversion: how to convert the measurement unit for distance to target to that of the (x,y)-coordinates in MOA calculation. Acts as override if variables dist.unit and point.unit are already included in xy. Example 'm2cm'. See getMOA.
center: logical: center groups to mean (0,0) first? If variable series does not exist, all shots are treated as belonging to the same group. Only available in method getConfEll.data.frame().
doRob: logical: should robust covariance matrix estimate be used as well?

Details

No coordinate transforms are done (unlike in groupLocation, groupShape, groupSpread), i.e., origin is not assumed to be in top-left corner, and points are not taken relative to point of aim.

Robust estimate for the covariance matrix of coordinates is from covMcd using the MCD algorithm. See getCEP for estimates of the circular/spherical error probable.

Examples

Run this code

# coordinates given by a suitable data frame
(ce <- getConfEll(DFsavage, level=0.5, dstTarget=100,
                  conversion='yd2in'))

# plot points, center, parametric confidence
# ellipse, and its axes
plot(point.y ~ point.x, data=DFsavage, asp=1, pch=16)
drawEllipse(ce, axes=TRUE, fg='blue', colCtr='blue', lwd=2, pch=4, cex=2)

# coordinates given by a matrix
if (FALSE) {
xy <- matrix(round(rnorm(100, 0, 5), 2), ncol=2)
getConfEll(xy, level=0.5, dstTarget=25, conversion='m2cm')
}