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)[source]#

Bases: _Base

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). "identical" gives the same bits on NVIDIA and AMD GPUs; "fast" applies on Apple GPUs.

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_
__init__(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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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