Tucker: Difference between revisions

From Eigenvector Research Documentation Wiki
Jump to navigation Jump to search
imported>Jeremy
(Importing text file)
 
imported>Jeremy
 
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
===Purpose===
===Purpose===
TUCKER analysis for n-way arrays.
TUCKER analysis for n-way arrays.
===Synopsis===
===Synopsis===
:model = tucker(x,ncomp,''initval,options'')          %tucker model
:model = tucker(x,ncomp,''initval,options'')          %tucker model
:pred  = tucker(x,model)                          %application
:pred  = tucker(x,model)                          %application
:options = tucker('options')
:tucker(model)               % provides a table of variances per component.
 
===Description===
===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:
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.
* x = the multi-way array to be decomposed and
 
* ncomp = the number of components to estimate, or
====Inputs====
* model =  a TUCKER model structure.
 
OPTIONAL INPUTS:
* '''x''' = the multi-way array to be decomposed and
* ''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),
* '''ncomp''' = the number of components to estimate, or
*'' options'' =  discussed below.
 
OUTPUTS:
* '''model''' =  a TUCKER model structure.
* model = a structure array with the following fields:
 
* modeltype: 'TUCKER',
Note that when specifying (ncomp), it must be a vector with K elements specifying the number of components for each mode.
* datasource: structure array with information about input data,
 
* date: date of creation,
====Optional Inputs====
* time: time of creation,
 
* info: additional model information,
* '''''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,  
* 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,
:: 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),
* tsqs: cell array with T<sup>2</sup> values for each mode,
 
* ssqresiduals: cell array with sum of squares residuals for each mode,
*'''''options''''' =  discussed below.
* description: cell array with text description of model, and
 
* detail: sub-structure with additional model details and results.
====Outputs====
* pred = is a structure array, similar to model, that contains prediction results for new data fit to the TUCKER model.
 
* '''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<sup>2</sup> 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===
* ''options'' =  a structure array with the following fields:
 
* display: [ {'on'} | 'off' ], governs level of display,
''options'' =  a structure array with the following fields:
* plots: [ {'final'} | 'all' | 'none' ], governs level of plotting,
 
* weights: [], used for fitting a weighted loss function (discussed below),
* '''display''': [ {'on'} | 'off' ], governs level of display,
* stopcrit: [1e-6 1e-6 10000 3600] defines the stopping criteria as [(relative tolerance) (absolute tolerance) (maximum number of iterations) (maximum time in seconds)],
* '''plots''': [ {'final'} | 'all' | 'none' ], governs level of plotting,
* init: [ 0 ], defines how parameters are initialized (see PARAFAC),
* '''waitbar''': [ {'on'} | 'off' ], governs use of waitbar while calculating,
* line: [ 0 | {1}] defines whether to use the line search {default uses it},
* '''weights''': [], used for fitting a weighted loss function (discussed below),
* algo: this option is not yet active,
* '''stopcrit''': [1e-6 1e-6 10000 3600] defines the stopping criteria as [(relative tolerance) (absolute tolerance) (maximum number of iterations) (maximum time in seconds)],
* blockdetails: 'standard'
* '''init''': [ 0 ], defines how parameters are initialized (see PARAFAC),
* missdat: this option is not yet active,
* '''line''': [ 0 | {1}] defines whether to use the line search {default uses it},
* samplemode: [1], defines which mode should be considered the sample or object mode and
* '''algo''': this option is not yet active,
* constraints: {4x1 cell}, defines constraints on parameters (see PARAFAC). The first three cells define constraints on loadings whereas the last cell defines constraints on the core.
* '''blockdetails''': 'standard'
The default options can be retreived using: options = tucker('options');.
* '''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'''<sup>T</sup> = '''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===
===See Also===
[[datahat]], [[gram]], [[mpca]], [[outerm]], [[parafac]], [[parafac2]], [[tld]], [[unfoldm]]
 
[[conload]], [[corcondia]], [[coreanal]], [[corecalc]], [[datahat]], [[gram]], [[mpca]], [[outerm]], [[parafac]], [[parafac2]], [[tld]], [[unfoldm]]

Latest revision as of 16:03, 22 February 2013

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 T2 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 GAT = 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