hvtiBoostmtree — Boosted Multivariate Trees for Longitudinal Data

Fork notice: hvtiBoostmtree is an internal-only fork of kogalur/boostmtree, branched at v1.5.1 and diverging independently since. It was renamed from boostmtree to hvtiBoostmtree so it no longer collides with the upstream boostmtree package on CRAN. The fitting function is still boostmtree() — only the package name changed.

hvtiBoostmtree implements Friedman's (2001) gradient descent boosting algorithm for modeling longitudinal responses using multivariate tree base learners. Covariate-time interactions are captured via penalized B-splines (P-splines) with an adaptively estimated smoothing parameter. The package handles continuous, binary, nominal, and ordinal responses, and works equally well for cross-sectional data.

Features

• Gradient boosting with multivariate tree base learners (powered by randomForestSRC)
• P-spline modeling of covariate × time interactions with adaptive smoothing
• Stochastic gradient descent with bootstrap sampling and OOB error estimation
• In-sample cross-validation for optimal stopping iteration selection
• Variable importance (VIMP) via permutation, including joint VIMP
• Partial and marginal dependence plots
• Supports Continuous, Binary, Nominal, and Ordinal longitudinal responses
• Parallel processing via the parallel package
• Missing covariate imputation (on-the-fly, via randomForestSRC)

Installation

This fork is available from GitHub only:

# install.packages("remotes")
remotes::install_github("ehrlinger/hvtiBoostmtree")

Optional enhanced visualization

For ggplot2-based visualization workflows, install the suggested packages:

remotes::install_github("ehrlinger/ggRandomForests")
remotes::install_github("ehrlinger/hvtiPlotR")
remotes::install_github("ehrlinger/hvtiRutilities")

Quick Start

Simulated continuous longitudinal data

library(hvtiBoostmtree)

## Simulate training and test data (model 1: linear time × covariate interaction)
set.seed(42)
dta <- simLong(n = 100, ntest = 100, model = 1, family = "Continuous", q = 5)

## Fit the model
fit <- boostmtree(
  x  = dta$dtaL$features[dta$trn, ],
  tm = dta$dtaL$time[dta$trn],
  id = dta$dtaL$id[dta$trn],
  y  = dta$dtaL$y[dta$trn],
  family = "Continuous",
  M  = 200,
  cv.flag = TRUE   # enables OOB-based optimal stopping
)

print(fit)
plot(fit)

Predict on held-out data

pred <- predict(
  fit,
  x  = dta$dtaL$features[-dta$trn, ],
  tm = dta$dtaL$time[-dta$trn],
  id = dta$dtaL$id[-dta$trn],
  y  = dta$dtaL$y[-dta$trn]
)

print(pred)
plot(pred)

Variable importance

## Individual VIMP for all covariates
vimp_obj <- vimp.boostmtree(fit)
vimpPlot(vimp_obj)

## Joint VIMP for a pair of variables
vimp_joint <- vimp.boostmtree(fit, x.names = c("x1", "x2"), joint = TRUE)

Partial and marginal dependence plots

## Marginal plot (fast, unadjusted)
marginalPlot(fit, xvar.names = c("x1", "x2"))

## Partial dependence plot (slower, confounder-adjusted)
partialPlot(fit, xvar.names = "x1")

Binary response — Atrial Fibrillation data

data(AF, package = "hvtiBoostmtree")

fit_af <- boostmtree(
  x      = AF$feature,
  tm     = AF$time,
  id     = AF$id,
  y      = AF$y,
  family = "Binary",
  M      = 300,
  cv.flag = TRUE
)

print(fit_af)
plot(fit_af)

## Variable importance
vimp_af <- vimp.boostmtree(fit_af)
vimpPlot(vimp_af)

Continuous response — Spirometry data

data(spirometry, package = "hvtiBoostmtree")

fit_spi <- boostmtree(
  x      = spirometry$features,
  tm     = spirometry$time,
  id     = spirometry$id,
  y      = spirometry$y,
  family = "Continuous",
  M      = 300,
  cv.flag = TRUE
)

print(fit_spi)
marginalPlot(fit_spi, xvar.names = colnames(spirometry$features)[1:4])

Key Functions

Function	Description
boostmtree()	Fit a boosted multivariate tree model
predict.boostmtree()	Predict on new data
print.boostmtree()	Print model summary
plot.boostmtree()	Diagnostic plots (error curve, fitted values, residuals)
vimp.boostmtree()	Variable importance scores
vimpPlot()	Plot variable importance
marginalPlot()	Marginal dependence plots (fast)
partialPlot()	Partial dependence plots (adjusted)
simLong()	Simulate longitudinal data

Datasets

Dataset	Subjects	Observations	Response	Description
AF	228	7,949	Binary	Atrial fibrillation presence/absence after surgical ablation
spirometry	509	9,471	Continuous	FEV1% after lung transplantation

Documentation

Full documentation is available at https://ehrlinger.github.io/hvtiBoostmtree/, including:

• Reference manual
• Introduction vignette
• Longitudinal analysis vignette

Authors

• Hemant Ishwaran — original methodology
• Amol Pande — original methodology
• Udaya B. Kogalur — original implementation
• John Ehrlinger — current maintainer

Citation

If you use hvtiBoostmtree in your research, please cite:

Pande A., Li L., Rajeswaran J., Ehrlinger J., Kogalur U.B., Blackstone E.H., Ishwaran H. (2017). Boosted multivariate trees for longitudinal data. Machine Learning, 106(2): 277–305. doi: 10.1007/s10994-016-5597-1

citation("hvtiBoostmtree")

References

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

Friedman J.H. (2002). Stochastic gradient boosting. Computational Statistics & Data Analysis, 38(4): 367–378.

Pande A., Li L., Rajeswaran J., Ehrlinger J., Kogalur U.B., Blackstone E.H., Ishwaran H. (2017). Boosted multivariate trees for longitudinal data. Machine Learning, 106(2): 277–305. doi: 10.1007/s10994-016-5597-1

License

GPL (>= 3) — see LICENSE for details.