Contents

1 Installation

Install from the Bioconductor release compatible with your R installation. Consult the package page for the requirements of your selected channel:

if (!require("BiocManager", quietly = TRUE)) install.packages("BiocManager")
BiocManager::install("BreastSubtypeR")

Bioconductor release, Bioconductor devel, and GitHub are separate distribution channels. GitHub may contain newer development changes that are not yet available through Bioconductor. Consult the official release package page and devel package page for available versions and their R requirements. Use the R version compatible with your selected Bioconductor release or devel environment; the package’s minimum R requirement does not replace that channel’s requirements. Matching version numbers do not guarantee matching source. After installing, record packageVersion("BreastSubtypeR"), the installation channel and source revision, and retain sessionInfo(). This vignette describes its own built package; use browseVignettes() for documentation matching an installed channel.

Use a separate R library and the R version required by Bioconductor devel when choosing the development channel:

BiocManager::install(version = "devel")
BiocManager::install("BreastSubtypeR")

Alternatively, use a separate library configured for the GitHub source’s Bioconductor dependencies, install the development source, and inspect the installed package version:

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

2 Citing BreastSubtypeR

If you use BreastSubtypeR, please cite:

For BibTeX/LaTeX, run in R:

citation("BreastSubtypeR")

3 Brief description

Breast cancer (BC) is a biologically heterogeneous disease with intrinsic molecular subtypes (e.g., Luminal A, Luminal B, HER2-enriched, Basal-like, Normal-like) that inform biological interpretation and clinical decision-making. While clinical assays such as Prosigna provide standardized subtyping in the clinic, research implementations have proliferated and diverge in pre-processing, gene mapping, and algorithmic assumptions—reducing reproducibility and complicating cross-cohort analyses.

BreastSubtypeR consolidates multiple published gene-expression signature classifiers into a unified, assumption-aware Bioconductor package with: - a unified multi-method API (run many classifiers in one call), - AUTO mode for cohort-aware method selection, - standardized, method-specific pre-processing for multiple input types (raw counts, log2-normalized RNA-seq expression, log2-processed arrays), - Entrez ID–based probe/gene mapping, - and a local Shiny app (iBreastSubtypeR) for non-programmers.

3.1 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): selects methods using implemented receptor-annotation and subgroup-size rules; returns per-method calls.
  • Method-specific pre-processing: routes raw RNA-seq counts, or log2-normalized RNA-seq/microarray/nCounter expression with RawCounts = FALSE.
  • Robust mapping: Entrez ID–based gene mapping with conflict resolution.
  • Local Shiny app (iBreastSubtypeR): point-and-click analysis in your local R session.
  • Reproducibility: Bioconductor distribution, unit tests, vignettes, and SummarizedExperiment compatibility.

3.2 Implemented approaches

The package includes implementations of commonly used subtyping methods (NC-based and SSP-based):

Method id Short description Group Reference
parker.original Original PAM50 by Parker et al., 2009 NC-based Parker et al., 2009
genefu.scale PAM50 implementation as in the genefu R package (scaled version) NC-based Gendoo et al., 2016
genefu.robust PAM50 implementation as in the genefu R package (robust version) NC-based Gendoo et al., 2016
cIHC Conventional ER-balancing using immunohistochemistry (IHC) NC-based Ciriello et al., 2015
cIHC.itr Iterative version of cIHC NC-based Curtis et al., 2012
PCAPAM50 Selects IHC-defined ER subsets, then uses Principal Component Analysis (PCA) to create ESR1 expression-based ER-balancing NC-based Raj-Kumar et al., 2019
ssBC Subgroup-specific gene-centering PAM50 NC-based Zhao et al., 2015
ssBC.v2 Updated subgroup-specific gene-centering PAM50 NC-based Fernandez-Martinez et al., 2020, 2024
AIMS Absolute Intrinsic Molecular Subtyping (AIMS) method SSP-based Paquet & Hallett, 2015
sspbc Single-Sample Predictors for Breast Cancer (AIMS adaptation) SSP-based Staaf et al., 2022

Zhao et al. (2015) introduced subgroup-specific gene centering. Fernandez-Martinez et al. (2020) described its HER2/ER-specific application. The packaged ssBC.v2 quantiles match the public SIGMA.txt reference in the Perou Lab normalization repository, associated with Fernandez-Martinez et al. (2024). Across the 50 PAM50 genes, ER.v2 uses ERneg_HER2neg, ERpos_HER2neg, HER2pos_ERneg and HER2pos_ERpos; TN.v2 uses TNBC. The original ER and TN quantiles remain separate. See ?BreastSubtypeRobj for the pinned numerical reference.

For research use. Package outputs are not clinical assay results and do not replace validated clinical diagnostics.

4 Quick start

The examples below use small example 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).

OSLO2EMIT0obj$se_obj contains expression values for 356 gene features from 102 OSLO2-EMIT0 samples, calculated as log2(FPKM + 1) from library-protocol-adjusted FPKM. Clinical metadata are stored in colData, and feature annotations in rowData. The source is OSLO2EMIT0.103.genematrix_noNeg.Rdata in Mendeley Data, version 3 (Vallon-Christersson, 2023). That source matrix has 19,675 features and 103 sample identifiers. The packaged subset retains source-relative order and omits OSLO2EMIT0.073. The historical sample-omission reason, feature-selection rationale and exact generating script are not established; the transformation is verified by matching source identifiers and numerical values. See ?OSLO2EMIT0obj for the packaged example’s source and structure.

library(BreastSubtypeR)

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

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

# Pre-processing: automatically apply tailored normalization, map probes/IDs to Entrez,
# and (optionally) impute missing values
data_input <- Mapping(
    OSLO2EMIT0obj$se_obj,
    method = "max", # mapping strategy (example)
    RawCounts = FALSE,
    impute = TRUE,
    verbose = FALSE
)

Notes

4.1 Descriptive input coverage

InputCoverage() reports the current processed inputs independently of which methods are selected or run. It uses the same calculation as the current GitHub Shiny coverage table. These features are available in current GitHub source. As of 18 October 2026, the published source packages for Bioconductor release 3.23 (BreastSubtypeR 1.4.1) and Bioconductor devel 3.24 (1.5.7) do not include them. Check your installed namespace with "InputCoverage" %in% getNamespaceExports("BreastSubtypeR"); matching package version numbers alone do not establish feature availability.

coverage <- InputCoverage(data_input)
coverage
#>                 model genes_present genes_total genes_absent
#> 1    NC-based (PAM50)            50          50            0
#> 2                AIMS           151         151            0
#> 3 SSPBC (ssp.subtype)           153         153            0
#> 4   SSPBC (ssp.pam50)           216         216            0
#>   rules_evaluable_min rules_evaluable_max rules_total
#> 1                  NA                  NA          NA
#> 2                 100                 100         100
#> 3                  84                  84          84
#> 4                 120                 120         120

The four rows are NC-based (PAM50), AIMS, SSPBC (ssp.subtype) and SSPBC (ssp.pam50). Denominators are derived from the bundled references and fitted models: respectively 50, 151, 153 and 216 unique genes; rule counts are not applicable, 100, 84 and 120. All three NC rule columns are NA.

Represented genes have matching identifiers even when their expression is zero or missing. An evaluable rule is a native gene-pair comparison with a nonmissing TRUE or FALSE result; a false rule is still evaluable. Missing genes and NA/NaN comparisons can make rules unavailable. Native zero, tie, infinity and duplicate-handling behavior is preserved. The minimum and maximum evaluable counts form a range across samples when they differ.

These are processed-input diagnostics. Mapping(impute = TRUE) may have already imputed values, and coverage cannot reconstruct which measurements were originally observed. Coverage is not prediction reliability, does not impose thresholds or exclude methods, and does not assess calibration feasibility. NC coverage concerns the shared PAM50 subtype reference, not every gene or component used in ROR calculations. See ?InputCoverage.

The bundled AIMS setting k = 20 identifies its fitted-model setting and output column. Its complete all.pairs vector and fitted naive Bayes tables contain 100 rule predictors involving 151 unique genes. Thus k is not the total rule denominator. SSPBC uses k = 21 for its 84-rule four-class model and k = 24 for its 120-rule five-class model. No model is altered by reporting.

2) Multi-method run (user-defined)

methods <- c("parker.original", "PCAPAM50", "sspbc")

res <- BS_Multi(
    data_input = data_input,
    methods = methods,
    Subtype = FALSE,
    hasClinical = FALSE
)

# Per-sample calls (rows = samples; columns = methods and entropy)
head(res$res_subtypes, 5)
#>                parker.original PCAPAM50  sspbc   entropy
#> OSLO2EMIT0.001            LumA     LumA   LumB 0.9182958
#> OSLO2EMIT0.002           Basal    Basal  Basal 0.0000000
#> OSLO2EMIT0.003            LumA     LumA   LumA 0.0000000
#> OSLO2EMIT0.004            LumA     LumA   LumA 0.0000000
#> OSLO2EMIT0.005          Normal     LumA Normal 0.9182958

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

AUTO selects a set of methods using implemented receptor-annotation and subgroup-size rules. It returns per-method calls, not a consensus prediction. Selection does not establish complete input adequacy or clinical validity.

res_auto <- BS_Multi(
    data_input = data_input,
    methods = "AUTO",
    Subtype = FALSE,
    hasClinical = FALSE
)

# visualize multi-method output and concordance
Vis_Multi(res_auto$res_subtypes)

AUTO logic (clarifications)

  • TNBC cohorts take precedence when all evaluable TN annotations indicate TN. At least 18 TN samples enable ssBC and ssBC.v2, plus SSP-based methods (AIMS, sspbc); smaller TN cohorts run SSP only.
  • HER2+ cohort detection: a cohort is treated as HER2+ when it has at least one evaluable HER2 value and every evaluable HER2 value is HER2+. The test reads the HER2 column alone, so one HER2- sample ends the HER2+ classification whether or not its ER value is known, and a sample whose HER2 value is missing or equivocal (“2+”) neither creates nor removes a HER2+ cohort. AUTO reports how many samples had no evaluable HER2 value and therefore took no part in the decision.
  • In this HER2+ cohort route, AUTO enables ssBC.v2 plus SSP when there are at least 8 ER+/HER2+ samples or 9 ER-/HER2+ samples; otherwise it runs SSP only. This route does not additionally require the total-ER minima of 15 and 18.
  • Cohorts without any evaluable HER2 value are not treated as HER2+; they follow the ER-based rules (ssBC.v2 then returns NA for every sample).
  • For remaining cohorts, both ER totals below their minima run SSP only. When only one ER group reaches its minimum, its HER2 subgroups determine whether ssBC and/or ssBC.v2 run alongside SSP: both HER2 subgroups reaching their minima enable both methods, while just one enables ssBC.v2.
  • Mixed cohorts with at least 15 ER+ and 18 ER- samples run ten methods when 0.39 < n_ERpos / (n_ERpos + n_ERneg) < 0.69. These are strict inequalities: at or outside either boundary, eight methods run, excluding parker.original and genefu.scale. Both branches include cIHC.itr.
  • Minimum sample group sizes (defaults used by AUTO):
    • ER+ total: n_ERpos_threshold = 15
    • ER− total: n_ERneg_threshold = 18
    • TNBC total: n_TN_threshold = 18 (currently aligned with ER−)
    • ER+ subgroups (HER2+ or HER2−): n_ERposHER2pos_threshold = n_ERposHER2neg_threshold = round(n_ERpos_threshold / 2)
    • ER− subgroups (HER2+ or HER2−): n_ERnegHER2pos_threshold = n_ERnegHER2neg_threshold = round(n_ERneg_threshold / 2)

Notes. Thresholds are selection gates for method eligibility; they do not force a consensus call.

Provenance & future updates. The ER+ (15) and ER- (18) cohort minimums are simulation-based defaults. ER/HER2 subgroup thresholds (approx. half of each ER total) are heuristic and may be updated as additional simulation studies are completed. For TNBC, we currently use the ER- minimum (18) as the cohort cutoff; TN-specific thresholds may likewise be refined in future releases.

4) Single-method run

PAM50 (NC-based)

res_pam <- BS_parker(
    se_obj = data_input$se_NC, # object prepared for NC-based methods
    calibration = "Internal",
    internal = "medianCtr",
    Subtype = FALSE,
    hasClinical = FALSE
)

AIMS (SSP-based)

res_aims <- BS_AIMS(data_input$se_SSP)

AIMS also accepts one sample. Map that sample and retain its identifiers:

one_sample <- Mapping(OSLO2EMIT0obj$se_obj[, 1], RawCounts = FALSE)
aims_one <- BS_AIMS(one_sample$se_SSP)
aims_one$cl
#>                20    
#> OSLO2EMIT0.001 "LumB"
stopifnot(
    identical(dim(aims_one$cl), c(1L, 1L)),
    identical(rownames(aims_one$cl), colnames(one_sample$se_SSP)),
    identical(dim(aims_one$prob), c(1L, 1L)),
    identical(dim(aims_one$all.probs[["20"]]), c(1L, 5L))
)

The cl component contains subtype calls and prob contains the probabilities of those assigned calls. Both are sample-by-one matrices with sample IDs as row names; all.probs[["20"]] has one row per sample and five subtype columns. These dimensions are preserved for one or many samples.

4.2 Iterative cIHC and ER balancing

BS_cIHC.itr() defaults to 100 iterations and er_subsample = "target". Its ratio = 54 / 64 is the target number of ER-positive samples per ER-negative sample, not the ER-positive fraction used by AUTO. The ratio must be one finite, strictly positive number. Values above 1 are allowed in target mode. Write 54 / 64, not the R sequence 54:64. Extreme positive ratios can retain very few samples from one ER group, making the calibration subset poorly representative. Acceptance of a ratio does not establish calibration adequacy for a particular cohort.

Each iteration subsamples the group over-represented relative to the target, without replacement, to ceiling(ratio * n_ERneg) ER+ samples or ceiling(n_ERpos / ratio) ER- samples, retaining the other group. A cohort already at the target within this rounding is used in full. For example, the default target gives 34 ER+ : 40 ER- from 100 ER+ : 40 ER-, and 40 ER+ : 48 ER- from 40 ER+ : 100 ER-.

# Ten iterations keep this example quick; the function default is 100.
res_itr <- BS_cIHC.itr(
    se_obj = data_input$se_NC,
    iteration = 10,
    ratio = 54 / 64,
    er_subsample = "target",
    Subtype = FALSE,
    hasClinical = FALSE
)
head(res_itr$BS.all)
#>                     PatientID    BS
#> OSLO2EMIT0.001 OSLO2EMIT0.001  LumA
#> OSLO2EMIT0.002 OSLO2EMIT0.002 Basal
#> OSLO2EMIT0.003 OSLO2EMIT0.003  LumA
#> OSLO2EMIT0.004 OSLO2EMIT0.004  LumA
#> OSLO2EMIT0.005 OSLO2EMIT0.005  LumA
#> OSLO2EMIT0.006 OSLO2EMIT0.006  LumA

For reproduction of BreastSubtypeR 1.5.5 and earlier, er_subsample = "larger" subsamples the numerically larger ER group to ceiling(ratio * n_smaller), retaining the smaller group. In that legacy mode, the ratio cannot exceed n_larger / n_smaller. With the default ratio and otherwise identical inputs, seed and settings, target and legacy modes agree when ER+ samples are at least as numerous as ER- samples. This equivalence is not guaranteed for other ratios. BS_Multi(er_subsample = "larger") passes the legacy choice to cIHC.itr only; AUTO selection is unchanged.

4.3 Four- versus five-class results and ROR

NC methods retain their five-class calls and add a four-class call when Subtype = TRUE. BS_Multi() likewise always returns the five-class table res_subtypes; Subtype = TRUE adds res_subtypes.Subtype. Both tables have sample IDs as row names, one column per method and an entropy column. AIMS is a five-class predictor with no four-class model: its Normal calls are set to NA only in the four-class multi-method summary. The original AIMS calls are retained in the five-class summary and per-method results. SSPBC uses its four-class ssp.subtype model for the four-class summary.

NC methods return ROR-S and ROR-P scores and risk groups in score.ROR without requiring clinical covariates. Setting hasClinical = TRUE requires TSIZE and NODE columns in colData and adds clinical ROR outputs. TSIZE is binary (0 for at most 2 cm, 1 for more than 2 cm); it enters ROR-C and both ROR-PC scores. No numerical ROR score uses NODE.

For NODE, supply the actual nonnegative integer number of positive lymph nodes as numeric values when available. Only the additional risk group ROR-PC Group (Subtype + Clinic + Prolif.Subtype) distinguishes 0, 1–3 and 4 or more positive nodes. With nonmissing TSIZE, 4 or more nodes receive high risk; 0 and 1–3 use different score cutoffs. Binary 0/1 coding is accepted, but cannot distinguish 1–3 from 4 or more positive nodes. The current R API checks numeric type without enforcing nonnegative integer counts.

In the R API, NA in NODE makes only this additional risk group missing. NA in TSIZE makes all clinical ROR scores and groups missing, while ROR-S and ROR-P remain available. These are missing values within required columns; the columns themselves must still be supplied. The additional subtype-specific ROR-PC group now uses inclusive upper boundaries: for NODE = 0, scores <= 40 are low, > 40 through 60 are intermediate, and > 60 are high; for 1–3 nodes, the corresponding boundaries are 15 and 40. Raw scores are not rounded before grouping. This resolves issue #154 and leaves the original Parker risk groups unchanged. Method-specific return components are documented in their help pages. These are research-use outputs, not a clinical assay result.

The research ROR outputs use Spearman centroid correlations (Parker et al., 2009; Buus et al., 2021). The additional ROR-PC (Subtype + Clinic + Prolif.Subtype) score uses a PAM50 subset excluding BIRC5, CCNB1, GRB7 and MYBL2, an 18-gene proliferation component and binary tumor size. Commercial Prosigna uses Pearson correlations within its validated assay workflow (Wallden et al., 2015). Shared coefficients do not establish equivalent preprocessing, calibration or clinical validation. These research scores and groups are not clinical Prosigna results; version 1.5.8 does not change these calculations.

Known exact-equality limitation. The original Parker-derived ROR-S, ROR-P, ROR-C and ROR-PC (Subtype + Clinic + Prolif) groups retain strict comparisons. At an exact unscaled cutoff, the group can contain numeric text instead of low, med or high. The unscaled pairs are -0.15/0.10, -0.25/0.10, -0.10/0.20 and -0.20/0.20, respectively, before 100 * (score + 0.35) / 0.85. They are not cutoffs on the displayed scaled scores. Numeric-text labels are invalid categories, not an additional risk group; do not infer an assignment by rounding. Version 1.5.8 temporarily defers this known defect pending scientific review of exact-equality assignments. The corrected NODE-dependent additional ROR-PC grouping from issue #154 remains unchanged.

5 Guidance & best practices

5.1 Input types

  • Provide one of the following as input:
    • raw counts plus gene lengths (for internal calculation of CPM/FPKM),
    • log2-normalized RNA-seq expression (for example, log2(FPKM+1)),
    • log2-processed microarray/nCounter matrices (e.g., RMA).
  • Set RawCounts = TRUE for raw RNA-seq counts with gene lengths in the Length annotation column. With RawCounts = FALSE, supply log2-normalized expression: it is used directly for NC methods and back-transformed with 2^x for SSP methods. This setting does not detect or log-transform a supplied linear FPKM/TPM matrix.
  • Include probe and ENTREZID in rowData, and sample identifiers in colData$PatientID matching the assay columns. Receptor fields are required by AUTO and methods that use them; see ?Mapping for their accepted coding.
  • BreastSubtypeR routes the supplied input to the appropriate, method-specific pre-processing pipeline — see ?Mapping, ?BS_Multi and Methods (Section 2.3) in the paper for details.

5.2 When to use AUTO

  • Use methods = "AUTO" (i.e. BS_Multi(methods = "AUTO", ...)) for exploratory datasets or cohorts of unknown / skewed composition.
  • AUTO applies its documented cohort-selection rules; it does not validate model-wide gene/rule adequacy or clinical applicability.
  • To study a published method, run the corresponding single-method implementation directly (for example, BS_parker()). Clinical validation requires paired clinical-assay data; calling a function alone is insufficient.

5.3 Interpretation

These outputs answer different questions:

Output Meaning in this implementation Limitation
Input coverage Identifier representation and native rule evaluability in processed matrices Does not establish reliability, calibration feasibility or measured-versus-imputed provenance
Entropy Raw Shannon entropy in bits, -sum(p * log2(p)), over available per-method calls Measures disagreement, not predictive confidence or accuracy
Parker Confidence round(1 - p, 2), where p is the Spearman correlation-test p-value between the processed sample and its assigned centroid over matched, complete gene pairs A correlation-test summary, not a calibrated subtype probability
SSP model probabilities Fitted naive Bayes predict(..., type = "raw") values; prob is the assigned class probability and all.probs retains class probabilities Conditional on the fitted model and native handling of available rule inputs; not clinical reliability

Missing calls are excluded from entropy. Zero means agreement among the contributing calls, including a single available call; NA means no calls contributed. Low entropy from a small contributing set is weak evidence of agreement across methods. Five- and four-class summaries use their own calls.

Parker Confidence is missing when a valid test cannot be computed (for example, insufficient or constant matched values). It differs from centroid correlation itself and from AIMS/SSPBC posterior probabilities. None of these quantities substitutes for external predictive or clinical validation.

Earlier affected builds could return false-zero Confidence values after losing centroid gene names during data.frame extraction. The defect is verified in the Bioconductor 3.23 version 1.4.1 and 3.24 version 1.5.7 source archives; GitHub revisions with the same version can differ. Users of those affected builds should recompute Confidence summaries and their downstream uses. Legitimate computed zeros remain possible; this finding alone does not invalidate subtype calls or numerical ROR scores. See the 1.5.8 NEWS entry. AUTO continues to return separate method calls without consensus voting.

6 Shiny app

For users new to R, we offer an intuitive Shiny app for interactive molecular subtyping.

6.1 Launch the local Shiny app

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

If needed, install UI dependencies and re-run:

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

The launcher runs the Shiny application locally in your R session. Uploaded inputs are processed by that local application; remotely hosting Shiny is a separate deployment with different data-handling responsibilities.

What you can do:
- Upload expression, clinical, and feature-annotation tables (clinical lives in colData).
- Run single methods, or run multiple classifiers at once with BS_Multi and AUTO enabled for cohort-aware selection.
- Choose 5-class (incl. Normal-like) or 4-class (AIMS is 5-class only).
- Inspect per-sample concordance (entropy), heatmap and pie summaries.
- Export current Calls-only results, or Full metrics for supported single NC methods. AUTO, AIMS and sspbc provide Calls-only exports. NC Full metrics include ROR-S/ROR-P; enabling Use clinical variables (ROR) with valid numeric TSIZE/NODE adds clinical ROR-C/ROR-PC outputs. AUTO exports calls and entropy with clinical ROR disabled.

6.2 Preprocessing, prediction and downloads

The following workflow describes the current GitHub interface; installed Bioconductor builds can have an older interface.

1. Data and preprocessing. Upload all three tables: expression with feature IDs in the first column and sample IDs as column names, clinical metadata with PatientID, and annotation with probe and ENTREZID. The application aligns overlapping sample and feature identifiers. Choose normalized log2 expression or raw RNA-seq counts; raw-count annotation must also contain gene lengths in Length (bp). Alternatively, use Load example data… to load the bundled example below. Click Preprocess & map. The Input coverage table appears after successful mapping and describes the current processed inputs, including possible imputation. It reports all four input models independently of method selection. Replacing or invalidating mapped inputs hides the table; a coverage-reporting error is informative and does not change prediction state.

2. Analysis settings. Select a method and its settings, then click Run subtyping. Before successful preprocessing, AUTO displays the neutral AUTO: awaiting preprocessing message and guidance to run Step 1. After mapping, valid annotations restore the readiness counts; genuinely blocked annotations retain their error guidance. A failed preprocessing operation still displays its actual error. AUTO applies the implemented receptor and subgroup-size selection rules without guaranteeing complete model-input adequacy or clinical validity.

Results and downloads. Inspect the plots and download current results as tab-separated text (TSV), saved with a .txt extension, using Calls only or Full metrics where supported. AUTO reports separate method predictions and raw Shannon entropy, not consensus calls or calibrated confidence. Research ROR outputs are not clinical Prosigna results.

Replacing any expression, clinical or annotation file, reloading the example, or changing the data type clears the mapped inputs, predictions, plots and downloads. Preprocess and run again. Changes to relevant prediction settings clear old predictions, plots and downloads but retain valid mapped inputs when no remapping is needed. A failed prediction also clears previous results.

Before a current successful prediction exists, the app asks you to run subtyping and offers no active download control. A successful run restores its plots and supported export choices. Unsupported Full metrics exports are identified explicitly. Server-side checks also reject direct requests to old download URLs after invalidation; an intentional HTTP 500 rejection from such a URL does not mean the Shiny session has disconnected.

For Shiny cIHC.itr, the ratio follows target-mode semantics above. Iterations default to 100, with a minimum of 10 and a control step of 10. Any whole number from 10 through 2147483647 is accepted, including 11; the step is not a multiple-of-ten requirement. Missing, nonnumeric, nonfinite, fractional or out-of-range iterations, and missing, nonnumeric, nonfinite or nonpositive ratios, produce an actionable error without disconnecting the session. Correct the setting and rerun without reloading the page or remapping valid inputs. These Shiny input checks do not change the underlying R API or its default settings.

6.3 Example data (for Shiny & scripts)

The Shiny UI provides a Load example data… button that preloads a small demo cohort (expression, clinical, annotation). After loading, click Preprocess & map in Data and preprocessing (Step 1), select settings in Analysis settings (Step 2), then click Run subtyping. Current plots and supported TSV exports appear under Results and downloads.

The Shiny expression file contains the same 356 features and 102 samples as OSLO2EMIT0obj$se_obj, with log2(FPKM + 1) expression agreeing at text serialization precision. The expression values are not binary-identical. The Shiny annotation table covers 19,675 genes, including all 356 packaged features with matching annotations. Its clinical table has 12 fields rather than the packaged object’s six; sample identifiers align, but PR labels use Negative/Positive instead of PR-/PR+. The full metadata tables therefore differ. Numerical agreement does not establish the exact historical generating or export script.

Programmatic access to the same Shiny files:

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")
file.exists(gex)
file.exists(clin)
file.exists(anno)

7 Limitations

BreastSubtypeR harmonizes many published, signature-based classifiers but has known limitations:

8 Appendix

8.2 References

  • Yang Q., Hartman J., Sifakis E.G. (2025). BreastSubtypeR: a unified R/Bioconductor package for intrinsic molecular subtyping in breast cancer research. NAR Genomics and Bioinformatics, 7(4):lqaf131. https://doi.org/10.1093/nargab/lqaf131

  • Parker JS, Mullins M, Cheang MCU, Leung S, Voduc D, Vickery T, et al. (2009). Supervised risk predictor of breast cancer based on intrinsic subtypes. J Clin Oncol, 27(8):1160–1167. https://doi.org/10.1200/JCO.2008.18.1370

  • Gendoo DMA, Ratanasirigulchai N, Schröder MS, Pare L, Parker JS, Prat A, Haibe-Kains B. (2016). Genefu: an R/Bioconductor package for computation of gene expression-based signatures in breast cancer. Bioinformatics, 32(7):1097–1099. https://doi.org/10.1093/bioinformatics/btv693

  • Ciriello G, Gatza ML, Beck AH, Wilkerson MD, Rhie SK, Pastore A, et al. (2015). Comprehensive molecular portraits of invasive lobular breast cancer. Cell, 163(2):506–519. https://doi.org/10.1016/j.cell.2015.09.033

  • Curtis C, Shah SP, Chin S-F, Turashvili G, Rueda OM, Dunning MJ, et al. (2012). The genomic and transcriptomic architecture of 2,000 breast tumors reveals novel subgroups. Nature, 486:346–352. https://doi.org/10.1038/nature10983

  • Raj-Kumar PK, Liu J, Hooke JA, Kovatich AJ, Kvecher L, Shriver CD, Hu H. (2019). PCA-PAM50 improves consistency between breast cancer intrinsic and clinical subtyping reclassifying a subset of luminal A tumors as luminal B. Sci Rep, 9:7956. https://doi.org/10.1038/s41598-019-44339-4

  • Zhao X, Rødland EA, Tibshirani R, Plevritis S. (2015). Molecular subtyping for clinically defined breast cancer subgroups. Breast Cancer Res, 17:29. https://doi.org/10.1186/s13058-015-0520-4

  • Fernandez-Martinez A, Krop IE, Hillman DW, et al. (2020). Survival, Pathologic Response, and Genomics in CALGB 40601 (Alliance), a Neoadjuvant Phase III Trial of Paclitaxel-Trastuzumab With or Without Lapatinib in HER2-Positive Breast Cancer. J Clin Oncol, 38(35):4184-4193. https://doi.org/10.1200/JCO.20.01276

  • Fernandez-Martinez A, Rediti M, Tang G, et al. (2024). Tumor Intrinsic Subtypes and Gene Expression Signatures in Early-Stage ERBB2/HER2-Positive Breast Cancer: A Pooled Analysis of CALGB 40601, NeoALTTO, and NSABP B-41 Trials. JAMA Oncol, 10(5):603-611. https://doi.org/10.1001/jamaoncol.2023.7304

  • Paquet ER, Hallett MT. (2015). Absolute assignment of breast cancer intrinsic molecular subtype. J Natl Cancer Inst, 107(1):dju357. https://doi.org/10.1093/jnci/dju357

  • Staaf J, Hakkinen J, Hegardt C, Saal LH, Kimbung S, Hedenfalk I, et al. (2022). RNA sequencing-based single sample predictors of molecular subtype and risk of recurrence for clinical assessment of early-stage breast cancer. npj Breast Cancer, 8:94. https://doi.org/10.1038/s41523-022-00465-3

  • Vallon-Christersson J (2023). RNA Sequencing-Based Single Sample Predictors of Molecular Subtype and Risk of Recurrence for Clinical Assessment of Early-Stage Breast Cancer. Mendeley Data, V3. https://doi.org/10.17632/yzxtxn4nmd.3

8.3 Session information

sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.5 LTS
#> 
#> Matrix products: default
#> BLAS:   /home/biocbuild/bbs-3.24-bioc/R/lib/libRblas.so 
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_GB              LC_COLLATE=C              
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: America/New_York
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] BreastSubtypeR_1.5.9 BiocStyle_2.41.0    
#> 
#> loaded via a namespace (and not attached):
#>  [1] SummarizedExperiment_1.43.0 gtable_0.3.6               
#>  [3] impute_1.87.0               circlize_0.4.18            
#>  [5] shape_1.4.6.1               rjson_0.2.23               
#>  [7] xfun_0.62                   bslib_0.12.0               
#>  [9] ggplot2_4.0.3               GlobalOptions_0.1.4        
#> [11] Biobase_2.73.2              lattice_0.23-1             
#> [13] Cairo_1.7-0                 vctrs_0.7.3                
#> [15] tools_4.6.1                 generics_0.1.4             
#> [17] stats4_4.6.1                parallel_4.6.1             
#> [19] tibble_3.3.1                proxy_0.4-29               
#> [21] cluster_2.1.8.3             pkgconfig_2.0.3            
#> [23] Matrix_1.7-6                data.table_1.18.6.1        
#> [25] RColorBrewer_1.1-3          S7_0.2.2                   
#> [27] S4Vectors_0.51.10           lifecycle_1.0.5            
#> [29] farver_2.1.2                compiler_4.6.1             
#> [31] stringr_1.6.0               tinytex_0.61               
#> [33] Seqinfo_1.3.2               codetools_0.2-20           
#> [35] ComplexHeatmap_2.29.0       clue_0.3-68                
#> [37] htmltools_0.5.9             class_7.3-24               
#> [39] sass_0.4.10                 yaml_2.3.12                
#> [41] pillar_1.11.1               crayon_1.5.3               
#> [43] jquerylib_0.1.4             cachem_1.1.0               
#> [45] DelayedArray_0.39.8         magick_2.9.1               
#> [47] iterators_1.0.14            abind_1.4-8                
#> [49] foreach_1.5.2               tidyselect_1.2.1           
#> [51] digest_0.6.39               stringi_1.8.9              
#> [53] dplyr_1.2.1                 bookdown_0.48              
#> [55] fastmap_1.2.0               grid_4.6.1                 
#> [57] colorspace_2.1-4            cli_3.6.6                  
#> [59] SparseArray_1.13.4          magrittr_2.0.5             
#> [61] S4Arrays_1.13.2             dichromat_2.0-1            
#> [63] e1071_1.7-17                withr_3.0.3                
#> [65] scales_1.4.0                rmarkdown_2.32             
#> [67] XVector_0.53.0              matrixStats_1.5.0          
#> [69] otel_0.2.0                  png_0.1-9                  
#> [71] GetoptLong_1.1.1            evaluate_1.0.5             
#> [73] knitr_1.52                  GenomicRanges_1.65.4       
#> [75] IRanges_2.47.5              doParallel_1.0.17          
#> [77] rlang_1.3.0                 Rcpp_1.1.2                 
#> [79] glue_1.8.1                  BiocManager_1.30.27        
#> [81] BiocGenerics_0.59.12        jsonlite_2.0.0             
#> [83] R6_2.6.1                    MatrixGenerics_1.25.0