coversim: Confidence Region Coverage

Description Usage Arguments Details Value Author(s) References See Also Examples

View source: R/coversim.R

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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.

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.

See Also

crplot, uniroot

Examples

1
2
3
4
5
6
7
## 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 documentation built on Aug. 24, 2020, 5:08 p.m.