mojolearn.NMF#

class mojolearn.NMF(n_components='auto', *, init=None, solver='cd', beta_loss='frobenius', tol=0.0001, max_iter=200, random_state=None, alpha_W=0.0, alpha_H='same', l1_ratio=0.0, verbose=0, shuffle=False, numeric_mode=None)#

Non-negative matrix factorization X ~ W @ H.

Follows scikit-learn’s NMF: finds non-negative W (n_samples, n_components) and H (n_components, n_features) minimizing the chosen beta divergence plus optional L1/L2 penalties. The NNDSVD initializations use an exact SVD rather than scikit-learn’s randomized one, and random draws come from mojolearn’s own generator, so results differ slightly from scikit-learn’s for the same seed.

Parameters:

  • n_components (int, “auto” or None, default “auto”) – Number of components. "auto" or None uses n_features (with init="custom", the number of rows of the given H).

  • init ({“random”, “nndsvd”, “nndsvda”, “nndsvdar”, “custom”} or None, default None) – Initialization. None uses "nndsvda" when n_components <= min(n_samples, n_features), else "random". The NNDSVD variants need n_components <= min(n_samples, n_features). "custom" takes W and H from fit_transform.

  • solver ({“cd”, “mu”}, default “cd”) – Coordinate descent or multiplicative update.

  • beta_loss ({“frobenius”, “kullback-leibler”, “itakura-saito”}, default “frobenius”) – Divergence to minimize; the last two need solver="mu". The numbers 2, 1 and 0 are accepted for the same three; any other float beta raises ValueError.

  • tol (float, default 1e-4) – Stopping tolerance.

  • max_iter (int, default 200) – Maximum number of iterations.

  • random_state (int or None, default None) – Seed for "random" and "nndsvdar" initialization and for shuffle; None means 0. Not scikit-learn’s random stream.

  • alpha_W (float, default 0.0) – Regularization strength on W.

  • alpha_H (float or “same”, default “same”) – Regularization strength on H; "same" uses alpha_W.

  • l1_ratio (float, default 0.0) – Mix of L1 (1.0) and L2 (0.0) regularization.

  • verbose (int, default 0) – Accepted for scikit-learn compatibility; nothing is printed.

  • shuffle (bool, default False) – Visit coordinates in random order in each "cd" sweep.

  • numeric_mode ({“identical”, “fast”} or None, default None) – Numeric mode for this estimator. None uses the package default ("identical" unless changed). In identical mode, mojolearn returns the same bits on Apple, NVIDIA and AMD GPUs. "fast" is available on Apple GPUs only.

Variables:

  • components_ (ndarray of shape (n_components, n_features)) – The factor H.

  • n_components_ (int)

  • n_iter_ (int)

  • reconstruction_err_ (float) – Beta divergence between X and W @ H (square-rooted, as in scikit-learn).

  • n_features_in_ (int)

Raises:

ValueError – If X has negative values, or an unsupported solver, init or beta_loss is requested.

Examples

>>> import numpy as np, mojolearn
>>> X = np.random.default_rng(0).random((1000, 8), dtype=np.float32)
>>> model = mojolearn.NMF(n_components=3, random_state=0)
>>> W = model.fit_transform(X)
>>> H = model.components_

See also

User guide: Decomposition and embeddings

Choosing an estimator

Methods

fit(X[, y])

Fit the model.

fit_transform(X[, y, W, H])

Fit the model and return W.

get_params([deep])

Return this estimator's constructor parameters.

inverse_transform(X)

Return X @ components_, the data reconstructed from W.

set_params(**params)

Set constructor parameters by keyword.

transform(X)

Solve for W with the fitted H held fixed.
fit_transform(X, y=None, W=None, H=None)#

Fit the model and return W.

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Non-negative data.

  • y (ignored)

  • W (array-like of shape (n_samples, n_components), optional) – Starting W; used only with init="custom".

  • H (array-like of shape (n_components, n_features), optional) – Starting H; used only with init="custom".

Returns:

ndarray of shape (n_samples, n_components), float32

fit(X, y=None, **params)#

Fit the model.

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Non-negative data.

  • y (ignored)

  • **params – W and H for init="custom", as in fit_transform.

Returns:

self

transform(X)#

Solve for W with the fitted H held fixed.

Parameters:

X (array-like of shape (n_samples, n_features)) – Non-negative data.

Returns:

ndarray of shape (n_samples, n_components), float32

inverse_transform(X)#

Return X @ components_, the data reconstructed from W.

Parameters:

X (array-like of shape (n_samples, n_components)) – A W matrix.

Returns:

ndarray of shape (n_samples, n_features), float32

get_params(deep=True)#

Return this estimator’s constructor parameters.

Parameters:

deep (bool, default True) – Accepted for scikit-learn compatibility; it has no effect.

Returns:

dict – Parameter name to current value.

set_params(**params)#

Set constructor parameters by keyword.

Raises:

ValueError – If a keyword is not a parameter of this estimator.

Returns:

self