BreastSubtypeR

BreastSubtypeR is an assumption-aware, multi-method R/Bioconductor package with a local Shiny app. It consolidates published intrinsic subtyping methods under one API and lets you run multiple classifiers at once. AUTO inspects cohort diagnostics to select compatible methods and reduce misclassification.

Research use only; in clinical practice, intrinsic molecular subtyping is standardized via approved diagnostics (e.g., Prosigna®).

📄 Publication: NAR Genomics and Bioinformatics (2025), Editor’s Choice → doi:10.1093/nargab/lqaf131

@article{Yang2025BreastSubtypeR,
  author  = {Yang, Qiao and Hartman, Johan and Sifakis, Emmanouil G.},
  title   = {{BreastSubtypeR}: a unified R/Bioconductor package for intrinsic molecular subtyping in breast cancer research},
  journal = {NAR Genomics and Bioinformatics},
  year    = {2025},
  volume  = {7},
  number  = {4},
  pages   = {lqaf131},
  doi     = {10.1093/nargab/lqaf131},
  url     = {https://doi.org/10.1093/nargab/lqaf131}
}

Features

• Unified interface for published methods: consolidates PAM50 variants, AIMS, ssBC/sspbc, and others under one consistent API.
• Run multiple methods at once (BS_Multi): execute several classifiers in a single call and compare results side by side.
• AUTO (cohort-aware selection): checks ER/HER2 distribution, subtype purity, and subgroup sizes; disables incompatible classifiers.
• Method-specific pre-processing: automatically routes raw RNA-seq counts, precomputed FPKM, or log2-processed microarray/nCounter matrices.
• Robust mapping: Entrez ID–based gene mapping with conflict resolution.
• Local Shiny app (iBreastSubtypeR): point-and-click analysis; data stay on your machine.
• Reproducibility: Bioconductor distribution, unit tests, vignettes, and SummarizedExperiment compatibility.

Methods included (single-method implementations)

(See the vignette for implementation details.)

Installation

Install the released version from Bioconductor:

# Requires R >= 4.5.0
if (!require("BiocManager", quietly = TRUE)) install.packages("BiocManager")
BiocManager::install("BreastSubtypeR")

# Devel:
BiocManager::install("BreastSubtypeR", version = "devel")

Or install from GitHub:

if (!require("remotes", quietly = TRUE)) install.packages("remotes")
remotes::install_github("yqkiuo/BreastSubtypeR")

Quick start

These examples use datasets shipped with the package. For your own data, provide a SummarizedExperiment with clinical metadata in colData (e.g., PatientID, ER, HER2; for ROR: TSIZE, NODE).

library(BreastSubtypeR)

# Example data
data("BreastSubtypeRobj")
data("OSLO2EMIT0obj")

1) Map & prepare (method-specific pre-processing + mapping)

data_input <- Mapping(OSLO2EMIT0obj$se_obj, RawCounts = FALSE, method = "max", impute = TRUE)

2) Multi-method run (user-defined)

res <- BS_Multi(data_input = data_input, methods = c("parker.original","PCAPAM50","sspbc"))
head(res$res_subtypes, 5)

3) AUTO mode (cohort-aware selection) + visualize

res_auto <- BS_Multi(data_input = data_input, methods = "AUTO")
Vis_Multi(res_auto$res_subtypes)

AUTO logic (clarifications)

• ER/HER2-defined cohorts (ER+/HER2−, ER−/HER2−, ER+/HER2+, ER−/HER2+):

ssBC.v2 only + SSP (AIMS, sspbc).

• ER-only (ER+ or ER−) and TNBC (size permitting):

ssBC and/or ssBC.v2 + SSP.

• ER balance gate (simulation-based): lower_ratio = 0.39, upper_ratio = 0.69.
• Minimum sizes (defaults): ER+ = 15, ER− = 18, TN = 18. Subgroups use half of ER totals (rounded):
  • ER+: n_ERposHER2pos_threshold = n_ERposHER2neg_threshold = round(15 / 2)
  • ER−: n_ERnegHER2pos_threshold = n_ERnegHER2neg_threshold = round(18 / 2)

Provenance: ER+/ER− minimums are simulation-based defaults. TN currently uses the ER− minimum (18). Subgroup gates and TN minimum may be refined in future releases as additional simulations become available.

4) Launch the local Shiny app

BreastSubtypeR::iBreastSubtypeR() # interactive GUI (local)

Notes:

• The app runs locally; no data leave your machine.

• If you see a missing UI dependency:

install.packages(c("shiny","bslib"))

Example data (for Shiny & scripts)

You can explore the app without preparing files:

• In iBreastSubtypeR, click “Load example data…” to pre-fill the UI with a small demo cohort. Then click Preprocess & map and proceed to Step 2.

• Programmatically, the same files are shipped inside the package:

  exdir   <- system.file("RshinyTest", package = "BreastSubtypeR")
  gex     <- file.path(exdir, "OSLO2EMIT0_GEX_log2.FPKM.txt")
  clin    <- file.path(exdir, "OSLO2EMIT0_clinical.txt")
  anno    <- file.path(exdir, "OSLO2EMIT0_anno.txt")
  stopifnot(all(file.exists(gex, clin, anno)))

Vignette & documentation

A comprehensive usage guide (input types, AUTO details, full method descriptions) is included as a vignette.

See function help pages for specifics (e.g., ?BS_Multi, ?Mapping, ?iBreastSubtypeR).

Contributing & issues

Canonical source
Bioconductor package page: https://bioconductor.org/packages/BreastSubtypeR
Bioconductor DOI: https://doi.org/10.18129/B9.bioc.BreastSubtypeR
Mirrors: https://github.com/yqkiuo/BreastSubtypeR (personal), https://github.com/JohanHartmanGroupBioteam/BreastSubtypeR (org)

Support & bugs
Bugs/PRs: https://github.com/yqkiuo/BreastSubtypeR/issues

License

GPL-3