tensorly.decomposition.constrained_parafac

constrained_parafac(tensor, rank, n_iter_max=100, n_iter_max_inner=10, init='svd', svd='truncated_svd', tol_outer=1e-08, tol_inner=1e-06, random_state=None, verbose=0, return_errors=False, cvg_criterion='abs_rec_error', fixed_modes=None, non_negative=None, l1_reg=None, l2_reg=None, l2_square_reg=None, unimodality=None, normalize=None, simplex=None, normalized_sparsity=None, soft_sparsity=None, smoothness=None, monotonicity=None, hard_sparsity=None)[source]

CANDECOMP/PARAFAC decomposition via alternating optimization of alternating direction method of multipliers (AO-ADMM):

Computes a rank-rank decomposition of tensor [1] such that:

tensor = [|weights; factors[0], ..., factors[-1] |],

where factors are either penalized or constrained according to the user-defined constraint.

In order to compute the factors efficiently, the ADMM algorithm introduces an auxilliary factor which is called factor_aux in the function.

Parameters:

tensorndarray

rankint

Number of components.

n_iter_maxint

Maximum number of iteration for outer loop

n_iter_max_innerint

Number of iteration for inner loop

init{‘svd’, ‘random’, cptensor}, optional

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

tol_outerfloat, optional

(Default: 1e-8) 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.

tol_innerfloat, optional

(Default: 1e-6) Absolute reconstruction error tolerance for factor update during inner loop, i.e. ADMM optimization.

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

verboseint, optional

Level of verbosity

return_errorsbool, optional

Activate return of iteration errors

non_negativebool or dictionary

This constraint is clipping negative values to ‘0’. If it is True, non-negative constraint is applied to all modes.

l1_regfloat or list or dictionary, optional

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

l2_regfloat or list or dictionary, optional

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

l2_square_regfloat or list or dictionary, optional

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

unimodalitybool or dictionary, optional

If it is True, unimodality constraint is applied to all modes. Applied to each column seperately.

normalizebool or dictionary, optional

This constraint divides all the values by maximum value of the input array. If it is True, normalize constraint is applied to all modes.

simplexfloat or list or dictionary, optional

Projects on the simplex with the given parameter Applied to each column seperately.

normalized_sparsityfloat or list or dictionary, optional

Normalizes with the norm after hard thresholding

soft_sparsityfloat or list or dictionary, optional

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

smoothnessfloat or list or dictionary, optional

Optimizes the factors by solving a banded system

monotonicitybool or dictionary, optional

Projects columns to monotonically decreasing distrbution Applied to each column seperately. If it is True, monotonicity constraint is applied to all modes.

hard_sparsityfloat or list or dictionary, optional

Hard thresholding with the given threshold

cvg_criterion{‘abs_rec_error’, ‘rec_error’}, optional

Stopping criterion if tol is not None. If ‘rec_error’, algorithm stops at current iteration if (previous rec_error - current rec_error) < tol. If ‘abs_rec_error’, algorithm terminates when |previous rec_error - current rec_error| < tol.

fixed_modeslist, default is None

A list of modes for which the initial value is not modified. The last mode cannot be fixed due to error computation.

Returns:

CPTensor(weight, factors)

• weights : 1D array of shape (rank, )

• factors : List of factors of the CP decomposition element i is of shape (tensor.shape[i], rank)

errorslist

A list of reconstruction errors at each iteration of the algorithms.

References

[1]

T.G.Kolda and B.W.Bader, “Tensor Decompositions and Applications”, SIAM REVIEW, vol. 51, n. 3, pp. 455-500, 2009.

[2]

Huang, Kejun, Nicholas D. Sidiropoulos, and Athanasios P. Liavas. “A flexible and efficient algorithmic framework for constrained matrix and tensor factorization.” IEEE Transactions on Signal Processing 64.19 (2016): 5052-5065.