jointVIP

jointVIP: Prioritizing variables in observational study design with joint variable importance plot in R - Published in JOSS (2024)

https://github.com/ldliao/jointvip

Keywords

Repository

Prioritize variables in observational study design through the joint variable importance plot; shiny app: https://ldliao.shinyapps.io/jointVIP/

README.Rmd

---
output: github_document
---



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

devtools::load_all(".")
```

# Joint variable importance plot 


[![CRAN_Status_Badge](https://img.shields.io/cran/v/jointVIP?color=952100)](https://cran.r-project.org/package=jointVIP) [![CRAN_Downloads_Badge](https://cranlogs.r-pkg.org/badges/jointVIP?color=952100)](https://cran.r-project.org/package=jointVIP)
[![R-CMD-check](https://github.com/ldliao/jointVIP/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ldliao/jointVIP/actions/workflows/R-CMD-check.yaml)


Joint variable importance plot (jointVIP) visualizes each variable's outcome importance via Pearson's correlation and treatment importance via cross-sample standardized mean differences. Bias curves enable comparisons to support variable prioritization among potential confounders.

## Installation

You can install the `jointVIP` package on CRAN using:

``` r
# for version on CRAN
install.packages("jointVIP")

# for development version on github
devtools::install_github("ldliao/jointVIP")
```

## BRFSS Example

To demonstrate, we use the 2015 Behavioral Risk Factor Surveillance System (BRFSS) example to answer the causal question: Does smoking increase the risk of chronic obstructive pulmonary disease (COPD)? The data and background is inspired by [Clay Ford's work from University of Virginia Library](https://data.library.virginia.edu/getting-started-with-matching-methods/). First, the data is cleaned to only have numeric variables, i.e., all factored variables are transformed via one-hot-encoding. Treatment variable `smoke` only contains 0 (control) and 1 (treatment).

With the cleaned data, you can specify details in the function `create_jointVIP()` like so:

```{r example}
library(jointVIP)
## basic example code
library(dplyr)

# load data
data('brfss', package='jointVIP')

treatment = 'smoke'
outcome = 'COPD'
covariates = names(brfss)[!names(brfss) %in% c(treatment, outcome)]

## select the pilot sample from random portion
## pilot data here are considered as 'external controls'
## can be a separate dataset; should be chosen with caution
set.seed(1234895)
pilot_prop = 0.2 
pilot_sample_num = sample(which(brfss %>% pull(treatment) == 0),
                          length(which(brfss %>% pull(treatment) == 0)) *
                          pilot_prop)

## set up pilot and analysis data
## we want to make sure these two data are non-overlapping

pilot_df = brfss[pilot_sample_num, ]
analysis_df = brfss[-pilot_sample_num, ]

## minimal example
brfss_jointVIP = create_jointVIP(treatment = treatment,
                                 outcome = outcome,
                                 covariates = covariates,
                                 pilot_df = pilot_df,
                                 analysis_df = analysis_df)
```

Generic functions can be used for the `jointVIP` object to extract information as a glance with `summary()` and `print()`. 

```{r generic}
summary(brfss_jointVIP)
print(brfss_jointVIP)
```


```{r plot, dpi=300, fig.asp = 0.75, fig.width = 6, fig.align = "center", message=FALSE}
plot(brfss_jointVIP)
```

In this example, `age_over65` and `average_drinks` are two most important variables to adjust. At a bias tolerance of 0.01, 3 variables: `age_over65`, `average_drinks`, and `age_25to34` are above the tolerance threshold. Moreover, `age_over65` and `average_drinks` are of higher importance for adjustment than `age_25to34`. Although `race_black` and `age_over65` have similar absolute standardized mean differences (0.322 and 0.333, respectively), `age_over65` is more important to adjust for since its highly correlated with the outcome.

## Acknowledgement
Ford, C. 2018. “Getting Started with Matching Methods.” UVA Library StatLab. https://library.virginia.edu/data/articles/getting-started-with-matching-methods/ (accessed Jan 29, 2024).

Owner

JOSS Publication

jointVIP: Prioritizing variables in observational study design with joint variable importance plot in R

Published

November 12, 2024

DOI

10.21105/joss.06093

Volume 9, Issue 103, Page 6093

Authors

Lauren D. Liao
Division of Biostatistics, University of California, Berkeley, USA

Samuel D. Pimentel
Department of Statistics, University of California, Berkeley, USA

Editor

Andrew Stewart

Tags

observational study study design visualization causal inference

View PDF Review Thread Software Archive

Citation (citation.cff)

cff-version: "1.2.0"
authors:
- family-names: Liao
  given-names: Lauren D.
  orcid: "https://orcid.org/0000-0003-4697-6909"
- family-names: Pimentel
  given-names: Samuel D.
  orcid: "https://orcid.org/0000-0002-0409-6586"
contact:
- family-names: Liao
  given-names: Lauren D.
  orcid: "https://orcid.org/0000-0003-4697-6909"
doi: 10.5281/zenodo.14020544
message: If you use this software, please cite our article in the
  Journal of Open Source Software.
preferred-citation:
  authors:
  - family-names: Liao
    given-names: Lauren D.
    orcid: "https://orcid.org/0000-0003-4697-6909"
  - family-names: Pimentel
    given-names: Samuel D.
    orcid: "https://orcid.org/0000-0002-0409-6586"
  date-published: 2024-11-12
  doi: 10.21105/joss.06093
  issn: 2475-9066
  issue: 103
  journal: Journal of Open Source Software
  publisher:
    name: Open Journals
  start: 6093
  title: "jointVIP: Prioritizing variables in observational study design
    with joint variable importance plot in R"
  type: article
  url: "https://joss.theoj.org/papers/10.21105/joss.06093"
  volume: 9
title: "jointVIP: Prioritizing variables in observational study design
  with joint variable importance plot in R"

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago

Packages