Using Native Constrained NMF¶
Start by importing Constrained Matrix Factorization.
import constrainedmf as cmf
For extensibility, each instance of NMF is inherits from a base class. This class set’s up the matrix factorization using the correct shapes and number of components. It also allows for portions of the matricies to be initialized, and fixed.
Simple NMF¶
A simple, albeit nonsensical, example of NMF can be accomplished with the following, starting from a matrix of 30 different 100 member vectors. We can constrain the components to be zeros and ones, and allow a third component to approximate the variation. This approach gives us the learning curve of the alternating update algorithm, and two numpy arrays of weights and components.
import torch
X = torch.rand(30, 100)
x_0 = torch.zeros(1, 100)
x_1 = torch.ones(1, 100)
model = cmf.nmf.models.NMF(X.shape,
3,
initial_components=[x_0, x_1],
fix_components=[True, True, False])
loss = model.fit(X) # Learning curve of loss over timesteps
learned_weights, learned_components = model.W.detach().numpy(), model.H.detach().numpy()
- class constrainedmf.nmf.models.NMF(X_shape, n_components, *, initial_components=None, fix_components=(), initial_weights=None, fix_weights=(), device=None, **kwargs)[source]¶
Standard NMF with ability for constraints constructed from input matrix shape.
W is (m_examples, n_components)
H is (n_components, n_example_features)
W @ H give reconstruction of X.
- Parameters
- X_shape: tuple
Tuple of ints describing shape of input matrix
- n_components: int
Number of desired components for the matrix factorization
- initial_components: tuple of torch.Tensor
Initial components for the factorization. Shape (1, n_features)
- fix_components: tuple of bool
Corresponding directive to fix each component in the factorization. The components are ordered, and the default behavior is to allow a component to vary. I.e. (True, False, True) for a 4 component factorization will result in the first and third component being fixed, while the second and fourth vary.
- initial_weights: tuple of torch.Tensor
Initial weights for the factorization. Shape (1, m_examples)
- fix_weights: tuple of bool
Corresponding directive to fix each weight in the factorization.
- device: str, torch.device, None
Device for matrix factorization to proceed on. Defaults to cpu.
- kwargs: dict
kwargs for torch.nn.Module
The underlying class¶
Referring to the base class details some of the constraint functionality available. The base class could be conceivibly used to construct different reconstruction approaches with NMF; however, has some required implementations for any child classes.
- class constrainedmf.nmf.models.NMFBase(W_shape, H_shape, n_components, *, initial_components=None, fix_components=(), initial_weights=None, fix_weights=(), device=None, **kwargs)[source]¶
Base class for setting up NMF
- Parameters
- W_shape: tuple of int
Shape of the weights matrix
- H_shape: tuple of int
Shape of the components matrix
- n_components: int
Number of components in the factorization
- initial_components: tuple of torch.Tensor
Initial components for the factorization. Shape (1, n_features)
- fix_components: tuple of bool
Corresponding directive to fix each component in the factorization. The components are ordered, and the default behavior is to allow a component to vary. I.e. (True, False, True) for a 4 component factorization will result in the first and third component being fixed, while the second and fourth vary.
- initial_weights: tuple of torch.Tensor
Initial weights for the factorization. Shape (1, m_examples)
- fix_weights: tuple of bool
Corresponding directive to fix each weight in the factorization.
- device: str, torch.device, None
Device for matrix factorization to proceed on. Defaults to cpu.
- kwargs: dict
Keyword arguments for torch.nn.Module
- get_H_positive(WH, beta, W_sum) -> (<class 'torch.Tensor'>, <class 'torch.Tensor'>)[source]¶
Get the positive denominator and/or W sum for multiplicative H update
- Parameters
- WH: torch.Tensor
Reconstruction of input matrix (in the simple case this is the matrix produce W @ H
- beta: int, float
Value for beta divergence
- W_sum: torch.Tensor, None
Sum over weights matrix to use in denominator of update. If unknown or not required use None.
- Returns
- get_W_positive(WH, beta, H_sum) -> (<class 'torch.Tensor'>, <class 'torch.Tensor'>)[source]¶
Get the positive denominator an/or H sum for multiplicative W update
- Parameters
- WH: torch.Tensor
Reconstruction of input matrix (in the simple case this is the matrix produce W @ H
- beta: int, float
Value for beta divergence
- H_sum: torch.Tensor, None
Sum over components matrix to use in denominator of update. If unknown or not required use None.
- Returns