scikit-learn/scikit-learn — pull request #1348 by omangin (2012-11-09 17:57:35+00:00)
Title: NMF for Kullback-Leibler divergence

Adds the KLdivNMF class to decomposion.
The implemented method uses multiplicative updates. It is optimized to work with sparse matrices with lots of features.

"""Non negative factorization with Kullback Leibler divergence cost.

Parameters
----------
X: {array-like, sparse matrix}, shape = [n_samples, n_features]
Data the model will be fit to.

n_components: int or None
Number of components, if n_components is not set all components
are kept

init: 'nndsvd' | 'nndsvda' | 'nndsvdar' | 'random'
Method used to initialize the procedure.
Default: 'nndsvdar' if n_components < n_features, otherwise random.
Valid options::

'nndsvd': Nonnegative Double Singular Value Decomposition (NNDSVD)
initialization (better for sparseness)
'nndsvda': NNDSVD with zeros filled with the average of X
(better when sparsity is not desired)
'nndsvdar': NNDSVD with zeros filled with small random values
(generally faster, less accurate alternative to NNDSVDa
for when sparsity is not desired)
'random': non-negative random matrices

tol: double, default: 1e-4
Tolerance value used in stopping conditions.

max_iter: int, default: 200
Number of iterations to compute.

subit: int, default: 10
Number of sub-iterations to perform on W (resp. H) before switching
to H (resp. W) update.

Attributes
----------
`components_` : array, [n_components, n_features]
Non-negative components of the data

random_state : int or RandomState
Random number generator seed control.

Examples
--------

>>> import numpy as np
>>> X = np.array([[1,1], [2, 1], [3, 1.2], [4, 1], [5, 0.8], [6, 1]])
>>> from sklearn.decomposition import KLdivNMF
>>> model = KLdivNMF(n_components=2, init='random', random_state=0)
>>> model.fit(X) #doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
KLdivNMF(eps=1e-08, init='random', max_iter=200, n_components=2,
random_state=0, subit=10, tol=1e-06)
>>> model.components_
array([[ 0.50303234, 0.49696766],
[ 0.93326505, 0.06673495]])

Notes
-----
This implements

Lee D. D., Seung H. S., Learning the parts of objects by non-negative
matrix factorization. Nature, 1999
"""