Description Usage Arguments Details Value Author(s) References See Also Examples
Solves the equation a %*% x = b
for x
subject to x > 0.
1 
a 
symmetric positive definite matrix giving coefficients of the linear system 
b 
matrix giving the righthand side(s) of the linear system 
cd_maxit 
maximum number of coordinate descent iterations 
cd_tol 
stopping criteria, difference in x across consecutive solutions over the sum of x 
fast_nnls 
initialize coordinate descent with a FAST NNLS approximation 
L1 
L1/LASSO penalty to be subtracted from 
This is a very fast implementation of nonnegative least squares (NNLS), suitable for very small or very large systems.
Algorithm. Sequential coordinate descent (CD) is at the core of this implementation, and requires an initialization of x. There are two supported methods for initialization of x:
Zerofilled initialization when fast_nnls = FALSE
and cd_maxit > 0
. This is generally very efficient for wellconditioned and small systems.
Approximation with FAST when fast_nnls = TRUE
. Forward active set tuning (FAST), described below, finds an approximate active set using unconstrained least squares solutions found by Cholesky decomposition and substitution. To use only FAST approximation, set cd_maxit = 0
.
a
must be symmetric positive definite if FAST NNLS is used, but this is not checked.
See our BioRXiv manuscript (references) for benchmarking against LawsonHanson NNLS and for a more technical introduction to these methods.
Coordinate Descent NNLS. Least squares by sequential coordinate descent is used to ensure the solution returned is exact. This algorithm was introduced by Franc et al. (2005), and our implementation is a vectorized and optimized rendition of that found in the NNLM R package by Xihui Lin (2020).
FAST NNLS. Forward active set tuning (FAST) is an exact or nearexact NNLS approximation initialized by an unconstrained least squares solution. Negative values in this unconstrained solution are set to zero (the "active set"), and all other values are added to a "feasible set". An unconstrained least squares solution is then solved for the "feasible set", any negative values in the resulting solution are set to zero, and the process is repeated until the feasible set solution is strictly positive.
The FAST algorithm has a definite convergence guarantee because the feasible set will either converge or become smaller with each iteration. The result is generally exact or nearly exact for small wellconditioned systems (< 50 variables) within 2 iterations and thus sets up coordinate descent for very rapid convergence. The FAST method is similar to the first phase of the socalled "TNTNN" algorithm (Myre et al., 2017), but the latter half of that method relies heavily on heuristics to refine the approximate active set, which we avoid by using coordinate descent instead.
vector or matrix giving solution for x
Zach DeBruine
DeBruine, ZJ, Melcher, K, and Triche, TJ. (2021). "Highperformance nonnegative matrix factorization for large singlecell data." BioRXiv.
Franc, VC, Hlavac, VC, and Navara, M. (2005). "Sequential CoordinateWise Algorithm for the Nonnegative Least Squares Problem. Proc. Int'l Conf. Computer Analysis of Images and Patterns."
Lin, X, and Boutros, PC (2020). "Optimization and expansion of nonnegative matrix factorization." BMC Bioinformatics.
Myre, JM, Frahm, E, Lilja DJ, and Saar, MO. (2017) "TNTNN: A Fast Active Set Method for Solving Large NonNegative Least Squares Problems". Proc. Computer Science.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22  ## Not run:
# compare solution to base::solve for a random system
X < matrix(runif(100), 10, 10)
a < crossprod(X)
b < crossprod(X, runif(10))
unconstrained_soln < solve(a, b)
nonneg_soln < nnls(a, b)
unconstrained_err < mean((a %*% unconstrained_soln  b)^2)
nonnegative_err < mean((a %*% nonneg_soln  b)^2)
unconstrained_err
nonnegative_err
all.equal(solve(a, b), nnls(a, b))
# example adapted from multiway::fnnls example 1
X < matrix(1:100,50,2)
y < matrix(101:150,50,1)
beta < solve(crossprod(X)) %*% crossprod(X, y)
beta
beta < nnls(crossprod(X), crossprod(X, y))
beta
## End(Not run)

Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.