R: Variance models for estimating prediction intervals

varmod {earth} | R Documentation

## Variance models for estimating prediction intervals

### Description

A variance model estimates the variance of predicted values. It can be used to estimate prediction intervals. See the `interval` argument of `predict.earth`.

A variance model is built by `earth` if `earth`'s `varmod.method` argument is specified. Results are stored in the `$varmod` field of the `earth` model. See the vignette “Variance models in earth” for details.

You probably won't need to directly call `print.varmod` or `summary.varmod`. They get called internally by `summary.earth`.

### Usage

    ## S3 method for class 'varmod'
    summary(
        object  = stop("no 'object' argument"),
        level   = .95,
        style   = "standard",
        digits  = 2,
        newdata = NULL,
        ...)

### Arguments

`object` | A `varmod` object. This is the only required argument.
`level` | Same as `predict.earth`'s `level` argument.
`style` | Determines how the coefficients of the `varmod` are printed by `summary.varmod`: `"standard"` (default) `"unit"` for easy comparison normalize the coefficients by dividing by the first coefficient.
`digits` | Number of digits to print. Default is `2`.
`newdata` | Default `NULL`. Else print the interval coverage table for the new data.
`...` | Dots are passed on.

### Note

A `"varmod"` object has the following fields:

- `call` The call used internally in the parent model to build the `varmod` object.

- `parent` The parent `earth` model.

- `method` Copy of the `varmod.method` argument to the parent model.

- `package` NULL, unless `method="gam"`, in which case either `"gam"` or `"mgcv"`.

- `exponent` Copy of the `varmod.exponent` argument to the parent model.

- `lambda` Currently always 1, meaning use absolute residuals.

- `rmethod` Currently always "hc2", meaning correct the residuals with `1/(1-h_ii)`.

- `converged` Did the residual submodel IRLS converge?

- `iters` Number of residual model IRLS iterations (1 to 50).

- `residmod` The residual submodel. So for example, if `varmod.method="lm"`, this will be an `lm` object.

- `min.sd` The predicted residual standard deviation is clamped so it will always be at least this value. This prevents prediction of negative or absurdly small variances. See `earth`'s `varmod.clamp` argument. Clamping takes place in `predict.varmod`, which is called by `predict.earth` when estimating prediction intervals.

- `model.var` An n x 1 matrix. The `model.var` for an observation is the estimated model variance for that observation over all datasets, and is estimated with repeated cross validation. It is the variance of the mean out-of-fold prediction for that observation over `ncross` repetitions.

- `abs.resids` An n x 1 matrix. The absolute residuals used to build the residual model.

- `parent.x` An n x p matrix. Parent earth model `x`.

- `parent.y` An n x 1 matrix. Parent earth model `y`.

- `iter.rsq` Weighted R-Squared of residual submodel `residmod`, after IRLS iteration.

- `iter.stderr` Standard errors of the coefficients of the residual submodel `residmod`, after IRLS iteration.

### See Also

`plot.varmod`, `predict.varmod`

### Examples

    data(ozone1)

    set.seed(1) # optional, for cross validation reproducibility

    # note: should really use ncross=30 below but for a quick demo we don't

    earth.mod <- earth(O3~temp, data=ozone1, nfold=10, ncross=3, varmod.method="lm")

    print(summary(earth.mod)) # note additional info on the variance model

    old.mfrow <- par(mfrow=c(2,2), mar=c(3, 3, 3, 1), mgp=c(1.5, 0.5, 0))

    plotmo(earth.mod, do.par=FALSE, response.col=1, level=.90, main="earth model: O3~temp")

    plot(earth.mod, which=3, level=.90) # residual plot: note 90% pred and darker conf intervals

    par(par=old.mfrow)

[Package earth version 5.1.2 Index]