aorsf

aorsf: An R package for supervised learning using the oblique random survival forest - Published in JOSS (2022)

https://github.com/ropensci/aorsf

Keywords

Repository

Accelerated Oblique Random Survival Forests

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  dpi = 300,
  warning = FALSE,
  message = FALSE
)

```

# aorsf 





[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
  [![Codecov test coverage](https://codecov.io/gh/bcjaeger/aorsf/branch/master/graph/badge.svg)](https://app.codecov.io/gh/bcjaeger/aorsf?branch=master)
[![R-CMD-check](https://github.com/bcjaeger/aorsf/workflows/R-CMD-check/badge.svg)](https://github.com/ropensci/aorsf/actions/)
[![Status at rOpenSci Software Peer Review](https://badges.ropensci.org/532_status.svg)](https://github.com/ropensci/software-review/issues/532/)

[![CRAN status](https://www.r-pkg.org/badges/version/aorsf)](https://CRAN.R-project.org/package=aorsf)
[![DOI](https://zenodo.org/badge/394311897.svg)](https://zenodo.org/doi/10.5281/zenodo.7116854)


Fit, interpret, and make predictions with oblique random forests (RFs).  

## Why aorsf?

- Fast and versatile tools for oblique RFs.^1^

- Accurate predictions.^2^

- Intuitive design with formula based interface.

- Extensive input checks and informative error messages.

- Compatible with `tidymodels` and `mlr3`

## Installation
You can install `aorsf` from CRAN using

``` r
install.packages("aorsf")
```


You can install the development version of aorsf from [GitHub](https://github.com/) with:

``` r
# install.packages("remotes")
remotes::install_github("ropensci/aorsf")
```

## Get started

```{r}
library(aorsf)
library(tidyverse)
```

`aorsf` fits several types of oblique RFs with the `orsf()` function, including classification, regression, and survival RFs. 

```{r, child='Rmd/orsf-fit-intro.Rmd'}

```

## What does "oblique" mean?

Decision trees are grown by splitting a set of training data into non-overlapping subsets, with the goal of having more similarity within the new subsets than between them. When subsets are created with a single predictor, the decision tree is *axis-based* because the subset boundaries are perpendicular to the axis of the predictor. When linear combinations (i.e., a weighted sum) of variables are used instead of a single variable, the tree is *oblique* because the boundaries are neither parallel nor perpendicular to the axis. 

**Figure**: Decision trees for classification with axis-based splitting (left) and oblique splitting (right). Cases are orange squares; controls are purple circles. Both trees partition the predictor space defined by variables X1 and X2, but the oblique splits do a better job of separating the two classes.


```{r fig_oblique_v_axis, out.width='100%', echo = FALSE}

knitr::include_graphics('man/figures/tree_axis_v_oblique.png')

```

So, how does this difference translate to real data, and how does it impact random forests comprising hundreds of axis-based or oblique trees? We will demonstrate this using the `penguin` data.^3^ We will also use this function to make several plots:

```{r}
plot_decision_surface <- function(predictions, title, grid){
 
 # this is not a general function for plotting
 # decision surfaces. It just helps to minimize 
 # copying and pasting of code.
 
 class_preds <- bind_cols(grid, predictions) %>%
  pivot_longer(cols = c(Adelie,
                        Chinstrap,
                        Gentoo)) %>%
  group_by(flipper_length_mm, bill_length_mm) %>%
  arrange(desc(value)) %>%
  slice(1)
 
 cols <- c("darkorange", "purple", "cyan4")

 ggplot(class_preds, aes(bill_length_mm, flipper_length_mm)) +
  geom_contour_filled(aes(z = value, fill = name),
                      alpha = .25) +
  geom_point(data = penguins_orsf,
             aes(color = species, shape = species),
             alpha = 0.5) +
  scale_color_manual(values = cols) +
  scale_fill_manual(values = cols) +
  labs(x = "Bill length, mm",
       y = "Flipper length, mm") +
  theme_minimal() +
  scale_x_continuous(expand = c(0,0)) +
  scale_y_continuous(expand = c(0,0)) +
  theme(panel.grid = element_blank(),
        panel.border = element_rect(fill = NA),
        legend.position = '') + 
  labs(title = title)
 
}
```

We also use a grid of points for plotting decision surfaces:

```{r}
grid <- expand_grid(

 flipper_length_mm = seq(min(penguins_orsf$flipper_length_mm),
                     max(penguins_orsf$flipper_length_mm),
                  len = 200),
 bill_length_mm = seq(min(penguins_orsf$bill_length_mm),
                      max(penguins_orsf$bill_length_mm),
                      len = 200)
)
```


We use `orsf` with `mtry=1` to fit axis-based trees: 

```{r}
fit_axis_tree <- penguins_orsf %>% 
 orsf(species ~ bill_length_mm + flipper_length_mm,
      n_tree = 1,
      mtry = 1,
      tree_seeds = 106760)

```

Next we use `orsf_update` to copy and modify the original model, expanding it to fit an oblique tree by using `mtry=2` instead of `mtry=1`, and to include 500 trees instead of 1:

```{r}
fit_axis_forest <- fit_axis_tree %>% 
 orsf_update(n_tree = 500)

fit_oblique_tree <- fit_axis_tree %>% 
 orsf_update(mtry = 2)

fit_oblique_forest <- fit_oblique_tree %>% 
 orsf_update(n_tree = 500)
```

And now we have all we need to visualize decision surfaces using predictions from these four fits:

```{r}
preds <- list(fit_axis_tree,
              fit_axis_forest,
              fit_oblique_tree,
              fit_oblique_forest) %>% 
 map(predict, new_data = grid, pred_type = 'prob')

titles <- c("Axis-based tree",
            "Axis-based forest",
            "Oblique tree",
            "Oblique forest")

plots <- map2(preds, titles, plot_decision_surface, grid = grid)
```

**Figure**: Axis-based and oblique decision surfaces from a single tree and an ensemble of 500 trees. Axis-based trees have boundaries perpendicular to predictor axes, whereas oblique trees can have boundaries that are neither parallel nor perpendicular to predictor axes. Axis-based forests tend to have 'step-function' decision boundaries, while oblique forests tend to have smooth decision boundaries.

```{r, echo=FALSE}

cowplot::plot_grid(plotlist = plots)

```

## Variable importance

The importance of individual predictor variables can be estimated in three ways using `aorsf` and can be used on any type of oblique RF. Also, variable importance functions always return a named character vector

- **negation**^2^: `r aorsf:::roxy_vi_describe('negate')`

  ```{r}
  orsf_vi_negate(pbc_fit)
  ```

- **permutation**: `r aorsf:::roxy_vi_describe('permute')`

  ```{r}
  orsf_vi_permute(penguin_fit)
  ```
  
- **analysis of variance (ANOVA)**^4^: `r aorsf:::roxy_vi_describe('anova')`

  ```{r}
  orsf_vi_anova(bill_fit)
  ```

You can supply your own R function to estimate out-of-bag error (see [oob vignette](https://docs.ropensci.org/aorsf/articles/oobag.html)) or to estimate out-of-bag variable importance (see [orsf_vi examples](https://docs.ropensci.org/aorsf/reference/orsf_vi.html#examples))

## Partial dependence (PD) 

`r aorsf:::roxy_pd_explain()`. You can use specific values for a predictor to compute PD or let `aorsf` pick reasonable values for you if you use `pred_spec_auto()`:

```{r}
# pick your own values
orsf_pd_oob(bill_fit, pred_spec = list(species = c("Adelie", "Gentoo")))

# let aorsf pick reasonable values for you:
orsf_pd_oob(bill_fit, pred_spec = pred_spec_auto(bill_depth_mm, island))

```


The summary function, `orsf_summarize_uni()`, computes PD for as many variables as you ask it to, using sensible values.

```{r}
orsf_summarize_uni(pbc_fit, n_variables = 2)
```

For more on PD, see the [vignette](https://docs.ropensci.org/aorsf/articles/pd.html)

## Individual conditional expectations (ICE)

`r aorsf:::roxy_ice_explain()`


For more on ICE, see the [vignette](https://docs.ropensci.org/aorsf/articles/pd.html#individual-conditional-expectations-ice)


## Interaction scores

The `orsf_vint()` function computes a score for each possible interaction in a model based on PD using the method described in Greenwell et al, 2018.^5^ It can be slow for larger datasets, but substantial speedups occur by making use of multi-threading and restricting the search to a smaller set of predictors. 

```{r}
preds_interaction <- c("albumin", "protime", "bili", "spiders", "trt")

# While it is tempting to speed up `orsf_vint()` by growing a smaller 
# number of trees, results may become unstable with this shortcut.
pbc_interactions <- pbc_fit %>% 
 orsf_update(n_tree = 500, tree_seeds = 329) %>% 
 orsf_vint(n_thread = 0,  predictors = preds_interaction)

pbc_interactions
```

What do the values in `score` mean? These values are the average of the standard deviation of the standard deviation of PD in one variable conditional on the other variable. They should be interpreted relative to one another, i.e., a higher scoring interaction is more likely to reflect a real interaction between two variables than a lower scoring one.

Do these interaction scores make sense? Let's test the top scoring and lowest scoring interactions using `coxph()`.

```{r}
library(survival)
# the top scoring interaction should get a lower p-value
anova(coxph(Surv(time, status) ~ protime * albumin, data = pbc_orsf))
# the bottom scoring interaction should get a higher p-value
anova(coxph(Surv(time, status) ~ spiders * trt, data = pbc_orsf))
```

Note: this is exploratory and not a true null hypothesis test. Why? Because we used the same data both to generate and to test the null hypothesis. We are not so much conducting statistical inference when we test these interactions with `coxph` as we are demonstrating the interaction scores that `orsf_vint()` provides are consistent with tests from other models.

## Comparison to existing software

For survival analysis, comparisons between `aorsf` and existing software are presented in our [JCGS paper](https://doi.org/10.1080/10618600.2023.2231048). The paper:

- describes `aorsf` in detail with a summary of the procedures used in the tree fitting algorithm 

- runs a general benchmark comparing `aorsf` with `obliqueRSF` and several other learners 

- reports prediction accuracy and computational efficiency of all learners.

- runs a simulation study comparing variable importance techniques with oblique survival RFs, axis based survival RFs, and boosted trees.

- reports the probability that each variable importance technique will rank a relevant variable with higher importance than an irrelevant variable.




## References

1. `r aorsf:::cite("jaeger_2019")`
1. `r aorsf:::cite("jaeger_2022")`
1. `r aorsf:::cite("penguins_2020")`
1. `r aorsf:::cite("menze_2011")`
1. `r aorsf:::cite("greenwell_2018")`



## Funding

The developers of `aorsf` received financial support from the Center for Biomedical Informatics, Wake Forest University School of Medicine. We also received support from the National Center for Advancing Translational Sciences of the National Institutes of Health under Award Number UL1TR001420. 

The content is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.

Owner

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "aorsf",
  "description": "Fit, interpret, and make predictions with oblique random survival forests. Oblique decision trees are notoriously slow compared to their axis based counterparts, but 'aorsf' runs as fast or faster than axis-based decision tree algorithms for right-censored time-to-event outcomes.",
  "name": "aorsf: Accelerated Oblique Random Survival Forests",
  "relatedLink": "https://bcjaeger.github.io/aorsf",
  "codeRepository": "https://github.com/bcjaeger/aorsf",
  "issueTracker": "https://github.com/bcjaeger/aorsf/issues",
  "license": "https://spdx.org/licenses/MIT",
  "version": "0.0.1",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.1.3 (2022-03-10)",
  "author": [
    {
      "@type": "Person",
      "givenName": "Byron",
      "familyName": "Jaeger",
      "email": "bjaeger@wakehealth.edu",
      "@id": "https://orcid.org/0000-0001-7399-2299"
    }
  ],
  "contributor": [
    {
      "@type": "Person",
      "givenName": "Nicholas",
      "familyName": "Pajewski"
    },
    {
      "@type": "Person",
      "givenName": "Sawyer",
      "familyName": "Welden",
      "email": "swelden@wakehealth.edu"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Byron",
      "familyName": "Jaeger",
      "email": "bjaeger@wakehealth.edu",
      "@id": "https://orcid.org/0000-0001-7399-2299"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "survival",
      "name": "survival",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=survival"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "survivalROC",
      "name": "survivalROC",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=survivalROC"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "ggplot2",
      "name": "ggplot2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ggplot2"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "version": ">= 3.0.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "glmnet",
      "name": "glmnet",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=glmnet"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "covr",
      "name": "covr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=covr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "units",
      "name": "units",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=units"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "Rcpp",
      "name": "Rcpp",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=Rcpp"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "data.table",
      "name": "data.table",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=data.table"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "R",
      "name": "R",
      "version": ">= 3.6"
    },
    "SystemRequirements": null
  },
  "fileSize": "9141.536KB",
  "citation": [
    {
      "@type": "ScholarlyArticle",
      "datePublished": "2019",
      "author": [
        {
          "@type": "Person",
          "givenName": [
            "Byron",
            "C."
          ],
          "familyName": "Jaeger"
        },
        {
          "@type": "Person",
          "givenName": [
            "D.",
            "Leann"
          ],
          "familyName": "Long"
        },
        {
          "@type": "Person",
          "givenName": [
            "Dustin",
            "M."
          ],
          "familyName": "Long"
        },
        {
          "@type": "Person",
          "givenName": "Mario",
          "familyName": "Sims"
        },
        {
          "@type": "Person",
          "givenName": [
            "Jeff",
            "M."
          ],
          "familyName": "Szychowski"
        },
        {
          "@type": "Person",
          "givenName": "Yuan-I",
          "familyName": "Min"
        },
        {
          "@type": "Person",
          "givenName": [
            "Leslie",
            "A."
          ],
          "familyName": "Mcclure"
        },
        {
          "@type": "Person",
          "givenName": "George",
          "familyName": "Howard"
        },
        {
          "@type": "Person",
          "givenName": "Noah",
          "familyName": "Simon"
        }
      ],
      "name": "Oblique Random Survival Forests",
      "url": "https://doi.org/10.1214/19-AOAS1261",
      "pagination": "1847--1883",
      "isPartOf": {
        "@type": "PublicationIssue",
        "issueNumber": "3",
        "datePublished": "2019",
        "isPartOf": {
          "@type": [
            "PublicationVolume",
            "Periodical"
          ],
          "volumeNumber": "13",
          "name": "Annals of Applied Statistics"
        }
      }
    }
  ],
  "releaseNotes": "https://github.com/bcjaeger/aorsf/blob/master/NEWS.md",
  "readme": "https://github.com/bcjaeger/aorsf/blob/master/README.md",
  "contIntegration": [
    "https://app.codecov.io/gh/bcjaeger/aorsf?branch=master",
    "https://github.com/bcjaeger/aorsf/actions",
    "https://github.com/bcjaeger/aorsf/actions?query=workflow%3Apkgcheck"
  ],
  "developmentStatus": "https://www.repostatus.org/#wip",
  "review": {
    "@type": "Review",
    "url": "https://github.com/ropensci/software-review/issues/532",
    "provider": "https://ropensci.org"
  },
  "keywords": [
    "r",
    "rstats",
    "data-science"
  ]
}

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago

Packages