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

• initval = if 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),

• options = discussed below.

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² 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