naginterfaces.library.matop.real_​nmf_​rcomm

naginterfaces.library.matop.real_nmf_rcomm(irevcm, w, h, ht, comm, seed=1, errtol=0.0)

real_nmf_rcomm computes a non-negative matrix factorization for a real non-negative $m\times n$ matrix $A$. It uses reverse communication for evaluating matrix products, so that the matrix $A$ is not accessed explicitly.

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f01/f01sbf.html

Parameters

irevcmint

On initial entry: must be set to $0$.

wfloat, ndarray, shape $(m,k)$, modified in place

On initial entry:

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_rcomm will generate a random initial iterate.

On intermediate exit: if $irevcm=1$ or $2$, $w$ contains the current iterate of the $m\times k$ non-negative matrix $W$.

On intermediate entry:

if $irevcm=3$, $w$ must contain $A{H}^T$, where $H^T$ is stored in $\text{ht}$.

If $irevcm=0$, $1$ or $2$, $w$ must not be changed.

On final exit: $w$ contains the $m\times k$ non-negative matrix $W$.

hfloat, ndarray, shape $(k,n)$, modified in place

On initial entry:

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_rcomm will generate a random initial iterate.

On intermediate exit: if $irevcm=1$, $h$ contains the current iterate of the $k\times n$ non-negative matrix $H$.

On intermediate entry: $h$ must not be changed.

On final exit: $h$ contains the $k\times n$ non-negative matrix $H$.

htfloat, ndarray, shape $(n,k)$, modified in place

On initial entry: $ht$ need not be set.

On intermediate exit: if $irevcm=3$, $ht$ contains the $n\times k$ non-negative matrix $H^T$, which is required in order to form $A{H}^T$.

On intermediate entry: if $irevcm=2$, $ht$ must contain $A^{T}W$.

If $irevcm=0$, $1$ or $3$, $ht$ must not be changed.

On final exit: $ht$ is undefined.

commdict, communication object, modified in place

Communication structure.

On initial entry: need not be set.

seedint, optional

On initial entry:

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.

Returns

irevcmint

On intermediate exit: specifies what action you must take before re-entering real_nmf_rcomm with $irevcm$ unchanged. The value of $irevcm$ should be interpreted as follows:

$irevcm=1$

Indicates the start of a new iteration. No action is required by you, but $w$ and $h$ are available for printing, and a limit on the number of iterations can be applied.

$irevcm=2$

Indicates that before re-entry to real_nmf_rcomm, the product $A^{T}W$ must be computed and stored in $ht$.

$irevcm=3$

Indicates that before re-entry to real_nmf_rcomm, the product $A{H}^T$ must be computed and stored in $w$.

On final exit: $irevcm=0$.

Raises

NagValueError

(errno $1$)

On intermediate re-entry, $irevcm=⟨value⟩$.

Constraint: $irevcm=1$, $2$ or $3$.

(errno $1$)

On initial entry, $irevcm=⟨value⟩$.

Constraint: $irevcm=0$.

(errno $2$)

On entry, $m=⟨value⟩$.

Constraint: $m\ge 2$.

(errno $3$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 2$.

(errno $4$)

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 $w$ or $h$ were negative.

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_rcomm 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_rcomm to generate the initial values using a random number generator.

real_nmf_rcomm does not explicitly need to access the elements of $A$; it only requires the result of matrix multiplications of the form $AX$ or $A^{T}Y$. A reverse communication interface is used, in which control is returned to the calling program whenever a matrix product is required.

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