marginal.plot.boostmtree: Marginal fitted-response summaries for boostmtree models

In boostmtree: Boosted Multivariate Trees for Longitudinal Data

Marginal fitted-response summaries for boostmtree models

Description

Create marginal fitted-response summaries for one or more covariates from a fitted boostmtree object. The function can draw the resulting curves, write them to a PDF file, or return the raw and smoothed curve data.

Usage

marginal.plot(object, ...)

## S3 method for class 'boostmtree'
marginal.plot(
  object,
  M = NULL,
  x.var.names = NULL,
  time.points = NULL,
  subset = NULL,
  prob.class = FALSE,
  response.labels = NULL,
  output = c("plot", "data", "pdf"),
  file = NULL,
  verbose = TRUE,
  ...
)

## S3 method for class 'marginal.plot.boostmtree'
plot(
  x,
  output = c("plot", "pdf"),
  file = NULL,
  verbose = TRUE,
  ...
)

Arguments

object	A fitted object of class (boostmtree, grow).
M	Number of boosting iterations to use. By default the function uses the fitted stopping value when available and otherwise uses the full fitted path.
x.var.names	Names of the covariates for which marginal summaries are requested. By default all fitted covariates are used.
time.points	Time points at which the fitted curves should be displayed. By default the deciles of the observed time values are used. Requested values are matched to the nearest observed training times.
subset	Optional vector selecting the fitted subjects to be used in the summary.
prob.class	Logical flag used only for ordinal fits. When TRUE, the function works with class probabilities rather than cumulative probabilities.
response.labels	Optional character vector selecting which response components to include in the summary. For continuous fits the only available label is "response". For binary, nominal, and ordinal fits the available labels are taken from the fitted object.
output	Either "plot" to draw the plots on the active graphics device, "data" to return the computed summary object without drawing it, or "pdf" to write the plots to a PDF file.
file	Optional file name used when output = "pdf" or plot(..., output = "pdf") is requested.
verbose	Should the file location be reported when PDF output is requested?
x	An object returned by marginal.plot.
...	Further arguments passed to predict.boostmtree.

Details

Marginal plots display the relationship between a covariate and the fitted response without averaging over modified covariate values. The fitted mean response is first obtained on a common time grid from predict.boostmtree, and then the association between the chosen covariate and that fitted response is summarized separately at each requested time point.

Compared with partial dependence, this is a less adjusted summary because the other covariates are not perturbed. It is often quicker to compute and is useful for seeing the broad shape of the fitted longitudinal response surface. When multiple response components are available, response.labels can be used to restrict the display to a chosen subset.

Value

If output = "data", an object of class "marginal.plot.boostmtree" with components:

data

Raw x-versus-fitted-response pairs for each requested time point.

smooth

Smoothed marginal curves used for plotting.

time.points

The observed time points used in the summary.

x.var.names

Covariate names included in the summary.

response.labels

Selected labels for the response component(s) included in the summary.

If output = "plot" or "pdf", the same object is returned invisibly after plotting.

References

Friedman, J. H. (2001). Greedy function approximation: a gradient boosting machine. Annals of Statistics, 29, 1189–1232.

Examples

## -------------------------------------------------------------
## Continuous longitudinal marginal summaries.
## -------------------------------------------------------------
set.seed(19)
sim.obj <- simLong(n = 40, n.time = 4, model = 2, family = "continuous")
dta <- sim.obj$data.list

fit <- boostmtree(
  x = dta$features,
  tm = dta$time,
  id = dta$id,
  y = dta$y,
  family = "continuous",
  M = 50,
  verbose = FALSE
)

## Draw directly on the active device.
marginal.plot(fit, x.var.names = c("x1", "x2"))

## Return the smoothed marginal curves.
mp <- marginal.plot(
  fit,
  x.var.names = "x2",
  output = "data"
)

str(mp$smooth)

## -------------------------------------------------------------
## Ordinal illustration using class probabilities.
## -------------------------------------------------------------

fit.ord <- boostmtree(
  x = dta$features,
  tm = dta$time,
  id = dta$id,
  y = cut(dta$y, breaks = 3, labels = c("low", "mid", "high")),
  family = "ordinal",
  M = 25,
  verbose = FALSE
)

marginal.plot(
  fit.ord,
  x.var.names = "x1",
  prob.class = TRUE,
  response.labels = c("low", "high")
)

boostmtree documentation built on April 10, 2026, 9:10 a.m.