# Tucker

### Purpose

TUCKER analysis for n-way arrays.

### Synopsis

- model = tucker(x,ncomp,
*initval,options*) %tucker model - pred = tucker(x,model) %application
- tucker(model) % provides a table of variances per component.

### Description

TUCKER decomposes an array of order *K* (where *K* ≥ 3) into the summation over the outer product of *K* vectors. As opposed to PARAFAC every combination of factors in each mode are included (subspaces). Missing values must be NaN or Inf.

#### Inputs

**x**= the multi-way array to be decomposed and

**ncomp**= the number of components to estimate, or

**model**= a TUCKER model structure.

Note that when specifying (ncomp), it must be a vector with K elements specifying the number of components for each mode.

#### Optional Inputs

= if**initval***initval*is the loadings from a previous TUCKER model are then these are used as the initial starting values to estimate a final model,

- if
*initval*is a TUCKER model structure then mode 1 loadings (scores) are estimated from x and the loadings in the other modes (see output pred),

- if

= discussed below.**options**

#### Outputs

**model**= a structure array with the following fields:**modeltype**: 'TUCKER',**datasource**: structure array with information about input data,**date**: date of creation,**time**: time of creation,**info**: additional model information,**loads**: 1 by*K*+1 cell array with model loadings for each mode/dimension,**pred**: cell array with model predictions for each input data block,**tsqs**: cell array with T^{2}values for each mode,**ssqresiduals**: cell array with sum of squares residuals for each mode,**description**: cell array with text description of model, and**detail**: sub-structure with additional model details and results.

**pred**= is a structure array, similar to model, that contains prediction results for new data fit to the TUCKER model.

### Options

*options* = a structure array with the following fields:

**display**: [ {'on'} | 'off' ], governs level of display,**plots**: [ {'final'} | 'all' | 'none' ], governs level of plotting,**waitbar**: [ {'on'} | 'off' ], governs use of waitbar while calculating,**weights**: [], used for fitting a weighted loss function (discussed below),**stopcrit**: [1e-6 1e-6 10000 3600] defines the stopping criteria as [(relative tolerance) (absolute tolerance) (maximum number of iterations) (maximum time in seconds)],**init**: [ 0 ], defines how parameters are initialized (see PARAFAC),**line**: [ 0 | {1}] defines whether to use the line search {default uses it},**algo**: this option is not yet active,**blockdetails**: 'standard'**missdat**: this option is not yet active,**samplemode**: [1], defines which mode should be considered the sample or object mode and**constraints**: {kx1 cell}, defines constraints on parameters (see below). The first three cells define constraints on loadings whereas the last cell defines constraints on the core.

CONSTRAINTS

The *options* field constraints is used to employ constraints on the parameters. It is a cell array with number of elements equal to the number of modes of the input data X. Each cell contains a structure array with the following fields:

**nonnegativity**: [ {0} | 1 ], a 1 imposes non-negativity.

**unimodality**: [ {0} | 1 ], a 1 imposes unimodality (1 local maxima).

**orthogonal**: [ {0} | 1 ], constrain factors in this mode to be orthogonal.

**orthonormal**: [ {0} | 1 ], constrain factors in this mode to be orthonormal.

**exponential**: [ {0} | 1 ], a 1 fits an exponential function to the factors in this mode.

- smoothness.weight: [0 to 1], imposes smoothness using B-splines, values near 1 impose high smoothness and values close to 0, impose less smoothness.

**fixed.position**: [ ], a matrix containing 1's and 0's of the same size as the corresponding loading matrix, with a 1 indicating where parameters are fixed.

**fixed.value**: [ ], a vector containing the fixed values. Thus, if B is the loading matrix, then we seek B(find(fixed.position)) = fixed.value. Therefore, fixed.value must be a matrix of the same size as the loadings matrix and with the corresponding elements to be fixed at their appropriate values. All other elements of fixed.value are disregarded.

**fixed.weight**: [ ], a scalar (0 ? fixed.weight ? 1) indicating how strongly the fixed.value is imposed. A value of 0 (zero) does not impose the constraint at all, whereas a value of 1 (one) fixes the constraint.

**ridge.weight**: [ ], a scalar value between 0 and 1 that introduces a ridging in the update of the loading matrix. It is a penalty on the size of the esimated loadings. The closer to 1, the higher the ridge. Ridging is useful when a problem is difficult to fit.

**equality.G**: [ ], matrix with*N*columns, where*N*is the number of factors, used with equality.H. If**A**is the loadings for this mode then the constraint is imposed such that**GA**^{T}=**H**. For example, if**G**is a row vector of ones and**H**is a vector of ones (1's), this would impose closure.

**equality.H**: [ ], matrix of size consistent with the constriant imposed by equality.G.

**equality.weight**: [ ], a scalar (0 ? equality.weight ? 1) indicating how strongly the equality.H and equality.G is imposed. A value of 0 (zero) does not impose the constraint at all, whereas a value of 1 (one) fixes the constraint.

**leftprod**: [0], If the loading matrix,**B**is of size JxR, the leftprod is a matrx**G**of size JxM. The loading**B**is then constrained to be of the form**B = GH**, where only**H**is updated. For example,**G**may be a certain JxJ subspace, if the loadings are to be within a certain subspace.

**rightprod**: [0], If the loading matrix,**B**is of size JxR, the rightprod is a matrx**G**of size MxR. The loading**B**is then constrained to be of the form**B**=**HG**, where only**H**is updated. For example, if rightprod is [1 1 0;0 0 1], then the first two components in**B**are forced to be the same.

**iterate_to_conv**: [0], Usually the constraints are imposed within an iterative algorithm. Some of the constraints use iterative algorithms themselves. Setting iterate_to_conv to one, will force the iterative constraint algorithms to continue until convergence.

**timeaxis**: [], This field (if supplied) is used as the time axis when fitting loadings to a function (e.g. see exponential). Therefore, it must have the same number of elements as one of the loading vectors for this mode.

**description**: [1x1592 char],

If the constraint in a mode is set as fixed, then the loadings of that mode will not be updated, hence the initial loadings stay fixed.

### See Also

conload, corcondia, coreanal, corecalc, datahat, gram, mpca, outerm, parafac, parafac2, tld, unfoldm