confint.egf: Confidence Intervals

Description

Computes confidence intervals on fixed effect coefficients, random effect covariance parameters, and linear combinations thereof, including population fitted values. Intervals on individual fitted values accounting for random effects are supported, but only by method = "wald".

Usage

# S3 method for egf
confint(object, parm, level = 0.95,
        A = seq_along(par), method = c("wald", "profile", "uniroot"), scale = 7,
        parallel = egf_parallel(), trace = FALSE,
        top = egf_top(object), subset = NULL, select = NULL,
        class = FALSE, link = TRUE, random = FALSE, ...)
# S3 method for confint.egf
plot(x, by = 12L,
     subset = NULL, order = NULL, label = NULL, main = NULL, ...)

Value

A numeric array in 2 or 3 dimensions containing the lower and upper confidence limits in the last dimension.

When confidence intervals on fitted values are desired, the user will set A = NULL and in that case have the option of passing class = TRUE to obtain an augmented result. Thus, alternatively:

A data frame inheriting from class confint.egf, with variables:

top: top level nonlinear model parameter, from egf_top(object).
ts: time series, from levels(model.frame(object)[["ts"]]).
window: fitting window, from levels(model.frame(object)[["window"]]).
value: fitted value.
ci: a numeric matrix with two columns giving the lower and upper confidence limits.
...: further variables from model.frame(object, "combined") specified by argument select.

The confidence level level is preserved as an attribute.

Arguments

object: an egf object.
parm: unused argument, for consistency with the generic function.
level: a number in the interval \((0,1)\) indicating a confidence level.
A: a numeric matrix with 1+p columns, where p = length(coef(object)), in which case each row specifies a linear combination of the elements of c(1, coef(fitted)) for which intervals are computed; or a valid index vector for coef(fitted), in which case intervals are computed for the indexed elements; or NULL, in which case intervals on fitted values are computed.
method: a character string indicating how intervals are computed.
scale: a positive number, for method = "uniroot". tmbroot will search for roots between value-scale*se and value+scale*se, where value and se are the estimate and standard error.
parallel: an egf_parallel object defining options for R level parallelization.
trace: a logical. If TRUE, then basic tracing messages indicating progress are printed. These may be mixed with optimizer output depending on object[["control"]][["trace"]].
top: a subset of egf_top(object) naming top level nonlinear model parameters for which intervals on fitted values should be computed.
subset, select: index vectors for the rows and columns of model.frame(object, "combined") or language objects evaluating to such vectors. subset indicates fitting windows for which intervals should be computed; the default indicates all. select indicates variables that should be appended to the result; the default indicates none. Evaluation of language objects follows the implementation of subset.data.frame.

For the plot method:
an index vector for seq_len(nrow(x)) or a language object evaluating in x to such a vector. subset indicates which intervals are plotted; the default indicates all.
class: a logical. If TRUE and if A = NULL, then the value of the confint call is a confint.egf object, not a matrix.
link: a logical. If FALSE and if A = NULL and class = TRUE, then fitted values and confidence limits are returned on the “natural” (inverse link) scale.
random: a logical, affecting only method = "wald". If TRUE, then intervals are computed for individual fitted values, which count random effects, rather than population fitted values, which do not.
...: additional arguments passed from or to other methods.
x: a confint.egf object.
by: a positive integer indicating the number of intervals displayed in one plot.
order: a permutation of seq_len(nrow(x)) or a language object evaluating in x to such a vector. order indicates the order in which intervals are plotted; the default indicates the original order.
label: a character or expression vector of length nrow(x) or a language object evaluating in x to such a vector. label indicates \(y\)-axis labels for intervals; the default is to use as.character(x[["window"]]).
main: a character or expression vector of length 1 indicating a plot title, to be recycled for all plots.

Details

Three methods for computing confidence intervals are available:

"wald"

confidence limits are calculated as

value + c(-1, 1) * sqrt(q) * se

where q = qchisq(level, df = 1).

"profile", "uniroot"

confidence limits are calculated as approximate solutions of the equation

2 * (f(x) - f(value)) = q

where q = qchisq(level, df = 1) and f is the negative log marginal likelihood function expressed as a function of the parameter x in question. Solutions are approximated by interpolating a likelihood profile ("profile") or by rootfinding ("uniroot").

"wald" assumes asymptotic normality of the maximum likelihood estimator. "profile" and "uniroot" avoid this contraint but are typically expensive, requiring estimation of many restricted models. They are parallelized at the C++ level when there is OpenMP support and object[["control"]][["omp_num_threads"]] is set to an integer greater than 1. When there is no OpenMP support, they can still be parallelized at the R level with appropriate setting of argument parallel.

Examples

Run this code

# \donttest{
example("egf", package = "epigrowthfit")

zz1 <- confint(m1, A = NULL, method =    "wald", class = TRUE,
               random = TRUE)
str(zz1)

op <- par(mar = c(4.5, 4, 2, 1), oma = c(0, 0, 0, 0))
plot(zz1)
par(op)

zz2 <- confint(m1, A = NULL, method = "profile", class = TRUE,
               top = "log(r)", subset = quote(country == "A" & wave == 1))
zz3 <- confint(m1, A = NULL, method = "uniroot", class = TRUE,
               top = "log(r)", subset = quote(country == "A" & wave == 1))
# }