Package: RcppML 1.0.0

RcppML: Fast Non-Negative Matrix Factorization and Divisive Clustering

High-performance non-negative matrix factorization (NMF), singular value decomposition (SVD), and divisive clustering for large sparse and dense matrices. Implements alternating least squares with coordinate descent and Cholesky NNLS solvers, diagonal scaling for interpretable factors, cross-validation for automatic rank selection, multiple distribution-based losses (Gaussian, Poisson, Generalized Poisson, Negative Binomial, Gamma, Inverse Gaussian, Tweedie) via iteratively reweighted least squares, regularization (L1, L2, L21, angular, graph Laplacian), and optional GPU acceleration via CUDA. Includes divisive clustering via recursive rank-2 factorization, consensus clustering, and the StreamPress compressed sparse matrix format. Methods are described in DeBruine, Melcher, and Triche (2021) <doi:10.1101/2021.09.01.458620>.

Authors:Zachary DeBruine [aut, cre], Markus Buehren [ctb, cph], Cong Ma [ctb, cph], Justin Silverman [ctb, cph]

RcppML_1.0.0.tar.gz
RcppML_1.0.0.zip(r-4.7-x86_64)RcppML_1.0.0.zip(r-4.7-arm64)RcppML_1.0.0.zip(r-4.6-x86_64)RcppML_1.0.0.zip(r-4.6-arm64)RcppML_1.0.0.zip(r-4.5-x86_64)
RcppML_1.0.0.tgz(r-4.6-x86_64)RcppML_1.0.0.tgz(r-4.6-arm64)RcppML_1.0.0.tgz(r-4.5-x86_64)RcppML_1.0.0.tgz(r-4.5-arm64)
RcppML_1.0.0.tar.gz(r-4.7-arm64)RcppML_1.0.0.tar.gz(r-4.7-x86_64)RcppML_1.0.0.tar.gz(r-4.6-arm64)RcppML_1.0.0.tar.gz(r-4.6-x86_64)
RcppML_1.0.0.tgz(r-4.6-emscripten)
manual.pdf |manual.html✨
DESCRIPTION
card.svg |card.png
RcppML/json (API)

# Install 'RcppML' in R:
install.packages('RcppML', repos = c('https://zdebruine.r-universe.dev', 'https://cloud.r-project.org'))

Bug tracker:https://github.com/zdebruine/rcppml/issues

Uses libs:
  • c++– GNU Standard C++ Library v3
  • openmp– GCC OpenMP (GOMP) support library
Datasets:
  • aml - Acute Myelogenous Leukemia (AML) Dataset
  • digits - MNIST Digits Dataset
  • golub - Golub ALL-AML Dataset
  • hawaiibirds - Hawaii Bird Species Frequency Dataset
  • movielens - MovieLens Dataset
  • olivetti - Olivetti Faces Dataset
  • pbmc3k - PBMC 3k Single-Cell RNA-seq Dataset

On CRAN:

Conda:

clusteringmatrix-factorizationnmfrcpprcppeigensparse-matrixcppopenmp

11.49 score 124 stars 64 packages 24k downloads 78 exports 4 dependencies

Last updated from:bd51784f97. Checks:14 OK, 1 ERROR. Indexed: yes.

TargetResultTimeFilesSyslog
linux-devel-arm64OK515
linux-devel-x86_64OK511
source / vignettesOK727
linux-release-arm64OK518
linux-release-x86_64OK411
macos-release-arm64OK349
macos-release-x86_64OK615
macos-oldrel-arm64OK336
macos-oldrel-x86_64OK799
windows-devel-arm64ERROR540
windows-devel-x86_64OK503
windows-release-arm64OK622
windows-release-x86_64OK402
windows-oldrel-x86_64OK308
wasm-releaseOK225

Exports:alignassessauto_nmf_distributionbipartiteMatchbipartitionbiplotclassify_embeddingclassify_logisticclassify_rfcoercecompare_nmfcompute_targetconsensus_nmfcosinecross_validate_graphcrossValidatedclustdiagnose_dispersiondiagnose_zero_inflationevaluateexport_logfactor_addfactor_concatfactor_conditionfactor_configfactor_inputfactor_netfactor_sharedfitgpu_availablegpu_infogpu_statusHheadinstall_gpumsenmfnmf_layernnlspcapredictprojectreconstructrefinescore_test_distributionshowsimulateNMFsimulateSwimmersortsparsityst_add_transposest_chunk_rangesst_filter_colsst_filter_rowsst_free_gpust_infost_map_chunksst_obs_indicesst_readst_read_densest_read_gpust_read_obsst_read_varst_slicest_slice_colsst_slice_rowsst_writest_write_densest_write_listsubsetsummarysvdsvd_layerttailtraining_loggervariance_explainedW

Dependencies:latticeMatrixRcppRcppEigen

Clustering, Consensus, and Classification
Why NMF for Clustering? | API Reference | Consensus NMF | Divisive Clustering | Factor Matching | Classification from Embeddings | Theory | Example 1: Cancer Subtype Discovery (Golub Leukemia) | Going Deeper: k = 5 Reveals Substructure | Example 2: Hierarchical Clustering with dclust (AML Methylation) | Splitting Hierarchy | Example 3: Classification from NMF Embeddings (AML Subtypes) | UMAP of Factor Embeddings | What's Next

Last update: 2026-11-13
Started: 2026-03-09

Cross-Validation for NMF Rank Selection
Motivation | API Reference | Cross-Validation via nmf() | mask Semantics | Theory | Speckled Holdout | Choosing $k$ | Overfitting Dynamics | Multiple Replicates | Worked Examples | Example 1: Recovering True Rank from Synthetic Data | Example 2: Overfitting Dynamics (Epoch Plot) | Example 3: Recommendation Data with mask = "zeros" | Example 4: Ecological Survey Data | Example 5: Effect of test_fraction | Next Steps

Last update: 2026-11-13
Started: 2026-03-08

Factorization Graphs
Why Factorization Graphs? | Building Blocks | Example 1: Graph ≡ Plain NMF | Example 2: Multi-Modal Shared Factorization | Bird Communities + Geography | Comparison: Shared vs. Separate Factorizations | Example 3: Deep NMF | Coarse → Fine in AML | The Connecting Matrix | Example 4: Target Regularization in Graphs | Example 5: Cross-Validation over Graph Parameters | Composable Architectures | Summary | What's Next

Last update: 2026-11-13
Started: 2026-03-09

Getting Started with RcppML
What Is RcppML? | Installation | Quick NMF Demo | Quick SVD Demo | Quick Cross-Validation Demo | Built-in Datasets | Where to Go Next | Core Techniques | Advanced Methods | Infrastructure

Last update: 2026-11-13
Started: 2026-03-08

GPU-Accelerated Computing
Motivation | Quick Start | Benchmarks on Real Data | Data Preparation | Results | Key Observations | Why GPU Gains Are Larger for CV and IRLS | API Reference | Resource Override Priority | GPU-Supported Features | GPU-Direct StreamPress Reading | Building the GPU Library | Requirements | Building from a source checkout | Library Search Path | GPU Memory | HPC / SLURM Usage | Troubleshooting | Key Takeaways

Last update: 2026-11-13
Started: 2026-03-08

Guided NMF: Label-Informed Factorization
Motivation | Setup: Hawaii Birds Dataset | Step 1: Baseline NMF | Step 2: Post-Hoc Refinement | Step 3: In-NMF Target Regularization | Comparison | Visualizing the Embeddings | UMAP Projections | Factor Composition by Island | Guidance on Choosing a Method | Removing Label-Specific Information (Batch Removal) | Comparing Enrichment vs Removal | UMAP: Enrichment vs Removal | Factor Composition: Enrichment vs Removal | Integration with Factor Graphs

Last update: 2026-11-13
Started: 2026-03-14

NMF Fundamentals
Motivation | API Reference | The nmf() Function | Factor Extraction and Inspection | Reconstruction and Loss | Model Comparison | Convergence Control | Theory and Algorithms | Objective | Alternating NNLS | Initialization | Non-uniqueness | Projective NMF | Worked Examples | Example 1: Recovering Known Factors from Synthetic Data | Example 2: Choosing Rank with Cross-Validation | Per-Iteration Convergence: Underfitting vs. Overfitting | Example 3: Methylation Factor Interpretation (AML Data) | Example 4: Convergence and Initialization Comparison | Next Steps

Last update: 2026-11-13
Started: 2026-03-10

Regularization and Constraints
Why Regularize? | API Reference | Sparsity Penalties | Structural Penalties | Box Constraints | Parameter Conventions | Theory | Example 1: L1 Sparsity Spectrum on Swimmers | Example 2: Angular Decorrelation on Face Data | Angular Penalty Sweep | L1 for Parts-Based Decomposition | Example 3: Graph Laplacian for Spatial Smoothness | What's Next

Last update: 2026-11-13
Started: 2026-03-09

Statistical Distributions for NMF
Motivation | API Reference | Distribution Selection in nmf() | Dispersion Control | Zero-Inflation | Diagnostic Functions | Theory | Variance-Mean Relationship | IRLS | Dispersion | Recommended Workflow | Information Criteria | Worked Examples | Example 1: Distribution Auto-Selection on Count Data | Example 2: Score Test Diagnostics | Example 3: Zero-Inflation Detection and Modeling | Next Steps

Last update: 2026-11-13
Started: 2026-03-10

StreamPress: High-Performance Sparse Matrix I/O
Motivation | API Reference | Writing Sparse Matrices | Reading Sparse Matrices | Inspecting Files | Dense Matrix Support | Theory | Columnar Storage | Compression Pipeline | Precision Hierarchy | Worked Examples | Example 1: Sparse Matrix Round-Trip | Example 2: Dense Matrix Round-Trip | Example 3: Precision Mode Comparison | Example 4: Real-World Dataset — pbmc3k Single-Cell RNA-seq | Example 5: Out-of-Core Streaming NMF (Conceptual) | When StreamPress Wins | Why SPZ Beats Raw CSC Even at 1 Thread | Parallel Scaling | The I/O Bandwidth Picture | Summary: When to Use SPZ | Thread Guidance | Key Takeaways

Last update: 2026-11-13
Started: 2026-03-09

SVD and PCA
Motivation | API Reference | svd(A, k, ...) | pca(A, k, ...) | Sparse PCA and Nonneg PCA | Inspection Methods | Theory | SVD Decomposition | PCA as Centered SVD | Sparse and Nonneg PCA | SVD Algorithms in RcppML | Algorithm Summary | Deflation (Sequential Rank-1 ALS) | Krylov (KSPR — Krylov-Seeded Projected Refinement) | Lanczos (Golub-Kahan Bidiagonalization) | IRLBA (Implicitly Restarted Lanczos Bidiagonalization) | Randomized SVD (Stochastic Projection) | Automatic Method Selection | Runtime Comparison | Tuning Hyperparameters | Worked Examples | Example 1: Eigenfaces from Olivetti | Example 2: Sparse PCA for Interpretable Loadings | Example 3: Nonneg SVD vs NMF | Example 4: Method Choice for Constrained Problems | Next Steps

Last update: 2026-11-13
Started: 2026-03-10

Readme and manuals

Help Manual

Help pageTopics
RcppML: Fast Non-Negative Matrix Factorization and Divisive ClusteringRcppML-package RcppML
Access layer results by name$.factor_net_result
Align two NMF modelsalign align,nmf-method
Acute Myelogenous Leukemia (AML) Datasetaml
Convert assessment results to a one-row data frameas.data.frame.nmf_assessment
Convert training log to data.frameas.data.frame.training_logger
Assess Embedding Qualityassess
Auto-select NMF distributionauto_nmf_distribution
Bipartite graph matchingbipartiteMatch
Bipartition a sample setbipartition
Biplot for NMF factorsbiplot,nmf-method
Evaluate classification performance of factor embeddingsclassify_embedding
Logistic regression classifier for factor embeddingsclassify_logistic
Random forest classifier for factor embeddingsclassify_rf
Compare Multiple NMF Modelscompare_nmf
Compute a Target Matrix for Guided NMFcompute_target
Consensus Clustering for NMFconsensus_nmf
Cosine similaritycosine
Cross-validate a factorization networkcross_validate_graph
Divisive clusteringdclust
Diagnose dispersion modediagnose_dispersion
Diagnose zero inflationdiagnose_zero_inflation
MNIST Digits Datasetdigits
Evaluate an NMF modelevaluate evaluate,nmf-method
Export training log to CSVexport_log
Element-wise H addition (skip/residual connection)factor_add
Concatenate H factors from branches (row-bind)factor_concat
Concatenate conditioning metadata to a layer's Hfactor_condition
Global configuration for a factorization networkfactor_config
Create an input node for a factorization networkfactor_input
Compile a factorization networkfactor_net
Shared factorization across multiple inputs (multi-modal)factor_shared
Fit a factorization networkfit fit.factor_net
Golub ALL-AML Dataset (Brunet et al. 2004)golub
Check if GPU acceleration is availablegpu_available
Get GPU device informationgpu_info
Methods for gpu_sparse_matrix objectsdim.gpu_sparse_matrix gpu_sparse_matrix-methods ncol.gpu_sparse_matrix nrow.gpu_sparse_matrix print.gpu_sparse_matrix
Report the state of GPU supportgpu_status
Hawaii Bird Species Frequency Datasethawaiibirds
Build and install the GPU libraryinstall_gpu
MovieLens Datasetmovielens
Non-negative matrix factorizationnmf
Create an NMF factorization layernmf_layer
nmf S4 Classnmf-class
Non-negative Least Squares Projectionnnls
Olivetti Faces Datasetolivetti
PBMC 3k Single-Cell RNA-seq Dataset (StreamPress Compressed)pbmc3k
PCA (centered SVD)pca
Plot Consensus Matrix Heatmapplot.consensus_nmf
Plot divisive clustering hierarchyplot.dclust
Plot NMF Training History and Diagnosticsplot.nmf
Plot Cross-Validation Resultsplot.nmfCrossValidate
Plot training logplot.training_logger
Project new data through a trained factor networkpredict.factor_net_result
Print a factor_netprint.factor_net
Print a factor_net_cv resultprint.factor_net_cv
Print a factor_net_resultprint.factor_net_result
Print a classifier evaluation resultprint.fn_classifier_eval
Print an fn_factor_configprint.fn_factor_config
Print an fn_global_configprint.fn_global_config
Print an fn_nodeprint.fn_node
Print method for nmf_assessment objectsprint.nmf_assessment
Print a training logprint.training_logger
Refine an NMF Model Using Label-Guided Correctionrefine
Score-test distribution diagnosticscore_test_distribution
Simulate an NMF datasetsimulateNMF
Simulate Swimmer DatasetsimulateSwimmer
Compute the sparsity of each NMF factorsparsity sparsity,nmf-method
Add Transpose Section to an Existing StreamPress Filest_add_transpose
Get Column Ranges for Each Chunk in a StreamPress Filest_chunk_ranges
Slice Columns Matching Variable Metadata Filterst_filter_cols
Slice Rows Matching Observation Metadata Filterst_filter_rows
Free GPU-Resident Sparse Matrixst_free_gpu
Get metadata from a StreamPress filest_info
Apply a Function to Every Chunk in a StreamPress Filest_map_chunks
Get Row Indices Matching Observation Metadata Filterst_obs_indices
Read a StreamPress file into a dgCMatrixst_read
Read a Dense Matrix from StreamPress v3 Formatst_read_dense
Read StreamPress File Directly to GPU Memoryst_read_gpu
Read Observation (Row) Metadata from a StreamPress Filest_read_obs
Read Variable (Column) Metadata from a StreamPress Filest_read_var
Slice Rows and/or Columns from a StreamPress Filest_slice
Slice Columns from a StreamPress Filest_slice_cols
Slice Rows from a StreamPress Filest_slice_rows
Write a sparse matrix to a StreamPress filest_write
Write a Dense Matrix to StreamPress v3 Formatst_write_dense
Write a List of Matrices as a Single StreamPress Filest_write_list
StreamPress I/O: Read, Write, and Inspect Compressed Matricesstreampress
nmf class methods$,nmf-method coerce,nmf,list-method dim,nmf-method dimnames,nmf-method head,nmf-method head.nmf predict,nmf-method prod,nmf-method show,nmf-method sort,nmf-method subset,nmf-method t,nmf-method tail,nmf-method tail.nmf [,nmf,ANY,ANY,ANY-method [[,nmf-method
Summarize NMF factorsplot.nmfSummary summary,nmf-method
Summary for Consensus NMFsummary.consensus_nmf
Summarize a factor_net_resultsummary.factor_net_result
Summarize a classifier evaluation resultsummary.fn_classifier_eval
Truncated SVD / PCA with constraints and regularizationsvd
Create an SVD/PCA factorization layersvd_layer
svd S4 Classdim,svd-method head,svd-method head.svd predict,svd-method reconstruct reconstruct,svd-method show,svd-method svd-class tail,svd-method tail.svd variance_explained variance_explained,svd-method [,svd,ANY,ANY,ANY-method
Create a training logger for factor network fittingtraining_logger
Per-factor configuration for factorization layersH W