R: rms Special Transformation Functions

rms.trans {rms} | R Documentation

## rms Special Transformation Functions

### Description

This is a series of functions (`asis`, `pol`, `lsp`, `rcs`, `catg`, `scored`, `strat`, `matrx`, and `%ia%`) that set up special attributes (such as knots and nonlinear term indicators) that are carried through to fits (using for example `lrm`,`cph`, `ols`, `psm`). `anova.rms`, `summary.rms`, `Predict`, `survplot`, `fastbw`, `validate`, `specs`, `which.influence`, `nomogram` and `latex.rms` use these attributes to automate certain analyses (e.g., automatic tests of linearity for each predictor are done by `anova.rms`). Many of the functions are called implicitly. Some S functions such as `ns` derive data-dependent transformations that are not always "remembered" when predicted values are later computed, so the predictions may be incorrect. The functions listed here solve that problem when used in the `rms` context.

`asis` is the identity transformation, `pol` is an ordinary (non-orthogonal) polynomial, `rcs` is a linear tail-restricted cubic spline function (natural spline, for which the `rcspline.eval` function generates the design matrix, the presence of system option `rcspc` causes `rcspline.eval` to be invoked with `pc=TRUE`, and the presence of system option `fractied` causes this value to be passed to `rcspline.eval` as the `fractied` argument), `catg` is for a categorical variable, `scored` is for an ordered categorical variable, `strat` is for a stratification factor in a Cox model, `matrx` is for a matrix predictor, and `%ia%` represents restricted interactions in which products involving nonlinear effects on both variables are not included in the model. `asis, catg, scored, matrx` are seldom invoked explicitly by the user (only to specify `label` or `name`, usually).

In the list below, functions `asis` through `strat` can have arguments `x, parms, label, name` except that `parms` does not apply to `asis, matrx, strat`.

### Usage

    asis(...)
    matrx(...)
    pol(...)
    lsp(...)
    rcs(...)
    catg(...)
    scored(...)
    strat(...)
    x1 %ia% x2

### Arguments

`...` | The arguments ... above contain the following. `x` a predictor variable (or a function of one). If you specify e.g. `pol(pmin(age,10),3)`, a cubic polynomial will be fitted in `pmin(age,10)` (`pmin` is the S vector element–by–element function). The predictor will be labeled `age` in the output, and plots with have `age` in its original units on the axes. If you use a function such as `pmin`, the predictor is taken as the first argument, and other arguments must be defined in the frame in effect when predicted values, etc., are computed. `parms` parameters of transformation (e.g. number or location of knots). For `pol` the argument is the order of the polynomial, e.g. `2` for quadratic (the usual default). For `lsp` it is a vector of knot locations (`lsp` will not estimate knot locations). For `rcs` it is the number of knots (if scalar), or vector of knot locations (if `>2` elements). The default number is the `nknots` system option if `parms` is not given. If the number of knots is given, locations are computed for that number of knots. If system option `rcspc` is `TRUE` the `parms` vector has an attribute defining the principal components transformation parameters. For `catg`, `parms` is the category labels (not needed if variable is an S category or factor variable). If omitted, `catg` will use `unique(x)`, or `levels(x)` if `x` is a `category` or a `factor`. For `scored`, `parms` is a vector of unique values of variable (uses `unique(x)` by default). This is not needed if `x` is an S `ordered` variable. For `strat`, `parms` is the category labels (not needed if variable is an S category variable). If omitted, will use `unique(x)`, or `levels(x)` if `x` is `category` or `factor`. `parms` is not used for `matrix`. `label` label of predictor for plotting (default = `"label"` attribute or variable name) `name` Name to use for predictor in model. Default is name of argument to function.
`x1,x2` | two continuous variables for which to form a non-doubly-nonlinear interaction

### Author(s)

Frank Harrell
Department of Biostatistics, Vanderbilt University
f.harrell@vanderbilt.edu

### See Also

`rcspline.eval`, `rcspline.restate`, `rms`, `cph`, `lrm`, `ols`, `datadist`

### Examples

    ## Not run:
    options(knots=4, poly.degree=2)
    # To get the old behavior of rcspline.eval knot placement (which didnt' handle
    # clumping at the lowest or highest value of the predictor very well):
    # options(fractied = 1.0)   # see rcspline.eval for details
    country <- factor(country.codes)
    blood.pressure <- cbind(sbp=systolic.bp, dbp=diastolic.bp)
    fit <- lrm(Y ~ sqrt(x1)*rcs(x2) + rcs(x3,c(5,10,15)) +
           lsp(x4,c(10,20)) + country + blood.pressure + poly(age,2))
    # sqrt(x1) is an implicit asis variable, but limits of x1, not sqrt(x1)
    #       are used for later plotting and effect estimation
    # x2 fitted with restricted cubic spline with 4 default knots
    # x3 fitted with r.c.s. with 3 specified knots
    # x4 fitted with linear spline with 2 specified knots
    # country is an implied catg variable
    # blood.pressure is an implied matrx variable
    # since poly is not an rms function (pol is), it creates a
    #       matrx type variable with no automatic linearity testing
    #       or plotting
    f1 <- lrm(y ~ rcs(x1) + rcs(x2) + rcs(x1) %ia% rcs(x2))
    # %ia% restricts interactions. Here it removes terms nonlinear in
    # both x1 and x2
    f2 <- lrm(y ~ rcs(x1) + rcs(x2) + x1 %ia% rcs(x2))
    # interaction linear in x1
    f3 <- lrm(y ~ rcs(x1) + rcs(x2) + x1 %ia% x2)
    # simple product interaction (doubly linear)
    # Use x1 %ia% x2 instead of x1:x2 because x1 %ia% x2 triggers
    # anova to pool x1*x2 term into x1 terms to test total effect
    # of x1

    ## End(Not run)

[Package rms version 5.1-1 Index]