spectrochempy.MCRALS

class MCRALS(*args, constraints=None, solver_C='lstsq', solver_St='lstsq', max_iter=50, tol_residual_change=0.001, tol_reconstruction_error=None, tol_profile_change=None, maxdiv=5, warm_start=False, log_level=30)[source]

Multivariate Curve Resolution Alternating Least Squares (MCRALS).

MCR-ALS ( Multivariate Curve Resolution Alternating Least Squares ) resolve’s a set (or several sets) of spectra \(X\) of an evolving mixture (or a set of mixtures) into the spectra \(S^t\) of “pure” species and their concentration profiles \(C\).

In terms of matrix equation:

\[X = C.S^t + E\]

where \(E\) is the matrix of residuals.

Parameters:

constraints (list of Constraint, optional, default: None) – Public constraint objects describing scientific prior knowledge about the concentration ("C") or spectral ("St") profiles. When provided, each element must be an instance of a public constraint class (e.g., NonNegative, Unimodal, Closure, Monotonic, ModelProfile). None selects the built-in default constraints; an empty list requests an unconstrained fit.

constraints can be passed at construction time or assigned before calling fit:
```
from spectrochempy.analysis import constraints as mc

mcr = MCRALS()
mcr.constraints = [
    mc.NonNegative("C"),
    mc.Closure("C"),
]
mcr.fit(X, guess)
```
Added in version 0.7.0.
solver_C ('lstsq' | 'nnls' | 'pnnls', optional, default: 'lstsq') – Solver used to estimate concentration profiles C from X and St.
solver_St ('lstsq' | 'nnls' | 'pnnls', optional, default: 'lstsq') – Solver used to estimate spectral profiles St from X and C.
max_iter (int, optional, default: 50) – Maximum number of ALS iteration.
tol_residual_change (float, optional, default: 0.001) – Relative tolerance on the change in residual standard deviation. The dimensionless value is abs(sigma_k - sigma_(k-1)) / sigma_(k-1); 1e-3 therefore means 0.1%. Set to None to disable this stopping criterion.
tol_reconstruction_error (float, optional, default: None) – Tolerance on the relative reconstruction error norm(X - C @ St) / norm(X). This dimensionless stopping criterion is disabled when set to None.
tol_profile_change (float, optional, default: None) – Relative tolerance on the change of the resolved C and St profiles between successive iterations. Factor pairs are first normalized to remove their arbitrary reciprocal scale and sign; the larger relative Frobenius change of C and St is used. This dimensionless criterion is disabled when set to None.
maxdiv (int, optional, default: 5) – Maximum number of successive non-converging iterations.
warm_start (bool, optional, default: False) – When fitting repeatedly on the same dataset, but for multiple parameter values (such as to find the value maximizing performance), reuse the solution of the previous call to fit and add more components (if available) in a sequential manner.

When warm_start is True, the existing fitted model attributes is used to initialize the new model in a subsequent call to fit.
log_level (any of ["INFO", "DEBUG", "WARNING", "ERROR"], optional, default: "WARNING") – The log level at startup. It can be changed later on using the set_log_level method or by changing the log_level attribute.

See also

fit: Fit the MCRALS model on X.
transform: Apply dimensionality reduction.
fit_transform: Fit the model and apply dimensionality reduction.

Notes

Three dimensionless stopping diagnostics are evaluated after each ALS iteration: reconstruction_error measures the current relative reconstruction error, residual_change measures the relative change in residual standard deviation since the preceding iteration, and profile_change measures the scale/sign-invariant relative change of the resolved factor profiles. Convergence is reached as soon as any enabled tolerance is satisfied. By default, only tol_residual_change=1e-3 is enabled.

With log_level="INFO", these three diagnostics are printed using the same relative, dimensionless convention as their tolerances. The final message identifies the stopping diagnostic, its value, and its tolerance.

The bilinear model has an intrinsic scale ambiguity: without a calibrated, unit-bearing initial C0 or St0, the individual value units of the resolved factors are undefined. In that case C and St remain unitless and use conservative titles. A calibrated initial factor fixes the scale convention, allowing the complementary units to be derived from [X] = [C][St].

Operations that explicitly reset or exchange factor scale — spectral normalization, closure, and model/hard profile replacement — clear the resolved factor units. For horizontal augmentation, St_blocks carries block-specific physical metadata; the heterogeneous concatenated St is deliberately unitless with a neutral title.

Initialize the BaseConfigurable class.

Parameters:

log_level (int, optional) – The log level at startup. Default is logging.WARNING.
**kwargs (dict) – Additional keyword arguments for configuration.

Attributes Summary

`C`	The final accepted concentration profiles.
`C_blocks`	Concentration profiles split by experiment (block).
`C_constrained`	Final accepted concentration profiles.
`C_constrained_list`	Final accepted concentration profiles by ALS iteration.
`C_ls_list`	Unconstrained concentration least-squares solutions by ALS iteration.
`St`	The final accepted spectral profiles.
`St_blocks`	Spectral profiles split by experiment (block).
`St_constrained_list`	Final accepted spectral profiles by ALS iteration.
`St_ls`	The last spectral profiles obtained by least-square optimization, before constraints.
`St_ls_list`	Unconstrained spectral least-squares solutions by ALS iteration.
`X`	Return the X input dataset (eventually modified by the model).
`Y`	The `Y` input.
`argsGetConc`	Supplementary positional arguments passed to the external function.
`argsGetSpec`	Supplementary positional arguments passed to the external function.
`augmented_structure`	The internal augmented data structure, or `None` for simple 2D data.
`closureConc`	Defines the concentration profiles subjected to closure constraint.
`closureMethod`	The method used to enforce closure (Omidikia et al. [2018]).
`closureTarget`	The value of the sum of concentrations profiles subjected to closure.
`components`	`NDDataset` with components in feature space (n_components, n_features).
`config`	`traitlets.config.Config` object.
`constraints`	Public constraint objects for MCR-ALS.
`extraOutputGetConc`	The extra outputs of the external function used to get concentrations.
`extraOutputGetSpec`	The extra outputs of the external function used to get spectra.
`getC_to_C_idx`	Correspondence of the profiles returned by `getConc` and `C[:,hardConc]`.
`getConc`	An external function that provide `len(hardConc)` concentration profiles.
`getSpec`	An external function that will provide `len(hardSpec)` concentration profiles.
`getSt_to_St_idx`	Correspondence between the indexes of the spectra returned by `getSpec` and `St`.
`hardConc`	Defines hard constraints on the concentration profiles.
`hardSpec`	Defines hard constraints on the spectral profiles.
`is_augmented`	Whether the fit was performed on augmented (multiset) data.
`kwargsGetConc`	Supplementary keyword arguments passed to the external function.
`kwargsGetSpec`	Supplementary keyword arguments passed to the external function.
`log`	Return `log` output.
`max_iter`	Maximum number of ALS iteration.
`maxdiv`	Maximum number of successive non-converging iterations.
`monoDecConc`	Monotonic decrease constraint on concentrations.
`monoDecTol`	Tolerance parameter for monotonic decrease.
`monoIncConc`	Monotonic increase constraint on concentrations.
`monoIncTol`	Tolerance parameter for monotonic increase.
`n_components`	Number of components that were fitted.
`name`	Object name
`nonnegConc`	Non-negativity constraint on concentrations.
`nonnegSpec`	Non-negativity constraint on spectra.
`normSpec`	Defines whether the spectral profiles should be normalized.
`result`	`AnalysisResult` object wrapping the fitted MCRALS estimator.
`solverConc`	Solver used to get `C` from `X` and `St`.
`solverSpec`	Solver used to get `St` from `X` and `C`.
`solver_C`	Solver used to get `C` from `X` and `St`.
`solver_St`	Solver used to get `St` from `X` and `C`.
`storeIterations`	Whether to store the C and St generated at each iteration.
`tol`	Deprecated alias for 100 * tol_residual_change (percent).
`tol_profile_change`	Relative tolerance on the change of the resolved C and St profiles between successive iterations.
`tol_reconstruction_error`	Tolerance on the relative reconstruction error norm(X - C @ St) / norm(X).
`tol_residual_change`	Relative tolerance on the change in residual standard deviation.
`unimodConc`	Unimodality constraint on concentrations.
`unimodConcMod`	Method to apply unimodality.
`unimodConcTol`	Tolerance parameter for unimodality.
`unimodSpec`	Unimodality constraint on Spectra.
`unimodSpecMod`	Method used to apply unimodality.
`unimodSpecTol`	Tolerance parameter for unimodality.
`warm_start`	Whether to reuse the previous solution on the next `fit` call.

Methods Summary

`fit`(X, Y[, augmentation])	Fit the MCRALS model on an X dataset using initial concentration or spectra.
`fit_transform`(X, Y, **kwargs)	Fit the model with `X` and apply the dimensionality reduction on `X`.
`get_components`([n_components])	Return the component's dataset: (selected n_components, n_features).
`get_params`([deep])	Get the configuration parameters of this estimator.
`inverse_transform`([X_transform])	Transform data back to its original space.
`params`([default])	Return current or default configuration values.
`plot_merit`([X, X_hat])	Plot the input (`X`), reconstructed (`X_hat`) and residuals.
`plotmerit`([replace, removed, X, X_hat])	Backward-compatible alias for `plot_merit`.
`reset`()	Reset configuration parameters to their default values.
`set_params`(**params)	Set configuration parameters on this estimator.
`to_dict`()	Return config value in a dict form.
`transform`([X])	Return accepted concentrations with MCRALS factor metadata.

Attributes Documentation

C

The final accepted concentration profiles.

C is the factor accepted in the last ALS iteration after applying the configured concentration constraint pipeline and joint spectral normalization. If no configured operation changes the least-squares estimate, it is accepted unchanged. Together with St it satisfies C @ St ≈ X (reconstruction of the input data), where the reconstruction fidelity depends on the active constraints.

For non-augmented and vertically augmented fits, the observation axis (rows) carries the observation coordinate of the original input dataset.

For horizontally augmented fits, all blocks share the same observation axis. C preserves this shared coordinate (e.g. temperature) on its observation dimension.

The component axis (columns) carries component labels obtained from _get_component_labels.

Value metadata follow the MCRALS scale policy: a calibrated C0 supplies the title and units, or the units are derived from calibrated St0 as X.units / St0.units. Without a preserved calibrated scale, the title is "relative concentration" and units are absent.

C_blocks

Concentration profiles split by experiment (block).

For vertically augmented data, one block per input dataset is returned, each with its own observation coordinate and title.

For horizontally augmented data, a single block is returned (all blocks share the same concentration matrix C).

When the input datasets were NDDataset, each block is returned as an NDDataset carrying the original observation coordinates and title where available. For plain array inputs, blocks are returned as numpy.ndarray.

The blocks are copies of the relevant rows of the concatenated C matrix. Modifying a returned block does not affect the fitted estimator (unlike _outfit[0] which returns the internal array directly).

Each dataset block carries the resolved C value title and units. Experimental X value units are never copied directly: calibrated units come from C0 or are derived from X.units / St0.units. Coordinate metadata remain block-specific and come from the matching input dataset.

Returns:: tuple of numpy.ndarray or NDDataset – One element per block. For non-augmented data, a single-element tuple containing the full C array is returned.

C_constrained

Final accepted concentration profiles.

This compatibility output is synchronized with C after the configured concentration constraint pipeline, joint normalization, and final ComponentPresence enforcement.

C_constrained_list

Final accepted concentration profiles by ALS iteration.

Entries include the configured concentration constraint pipeline, joint normalization, and final ComponentPresence enforcement. They are independent snapshots and require MCRALS.storeIterations set to True.

C_ls_list

Unconstrained concentration least-squares solutions by ALS iteration.

Each entry is the unconstrained least-squares solution before concentration constraints and normalization. Entries are independent snapshots and require MCRALS.storeIterations set to True.

St

The final accepted spectral profiles.

St is the factor accepted in the last ALS iteration after applying the configured spectral constraint pipeline and normalization. If no configured operation changes the least-squares estimate, it is accepted unchanged. Together with C it satisfies C @ St ≈ X (reconstruction of the input data).

For non-augmented and vertically augmented fits, St carries the original spectral coordinate on its feature axis.

For horizontally augmented fits, the spectral axis is the concatenation of all blocks’ feature axes. Because different blocks may have incompatible spectral coordinates (e.g. UV wavelength vs CD wavelength), the global St uses a generic feature index. Use St_blocks to obtain per-block spectral matrices with the original physical coordinates.

A calibrated St0 supplies value title and units, or units are derived from X.units / C0.units. Without a preserved calibrated scale, units are absent. For horizontal augmentation the global concatenated factor is always unitless with the neutral title "concatenated spectral profiles"; St_blocks is authoritative.

St_blocks

Spectral profiles split by experiment (block).

Only meaningful for horizontally augmented data where each block has its own spectral matrix. For vertically augmented data (and for non-augmented data), St is common across blocks and this property returns a single-element tuple containing the full St matrix.

When the input datasets were NDDataset, each block is returned as an NDDataset carrying:

the spectral coordinate (e.g. wavelength) from the corresponding input block on its feature axis;
component labels on its component axis.
block-specific value title and units from calibrated St0 blocks, or units derived from the corresponding X block and calibrated C0.

For plain array inputs, blocks are returned as numpy.ndarray.

The blocks are copies of the relevant columns of the concatenated St matrix. Modifying a returned block does not affect the fitted estimator.

Returns:: tuple of numpy.ndarray or NDDataset – One element per block.

St_constrained_list

Final accepted spectral profiles by ALS iteration.

Entries include the configured spectral constraint pipeline and normalization. They are independent snapshots and require MCRALS.storeIterations set to True.

St_ls

The last spectral profiles obtained by least-square optimization, before constraints.

Spectra obtained after solving \(C_{\textrm{constrained}} \cdot St = X\) for \(St\).

St_ls_list

Unconstrained spectral least-squares solutions by ALS iteration.

Each entry precedes spectral constraints and normalization. Entries are independent snapshots and require MCRALS.storeIterations set to True.

X: Return the X input dataset (eventually modified by the model).

Y: The Y input.

argsGetConc: Supplementary positional arguments passed to the external function.

argsGetSpec: Supplementary positional arguments passed to the external function.

augmented_structure

The internal augmented data structure, or None for simple 2D data.

Returns a read-only view of the _AugmentedStructure describing the block structure of vertically-augmented datasets. Only available after fitting.

closureConc

Defines the concentration profiles subjected to closure constraint.

[]: no constraint is applied.
'all': all profile are constrained so that their weighted sum equals the closureTarget
list of indexes: the corresponding profiles are constrained so that their weighted sum equals closureTarget.

closureMethod

The method used to enforce closure (Omidikia et al. [2018]).

'scaling' recompute the concentration profiles using least squares:

\[C \leftarrow C \cdot \textrm{diag} \left( C_L^{-1} c_t \right)\]

where \(c_t\) is the vector given by closureTarget and \(C_L^{-1}\) is the left inverse of \(C\).
'constantSum' normalize the sum of concentration profiles to closureTarget.

closureTarget

The value of the sum of concentrations profiles subjected to closure.

'default': the total concentration is set to 1.0 for all observations.
array-like of size n_observations: the values of concentration for each observation. Hence, np.ones(X.shape[0]) would be equivalent to 'default'.

components

NDDataset with components in feature space (n_components, n_features).