R: Update an earth model

update.earth {earth} | R Documentation

## Update an earth model

### Description

Update an `earth` model.

### Usage

    ## S3 method for class 'earth'
    update(object = stop("no 'object' argument"),
           formula. = NULL, ponly = FALSE, ..., evaluate = TRUE)

### Arguments

`object` | The earth object
`formula.` | The `formula.` argument is treated like earth's `formula` argument.
`ponly` | Force pruning only, no forward pass. Default is `FALSE`, meaning `update.earth` decides automatically if a forward pass is needed. See note below.
`...` | Arguments passed on to `earth`.
`evaluate` | If `TRUE` (default) evaluate the new call, else return the call. Mostly for compatibility with the generic `update`.

### Details

If only the following arguments are used, a forward pass is unnecessary, and `update.earth` will perform only the pruning pass. This is usually much faster for large models.

         object
         glm
         trace
         nprune
         pmethod
         Eval.model.subsets
         Print.pruning.pass
         Force.xtx.prune
         Use.beta.cache
         Endspan.penalty
         Get.leverages

This automatic determination to do a forward pass can be overridden with the `ponly` argument. If `ponly=TRUE` the forward pass will be skipped and only the pruning pass will be executed. This is useful for doing a pruning pass with new data. (Use earth's `data` argument to specify the new data.) Typically in this scenario you would also specify `penalty=-1`. This is because with sufficient new data, independent of the original training data, the RSS not the GCV should be used for evaluating model subsets (The GCV approximates what the RSS would be on new data — but here we actually have new data, so why bother approximating. This "use new data for pruning" approach is useful in situations where you don't trust the GCV approximation for your data.) By making `penalty=-1`, earth will calculate the RSS, not the GCV. See also the description of `penalty` on the `earth` help page.
Another (somewhat esoteric) use of `ponly=TRUE` is to do subset selection with a different `penalty` from that used to build the original model.
With `trace=1`, `update.earth` will tell you if earth's forward pass was skipped.
If you used `keepxy=TRUE` in your original call to `earth`, then `update.earth` will use the saved values of `x`, `y`, etc., unless you specify otherwise by arguments to `update.earth`. It can be helpful to set `trace=1` to see which `x` and `y` is used by `update.earth`.

### Value

The value is the same as that returned by `earth`. If `object` is the only parameter then no changes are made — the returned value will be the same as the original `object`.

### See Also

`earth`

### Examples

    data(ozone1)

    (earth.mod <- earth(O3 ~ ., data = ozone1, degree = 2))

    update(earth.mod, formula = O3 ~ . - temp) # requires forward pass and pruning

    update(earth.mod, nprune = 8)              # requires only pruning

    update(earth.mod, penalty=1, ponly=TRUE)   # pruning pass only with a new penalty

[Package earth version 5.1.2 Index]