get_qq_band {qqconf}

Create QQ Plot Testing Band

Description

Flexible interface for creating a testing band for a Quantile-Quantile (QQ) plot.

Usage

get_qq_band(
  n,
  obs,
  alpha = 0.05,
  distribution = qnorm,
  dparams = list(),
  ell_params = list(),
  band_method = c("ell", "ks", "pointwise"),
  prob_pts_method = c("best_available", "normal", "uniform", "median")
)

Arguments

n, obs

either a number of observations (specified by setting n), or a numeric vector of observations (specified by setting obs). One argument must be specified. If all parameters of distribution are known, then the testing band only depends on the number of observations n. Thus, providing n is simpler when all parameters of distribution are known and specified via dparams (or when using all default parameter choices of distribution is desired). If estimating parameters from the data is preferred, obs should be specified and estimation will take place as described in the documentation for argument dparams.

alpha

(optional) desired significance level of the testing band. If method is set to "ell" or "ks", then this is the global significance level of the testing band. If method is set to "pointwise", then the band is equivalent to simply conducting a level alpha test on each order statistic individually. Pointwise bands will generally have much larger global Type I error than alpha. Defaults to .05.

distribution

The quantile function for the specified distribution. Defaults to qnorm, which is appropriate for testing normality of the observations in a QQ plot.

dparams

(optional) List of additional arguments for the distribution function (e.g. df=1). If obs is not specified and this argument is left blank, the default arguments of distribution are used. If obs is specified and this argument is left blank, parameters are estimated from the data (except if distribution is set to qunif, in which case no estimation occurs and the default parameters are max = 1 and min = 0). For the normal distribution, we estimate the mean as the median and the standard deviation as Sn from the paper by Rousseeuw and Croux 1993 "Alternatives to the Median Absolute Deviation". For all other distributions besides uniform and normal, the code uses MLE to estimate the parameters. Note that if any parameters of the distribution are specified in dparams, parameter estimation will not be performed on the unspecified parameters, and instead they will take on the default values set by distribution.

ell_params

(optional) list of optional arguments for get_bounds_two_sided (i.e. tol, max_it, method). Only used if method is set to "ell"

band_method

(optional) method for creating the testing band. The default, "ell" uses the equal local levels method (see get_bounds_two_sided for more information). "ks" uses the Kolmogorov-Smirnov test. "pointwise" uses a pointwise band (see documentation for argument alpha for more information). "ell" is recommended and is the default.

prob_pts_method

(optional) method used to get probability points for use in a QQ plot. The quantile function will be applied to these points to get the expected values. When this argument is set to "normal" (recommended for a normal QQ plot) ppoints(n) will be used, which is what most other plotting software uses. When this argument is set to "uniform" (recommended for a uniform QQ plot) ppoints(n, a=0), which are the expected values of the order statistics of Uniform(0, 1), will be used. Finally, when this argument is set to "median" (recommended for all other distributions) qbeta(.5, c(1:n), c(n:1)) will be used. Under the default setting, "best_available", the probability points as recommended above will be used. Note that "median" is suitable for all distributions and is particularly recommended when alpha is large.

Value

A list with components

• lower_bound - Numeric vector of length n containing the lower bounds for the acceptance regions of the test corresponding to each order statistic. These form the lower boundary of the testing band for the QQ-plot.

• upper_bound - Numeric vector of length n containing the upper bounds for the acceptance regions of the test corresponding to each order statistic. These form the upper boundary of the testing band for the QQ-plot.

• expected_value - Numeric vector of length n containing the exact or approximate expectation (or median) of each order statistic, depending on how prob_pts_method is set. These are the x-coordinates for both the bounds and the data points if used in a qq-plot. Note that if adding a band to an already existing plot, it is essential that the same x-coordinates be used for the bounds as were used to plot the data. Thus, if some other x-coordinates have been used to plot the data those same x-coordinates should always be used instead of this vector to plot the bounds.

• dparams - List of arguments used to apply distribution to obs (if observations are provided). If the user provides parameters, then these parameters will simply be returned. If parameters are estimated from the data, then the estimated parameters will be returned.

Examples

# Get ell level .05 QQ testing band for normal(0, 1) distribution with 100 observations
band <- get_qq_band(n = 100)

# Get ell level .05 QQ testing band for normal distribution with unknown parameters
obs <- rnorm(100)
band <- get_qq_band(obs = obs)

# Get ell level .05 QQ testing band for t(2) distribution with 100 observations
band <- get_qq_band(
  n = 100, distribution = qt, dparams = list(df = 2)
)