README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

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

# bregr: Easy and Efficient Batch Processing of Regression Models in R <a href="https://wanglabcsu.github.io/bregr/"><img src="man/figures/logo.png" align="right" height="139" alt="bregr website" /></a>

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/bregr)](https://CRAN.R-project.org/package=bregr)
[![](https://cranlogs.r-pkg.org/badges/grand-total/bregr?color=blue)](https://cran.r-project.org/package=bregr)
[![R-CMD-check](https://github.com/WangLabCSU/bregr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/WangLabCSU/bregr/actions/workflows/R-CMD-check.yaml)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/WangLabCSU/bregr)
<!-- badges: end -->

The **bregr** package revolutionizes batch regression modeling in R, enabling you to run **hundreds of models simultaneously** with a clean, intuitive workflow. Designed for both univariate and multivariate analyses, it delivers **tidy-formatted results** and publication-ready visualizations, transforming cumbersome statistical workflows into efficient pipelines.

## Key Features

- 🚀 **Batch Processing**: Automate regression modeling across multiple dependent/independent variables.
- 📊 **Tidy Output**: Structured results compatible with `tidyverse` for seamless downstream analysis.
- 📈 **Integrated Visualization**: One-command forest plots and model diagnostics.
- ⚡️ **Unified Workflow**: Chain operations with native R pipes (`|>`).
- 📦 **Model Agnostic**: Supports linear models, Cox regression, and more.

## Batch Regression Modeling Overview

Batch regression streamlines analyses where:

- Each model shares **identical control variables** ($c_1$, $c_2$, ...).
- **Focal predictors** ($x_1$, $x_2$, ...) or **response variables** ($y_1$, $y_2$, ...) vary systematically.

A simplified overview of batch regression modeling is given below for illustration:

<p align="center">
<img src="man/figures/breg_formula.svg">
</p>


## Installation

You can install the stable version of bregr from CRAN with:

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

Alternatively, install the development version from [r-universe](https://wanglabcsu.r-universe.dev/bregr) with:

``` r
install.packages('bregr', repos = c('https://wanglabcsu.r-universe.dev', 'https://cloud.r-project.org'))
```

or from [GitHub](https://github.com/) with:

``` r
#install.packages("remotes")
remotes::install_github("WangLabCSU/bregr")
```

## Usage

Load package(s):

```{r load-package}
library(bregr)
```

Load data:

```{r load-data}
lung <- survival::lung |>
  dplyr::filter(ph.ecog != 3)
lung$ph.ecog <- factor(lung$ph.ecog)
```

bregr is designed and implemented following [Tidy design principles](https://design.tidyverse.org/) and [Tidyverse style guide](https://style.tidyverse.org/), making it intuitive and user-friendly.


### Core workflow

Define and construct batch models:

```{r}
mds <- breg(lung) |> # Init breg object
  br_set_y(c("time", "status")) |> # Survival outcomes
  br_set_x(colnames(lung)[6:10]) |> # Focal predictors
  br_set_x2(c("age", "sex")) |> # Controls
  br_set_model("coxph") |> # Cox Proportional Hazards
  br_run() # Execute models
```

### One-Step Pipeline

```{r eval=FALSE}
mds <- br_pipeline(
  lung,
  y = c("time", "status"),
  x = colnames(lung)[6:10],
  x2 = c("age", "sex"),
  method = "coxph"
)
```

Run in parallel:

```{r warning=FALSE}
mds_p <- br_pipeline(
  lung,
  y = c("time", "status"),
  x = colnames(lung)[6:10],
  x2 = c("age", "sex"),
  method = "coxph",
  n_workers = 3
)
```

```{r}
all.equal(mds, mds_p)
```

Two global options have been introduced to control whether models are saved as local files (`bregr.save_model`, default is `FALSE`) and where they should be saved (`bregr.path`, default uses a temporary path).

### Output Inspection

Use `br_get_*()` function family to access attributes and data of result `breg` object.

```{r}
br_get_models(mds) # Raw model objects
br_get_results(mds) # Comprehensive estimates
br_get_results(mds, tidy = TRUE) # Tidy-formatted coefficients
```

### Visualization

#### Forest Plot (Key Results)

bregr mainly provides `br_show_forest()` for plotting data table of modeling results.

```{r dpi=150}
br_show_forest(mds)
```

We can tune the plot to only keep focal variables and adjust the limits of x axis.

```{r dpi=150}
br_show_forest(
  mds,
  rm_controls = TRUE, # Focus on focal predictors
  xlim = c(0, 3), # Custom axis scaling
  #   Use x_trans = "log" to transform the axis
  #   Use log_first = TRUE to transform both
  #       the axis and estimate table
  drop = 1 # Remove redundant columns
)
```

We also provide some interfaces from other packages for plotting constructed model(s), e.g., `br_show_forest_ggstats()`, `br_show_forest_ggstatsplot()`, `br_show_fitted_line()`,
and `br_show_fitted_line_2d()`.

#### Comparing Univariate vs Multivariate Models

A common analysis task is to compare how predictor effects change when modeled individually (univariate) versus together (multivariate). The `br_compare_models()` function builds both types of models and displays them side-by-side:

```{r dpi=150, fig.height=5}
# Compare univariate and multivariate models
comparison <- br_compare_models(
  lung,
  y = c("time", "status"),
  x = c("ph.ecog", "ph.karno", "pat.karno"),
  x2 = c("age", "sex"),
  method = "coxph"
)

# Show forest plot with both models
br_show_forest_comparison(comparison)
```

This allows you to see how adjusting for other predictors affects the estimates for each variable.

For Cox-PH modeling results (focal variables must be continuous type), we provide a risk network plotting function.

```{r}
mds2 <- br_pipeline(
  survival::lung,
  y = c("time", "status"),
  x = colnames(survival::lung)[6:10],
  x2 = c("age", "sex"),
  method = "coxph"
)
```

```{r dpi=150, fig.height=8}
br_show_risk_network(mds2)
```

#### Model Score Prediction and Survival Curves

For Cox-PH models, you can generate model predictions (risk scores) and create survival curves grouped by these scores:

```{r}
# Generate model predictions
scores <- br_predict(mds2, idx = "ph.ecog")
head(scores)
```

```{r dpi=150, fig.height=6}
# Create survival curves based on model scores
br_show_survival_curves(
  mds2,
  idx = "ph.ecog",
  n_groups = 3,
  title = "Survival Curves by 'ph.ecog' Model Risk Score"
)
```

### Table

Show tidy table result as pretty table:

```{r}
br_show_table(mds)
```

As markdown table:

```{r}
br_show_table(mds, export = TRUE)
```

As HTML table:

```{r eval=FALSE}
br_show_table(mds, export = TRUE, args_table_export = list(format = "html"))
```

## Documentation

All functions are documented in the [package reference](https://wanglabcsu.github.io/bregr/reference/), with full documentation available on the [package site](https://wanglabcsu.github.io/bregr/).

## Coverage

```{r eval=FALSE}
covr::package_coverage()
```

## Citation

If you use **bregr** in academic field, please cite:

- Wang S, Peng Y, Shu C, et al. bregr: An R Package for Streamlined Batch Processing and Visualization of Biomedical Regression Models[J]. Med Research, 2025. https://doi.org/10.1002/mdr2.70028

## Related/Similar Project(s)

- [ezcox: Easily Process a Batch of Cox Models](https://github.com/ShixiangWang/ezcox/)
- [autoReg](https://github.com/cardiomoon/autoReg/)
- [riskRegression](https://github.com/tagteam/riskRegression/)

## LICENSE

(GPL-3) Copyright (c) 2025 Shixiang Wang & WangLabCSU team