Package 'rpart' reference manual

Title:	Recursive Partitioning and Regression Trees
Description:	Recursive partitioning for classification, regression and survival trees. An implementation of most of the functionality of the 1984 book by Breiman, Friedman, Olshen and Stone.
Authors:	Terry Therneau [aut], Beth Atkinson [aut, cre], Brian Ripley [trl] (producer of the initial R port, maintainer 1999-2017)
Maintainer:	Beth Atkinson <[email protected]>
License:	GPL-2 \| GPL-3
Version:	4.1.23
Built:	2024-03-27 22:42:15 UTC
Source:	CRAN

Title:

Recursive Partitioning and Regression Trees

Description:

Recursive partitioning for classification, regression and survival trees. An implementation of most of the functionality of the 1984 book by Breiman, Friedman, Olshen and Stone.

Authors:

Terry Therneau [aut], Beth Atkinson [aut, cre], Brian Ripley [trl] (producer of the initial R port, maintainer 1999-2017)

Maintainer:

Beth Atkinson <[email protected]>

License:

GPL-2 | GPL-3

Version:

4.1.23

Built:

2024-03-27 22:42:15 UTC

Source:

CRAN

data(car90) plot(car90$Price/1000, car90$Weight, xlab = "Price (thousands)", ylab = "Weight (lbs)") mlowess <- function(x, y, ...) { keep <- !(is.na(x) | is.na(y)) lowess(x[keep], y[keep], ...) } with(car90, lines(mlowess(Price/1000, Weight, f = 0.5)))

fit <- rpart(Kyphosis ~ Age + Number + Start, data = kyphosis) fit2 <- rpart(Kyphosis ~ Age + Number + Start, data = kyphosis, parms = list(prior = c(0.65, 0.35), split = "information")) fit3 <- rpart(Kyphosis ~ Age + Number + Start, data=kyphosis, control = rpart.control(cp = 0.05)) par(mfrow = c(1,2), xpd = TRUE) plot(fit) text(fit, use.n = TRUE) plot(fit2) text(fit2, use.n = TRUE)

Plot an Rpart Object

Description

Plots an rpart object on the current graphics device.

Usage

## S3 method for class 'rpart'
plot(x, uniform = FALSE, branch = 1, compress = FALSE, nspace,
     margin = 0, minbranch = 0.3, branch.col = 1, branch.lty = 1, 
     branch.lwd = 1, ...)

Arguments

`x`	a fitted object of class `"rpart"`, containing a classification, regression, or rate tree.
`uniform`	if `TRUE`, uniform vertical spacing of the nodes is used; this may be less cluttered when fitting a large plot onto a page. The default is to use a non-uniform spacing proportional to the error in the fit.
`branch`	controls the shape of the branches from parent to child node. Any number from 0 to 1 is allowed. A value of 1 gives square shouldered branches, a value of 0 give V shaped branches, with other values being intermediate.
`compress`	if `FALSE`, the leaf nodes will be at the horizontal plot coordinates of `1:nleaves`. If `TRUE`, the routine attempts a more compact arrangement of the tree. The compaction algorithm assumes `uniform=TRUE`; surprisingly, the result is usually an improvement even when that is not the case.
`nspace`	the amount of extra space between a node with children and a leaf, as compared to the minimal space between leaves. Applies to compressed trees only. The default is the value of `branch`.
`margin`	an extra fraction of white space to leave around the borders of the tree. (Long labels sometimes get cut off by the default computation).
`minbranch`	set the minimum length for a branch to `minbranch` times the average branch length. This parameter is ignored if `uniform=TRUE`. Sometimes a split will give very little improvement, or even (in the classification case) no improvement at all. A tree with branch lengths strictly proportional to improvement leaves no room to squeeze in node labels.
`branch.col`	set the color of the branches.
`branch.lty`	set the line type of the branches.
`branch.lwd`	set the line width of the branches.
`...`	arguments to be passed to or from other methods.

Details

This function is a method for the generic function plot, for objects of class rpart. The y-coordinate of the top node of the tree will always be 1.

Value

The coordinates of the nodes are returned as a list, with components x and y.

Side Effects

An unlabeled plot is produced on the current graphics device: one being opened if needed.

In order to build up a plot in the usual S style, e.g., a separate text command for adding labels, some extra information about the plot needs be retained. This is kept in an environment in the package.

Examples

fit <- rpart(Price ~ Mileage + Type + Country, cu.summary)
par(xpd = TRUE)
plot(fit, compress = TRUE)
text(fit, use.n = TRUE)

post(tree, ...) ## S3 method for class 'rpart' post(tree, title., filename = paste(deparse(substitute(tree)), ".ps", sep = ""), digits = getOption("digits") - 2, pretty = TRUE, use.n = TRUE, horizontal = TRUE, ...)

## Not run: z.auto <- rpart(Mileage ~ Weight, car.test.frame) post(z.auto, file = "") # display tree on active device # now construct postscript version on file "pretty.ps" # with no title post(z.auto, file = "pretty.ps", title = " ") z.hp <- rpart(Mileage ~ Weight + HP, car.test.frame) post(z.hp) ## End(Not run)

z.auto <- rpart(Mileage ~ Weight, car.test.frame) predict(z.auto) fit <- rpart(Kyphosis ~ Age + Number + Start, data = kyphosis) predict(fit, type = "prob") # class probabilities (default) predict(fit, type = "vector") # level numbers predict(fit, type = "class") # factor predict(fit, type = "matrix") # level number, class frequencies, probabilities sub <- c(sample(1:50, 25), sample(51:100, 25), sample(101:150, 25)) fit <- rpart(Species ~ ., data = iris, subset = sub) fit table(predict(fit, iris[-sub,], type = "class"), iris[-sub, "Species"])

z.auto <- rpart(Mileage ~ Weight, car.test.frame) z.auto ## Not run: node), split, n, deviance, yval * denotes terminal node 1) root 60 1354.58300 24.58333 2) Weight>=2567.5 45 361.20000 22.46667 4) Weight>=3087.5 22 61.31818 20.40909 * 5) Weight<3087.5 23 117.65220 24.43478 10) Weight>=2747.5 15 60.40000 23.80000 * 11) Weight<2747.5 8 39.87500 25.62500 * 3) Weight<2567.5 15 186.93330 30.93333 * ## End(Not run)

z.auto <- rpart(Mileage ~ Weight, car.test.frame) printcp(z.auto) ## Not run: Regression tree: rpart(formula = Mileage ~ Weight, data = car.test.frame) Variables actually used in tree construction: [1] Weight Root node error: 1354.6/60 = 22.576 CP nsplit rel error xerror xstd 1 0.595349 0 1.00000 1.03436 0.178526 2 0.134528 1 0.40465 0.60508 0.105217 3 0.012828 2 0.27012 0.45153 0.083330 4 0.010000 3 0.25729 0.44826 0.076998 ## End(Not run)

fit <- rpart(Kyphosis ~ Age + Number + Start, data = kyphosis) fit2 <- rpart(Kyphosis ~ Age + Number + Start, data = kyphosis, parms = list(prior = c(.65,.35), split = "information")) fit3 <- rpart(Kyphosis ~ Age + Number + Start, data = kyphosis, control = rpart.control(cp = 0.05)) par(mfrow = c(1,2), xpd = NA) # otherwise on some devices the text is clipped plot(fit) text(fit, use.n = TRUE) plot(fit2) text(fit2, use.n = TRUE)

rpart.control(minsplit = 20, minbucket = round(minsplit/3), cp = 0.01, maxcompete = 4, maxsurrogate = 5, usesurrogate = 2, xval = 10, surrogatestyle = 0, maxdepth = 30, ...)

Recursive Partitioning and Regression Trees Object

Description

These are objects representing fitted rpart trees.

Value

`frame`	data frame with one row for each node in the tree. The `row.names` of `frame` contain the (unique) node numbers that follow a binary ordering indexed by node depth. Columns of `frame` include `var`, a factor giving the names of the variables used in the split at each node (leaf nodes are denoted by the level `"<leaf>"`), `n`, the number of observations reaching the node, `wt`, the sum of case weights for observations reaching the node, `dev`, the deviance of the node, `yval`, the fitted value of the response at the node, and `splits`, a two column matrix of left and right split labels for each node. Also included in the frame are `complexity`, the complexity parameter at which this split will collapse, `ncompete`, the number of competitor splits recorded, and `nsurrogate`, the number of surrogate splits recorded. Extra response information which may be present is in `yval2`, which contains the number of events at the node (poisson tree), or a matrix containing the fitted class, the class counts for each node, the class probabilities and the ‘node probability’ (classification trees).
`where`	an integer vector of the same length as the number of observations in the root node, containing the row number of `frame` corresponding to the leaf node that each observation falls into.
`call`	an image of the call that produced the object, but with the arguments all named and with the actual formula included as the formula argument. To re-evaluate the call, say `update(tree)`.
`terms`	an object of class `c("terms", "formula")` (see `terms.object`) summarizing the formula. Used by various methods, but typically not of direct relevance to users.
`splits`	a numeric matrix describing the splits: only present if there are any. The row label is the name of the split variable, and columns are `count`, the number of observations (which are not missing and are of positive weight) sent left or right by the split (for competitor splits this is the number that would have been sent left or right had this split been used, for surrogate splits it is the number missing the primary split variable which were decided using this surrogate), `ncat`, the number of categories or levels for the variable (`+/-1` for a continuous variable), `improve`, which is the improvement in deviance given by this split, or, for surrogates, the concordance of the surrogate with the primary, and `index`, the numeric split point. The last column `adj` gives the adjusted concordance for surrogate splits. For a factor, the `index` column contains the row number of the csplit matrix. For a continuous variable, the sign of `ncat` determines whether the subset `x < cutpoint` or `x > cutpoint` is sent to the left.
`csplit`	an integer matrix. (Only present only if at least one of the split variables is a factor or ordered factor.) There is a row for each such split, and the number of columns is the largest number of levels in the factors. Which row is given by the `index` column of the `splits` matrix. The columns record `1` if that level of the factor goes to the left, `3` if it goes to the right, and `2` if that level is not present at this node of the tree (or not defined for the factor).
`method`	character string: the method used to grow the tree. One of `"class"`, `"exp"`, `"poisson"`, `"anova"` or `"user"` (if splitting functions were supplied).
`cptable`	a matrix of information on the optimal prunings based on a complexity parameter.
`variable.importance`	a named numeric vector giving the importance of each variable. (Only present if there are any splits.) When printed by `summary.rpart` these are rescaled to add to 100.
`numresp`	integer number of responses; the number of levels for a factor response.
`parms`, `control`	a record of the arguments supplied, which defaults filled in.
`functions`	the `summary`, `print` and `text` functions for method used.
`ordered`	a named logical vector recording for each variable if it was an ordered factor.
`na.action`	(where relevant) information returned by `model.frame` on the special handling of `NA`s derived from the `na.action` argument.

There may be attributes "xlevels" and "levels" recording the levels of any factor splitting variables and of a factor response respectively.

Optional components include the model frame (model), the matrix of predictors (x) and the response variable (y) used to construct the rpart object.

Structure

The following components must be included in a legitimate rpart object.

`object`	fitted model object of class `"rpart"`. This is assumed to be the result of some function that produces an object with the same named components as that returned by the `rpart` function.
`digits`	the number of digits to be used for numeric values. All of the `rpart` functions that call labels explicitly set this value, with `options("digits")` as the default.
`minlength`	the minimum length for abbreviation of character or factor variables. If `0` no abbreviation is done; if `1` single English letters are used, first lower case than upper case (with a maximum of 52 levels). If the value is greater than , the `abbreviate` function is used, passed the `minlength` argument.
`pretty`	an argument included for compatibility with the original Splus tree package: `pretty = 0` implies `minlength = 0L`, `pretty = NULL` implies `minlength = 1L`, and `pretty = TRUE` implies `minlength = 4L`.
`collapse`	logical. The returned set of labels is always of the same length as the number of nodes in the tree. If `collapse = TRUE` (default), the returned value is a vector of labels for the branch leading into each node, with `"root"` as the label for the top node. If `FALSE`, the returned value is a two column matrix of labels for the left and right branches leading out from each node, with `"leaf"` as the branch labels for terminal nodes.
`...`	optional arguments to `abbreviate`.

`tree`	fitted model object of class `"rpart"`. This is assumed to be the result of some function that produces an object with the same named components as that returned by the `rpart` function.
`xlab`	x-axis label for the plot.
`ylab`	y-axis label for the plot.
`...`	additional graphical parameters may be supplied as arguments to this function.

`x`	fitted value at terminal nodes (`yval`).
`y`	deviance of node divided by number of observations at node.
`label`	node number.

`tree`	fitted model object of class `"rpart"`. This is assumed to be the result of some function that produces an object with the same named components as that returned by the `rpart` function.
`nodes`	an integer vector containing indices (node numbers) of all nodes for which paths are desired. If missing, user selects nodes as described below.
`pretty`	an integer denoting the extent to which factor levels in split labels will be abbreviated. A value of (0) signifies no abbreviation. A `NULL`, the default, signifies using elements of letters to represent the different factor levels.
`print.it`	Logical. Denotes whether paths will be printed out as nodes are interactively selected. Irrelevant if `nodes` argument is supplied.

`x`	an object of class `"rpart"`
`minline`	whether a horizontal line is drawn 1SE above the minimum of the curve.
`lty`	line type for this line
`col`	colour for this line
`upper`	what is plotted on the top axis: the size of the tree (the number of leaves), the number of splits or nothing.
`...`	additional plotting parameters

`tree`	fitted model object of class `"rpart"`. This is assumed to be the result of some function that produces an object with the same named components as that returned by the `rpart` function.
`title.`	a title which appears at the top of the plot. By default, the name of the `rpart` endpoint is printed out.
`filename`	ASCII file to contain the output. By default, the name of the file is the name of the object given by `rpart` (with the suffix `.ps` added). If `filename = ""`, the plot appears on the current graphical device.
`digits`	number of significant digits to include in numerical data.
`pretty`	an integer denoting the extent to which factor levels will be abbreviated in the character strings defining the splits; (0) signifies no abbreviation of levels. A `NULL` signifies using elements of letters to represent the different factor levels. The default (`TRUE`) indicates the maximum possible abbreviation.
`use.n`	Logical. If `TRUE` (default), adds to the label `⁠#events level1/ #events level2/⁠` etc. for method `class`, `⁠n⁠` for method `anova`, and `⁠#events/n⁠` for methods `poisson` and `exp`).
`horizontal`	Logical. If `TRUE` (default), plot is horizontal. If `FALSE`, plot appears as landscape.
`...`	other arguments to the `postscript` function.

`object`	fitted model object of class `"rpart"`. This is assumed to be the result of some function that produces an object with the same named components as that returned by the `rpart` function.
`newdata`	data frame containing the values at which predictions are required. The predictors referred to in the right side of `formula(object)` must be present by name in `newdata`. If missing, the fitted values are returned.
`type`	character string denoting the type of predicted value returned. If the `rpart` object is a classification tree, then the default is to return `prob` predictions, a matrix whose columns are the probability of the first, second, etc. class. (This agrees with the default behavior of `tree`). Otherwise, a vector result is returned.
`na.action`	a function to determine what should be done with missing values in `newdata`. The default is to pass them down the tree using surrogates in the way selected when the model was built. Other possibilities are `na.omit` and `na.fail`.
`...`	further arguments passed to or from other methods.

`x`	fitted model object of class `"rpart"`. This is assumed to be the result of some function that produces an object with the same named components as that returned by the `rpart` function.
`minlength`	Controls the abbreviation of labels: see `labels.rpart`.
`spaces`	the number of spaces to indent nodes of increasing depth.
`digits`	the number of digits of numbers to print.
`nsmall`	the number of digits to the right of the decimal. See `format`.
`cp`	prune all nodes with a complexity less than `cp` from the printout. Ignored if unspecified.
`...`	arguments to be passed to or from other methods.

`formula`	a formula, with a response but no interaction terms. If this is a data frame, it is taken as the model frame (see `model.frame).`
`data`	an optional data frame in which to interpret the variables named in the formula.
`weights`	optional case weights.
`subset`	optional expression saying that only a subset of the rows of the data should be used in the fit.
`na.action`	the default action deletes all observations for which `y` is missing, but keeps those in which one or more predictors are missing.
`method`	one of `"anova"`, `"poisson"`, `"class"` or `"exp"`. If `method` is missing then the routine tries to make an intelligent guess. If `y` is a survival object, then `method = "exp"` is assumed, if `y` has 2 columns then `method = "poisson"` is assumed, if `y` is a factor then `method = "class"` is assumed, otherwise `method = "anova"` is assumed. It is wisest to specify the method directly, especially as more criteria may added to the function in future. Alternatively, `method` can be a list of functions named `init`, `split` and `eval`. Examples are given in the file ‘tests/usersplits.R’ in the sources, and in the vignettes ‘User Written Split Functions’.
`model`	if logical: keep a copy of the model frame in the result? If the input value for `model` is a model frame (likely from an earlier call to the `rpart` function), then this frame is used rather than constructing new data.
`x`	keep a copy of the `x` matrix in the result.
`y`	keep a copy of the dependent variable in the result. If missing and `model` is supplied this defaults to `FALSE`.
`parms`	optional parameters for the splitting function. Anova splitting has no parameters. Poisson splitting has a single parameter, the coefficient of variation of the prior distribution on the rates. The default value is 1. Exponential splitting has the same parameter as Poisson. For classification splitting, the list can contain any of: the vector of prior probabilities (component `prior`), the loss matrix (component `loss`) or the splitting index (component `split`). The priors must be positive and sum to 1. The loss matrix must have zeros on the diagonal and positive off-diagonal elements. The splitting index can be `gini` or `information`. The default priors are proportional to the data counts, the losses default to 1, and the split defaults to `gini`.
`control`	a list of options that control details of the `rpart` algorithm. See `rpart.control`.
`cost`	a vector of non-negative costs, one for each variable in the model. Defaults to one for all variables. These are scalings to be applied when considering splits, so the improvement on splitting on a variable is divided by its cost in deciding which split to choose.
`...`	arguments to `rpart.control` may also be specified in the call to `rpart`. They are checked against the list of valid arguments.

`minsplit`	the minimum number of observations that must exist in a node in order for a split to be attempted.
`minbucket`	the minimum number of observations in any terminal `<leaf>` node. If only one of `minbucket` or `minsplit` is specified, the code either sets `minsplit` to `minbucket*3` or `minbucket` to `minsplit/3`, as appropriate.
`cp`	complexity parameter. Any split that does not decrease the overall lack of fit by a factor of `cp` is not attempted. For instance, with `anova` splitting, this means that the overall R-squared must increase by `cp` at each step. The main role of this parameter is to save computing time by pruning off splits that are obviously not worthwhile. Essentially,the user informs the program that any split which does not improve the fit by `cp` will likely be pruned off by cross-validation, and that hence the program need not pursue it.
`maxcompete`	the number of competitor splits retained in the output. It is useful to know not just which split was chosen, but which variable came in second, third, etc.
`maxsurrogate`	the number of surrogate splits retained in the output. If this is set to zero the compute time will be reduced, since approximately half of the computational time (other than setup) is used in the search for surrogate splits.
`usesurrogate`	how to use surrogates in the splitting process. `0` means display only; an observation with a missing value for the primary split rule is not sent further down the tree. `1` means use surrogates, in order, to split subjects missing the primary variable; if all surrogates are missing the observation is not split. For value `2` ,if all surrogates are missing, then send the observation in the majority direction. A value of `0` corresponds to the action of `tree`, and `2` to the recommendations of Breiman et.al (1984).
`xval`	number of cross-validations.
`surrogatestyle`	controls the selection of a best surrogate. If set to `0` (default) the program uses the total number of correct classification for a potential surrogate variable, if set to `1` it uses the percent correct, calculated over the non-missing values of the surrogate. The first option more severely penalizes covariates with a large number of missing values.
`maxdepth`	Set the maximum depth of any node of the final tree, with the root node counted as depth 0. Values greater than 30 `rpart` will give nonsense results on 32-bit machines.
`...`	mop up other arguments.

`y`	the response, which will be of class `Surv`
`offset`	optional offset
`parms`	parameters controlling the fit. This is a list with components `shrink` and `method`. The first is the prior for the coefficient of variation of the predictions. The second is either `"deviance"` or `"sqrt"` and is the measure used for cross-validation. If values are missing the defaults are used, which are `"deviance"` for the method, and a shrinkage of 1.0 for the deviance method and 0 for the square root.
`wt`	case weights, if present

`x`	fitted model object of class `"rpart"`. This is assumed to be the result of some function that produces an object with the same named components as that returned by the `rpart` function.
`toss`	an integer vector containing indices (node numbers) of all subtrees to be snipped off. If missing, user selects branches to snip off as described below.

`x`	fitted model object of class `"rpart"`. This is assumed to be the result of some function that produces an object with the same named components as that returned by the `rpart` function.
`splits`	logical flag. If `TRUE` (default), then the splits in the tree are labeled with the criterion for the split.
`label`	For compatibility with `rpart2`, ignored in this version (with a warning).
`FUN`	the name of a labeling function, e.g. `text`.
`all`	Logical. If `TRUE`, all nodes are labeled, otherwise just terminal nodes.
`minlength`	the length to use for factor labels. A value of 1 causes them to be printed as ‘a’, ‘b’, ..... Larger values use abbreviations of the label names. See the `labels.rpart` function for details.
`pretty`	an alternative to the `minlength` argument, see `labels.rpart`.
`digits`	number of significant digits to include in numerical labels.
`use.n`	Logical. If `TRUE`, adds to label `⁠(#events level1/ #events level2/⁠` etc. for `class`, `n` for `anova`, and `⁠#events/n⁠` for `poisson` and `exp`).
`fancy`	Logical. If `TRUE`, nodes are represented by ellipses (interior nodes) and rectangles (leaves) and labeled by `yval`. The edges connecting the nodes are labeled by left and right splits.
`fwidth`	Relates to option `fancy` and the width of the ellipses and rectangles. If `fwidth < 1` then it is a scaling factor (default = 0.8). If `fwidth > 1` then it represents the number of character widths (for current graphical device) to use.
`fheight`	Relates to option `fancy` and the height of the ellipses and rectangles. If `fheight <1` then it is a scaling factor (default = 0.8). If `fheight > 1` then it represents the number of character heights (for current graphical device) to use.
`bg`	The color used to paint the background to annotations if `fancy = TRUE`.
`...`	Graphical parameters may also be supplied as arguments to this function (see `par`). As labels often extend outside the plot region it can be helpful to specify `xpd = TRUE`.

`fit`	a object of class `"rpart"`.
`xval`	number of cross-validation groups. This may also be an explicit list of integers that define the cross-validation groups.
`cp`	the desired list of complexity values. By default it is taken from the `cptable` component of the fit.
`return.all`	if FALSE return only the first element of the prediction

Package 'rpart'

Help Index

Automobile Data from 'Consumer Reports' 1990

Description

Usage

Format

Source

See Also

Examples

Automobile Data from 'Consumer Reports' 1990

Description

Usage

Format

Source

See Also

Examples

Automobile Data from 'Consumer Reports' 1990

Description

Usage

Format

Source

See Also

Examples

Data on Children who have had Corrective Spinal Surgery

Description

Usage

Format

Source

Examples

Create Split Labels For an Rpart Object

Description

Usage

Arguments

Value

See Also

Mean-Variance Plot for an Rpart Object

Description

Usage

Arguments

Value

Side Effects

See Also

Examples

Handles Missing Values in an Rpart Object

Description

Usage

Arguments

Details

Follow Paths to Selected Nodes of an Rpart Object

Description

Usage

Arguments

Details

Value

Graphical Interaction

References

See Also

Examples

Plot an Rpart Object

Description

Usage

Arguments

Details

Value

Side Effects

See Also

Examples

Plot a Complexity Parameter Table for an Rpart Fit

Description

Usage

Arguments

Details

Value

Side Effects

See Also

PostScript Presentation Plot of an Rpart Object

Description

Usage

Arguments

Details