nnmf: Non-negative matrix factorization by alternating NNLS

In zdebruine/scNMF: Fast Non-negative matrix factorization toolkit for single cell data

Description

Fast non-negative matrix factorization by alternating least squares with sequential coordinate descent against mean squared error loss

Usage

nnmf(
  A,
  k = NULL,
  max.iter = 1000,
  rel.tol = 0.001,
  n.threads = 0,
  verbose = TRUE,
  trace = 5,
  reduction.use = NULL,
  reduction.key = "NMF_",
  reduction.name = "nmf",
  inner.rel.tol = 1e-06,
  inner.max.iter = 100
)

Arguments

A	A matrix or a Seurat object to be factorized. If a Seurat object, a reduction name may also be supplied, otherwise the entire dataset will be factorized. If sparse, will be converted to dense.
k	Decomposition rank, integer (required)
max.iter	Maximum number of alternating NNLS solutions for H and W, integer (default 1000)
rel.tol	Stop criterion, defined as the relative tolerance between two successive iterations: |e2-e1|/avg(e1,e2). (default 1e-3)
n.threads	Number of threads/CPUs to use. Default to 0 (all cores).
verbose	boolean, give updates every trace iterations
trace	An integer specifying a multiple of iterations at which MSE error should be calculated and checked for convergence. To check error every iteration, specify 1. To avoid checking error at all, specify trace > max.iter (default is 5, and is generally an efficient and effective value)
reduction.use	seurat obj input only: Specify a reduction to use feature loadings (i.e. cluster centers, such as "dclus"), otherwise leave as NULL to use the entire counts matrix from the default assay (NULL by default). If a reduction is specified, the NMF coordinates will be projected back onto all cells and the results of the projection will be stored in a dimensional reduction object. The original model will be stored in the "misc" slot of that object.
reduction.key	Seurat obj input only: reduction key for the resulting projection. Should end in an underscore. (default "NMF_")
reduction.name	Seurat obj input only: reduction name for the resulting projection (default "nmf")
inner.rel.tol	Tolerance for NNLS SCD
inner.max.iter	Maximum iterations permitted for NNLS SCD

Details

Methods are adapted from Lin and Boutros, 2018 BMC Bioinformatics with several improvements for efficiency in unregularized and non-masked use cases. This function is theoretically equivalent to NNLM::nnmf(..., method = "scd", loss = "mse", alpha = c(0,0,0), beta = c(0,0,0), mask = NULL, init = NULL). scNMF::nnmf offers >2x faster calculation than NNLM::nnmf on a single thread for low-rank factorization of a 10k x 200 matrix, and increasingly faster with matrix size, number of threads, and matrix rank. Key differences from NNLM::nnmf are 1) an improved OpemMP multithreading loop structure, 2) a parallelized MSE error loss function, 3) fewer conditional checks, 4) no MKL error calculations, and 5) no support for regularization, masking, or non-random initialization

In addition to bare matrices, Seurat objects may be passed to this function. Automatically, nnmf will extract the counts matrix from the default assay, but when reduction.use is specified with a valid dimensional reduction slot, the feature embeddings will be factorized and the resulting NMF model will be projected to all samples. This is convenient, for example, when NMF is run on cluster centers and cells must be visualized on the resulting NMF coordinates.

See also scNMF::nnmf.cv and scNMF::canyon.plot, dedicated functions for NMF cross-validation. These functions are helpful in determining the optimal rank k for any factorization.

For details on the projection algorithm (when Seurat objects are specified and reduction.use is specified, see scNMF::nnls.project documentation. A block size of 1000 is used in this instance.

Value

A list of W and H matrices if a matrix was input, or a Seurat object with result as a dimensional reduction of reduction.key with projections for all cells

See Also

scNMF::nnmf.cv

zdebruine/scNMF documentation built on Jan. 1, 2021, 1:50 p.m.