conf: coversim – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

coversim

Confidence Region Coverage

Description

Creates a confidence region and determines coverage results for a corresponding point of interest. Iterates through a user specified number of trials. Each trial uses a random dataset with user-specified parameters (default) or a user specified dataset matrix ('n' samples per column, 'iter' columns) and returns the corresponding actual coverage results. See the CRAN website https://CRAN.R-project.org/package=conf for a link to a coversim vignette.

Usage

coversim(alpha, distn,
                n         = NULL,
                iter      = NULL,
                dataset   = NULL,
                point     = NULL,
                seed      = NULL,
                a         = NULL,
                b         = NULL,
                kappa     = NULL,
                lambda    = NULL,
                mu        = NULL,
                s         = NULL,
                sigma     = NULL,
                theta     = NULL,
                heuristic = 1,
                maxdeg    = 5,
                ellipse_n = 4,
                pts       = FALSE,
                mlelab    = TRUE,
                sf        = c(5, 5),
                mar       = c(4, 4.5, 2, 1.5),
                xlab      = "",
                ylab      = "",
                main      = "",
                xlas      = 0,
                ylas      = 0,
                origin    = FALSE,
                xlim      = NULL,
                ylim      = NULL,
                tol       = .Machine$double.eps ^ 1,
                info      = FALSE,
                returnsamp  = FALSE,
                returnquant = FALSE,
                repair    = TRUE,
                exact     = FALSE,
                showplot  = FALSE,
                delay     = 0 )

Arguments

`alpha`	significance level; scalar or vector; resulting plot illustrates a 100(1 - `alpha`)% confidence region.
`distn`	distribution to fit the dataset to; accepted values: `'cauchy'`, `'gamma'`, `'invgauss'`, `'logis'`, `'llogis'`, `'lnorm'`, `'norm'`, `'unif'`, `'weibull'`.
`n`	trial sample size (producing each confidence region); scalar or vector; needed if a dataset is not given.
`iter`	iterations (or replications) of individual trials per parameterization; needed if a dataset is not given.
`dataset`	a `'n'` x `'iter'` matrix of dataset values, or a vector of length `'n'` (for a single iteration).
`point`	coverage is assessed relative to this point.
`seed`	random number generator seed.
`a`	distribution parameter (when applicable).
`b`	distribution parameter (when applicable).
`kappa`	distribution parameter (when applicable).
`lambda`	distribution parameter (when applicable).
`mu`	distribution parameter (when applicable).
`s`	distribution parameter (when applicable).
`sigma`	distribution parameter (when applicable).
`theta`	distribution parameter (when applicable).
`heuristic`	numeric value selecting method for plotting: 0 for elliptic-oriented point distribution, and 1 for smoothing boundary search heuristic.
`maxdeg`	maximum angle tolerance between consecutive plot segments in degrees.
`ellipse_n`	number of roughly equidistant confidence region points to plot using the elliptic-oriented point distribution (must be a multiple of four because its algorithm exploits symmetry in the quadrants of an ellipse).
`pts`	displays confidence region boundary points if `TRUE` (applies to confidence region plots in which `showplot = TRUE`).
`mlelab`	logical argument to include the maximum likelihood estimate coordinate point (default is `TRUE`, applies to confidence region plots when `showplot = TRUE`).
`sf`	significant figures in axes labels specified using sf = c(x, y), where x and y represent the optional digits argument in the R function `round` as it pertains the horizontal and vertical labels.
`mar`	specifies margin values for `par(mar = c( ))` (see `mar` in `par`).
`xlab`	string specifying the horizontal axis label (applies to confidence region plots when `showplot = TRUE`).
`ylab`	string specifying the vertical axis label (applies to confidence region plots when `showplot = TRUE`).
`main`	string specifying the plot title (applies to confidence region plots when `showplot = TRUE`).
`xlas`	numeric in 0, 1, 2, 3 specifying the style of axis labels (see `las` in `par`, applies to confidence region plots when `showplot = TRUE`).
`ylas`	numeric in 0, 1, 2, 3 specifying the style of axis labels (see `las` in `par`, applies to confidence region plots when `showplot = TRUE`).
`origin`	logical argument to include the plot origin (applies to confidence region plots when `showplot = TRUE`).
`xlim`	two element vector containing horizontal axis minimum and maximum values (applies to confidence region plots when `showplot = TRUE`).
`ylim`	two element vector containing vertical axis minimum and maximum values (applies to confidence region plots when `showplot = TRUE`).
`tol`	the `uniroot` parameter specifying its required accuracy.
`info`	logical argument to return coverage information in a list; includes `alpha` value(s), `n` value(s), coverage and error results per iteration, and `returnsamp` and/or `returnquant` when requested.
`returnsamp`	logical argument; if `TRUE` returns random samples used in a matrix with `n` rows, `iter` cols.
`returnquant`	logical argument; if `TRUE` returns random quantiles used in a matrix with `n` rows, `iter` cols.
`repair`	logical argument to repair regions inaccessible using a radial angle from its MLE (multiple root azimuths).
`exact`	logical argument specifying if alpha value is adjusted to compensate for negative coverage bias in order to achieve (1 - alpha) coverage probability using previously recorded Monte Carlo simulation results; available for limited values of alpha (roughly <= 0.2–0.3), n (typically n = 4, 5, ..., 50) and distributions (distn suffixes: weibull, llogis, norm).
`showplot`	logical argument specifying if each coverage trial produces a plot.
`delay`	numeric value of delay (in seconds) between trials so its plot can be seen (applies when `showplot = TRUE`).

Details

Parameterizations for supported distributions are given following the default axes convention in use by crplot and coversim, which are:

	Horizontal	Vertical
Distribution	Axis	Axis
Cauchy	a	s
gamma	θ	κ
inverse Gaussian	μ	λ
log logistic	λ	κ
log normal	μ	σ
logistic	μ	σ
normal	μ	σ
uniform	a	b
Weibull	κ	λ

Each respective distribution is defined below.

The Cauchy distribution for the real-numbered location parameter a, scale parameter s, and x is a real number, has the probability density function

1 / (s π (1 + ((x - a) / s) ^ 2)).
The gamma distribution for shape parameter κ > 0, scale parameter θ > 0, and x > 0, has the probability density function

1 / (Gamma(κ) θ ^ κ) x ^ {(κ - 1)} exp(-x / θ).
The inverse Gaussian distribution for mean μ > 0, shape parameter λ > 0, and x > 0, has the probability density function

√ (λ / (2 π x ^ 3)) exp( - λ (x - μ) ^ 2 / (2 μ ^ 2 x)).
The log logistic distribution for scale parameter λ > 0, shape parameter κ > 0, and x ≥ 0, has a probability density function

(κ λ) (x λ) ^ {(κ - 1)} / (1 + (λ x) ^ κ) ^ 2.
The log normal distribution for the real-numbered mean μ of the logarithm, standard deviation σ > 0 of the logarithm, and x > 0, has the probability density function

1 / (x σ √(2 π)) exp(-(\log x - μ) ^ 2 / (2 σ ^ 2)).
The logistic distribution for the real-numbered location parameter μ, scale parameter σ, and x is a real number, has the probability density function

(1 / σ) exp((x - μ) / σ) (1 + exp((x - μ) / σ)) ^ {-2}
The normal distribution for the real-numbered mean μ, standard deviation σ > 0, and x is a real number, has the probability density function

1 / √ (2 π σ ^ 2) exp(-(x - μ) ^ 2 / (2 σ ^ 2)).
The uniform distribution for real-valued parameters a and b where a < b and a ≤ x ≤ b, has the probability density function

1 / (b - a).
The Weibull distribution for scale parameter λ > 0, shape parameter κ > 0, and x > 0, has the probability density function

κ (λ ^ κ) x ^ {(κ - 1)} exp(-(λ x) ^ κ).

Value

If the optional argument info = TRUE is included then a list of coverage results is returned. That list includes alpha value(s), n value(s), coverage and error results per iteration. Additionally, returnsamp = TRUE and/or returnquant = TRUE will result in an n row, iter column maxtix of sample and/or sample cdf values.

Author(s)

Christopher Weld (ceweld@email.wm.edu)

Lawrence Leemis (leemis@math.wm.edu)

References

Weld, C., Loh, A., Leemis, L. (in press), "Plotting Likelihood-Ratio Based Confidence Regions for Two-Parameter Univariate Probability Models", The American Statistician.

Examples

## assess actual coverage at various alpha = {0.5, 0.1} given n = 30 samples,  completing
## 10 trials per parameterization (iter) for a normal(mean = 2, sd = 3) rv
coversim(alpha = c(0.5, 0.1), "norm", n = 30, iter = 10, mu = 2, sigma = 3)

## show plots for 5 iterations of 30 samples each from a Weibull(2, 3)
coversim(0.5, "weibull", n = 30, iter = 5, lambda = 1.5, kappa = 0.5, showplot = TRUE,
origin = TRUE)

conf

Visualization and Analysis of Statistical Measures of Confidence

v1.7.0

GPL (<= 2)

Authors

Christopher Weld [aut, cre] (<https://orcid.org/0000-0001-5902-9738>), Hayeon Park [aut], Kexin Feng [aut], Heather Sasinowska [aut], Lawrence Leemis [aut], Andrew Loh [ctb], Yuan Chang [ctb], Brock Crook [ctb], Xin Zhang [ctb]

Initial release