naginterfaces.library.matop.real_​nmf

naginterfaces.library.matop.real_nmf(a, k=None, w=None, h=None, seed=None, errtol=0.0, maxit=0)

real_nmf computes a non-negative matrix factorization for a real non-negative $m\times n$ matrix $A$.

For full information please refer to the NAG Library document for f01sa

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f01/f01saf.html

Parameters

afloat, array-like, shape $(m,n)$

The $m\times n$ non-negative matrix $A$.

kNone or int, optional

Note: if this argument is None then a default value will be used, determined as follows: dimension 1 of $h$.

$k$, the factorization rank.

This argument is only referenced if you are not supplying initial iterates $W$ and $H$.

If you are providing initial iterates $W$ and $H$ then your supplied value of $k$ will be ignored and it will be inferred from those arrays instead.

wNone or float, array-like, shape $(m,k)$, optional

If $seed\le 0$, $w$ should be set to an initial iterate for the non-negative matrix factor, $W$.

If $seed\ge 1$, $w$ need not be set. real_nmf will generate a random initial iterate.

hNone or float, array-like, shape $(k,n)$, optional

If $seed\le 0$, $h$ should be set to an initial iterate for the non-negative matrix factor, $H$.

If $seed\ge 1$, $h$ need not be set. real_nmf will generate a random initial iterate.

seedNone or int, optional

Note: if this argument is None then a default value will be used, determined as follows: if $w\text{is not}None$: $0$; otherwise: $1$.

If $seed\le 0$, the supplied values of $W$ and $H$ are used for the initial iterate.

If $seed\ge 1$, the value of $seed$ is used to seed a random number generator for the initial iterates $W$ and $H$. See Generating Random Initial Iterates for further details.

errtolfloat, optional

The convergence tolerance for when the Hierarchical Alternating Least Squares iteration has reached a stationary point. If $errtol\le 0.0$, $max(m,n)\times \sqrt{\text{machine precision}}$ is used.

maxitint, optional

Specifies the maximum number of iterations to be used. If $maxit\le 0$, $200$ is used.

Returns

wfloat, ndarray, shape $(m,k)$

The non-negative matrix factor, $W$.

hfloat, ndarray, shape $(k,n)$

The non-negative matrix factor, $H$.

Raises

NagValueError

(errno $1$)

On entry, $m=⟨value⟩$.

Constraint: $m\ge 2$.

(errno $2$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 2$.

(errno $3$)

On entry, $k=⟨value⟩$, $m=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $1\le k<min(m,n)$.

(errno $8$)

An internal error occurred when generating initial values for $w$ and $h$. Please contact NAG.

(errno $9$)

On entry, one of more of the elements of $a$, $w$ or $h$ were negative.

(errno $14$)

Both or neither of $w$ and $h$ must be provided.

(errno $15$)

$h$ or $k$ must be provided.

Warns

NagAlgorithmicWarning

(errno $7$)

The function has failed to converge after $⟨value⟩$ iterations. The factorization given by $w$ and $h$ may still be a good enough approximation to be useful. Alternatively an improved factorization may be obtained by increasing $maxit$ or using different initial choices of $w$ and $h$.

Notes

The matrix $A$ is factorized into the product of an $m\times k$ matrix $W$ and a $k\times n$ matrix $H$, both with non-negative elements. The factorization is approximate, $A\approx WH$, with $W$ and $H$ chosen to minimize the functional

$$f(W,H)={\parallel A-WH\parallel }_F^2\text{.}$$

You are free to choose any value for $k$, provided $k<min(m,n)$. The product $WH$ will then be a low-rank approximation to $A$, with rank at most $k$.

real_nmf finds $W$ and $H$ using an iterative method known as the Hierarchical Alternating Least Squares algorithm. You may specify initial values for $W$ and $H$, or you may provide a seed value for real_nmf to generate the initial values using a random number generator.

References

Cichocki, A and Phan, A–H, 2009, Fast local algorithms for large scale nonnegative matrix and tensor factorizations, IEICE Transactions on Fundamentals of Electronics, Communications and Computer Sciences (E92–A), 708–721

Cichocki, A, Zdunek, R and Amari, S–I, 2007, Hierarchical ALS algorithms for nonnegative matrix and 3D tensor factorization, Lecture Notes in Computer Science (4666), Springer, 169–176

Ho, N–D, 2008, Nonnegative matrix factorization algorithms and applications, PhD Thesis, Univ. Catholique de Louvain