spectrochempy.tensor.CP

CP(dataset) = <spectrochempy.tensor.CP unresolved>

CP/PARAFAC decomposition of 3D datasets using TensorLy.

CP (Canonical Polyadic) decomposition, also known as PARAFAC, factorizes a 3D tensor into a sum of rank-1 tensors. By default, this implementation uses TensorLy’s parafac function. When constraints or penalties are active (e.g., non_negative, l1_reg, smoothness, etc.), it automatically switches to TensorLy’s constrained_parafac function with AO-ADMM optimization.

Note: fixed_modes is supported by both parafac and constrained_parafac, so using fixed_modes alone does not trigger the constrained path.

Only 3D datasets are supported. For 2D data, use PCA, NMF, or SVD instead.

Parameters:

  • Number of components (rank) for the decomposition.

  • Maximum number of outer iterations for the ALS algorithm.

  • Number of iterations for inner loop (ADMM optimization).

  • Type of factor matrix initialization. If a CPTensor is passed, it is used directly.

  • Function to use for SVD computation during initialization.

  • Relative reconstruction error tolerance for outer loop convergence.

  • Absolute reconstruction error tolerance for inner loop (ADMM optimization).

  • Seed for random number generator or RandomState instance for reproducibility.

  • Level of verbosity for iteration logging.

  • Whether to store iteration errors after fitting. Errors are only

  • available when using constrained_parafac (i.e., when constraints

  • are active). For unconstrained parafac, errors will be None.

  • If True, applies non-negative constraint to all modes. Can also be a dict

  • specifying constraints per mode.

  • L1 norm regularization parameter for sparsity. Applied to factors.

  • L2 norm regularization parameter. Applied to factors.

  • L2 square norm regularization parameter. Applied to factors.

  • If True, enforces unimodality constraint on all modes.

  • If True, normalizes factors by dividing by maximum value.

  • Projects factors onto the simplex with the given parameter.

  • Normalizes factors with L1 norm after hard thresholding.

  • Imposes L1 norm bound on factor columns.

  • Optimizes factors by solving a banded system for smoothness.

  • If True, projects factor columns to monotonically decreasing distribution.

  • Applies hard thresholding with the given threshold.

  • Stopping criterion for ALS. “abs_rec_error” uses absolute difference,

  • “rec_error” uses relative difference.

  • Modes for which initial values are not modified during optimization.

  • The last mode cannot be fixed.

cvg_criterionany value of ['abs_rec_error', 'rec_error'], optional, default: 'abs_rec_error'

Stopping criterion for ALS, works if tol is not None.

If ‘rec_error’, ALS stops at current iteration if (previous rec_error - current rec_error) < tol. If ‘abs_rec_error’, ALS terminates when |previous rec_error - current rec_error| < tol.

fixed_modeslist, optional, default: []
A list of modes for which the initial value is not modified.

The last mode cannot be fixed due to error computation.

hard_sparsitya float or a list or a dict, optional, default: None

Hard thresholding with the given threshold.

initany value of ['random', 'svd', 'CPTensor'], optional, default: 'svd'

Type of factor matrix initialization.

If a CPTensor is passed, this is directly used for initialization. See initialize_factors.

l1_rega float or a list or a dict, optional, default: None

Penalizes the factor with the l1 norm using the input value as regularization parameter.

l2_rega float or a list or a dict, optional, default: None

Penalizes the factor with the l2 norm using the input value as regularization parameter.

l2_square_rega float or a list or a dict, optional, default: None

Penalizes the factor with the l2 square norm using the input value as regularization parameter.

monotonicitya boolean or a dict, optional, default: None
Projects columns to monotonically decreasing distribution.

Applied to each column separately. If True, monotonicity constraint is applied to all modes.

n_componentsint, optional, default: 0

Number of components (this is the ‘rank’ parameter used in TensorLy).

n_iter_maxint, optional, default: 100

Maximum number of outer iterations.

n_iter_max_innerint, optional, default: 10

Number of iterations for inner loop (ADMM optimization).

non_negativea boolean or a dict, optional, default: False

This constraint clips negative values to ‘0’.

If True, non-negative constraint is applied to all modes.

normalizea boolean or a dict, optional, default: None
This constraint divides all the values by maximum value of the input array.

If True, normalize constraint is applied to all modes.

normalized_sparsitya float or a list or a dict, optional, default: None

Normalizes with the norm after hard thresholding.

random_statean int or a RandomState, optional, default: None
If int, used to set the seed of the random number generator.

If numpy.random.RandomState, used to initialize factor matrices with uniform distribution.

return_errorsbool, optional, default: False

Activate return of iteration errors.

simplexa float or a list or a dict, optional, default: None
Projects on the simplex with the given parameter.

Applied to each column separately.

smoothnessa float or a list or a dict, optional, default: None

Optimizes the factors by solving a banded system.

soft_sparsitya float or a list or a dict, optional, default: None

Impose that the columns of factors have L1 norm bounded by a user-defined threshold.

svdany value of ['numpy_svd', 'truncated_svd', 'randomized_svd'], optional, default: 'truncated_svd'

Function to use to compute the SVD. Maps to tensorly SVD functions.

tol_innerfloat, optional, default: 1e-06
Absolute reconstruction error tolerance for factor update during inner loop,

i.e., ADMM optimization.

tol_outerfloat, optional, default: 1e-08

Relative reconstruction error tolerance for outer loop.

The algorithm is considered to have found a local minimum when the reconstruction error is less than tol_outer.

unimodalitya boolean or a dict, optional, default: None
If True, enforces unimodality constraint on all modes.

Applied to each mode separately.

verboseint, optional, default: 0

Level of verbosity.

See also

PCA

Principal Component Analysis for 2D data.

SVD

Singular Value Decomposition for 2D data.

Notes

This method requires the optional dependency tensorly. Install it with:

pip install spectrochempy-tensor

CP decomposition is sensitive to initialization and rank choice. The results may vary with different random seeds. Use random_state for reproducibility.

Core consistency (CORCONDIA) helps assess model validity. Values close to 100% indicate a good fit, while negative values suggest overfactoring.

Examples

>>> import spectrochempy as scp
>>> import numpy as np
>>> X = np.random.rand(6, 8, 10)
>>> ds = scp.NDDataset(X)
>>> cp = scp.tensor.CP(n_components=2)
>>> _ = cp.fit(ds)
>>> A, B, C = cp.result.factors
>>> Xr = cp.inverse_transform()
A[source]

Factor matrix for mode 0 with shape (mode_0_size, n_components).

Type:

NDDataset

B[source]

Factor matrix for mode 1 with shape (mode_1_size, n_components).

Type:

NDDataset

C[source]

Factor matrix for mode 2 with shape (mode_2_size, n_components).

Type:

NDDataset

loadings[source]

Tuple of factor matrices (A, B, C).

Type:

tuple

weights[source]

Weights from CP decomposition.

Type:

ndarray

errors[source]

Iteration errors during fitting. Available when TensorLy returns them (typically with constrained_parafac). Returns None if unavailable or if not fitted yet.

Type:

list or None

SSE[source]

Sum of Squared Errors of the reconstruction.

Type:

float

explained_variance[source]

Percentage of variance explained by the model.

Type:

float

core_consistency[source]

CORCONDIA (Core Consistency) diagnostic value. Can be negative if overfactoring.

Type:

float

fit(X)[source]

Fit the CP model to a 3D dataset.

fit_transform(X)[source]

Fit the model and return the reconstructed tensor.

inverse_transform()[source]

Return the reconstructed tensor from fitted factors.