Skip to content

NEWS.md

Latest commit

 

History

History
117 lines (97 loc) · 5.66 KB

NEWS.md

File metadata and controls

117 lines (97 loc) · 5.66 KB
Raw

RcppML (development version)

Bug fixes

  • svd()/pca() with method = "deflation" and nonneg/L1/upper_bound now use projection (generalized) deflation for constrained factors, as in nsprcomp: each factor is fit to the data with earlier constrained directions projected out. Hotelling deflation left energy along earlier constrained factors, so at larger k later factors repeated earlier ones (e.g. pbmc3k, k = 16: 16 factors spanned only 8 directions). Unconstrained SVD/PCA is unchanged. CPU path only; the GPU deflation path is not yet updated.
  • svd()/pca() with method = "deflation": factors with projection constraints (nonneg, L1, upper_bound) no longer go through the post-factor Gram-Schmidt step, which re-introduced negative entries and removed L1 zeros on every component after the first. Constrained factors are now returned as fitted (non-negative/sparse, not mutually orthogonal); unconstrained SVD/PCA is unchanged. Applies to the CPU and GPU deflation paths.
  • Constrained factors after the first now start from a non-negative random vector instead of the orthogonalized power-step warm start, which could collapse to zero after projection.
  • method = "auto" now selects "deflation" whenever nonneg, L1, or upper_bound is set (previously "krylov" for k >= 8), and requesting method = "krylov" with these constraints and k > 1 warns that components may be redundant or all-zero.

RcppML 1.0.0

Breaking Changes

Removed Functions

  • project(): Use predict() for NMF objects, or nnls() for raw matrix projection
  • crossValidate(): Use nmf() with test_fraction and a vector of ranks
  • lnmf(): Discontinued

Renamed Parameters

  • mask_zeros = TRUE → mask = "zeros"

New Features

Statistical Distributions via IRLS

NMF now supports six distribution-appropriate loss functions via Iteratively Reweighted Least Squares:

  • "mse" (Gaussian, default), "gp" (Generalized Poisson), "nb" (Negative Binomial), "gamma", "inverse_gaussian", "tweedie"
  • Automatic distribution selection via auto_nmf_distribution()
  • Zero-inflation models (zi = "row" or zi = "col") for ZINB and ZIGP

StreamPress I/O (.spz Format)

  • Column-oriented binary format with 10–20× compression via rANS entropy coding
  • Streaming NMF directly from .spz files for datasets larger than RAM
  • st_write(), st_read(), st_info() for reading and writing .spz files
  • Embedded obs/var metadata tables via st_read_obs() and st_read_var()
  • GPU-direct reading with st_read_gpu() for zero-copy GPU NMF

FactorNet Graph API

  • factor_net() composes multi-modal, deep, and branching NMF pipelines
  • Multi-modal NMF with shared embeddings across data modalities
  • Deep NMF with hierarchical decomposition
  • Conditional factorization by sample groups
  • Cross-validation for graph architectures via cross_validate_graph()

GPU Acceleration

  • Optional CUDA backend via cuBLAS/cuSPARSE with automatic CPU fallback
  • gpu_available() and gpu_info() for device queries
  • Streaming GPU NMF for matrices exceeding VRAM
  • Dense and sparse GPU NMF paths

Cross-Validation Improvements

  • Speckled holdout masks for principled rank selection
  • mask_zeros parameter for recommendation data (only non-zero entries held out)
  • Automatic rank search with k = "auto"
  • Multiple replicates via cv_seed vector
  • Early stopping with configurable patience

SVD and PCA

  • svd() for truncated SVD with five methods: deflation, Krylov, Lanczos, IRLBA, randomized
  • pca() convenience wrapper (centered and optionally scaled SVD)
  • Constrained PCA: non-negative (nonneg = TRUE), sparse (L1), and combined
  • variance_explained() for scree plots
  • predict() for SVD objects (out-of-sample projection)

Projective and Symmetric NMF

  • projective = TRUE: H is computed as $W^T A$ instead of solved independently, producing more orthogonal factors
  • symmetric = TRUE: For symmetric matrices, enforces $H = W^T$

Enhanced NNLS Solver

  • nnls() now supports loss, L21, and angular parameters (parity with nmf())
  • Non-MSE losses delegate through single-iteration NMF with IRLS
  • predict() for NMF objects now uses the config (L1, L2, upper_bound) stored during fitting

Additional Regularization

  • L1 / L2 penalties with separate values for W and H
  • L21 group sparsity for automatic factor selection
  • Angular decorrelation penalty (replaces ortho)
  • Upper bound constraints on factor values
  • Graph Laplacian regularization for spatial/network smoothness

New Datasets

  • golub: Leukemia gene expression (38 × 5,000 sparse)
  • olivetti: Olivetti face images (400 × 4,096 sparse)
  • digits: Handwritten digit images (1,797 × 64 dense)
  • pbmc3k: PBMC 3k scRNA-seq with cell type annotations (13,714 × 2,638, StreamPress compressed)

Other

  • Multiple random initializations with best-model selection via seed = c(...)
  • Automatic NA detection and masking
  • consensus_nmf() for robust factorizations across multiple random starts

Enhancements

  • S4 class system with backward-compatible $ accessor (migrated from implicit S4)
  • on_iteration callback for custom per-iteration logging
  • Lanczos and IRLBA initialization for faster NMF convergence

Internal Changes

  • Unified NMF configuration into NMFConfig struct
  • Pure C++ header library (Rcpp-free core algorithms in inst/include/RcppML/)
  • DataAccessor<MatrixType> template for unified sparse/dense dispatch
  • Consolidated header structure and eliminated code duplication
  • OpenMP parallelization with proper reduction clauses