envelope: Generate Simulated Envelope

Description

Generates QQ-plot with simulated envelope residuals.

Usage

envelope(
  model,
  residual_fn = envelope_residual(model),
  alpha = 0.05,
  nsim = 100,
  responses = NULL,
  no_warnings = FALSE,
  no_messages = FALSE,
  converged_only = FALSE,
  show_progress = TRUE,
  plot.it = TRUE,
  refit_fn = NULL,
  ...
)

Value

An object of class AD_envelope, which contains the following components:

observed: A vector of observed quantiles from the model residuals.
outside: A logical vector indicating whether each observation falls outside the constructed envelope bounds.
lower: The lower bounds of the envelope for each observation.
med: The median bounds of the envelope for each observation.
upper: The upper bounds of the envelope for each observation.

Arguments

model: A model to generate responses and compute the observed residuals.
residual_fn: A function to calculate model residuals. The default is envelope_residual() for an absolute residual.
alpha: The significance level for constructing the envelope bounds. Defaults to 0.05.
nsim: The number of simulations to perform for envelope construction. Defaults to 100.
responses: An optional list of values to be used as response variables to refit the model.
no_warnings: If TRUE, ignore simulations that threw warnings.
no_messages: If TRUE, ignore simulations that shown messages.
converged_only: Use p-values from converged models only.
show_progress: Display a progress bar for the simulation iteration.
plot.it: Logical. Generate envelope plot.
refit_fn: Function to refit the model with new responses. If NULL, defaults to get_refit(model, y, ...).
...: Extra arguments to get_refit()

Details

Simulates new responses using stats::simulate() and refits the model for each vector of new responses using get_refit(). The function then computes residuals for each simulation, sorts them, and constructs envelope bands and a median line based on the quantiles of these residuals.

refit_fn is a function that supposedly compute the refit of model. Use this method if the default get_refit() doesn't work. If refit_fn is NULL, it's value is defined as function(y, ...) get_refit(model, y, ...).

Examples

Run this code

fit <- lm(mpg ~ cyl, data = mtcars)

envelope(fit)

# Use pearson residuals, and plot it agains the expected normal quantiles.
env_measures <- envelope(fit,
  residual_fn = function(x) residuals.lm(x, type = "pearson"), plot.it = FALSE
)
plot(env_measures, distribution = stats::qnorm, colors = c("gray", "black"))

## Using custom refit_fn
if (require("survival")) {
  fit <- survreg(Surv(futime, fustat) ~ ecog.ps + rx, ovarian,
    dist = "exponential"
  )
  fitted_rate <- 1 / fitted(fit)
  new_responses <- replicate(100, rexp(length(fitted_rate), fitted_rate), simplify = FALSE)
  refit_surv_ovarian <- function(.y) {
    survreg(Surv(.y, fustat) ~ ecog.ps + rx, ovarian, dist = "exponential")
  }
  env_measures <- envelope(fit,
    responses = new_responses,
    residual_fn = function(x) abs(residuals(x, type = "deviance")),
    refit_fn = refit_surv_ovarian, plot.it = FALSE
  )
  # Absolute residuals are best shown with halfnormal quantiles
  plot(env_measures, distribution = function(p) qnorm((1 + p) / 2))
}