Wrappers and Companion Agents

While the functionality of nmf.models is all that is necessary to perform constrained matrix factorization, it is worth developing some task specific agents that create reports or characterize data based on the CMF results.

We divide this into two areas:

  1. The wrappers of CMF that do some regular preprocessing or specific deployment that might be pertinent to a single class of experiments.

  2. How the agent that depends on this wrapper interfaces with your experimental workflow (see bluesky-adaptive).

Experiment specific wrappers

Total scattering: diffraction and pair distribution function

We use the I(q) function nomenclature as a placeholder for f(x), but this could easily be swapped for datasets like F(q), I(2theta), or G(r).

  • constrainedmf.wrappers.scattering.decomposition(Q, I, *, n_components=3, q_range=None, initial_components=None, fix_components=(), mode='Linear', kernel_width=1, max_iter=1000, bkg_removal=None, normalize=False, device=None, **kwargs)[source]

    Decompose and label a set of I(Q) data with optional focus bounds. Can be used for other 1-dimensional response functions, written with total scattering in mind.

    Two operating modes are available: Linear (conventional) and Deconvolutional. The former will proceed as conventional NMF as implemented in sklearn, with the added flexibility of the torch implementation. The latter will include a convolutional kernel in the reconstruction between the component and weight matricies.

    Initial components can be set as starting conditions of the component matrix for the optimization. These components can be fixed or allowed to vary using the fix_components argument as a tuple of booleans.

    Keyword arguments are passed to the fit method

    Parameters
    Qarray

    Ordinate Q for I(Q). Assumed to be rank 2, shape (m_patterns, n_data)

    Iarray

    The intensity values for each Q, assumed to be the same shape as Q. (m_patterns, n_data)

    n_components: int

    Number of components for NMF

    q_rangetuple, list

    (Min, Max) Q values for consideration in NMF. This enables a focused region for decomposition.

    initial_components: array

    Initial starting conditions of intensity components. Assumed to be shape (n_components, n_data). If q_range is given, these will be trimmed in accordance with I.

    fix_components: tuple(bool)

    Flags for fixing a subset of initial components

    mode: {“Linear”, “Deconvolutional”}

    Operating mode

    kernel_width: int

    Width of 1-dimensional convolutional kernel

    max_iter: int

    Maximum number of iterations for NMF

    bkg_removal: int, optional

    Integer degree for peakutils background removal

    normalize: bool, optional

    Flag for min-max normalization

    device: str, torch.device, None

    Device for matrix factorization to proceed on. Defaults to cpu.

    **kwargs: dict

    Arguments passed to the fit method. See nmf.models.NMFBase.

    Returns
    sub_Qarray

    Subsampled ordinate used for NMF

    sub_Iarray

    Subsampled I used for NMF

    alphasarray

    Resultant weights from NMF

    components: array

    Resultant components from NMF

A handy alternative that makes use of constrainedmf.nmf.utils.iterative_nmf is the iterative decomposition that makes use of the members the dataset to chose constraints for the NMF. This process occurs iteratively, and uses the dataset end-members, then the members that produce the maximal information gain of the model. Commonly, this function will be used with multiple numbers of components in parallel, feeding the scientist a visualization of their dataset in real-time.

  • constrainedmf.wrappers.scattering.iterative_decomposition(Q, I, *, n_components=3, q_range=None, mode='Linear', kernel_width=1, bkg_removal=None, normalize=False, **kwargs)[source]

    Iterative decomposition by performing constrained NMF using dataset members as constraints. The first 2 constraints are the end members of the dataset. The next constraint is chosen by examining the most prominent (heavily weighted) learned component. The index where this component’s weight is the highest, is used to select the next constraint from the dataset. This continues until all components are constrained by dataset members.

    Parameters
    Qarray

    Ordinate Q for I(Q). Assumed to be rank 2, shape (m_patterns, n_data)

    Iarray

    The intensity values for each Q, assumed to be the same shape as Q. (m_patterns, n_data)

    n_components: int

    Number of components for NMF

    q_rangetuple, list

    (Min, Max) Q values for consideration in NMF. This enables a focused region for decomposition.

    mode: {“Linear”, “Deconvolutional”}

    Operating mode

    kernel_width: int

    Width of 1-dimensional convolutional kernel

    bkg_removal: int, optional

    Integer degree for peakutils background removal

    normalize: bool, optional

    Flag for min-max normalization

    kwargs: dict

    Keyword arguments first get passed to nmf.utils.iterative_nmf to control fit parameters. Fit parameters include beta, alpha, tol, max_iter. Keyword arguments are then passed to the class initialization. Common init parameters include device, or initial_weights

    Returns
    sub_Q: array

    Subselected region of Q

    sub_I: array

    Subselected region of I

    weights: array

    Final weights from NMF

    components: array

    Final components from NMF

Companion agents for bluesky

Building useful companion agents is an active area of development. For more insights in how to deploy cmf, check out this repository for experiments at 28-ID PDF.