NMFprofileR is an R package for comprehensive multi-rank Non-negative Matrix Factorization (NMF) analysis of transcriptomic data. It provides automated rank estimation, factor-specific gene assignment, gene set enrichment analysis, and publication-quality plots for consolidated summary and consensus maps.
- Multi-rank NMF with reproducible results (
brunet,lee, and others), with an optional parallel backend that still reproduces the seeded result. - Composable, exported pipeline stages returning results in memory, and
an
nmf_profileresult object. - Per-factor basis gene assignment (argmax or Kim-Park specificity) plus specificity-scored marker genes.
- Batch processing across many cohorts (
run_nmf_batch()) — resumable and consolidated into one tagged summary. - Cross-run factor alignment (
align_factors()), projection of new samples onto a learned factorization (nmf_project()), and factor stability assessment by subsampling (nmf_stability()). - Automated generation of rank survey/diagnostics plots, consensus maps, factor correspondence heatmaps, and consolidated summary metrics; themeable plots.
- User-defined gene backgrounds for enrichment, with an oversized-query guard, automatic retry, and an optional on-disk result cache.
- Reproducibility: run manifest, single-object result bundle, g:Profiler database version, and session info.
Install directly from GitHub using devtools. NMFprofileR depends on the
Bioconductor packages ComplexHeatmap and circlize, so make the Bioconductor
repositories available first (otherwise the install fails to resolve them):
# install.packages(c("devtools", "BiocManager"))
setRepositories(ind = c(1, 2)) # enable CRAN + Bioconductor
# or: options(repos = BiocManager::repositories())
devtools::install_github("MilesGithub/NMFprofileR")
library(NMFprofileR)
# Load example expression data (genes x samples)
data("example_expression_data")
# Run the NMFprofileR pipeline
result <- NMFprofileR(
expression_data = example_expression_data,
nmf_rank = 2:5,
output_prefix = "results/NMF",
nmf_method = "brunet",
nmf_nrun = 20,
gprofiler_organism = "hsapiens",
gprofiler_sources = c("GO:BP","GO:MF","GO:CC","REAC","TF"),
gprofiler_cutoff = 0.05
)
NMFprofileR() returns an nmf_profile object that carries the results in
memory (in addition to writing them to disk):
result # compact overview (print method)
summary(result) # consolidated per-factor metrics across ranks
result$fits[["3"]] # fitted NMF object for k = 3
result$basis_genes[["3"]] # gene -> dominant factor table
result$marker_genes[["3"]] # factor-specific marker genes
Set write_files = FALSE to compute entirely in memory without creating files.
The pipeline stages are also exported for composable use:
nmf_preprocess(), nmf_fit(), nmf_basis_genes(), nmf_marker_genes(),
nmf_sample_assignments(), nmf_enrichment(), and nmf_rank_diagnostics().
Run many cohorts and consolidate the results into one summary tagged by cohort:
batch <- run_nmf_batch(
list(cohort_A = m1, cohort_B = m2), # named list of expression matrices
output_dir = "batch_out",
nmf_rank = 2:4
)
batch$consolidated
The batch driver is resilient (a failing cohort is recorded, not fatal) and resumable (already-completed cohorts are skipped). See the Batch analysis vignette.
align_factors(list(run_a = fit_a, run_b = fit_b)) # match factors across runs
nmf_project(fit, newdata = m_new) # score new samples onto W
nmf_stability(m, rank = 3, nboot = 30) # factor reproducibility
With output_prefix = "results/NMF" the pipeline writes to
results/NMF_Results/:
NMF_Core_Objects/— fitted NMF objects per rank (.rds).Basis_Genes/— per-factor gene assignments and marker genes.Enrichment_Results/— per-factor and combined enrichment tables.Sample_Assignments/— sample-to-factor assignments with silhouette widths.Plots/— heatmaps, consensus/diagnostic maps, UMAP, and enrichment plots.Summaries/— consolidated summary, run manifest, session info, and amanifest.tsvlisting every file produced.<prefix>_nmf_profile.rds— the wholenmf_profileresult as a single object.
- Rank Survey Plot – metrics across tested ranks.
- Consensus Map – reproducibility of factorization.
- Factor Correspondence Heatmap – identifies similar factors across ranks.
- Consolidated Summary Heatmap – combined factor-level metrics for all ranks.
Miles Mee, 2025. NMFprofileR: Comprehensive multi-rank NMF analysis and enrichment in R. GitHub repository: https://github.com/MilesGithub/NMFprofileR
Also cite underlying methods:
- Gaujoux, R., & Seoighe, C. (2010). A flexible R package for nonnegative matrix factorization. BMC Bioinformatics, 11, 367.
- Raudvere, U., Kolberg, L., Kuzmin, I., Arak, T., Adler, P., Peterson, H., & Vilo, J. (2019). g:Profiler: a web server for functional enrichment analysis and conversions of gene lists. Nucleic Acids Research, 47(W1), W191–W198.
MIT License — see LICENSE.
Open an issue on GitHub or contact Miles Mee at miles.william.mee@gmail.com.