tensorly.decomposition.Parafac2

class Parafac2(rank, n_iter_max=2000, init='random', svd='truncated_svd', normalize_factors=False, tol=1e-08, absolute_tol=1e-13, nn_modes=None, random_state=None, verbose=False, return_errors=False, n_iter_parafac=5, linesearch=False)[source]

PARAFAC2 decomposition [1] of a third order tensor via alternating least squares (ALS)

Computes a rank-rank PARAFAC2 decomposition of the third-order tensor defined by tensor_slices. The decomposition is on the form \((A [B_i] C)\) such that the i-th frontal slice, \(X_i\), of \(X\) is given by

\[X_i = B_i diag(a_i) C^T,\]

where \(diag(a_i)\) is the diagonal matrix whose nonzero entries are equal to the \(i\)-th row of the \(I \times R\) factor matrix \(A\), \(B_i\) is a \(J_i \times R\) factor matrix such that the cross product matrix \(B_{i_1}^T B_{i_1}\) is constant for all \(i\), and \(C\) is a \(K \times R\) factor matrix. To compute this decomposition, we reformulate the expression for \(B_i\) such that

\[B_i = P_i B,\]

where \(P_i\) is a \(J_i \times R\) orthogonal matrix and \(B\) is a \(R \times R\) matrix.

An alternative formulation of the PARAFAC2 decomposition is that the tensor element \(X_{ijk}\) is given by

\[X_{ijk} = \sum_{r=1}^R A_{ir} B_{ijr} C_{kr},\]

with the same constraints hold for \(B_i\) as above.

Parameters:
rankint

Number of components.

n_iter_maxint, optional

(Default: 2000) Maximum number of iteration

Changed in version 0.6.1: Previously, the default maximum number of iterations was 100.

init{‘svd’, ‘random’, CPTensor, Parafac2Tensor}

Type of factor matrix initialization. See initialize_factors.

svdstr, default is ‘truncated_svd’

function to use to compute the SVD, acceptable values in tensorly.SVD_FUNS

normalize_factorsbool (optional)

If True, aggregate the weights of each factor in a 1D-tensor of shape (rank, ), which will contain the norms of the factors. Note that there may be some inaccuracies in the component weights.

tolfloat, optional

(Default: 1e-8) Relative reconstruction error decrease tolerance. The algorithm is considered to have converged when \(\left|\| X - \hat{X}_{n-1} \|^2 - \| X - \hat{X}_{n} \|^2\right| < \epsilon \| X - \hat{X}_{n-1} \|^2\). That is, when the relative change in sum of squared error is less than the tolerance.

Changed in version 0.6.1: Previously, the stopping condition was \(\left|\| X - \hat{X}_{n-1} \| - \| X - \hat{X}_{n} \|\right| < \epsilon\).

absolute_tolfloat, optional

(Default: 1e-13) Absolute reconstruction error tolearnce. The algorithm is considered to have converged when \(\left|\| X - \hat{X}_{n-1} \|^2 - \| X - \hat{X}_{n} \|^2\right| < \epsilon_\text{abs}\). That is, when the relative sum of squared error is less than the specified tolerance. The absolute tolerance is necessary for stopping the algorithm when used on noise-free data that follows the PARAFAC2 constraint.

If None, then the machine precision + 1000 will be used.

nn_modes: None, ‘all’ or array of integers

(Default: None) Used to specify which modes to impose non-negativity constraints on. We cannot impose non-negativity constraints on the the B-mode (mode 1) with the ALS algorithm, so if this mode is among the constrained modes, then a warning will be shown (see notes for more info).

random_state{None, int, np.random.RandomState}
verboseint, optional

Level of verbosity

return_errorsbool, optional

Activate return of iteration errors

n_iter_parafacint, optional

Number of PARAFAC iterations to perform for each PARAFAC2 iteration

Returns:
Parafac2Tensor(weight, factors, projection_matrices)
  • weights1D array of shape (rank, )

    all ones if normalize_factors is False (default), weights of the (normalized) factors otherwise

  • factorsList of factors of the CP decomposition element i is of shape

    (tensor.shape[i], rank)

  • projection_matricesList of projection matrices used to create evolving

    factors.

Notes

This formulation of the PARAFAC2 decomposition is slightly different from the one in [1]. The difference lies in that, here, the second mode changes over the first mode, whereas in [1], the second mode changes over the third mode. This change allows the function to accept both lists of matrices and a single nd-array as input without any mode reordering.

References

[1] (1,2,3)

Kiers, H.A.L., ten Berge, J.M.F. and Bro, R. (1999), PARAFAC2—Part I. A direct fitting algorithm for the PARAFAC2 model. J. Chemometrics, 13: 275-294.

fit_transform(tensor)[source]

Decompose an input tensor

Parameters:
tensortensorly.tensor
Returns:
self