Fasternnls

From Eigenvector Research Documentation Wiki
Jump to navigation Jump to search

Purpose

Fast non-negative least squares.

Synopsis

[b,xi] = fasternnls(x,y,tol,b0,eqconst,xi,nnconst);
[b,xi] = fasternnls(x,y,tol,b0,eqconst,nnconst);

Description

Solves the equation xb = y subject to the constraint that b is non-negative. The inputs are the matrix of predictor variables x, vector or matrix of predicted variables y. Optional inputs include: tolerance on the size of a regression coefficient that is considered zero, tol, initial guess for the regression vectors, b0, the equality constraints matrix, eqconst, containing a value of NaN to indicate an unconstrained value or any finite value to indicate a constrained value. The optional input xi is the cached inverses output by a previous run of fasternnls (see outputs) or 0 (zero) to disable caching. The optional input nnconst allows row-wise or element-wise control over the non-negativity constraint (disabling non-negative requirement for a given row or element of b - see Inputs below.)

The outputs are the non-negatively constrained least squares solution, b, and the cache of x inverses, xi. If input y is a matrix, the result is the solution for each column of y calculated independently.

NOTE: This function performs the same operation as fastnnls and fastnnls_sel except it is optimized for matrix operations and is significantly faster. It fully supports equality constraints and row-wise, or element-wise, control over non-negative and equality constraints (like fastnnls_sel)

Inputs

  • x = the matrix of predictor variables,
  • y = vector or matrix of predicted variables. If (y) is a matrix, the result is the solution for each column calculated independently.

Optional Inputs

  • tol = tolerance on the size of a regression coefficient that is considered zero. Not supplied or empty matrix is implies the default value (based on x and eps),
  • b0 = initial guess for the regression vectors. Default or empty matrix is interpreted as no known initial guess,
  • eqconst = equality constraints matrix equal in size to b0 and containing a value of NaN to indicate an value not equality-constrained or any finite value to indicate an equality-constrained value. An empty matrix indicates no equality constraints on any elements.
  • xi = cached inverses output by a previous run of fasternnls (see outputs) or 0 (zero) to disable caching. An empty matrix is valid as a placeholder in the inputs.
  • nnconst = KxN matrix or Kx1 vector used to indicate which elements of b are to be non-negatively constrained. If nnconst is a Kx1 vector, it operates on rows of b indicating with a 1 (one) which rows should be non-negatively constrained. If nnconst is a matrix, it must be equal in size to b and indicate with a 1 (one) which elements of b should be non-negatively constrained. A value of 0 (zero) indicates a non-constrained value (i.e., negative values are allowed). If not supplied or empty [ ], the default is that all values are non-negatively constrained.

Note that the input xi can be omitted even if the input nnconst is being included.

See Also

als, fastnnls, lsq2top, mcr, parafac