getHitProb: Hit probability within given region
In dwoll/shotGroups: Analyze Shot Group Data

getHitProb

R Documentation

Hit probability within given region

Description

Calculates the hit probability within a circular or spherical region for a given group of two- or three-dimensional coordinates.

Usage

getHitProb(xy, r=1, unit = 'unit', dstTarget, conversion,
           center = FALSE, accuracy = FALSE, type = 'CorrNormal', doRob = FALSE)

## S3 method for class 'data.frame'
getHitProb(xy, r=1, unit = 'unit', dstTarget, conversion,
           center = FALSE, accuracy = FALSE, type = 'CorrNormal', doRob = FALSE)

## Default S3 method:
getHitProb(xy, r=1, unit = 'unit', dstTarget, conversion,
           center = FALSE, accuracy = FALSE, type = 'CorrNormal', doRob = FALSE)

Arguments

`xy`	either a numerical (n x p)-matrix with the coordinates of n points (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`).
`r`	a numerical vector with the radius values for the circle/sphere that defines the region for which the probability should be calculated.
`unit`	Measurement unit for radius `r`. Default `'unit'` indicates that the measurement unit for (x,y)-coordinates given in `conversion`. Possible values are `'unit', 'm', 'cm', 'mm', 'yd', 'ft', 'in', 'deg', 'MOA', 'SMOA', 'rad', 'mrad', 'mil'`.
`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 `getHitProb.data.frame()`.
`accuracy`	logical: take systematic location bias into account? See details.
`type`	string vector indicating which estimation method to use. Possible values are `'CorrNormal', 'GrubbsPearson', 'GrubbsPatnaik', 'GrubbsLiu', 'Rayleigh'`.
`doRob`	logical: use robust estimation of center and covariance matrix as basis for estimates? For Rayleigh only available when `accuracy=FALSE`.

Details

The estimated hit probability is the same as the estimated fraction of shots with a distance to their group center of at most r.

For accuracy=FALSE (default), the estimated hit probability does not take into account accuracy, i.e., any systematic location bias. The data is then first centered on the empirical group mean, assumed to coincide with the point of aim. Set accuracy=TRUE to incorporate systematic accuracy bias such that the point of aim is in the origin 0, possibly offset from the true group center.

CorrNormal: For accuracy=FALSE and two-dimensional data, this estimate is based on the quantile function of the correlated bivariate normal distribution re-written in polar coordinates (radius and angle) (see Hoyt). For accuracy=TRUE or three-dimensional data, it is based on the (offset) circle/sphere probabilities for the correlated multivariate normal distribution (DiDonato & Jarnagin, 1961; DiDonato, 1981, see pmvnEll).
GrubbsPearson: The Grubbs-Pearson estimate (Grubbs, 1964) is based on the Pearson three-moment central chi^2-approximation of the true cumulative distribution function of radial error. The eigenvalues of the covariance matrix of shot-coordinates are used as variance estimates since they are the variances of the principal components (the PCA-rotated = decorrelated data).
GrubbsPatnaik: The Grubbs-Patnaik estimate (Grubbs, 1964) differs from the Grubbs-Pearson estimate insofar as it is based on the Patnaik two-moment central chi^2-approximation of the true cumulative distribution function of radial error.
GrubbsLiu: The Grubbs-Liu estimate was not proposed by Grubbs but follows the same principle as his original estimates. It differs from them insofar as it is based on the Liu-Tang-Zhang four-moment non-central chi^2-approximation of the true cumulative distribution function of radial error. For accuracy=FALSE, it is identical to GrubbsPearson.
Rayleigh: For accuracy=FALSE and two-dimensional data, this estimate uses the Rayleigh distribution (see getRayParam). It is valid for uncorrelated bivariate normal coordinates with equal variances. This estimate is available for all probability levels. For accuracy=FALSE and three-dimensional data, the Maxwell-Boltzmann distribution is used (see getRayParam). For accuracy=TRUE and two-dimensional data, the estimate uses the Rice distribution (see getRiceParam). For accuracy=TRUE and three-dimensional data, it is based on the offset sphere probabilities for the multivariate normal distribution set to have equal variances (see qmvnEll).

If package shiny is installed, an interactive web app for this functionality can be run with runGUI("hitprob").

Value

A vector with the (chosen) hit-probability estimates. For more than one r and more than one type, a matrix.

References

DiDonato, A. R. (1988). Integration of the trivariate normal distribution over an offset spehere and an inverse problem (NSWC TR 87-27). Dahlgren, VA: U.S. Naval Surface Weapons Center Dahlgren Division.

DiDonato, A. R., & Jarnagin, M. P. (1961). Integration of the general bivariate Gaussian distribution over an offset circle. Mathematics of Computation, 15 (76), 375-382.

Grubbs, F. E. (1964). Approximate circular and noncircular offset probabilities of hitting. Operations Research, 12(1), 51-62.

Liu, H., Tang, Y., & Zhang, H. H. (2009). A new chi-square approximation to the distribution of non-negative definite quadratic forms in non-central normal variables. Computational Statistics & Data Analysis, 53(4), 853-856.

Singh, H. P. 1992. Estimation of Circular Probable Error. The Indian Journal of Statistics, Series B 5(3), 289-305.

Examples

# coordinates given by a suitable data frame
# estimated fraction of shots within a circle with radius
# 1 and 1.5 MOA.
getHitProb(DFscar17, r=c(1, 1.5), unit='MOA', accuracy=FALSE,
           dstTarget=100, conversion='yd2in',
           type=c('CorrNormal', 'GrubbsPatnaik'))

# coordinates given by a matrix
## Not run: 
xy <- matrix(round(rnorm(100, 0, 5), 2), ncol=2)
getHitProb(xy, r=c(2, 2.5), unit='MOA', accuracy=FALSE,
           dstTarget=100, conversion='yd2in',
           type=c('CorrNormal', 'GrubbsPatnaik'))

## End(Not run)

dwoll/shotGroups documentation built on Feb. 16, 2024, 2:21 p.m.