R: Format earth objects

format.earth {earth} | R Documentation

## Format earth objects

### Description

Return a string representing an `earth` expression (`summary.earth` calls this function internally to display the terms of the `earth` model).

### Usage

    ## S3 method for class 'earth'
    format(x = stop("no 'x' argument"),
           style = "h", decomp = "anova", digits = getOption("digits"),
           use.names = TRUE, colon.char = ":", ...)

### Arguments

`x` | An `earth` object. This is the only required argument.
`style` | Formatting style. One of `"h"` (default) more compact `"pmax"` for those who prefer it `"max"` is the same as `"pmax"` but prints `max` rather than `pmax` `"C"` C style expression with zero based indexing `"bf"` basis function format
`decomp` | One of `"anova"` (default) order the terms using the "anova decomposition", i.e., in increasing order of interaction `"none"` order the terms as created during the earth forward pass.
`digits` | Number of significant digits. The default is `getOption(digits)`.
`use.names` | One of `TRUE` (default), use variable names if available. `FALSE` use names of the form `x[,1]`.
`colon.char` | Change colons in the returned string to colon.char. Default is ":" (no change). Specifying `colon.char="*"` can be useful in some contexts to change names of the form `x1:x2` to `x1*x2`.
`...` | Unused, but provided for generic/method consistency.

### Value

A character representation of the `earth` model.

If there are multiple responses, `format.earth` will return multiple strings.

If there are embedded GLM model(s), the strings for the GLM model(s) come after the strings for the standard `earth` model(s).

### Note

The FAQ section in the package vignette gives precise details of the `"anova"` ordering.

Using `format.earth`, perhaps after hand editing the returned string, you can create an alternative to `predict.earth`. For example:

    as.func <- function(object, digits = 8, use.names = FALSE, ...)
      eval(parse(text=paste(
        "function(x){\n",
        "if(is.vector(x))\n",
        "  x <- matrix(x, nrow = 1, ncol = length(x))\n",
        "with(as.data.frame(x),\n",
        format(object, digits = digits, use.names = use.names, style = "pmax", ...),
        ")\n",
        "}\n", sep = "")))

    earth.mod <- earth(Volume ~ ., data = trees)
    my.func <- as.func(earth.mod, use.names = FALSE)
    my.func(c(10,80))             # returns 16.84
    predict(earth.mod, c(10,80))  # returns 16.84

Note that with `pmax` the R expression generated by `format.earth` can handle multiple cases. Thus the expression is consistent with the way `predict` functions usually work in R — we can give `predict` multiple cases (i.e., multiple rows in the input matrix) and it will return a vector of predicted values.

The earth package also provides a function `format.lm`. It has arguments as follows
`format.lm(x, digits=getOption("digits"), use.names=TRUE, colon.char=":")`
(Strictly speaking, `format.lm` doesn't belong in the earth package.) Example:

    lm.mod <- lm(Volume ~ Height*Girth, data = trees)
    cat(format(lm.mod, colon.char="*"))

    # yields:
    #    69.4
    #    -  1.30 * Height
    #    -  5.86 * Girth
    #    + 0.135 * Height*Girth

### See Also

`summary.earth`, `pmax`,

### Examples

    earth.mod <- earth(Volume ~ ., data = trees)
    cat(format(earth.mod))

    # yields:
    #    37.9
    #    -  3.92 * h(16-Girth)
    #    +   7.4 * h(Girth-16)
    #    + 0.484 * h(Height-75)

    cat(format(earth.mod, style="pmax"))

    # yields:
    #    37.9
    #    -  3.92 * pmax(0,     16 -  Girth)
    #    +   7.4 * pmax(0,  Girth -     16)
    #    + 0.484 * pmax(0, Height -     75)

    cat(format(earth.mod, style="C"))

    # yields (note zero based indexing):
    #  37.927
    #    -  3.9187 * max(0,   16 - x[0])
    #    +  7.4011 * max(0, x[0] -   16)
    #    + 0.48411 * max(0, x[1] -   75)

    cat(format(earth.mod, style="bf"))

    # yields:
    #    37.9
    #    -  3.92 * bf1
    #    +   7.4 * bf2
    #    + 0.484 * bf3
    #
    #     bf1  h(16-Girth)
    #     bf2  h(Girth-16)
    #     bf3  h(Height-75)

[Package earth version 5.1.2 Index]