--- title: "Getting Started with RcppML" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Getting Started with RcppML} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set( dpi = 72, fig.retina = 1, # keep the built vignettes small (CRAN size limit) collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 4.5, message = FALSE, warning = FALSE ) library(RcppML) # CRAN allows at most two cores options(RcppML.threads = 2) # Chunks run only when NOT_CRAN is "true" (set when the package tarball and # the pkgdown site are built) and the suggested packages are installed. # CRAN's checks then rebuild the text without refitting the models. run_chunks <- identical(Sys.getenv("NOT_CRAN"), "true") && all(vapply(c("ggplot2"), requireNamespace, logical(1), quietly = TRUE)) knitr::opts_chunk$set(eval = run_chunks) if (run_chunks) { library(ggplot2) } ``` ## What Is RcppML? **RcppML** decomposes a nonnegative matrix $A$ into low-rank factors $A \approx W \cdot \text{diag}(d) \cdot H$, where $W$ captures features, $H$ captures sample loadings, and $d$ gives per-factor scale. Built on Rcpp and Eigen with OpenMP parallelism and optional CUDA GPU support, RcppML is designed for large sparse matrices common in genomics, recommender systems, and image analysis. Key capabilities include: - **NMF** with coordinate-descent and Cholesky NNLS solvers - **SVD / PCA** with optional non-negativity and L1 constraints - **Cross-validation** via speckled holdout for automatic rank selection - **Distribution-aware losses**: Gaussian, Poisson, Generalized Poisson, Negative Binomial, Gamma, Inverse Gaussian, Tweedie — plus zero-inflation - **Regularization**: L1, L2, L21, angular, graph Laplacian, upper bounds - **Consensus clustering** and divisive clustering (`dclust`) - **Composable factorization graphs** via `factor_net()` - **StreamPress** `.spz` format for out-of-core computation - **GPU acceleration** via CUDA ## Installation Install from CRAN: ```r install.packages("RcppML") ``` Or install the development version: ```r remotes::install_github("zdebruine/RcppML") ``` For GPU support, see the [GPU Acceleration](gpu-acceleration.html) vignette. ## Quick NMF Demo Factor the Hawaiian birds species-count matrix (183 species × 1,183 grid cells) into 10 components: ```{r nmf-demo} data(hawaiibirds) model <- nmf(hawaiibirds, k = 10, seed = 42, tol = 1e-5, maxit = 100) ``` ```{r nmf-summary, echo = FALSE} knitr::kable(data.frame( Rows = nrow(hawaiibirds), Columns = ncol(hawaiibirds), Rank = 10, `Reconstruction MSE` = format(evaluate(model, hawaiibirds), digits = 3, scientific = TRUE), Iterations = model@misc$iter, `Runtime (sec)` = round(as.numeric(model@misc$runtime, units = "secs"), 2), check.names = FALSE ), caption = "NMF model summary") ``` Each of the 10 factors captures a distinct pattern of bird species co-occurrence across Hawaiian survey sites. ```{r nmf-convergence, echo = FALSE, fig.height = 3.5} # Show convergence of a quick NMF run track_loss <- function() { losses <- numeric(0) list( callback = function(iter, train_loss, test_loss) { losses[iter] <<- train_loss }, get = function() losses ) } tracker <- track_loss() invisible(nmf(hawaiibirds, k = 10, seed = 42, tol = 1e-6, maxit = 100, on_iteration = tracker$callback, resource = "cpu")) loss_df <- data.frame(Iteration = seq_along(tracker$get()), Loss = tracker$get()) ggplot(loss_df, aes(x = Iteration, y = Loss)) + geom_line(color = "steelblue", linewidth = 0.8) + geom_point(color = "steelblue", size = 1.5) + scale_y_log10() + labs(title = "NMF Convergence (Hawaiian Birds, k = 10)", x = "Iteration", y = "Reconstruction Loss (log)") + theme_minimal() ``` ## Quick SVD Demo We can also decompose the same data with SVD, which captures directions of maximum variance rather than additive nonneg parts: ```{r svd-demo} data(hawaiibirds) sv <- svd(hawaiibirds, k = 10) ``` ```{r svd-scree, echo = FALSE, fig.height = 3.5} ve <- variance_explained(sv) ve_df <- data.frame( Component = 1:10, Additional = ve * 100 ) ggplot(ve_df, aes(x = Component, y = Additional)) + geom_line(color = "steelblue", linewidth = 0.8) + geom_point(color = "steelblue", size = 2.5) + scale_x_continuous(breaks = 1:10) + labs(title = "Incremental Variance Explained: Hawaiian Birds SVD", x = "Component", y = "Additional % Variance Explained") + theme_minimal() ``` The first component captures the dominant species-composition gradient, and each subsequent component adds progressively less explanatory power — the hallmark of effective dimensionality reduction. For PCA (centered and optionally scaled SVD), use the `pca()` convenience wrapper: ```{r pca-demo} pc <- pca(hawaiibirds, k = 5, seed = 42) # center = TRUE by default # Equivalent to: svd(hawaiibirds, k = 5, center = TRUE) ``` PCA centers the data before decomposition, so the first component captures the dominant direction of variation rather than the overall mean level. Use `scale = TRUE` for data where features have different units or widely varying magnitude. ## Quick Cross-Validation Demo Use speckled holdout cross-validation to find the best rank for the AML data: ```{r cv-demo} data(aml) cv <- nmf(aml, k = c(2, 4, 6, 8, 10), test_fraction = 0.2, seed = 42) ``` ```{r cv-plot, echo = FALSE, fig.height = 3.5} plot(cv, show_train = TRUE) ``` Training loss always decreases with rank, but test loss reveals where the model begins to overfit. The test-loss minimum identifies the optimal number of factors. ## Built-in Datasets RcppML ships seven datasets spanning diverse domains: ```{r dataset-table, echo = FALSE} ds <- data.frame( Dataset = c("`aml`", "`golub`", "`hawaiibirds`", "`movielens`", "`olivetti`", "`digits`", "`pbmc3k`"), Dimensions = c("824 × 135", "38 × 5,000", "183 × 1,183", "3,867 × 610", "400 × 4,096", "1,797 × 64", "13,714 × 2,638"), Type = c("Dense matrix", "Sparse (dgCMatrix)", "Sparse (dgCMatrix)", "Sparse (dgCMatrix)", "Sparse (dgCMatrix)", "Sparse (dgCMatrix)", "SPZ raw bytes"), Domain = c("DNA methylation (AML)", "Gene expression (leukemia)", "Bird species counts", "Movie ratings", "Face images (Olivetti)", "Handwritten digit images", "Single-cell RNA-seq (PBMCs)"), check.names = FALSE ) knitr::kable(ds, caption = "Shipped datasets") ``` The `pbmc3k` dataset is stored as StreamPress-compressed raw bytes containing the full **13,714 genes × 2,638 cells** from the 10x Genomics PBMC 3k dataset, with 9 Seurat-annotated cell types embedded as column metadata. Decompress it with `st_read()` and access annotations via `st_read_var()` — see the [StreamPress](streampress.html) vignette. ## Where to Go Next ### Core Techniques - [NMF Fundamentals](nmf-fundamentals.html) — Solvers, diagonal scaling, convergence, and basic workflow - [SVD and PCA](svd-pca.html) — Truncated SVD, PCA, non-negative and sparse variants - [Cross-Validation](cross-validation.html) — Speckled holdout for automatic rank selection - [Statistical Distributions](distributions.html) — Distribution-aware losses and zero-inflation handling - [Regularization and Constraints](regularization.html) — L1, L2, L21, angular penalties, and upper bounds ### Advanced Methods - [Clustering, Consensus, and Classification](clustering.html) — Divisive clustering, consensus NMF, and sample classification - [Factorization Graphs](factor-graphs.html) — Multi-modal and guided factorization via `factor_net()` ### Infrastructure - [StreamPress](streampress.html) — High-performance sparse matrix compression and out-of-core NMF - [GPU Acceleration](gpu-acceleration.html) — CUDA-based GPU support for large-scale factorization