Constrainfit and Solo Predictor Release Notes: Difference between pages

From Eigenvector Research Documentation Wiki
(Difference between pages)
Jump to navigation Jump to search
imported>Rasmus
No edit summary
 
imported>Scott
No edit summary
 
Line 1: Line 1:
===Purpose===
==Release Notes==


Finds '''A''' minimizing ||X-A*B'|| subject to constraints, given the small matrices ('''X''' ' '''B''') and ('''B''' ' '''B''')
The following are the release notes (i.e. whats new / whats changed) for the current and past versions.


===Synopsis===
*[[Release_Notes_Solo_Predictor_Version_3_9_4|Version 3.9.4]] - released February 2018
*[[Release_Notes_Solo_Predictor_Version_3_9|Version 3.9]] - released September 2017
*[[Release_Notes_Solo_Predictor_Version_3_8_1|Version 3.8.1]] - released September 2016
*[[Release_Notes_Solo_Predictor_Version_3_8|Version 3.8]] - released August 2016
*[[Release_Notes_Solo_Predictor_Version_3_7_1|Version 3.7.1]] - released April 2016
*[[Release_Notes_Solo_Predictor_Version_3_7|Version 3.7]] - released December 2015
*[[Release_Notes_Solo_Predictor_Version_3_6_1|Version 3.6.1]] - released August 2015
*[[Release_Notes_Solo_Predictor_Version_3_6|Version 3.6]] - released June 2015
*[[Release_Notes_Solo_Predictor_Version_3_5_1|Version 3.5.1]] - released October 2014
*[[Release_Notes_Solo_Predictor_Version_3_5|Version 3.5]] - released October 2014
*[[Release_Notes_Solo_Predictor_Version_3_1_1|Version 3.1.1]] - released July 2014
*[[Release_Notes_Solo_Predictor_Version_3_1|Version 3.1]] - released June 2014
*[[Release_Notes_Solo_Predictor_Version_3_0|Version 3.0]] - released January 2014
* Version 2.9 - released May 2013
*[[Release_Notes_Solo_Predictor_Version_2_8_2|Version 2.8.2]] - released December 2012
*[[Release_Notes_Solo_Predictor_Version_2_7_2|Version 2.7.2]] - released August 2012
*[[Release_Notes_Solo_Predictor_Version_2_7|Version 2.7]] - released March 2012
*[[Release_Notes_Solo_Predictor_Version_2_5_2|Version 2.5.2]] - released January 2012
*[[Release_Notes_Solo_Predictor_Version_2_5|Version 2.5]] - released October 2011
*[[Release_Notes_Solo_Predictor_Version_2_4_1|Version 2.4.1]] - released April 2011
*[[Release_Notes_Solo_Predictor_Version_2_4|Version 2.4]] - released March 2011
*[[Release_Notes_Solo_Predictor_Version_2_3_1|Version 2.3.1]] - released November 2010
*[[Release_Notes_Solo_Predictor_Version_2_3|Version 2.3]] - released October 2010
*[[Release_Notes_Solo_Predictor_Version_2_2_1|Version 2.2.1]] - released March 2010
*[[Release_Notes_Solo_Predictor_Version_2_2|Version 2.2]] - released February 2010
*[[Release_Notes_Solo_Predictor_Version_2_0|Version 2.0]] - released June 2009
*[[Release_Notes_Solo_Predictor_Version_1_0_2|Version 1.0.2]] - released Dec. 2008
*[[Release_Notes_Solo_Predictor_Version_1_0_1|Version 1.0.1]] - released Jan. 2008
*Version 1.0 - released Oct. 2007


:  [A]=constrainfit(XB,BtB,Aold);  % Unconstrained
==Solo_Predictor and PLS_Toolbox/Solo Compatibility Table==


'''Setting global constraints on A'''
The Solo_Predictor version in the first column is the minimum required to use a model from the [[Release_Notes_PLS_Toolbox_and_Solo|PLS_Toolbox/Solo version]] listed in the second column. A given Solo_Predictor version can read models from any ''older'' version of PLS_Toolbox/Solo (read each line as "Solo_Predictor >= ___ for PLS_Toolbox/Solo <= ___".)
:  opt = constrainfit('options');
:  opt.type='nonnegativity';
:  [A]=constrainfit(XB,BtB,Aold,opt); % Nonnegative


: '''Setting constraints on just one column of A'''
<table border="1" cellpadding="2" cellspacing="0" style="{font-face: monospaced}">
:  opt = constrainfit('options');
  <tr>
:  opt.type='columnwise';
    <td>
:  opt.columnconstraints={0;2;0}; % If three columns
      <div align="center"><b>Solo_Predictor</b></div>
:  [A]=constrainfit(XB,BtB,Aold,opt); % Second column unimodal
    </td>
    <td>
      <div align="center"><b>PLS_Toolbox/Solo</b></div>
    </td>
  </tr>


===Description===
  <tr>
    <td>
      <div align="center">3.9.3</div>
    </td>
    <td>
      <div align="center">8.6</div>
    </td>
  </tr>


CONSTRAINTFIT solves the least squares problem behind bilinear, trilinear and other multilinear models. Assuming a model '''X''' = '''A'''*'''B''' ' and assuming that '''X''' and '''B''' are known, the least squares estimate of '''A''' is obtained. Rather than using '''X''' and '''B''' this algorithm uses the cross product matrices ('''X''' ' '''B''') and ('''B''' ' '''B''') which are generally smaller and less memory-demanding especially in multi-way models.
  <tr>
    <td>
      <div align="center">3.9</div>
    </td>
    <td>
      <div align="center">8.5</div>
    </td>
  </tr>


CONSTRAINFIT can do a number of general types of regression problems such as nonnegativity-constrained regression, regression with column-orthogonality of '''A''' etc. These constraints are simply set in the option field 'type', e.g. option.type='nonnegativity'. Thus, for most problems, only the 'type' field needs to be set. CONSTRAINFIT will provide a least squares solution to most of these problems.
  <tr>
    <td>
      <div align="center">3.8</div>
    </td>
    <td>
      <div align="center">8.2</div>
    </td>
  </tr>


CONSTRAINFIT can also find '''A''' subject to different constraints on different columns. In this case, the update of '''A''' will be an improvement of the initially provided estimate '''Aold''' though not necessarilly the least squares solution. As CONSTRAINFIT is used inside iterative algorithms, an improvement is sufficient to guarantee overall convergence.
  <tr>
    <td>
      <div align="center">3.7</div>
    </td>
    <td>
      <div align="center">8.1</div>
    </td>
  </tr>


  <tr>
    <td>
      <div align="center">3.6</div>
    </td>
    <td>
      <div align="center">8.0</div>
    </td>
  </tr>


====Inputs====
  <tr>
* '''XB''' = This is the matrix '''X''' ' '''B'''.
    <td>
* '''BtB''' = This is the matrix '''B''' ' '''B'''.
      <div align="center">3.5</div>
* '''Aold''' = An initial estimate of '''A'''.
    </td>
    <td>
      <div align="center">7.9</div>
    </td>
  </tr>


====Optional Inputs====
  <tr>
* '''options''' = provides definitions for which type of constraint to impose.
    <td>
      <div align="center">3.1</div>
    </td>
    <td>
      <div align="center">7.8</div>
    </td>
  </tr>


====Outputs====
  <tr>
* '''A''' = The improved estimate of '''A'''.
    <td>
      <div align="center">3.0</div>
    </td>
    <td>
      <div align="center">7.5</div>
    </td>
  </tr>


===Options===
  <tr>
    <td>
      <div align="center">2.9</div>
    </td>
    <td>
      <div align="center">7.3</div>
    </td>
  </tr>


options = a structure array with the following fields:
  <tr>
    <td>
      <div align="center">2.8</div>
    </td>
    <td>
      <div align="center">7.0</div>
    </td>
  </tr>


* '''type''': [ {'unconstrained'} | 'nonnegativity' | 'unimodality' | 'orthogonality' | 'columnorthogonal' | 'equality' | 'exponential' | 'rightprod' | 'columnwise']
  <tr>
 
    <td>
 
      <div align="center">2.7</div>
::: provides quick access to most important settings
    </td>
::: 'unconstrained'   - do unconstrained fit of '''A'''
    <td>
::: 'nonnegativity'   - '''A''' is all nonnegative
      <div align="center">6.7</div>
::: 'unimodality'     - '''A''' has unimodal columns ''and'' is nonnegative
    </td>
::: 'orthogonality'  - '''A''' is orthogonal ('''A''' ' '''A''' = '''I''')
   </tr>
::: 'columnorthogonal'- '''A''' has orthogonal columns ('''A''' ' '''A''' = diagonal)
   <tr>
::: 'equality'        - columns in '''A''' are subject to equality constraints. Useful for e.g. imposing closure (see settings under options.equality below)
     <td>
::: 'exponential'     - Columns are mono-exponentials
      <div align="center">2.5</div>
::: 'rightprod'       - Fitting '''A''' subject to being of the form '''F*D''', where '''D''' is predefined (must be set in options.advanced.linearconstraints.matrix). if imposed then columnwise constraints (see below) are applied to the columns of '''F''' rather than '''A'''. Hence options.columnconstraints must be set appropriately.
    </td>
::: 'columnwise'      - A has other constraints than the above. These have to be defined in options.columnconstraints (see below).
     <td>
 
       <div align="center">6.5</div>
* '''columnconstraints''': cell where element f defines constraints on column f (only applicable if options.type = 'columnwise').
    </td>
 
  </tr>
::: columnconstraints is a cell vector {f1,f2,f3, ... fF}. Each element f1, f2, etc. corresponds to one column of A. f1 defines constraints on the first column of A etc. Each constraint on a column is defined by a number. For example if f1 is 2, then nonnegativity is imposed on the first column (see definitions below). If f1 = [2 4], then first nonnegativity is imposed and then smoothness. The following constraints are available on individual columns
  <tr>
::: a = 0 : Unconstrained
    <td>
::: a = 1 : Nonnegativity
      <div align="center">2.4</div>
::: a = 2 : Unimodality
    </td>
::: a = 3 : Inequality (every element >= scalar). Scalar has to be in options.inequality.scalar. This is a vector of size F, one scalar for each factor
    <td>
::: a = 4 : Smoothness. options.smoothness.operator can be used to hold operator (for speeding up. Won't have to be estimated each time. options.smoothness.alpha (0<alpha<1). Setting to zero means no smoothness while setting to 1 means high degree of smoothness.
      <div align="center">6.2</div>
:::  a = 5 : Fixed elements. The elements that are fixed are defined in options.fixed. ::: a = 6 : Not applicable
    </td>
::: a = 7 : Approximate unimodality. See options.unimodality.weight
  </tr>
::: a = 8 : Normalize the loading vectors to norm one
  <tr>
::: a = 20: Functional constraint. Using simple pre- or userdefined functions, any functional constraint can be imposed on individual columns. For example, that one column is exponential. Functional constraints require that a function is written (type HELP FITGAUSS for an example).  
    <td>
 
      <div align="center">2.3</div>
</pre>
    </td>
 
    <td>
As an example it will be shown how to set up the use of fitting the second loading vector as being Gaussian:
      <div align="center">6.0</div>
    </td>
NumberFactors=3;
  </tr>
options.functional=cell(NumberFactors,1);
  <tr>
ToFix = 2; % This constraint is for the second column
    <td>
options.functional{ToFix}.functionhandle = @fitgauss;
      <div align="center">2.2</div>
% Define starting parameters
    </td>
center = 100;width = 100;height = .1;
    <td>
options.functional{ToFix}.parameters = [center width height];
      <div align="center">5.8</div>
options.functional{ToFix}.additional=[]; % no additional input
    </td>
<pre>
  </tr>
 
  <tr>
    <td>  
When a column has more than one constraint these are generally imposed sequentially starting with the first one in options.columnconstraint. For most constraints, the order of constraints will not be important. Advise is to input constraints with smaller numbers first.
      <div align="center">2.1</div>
    </td>
 
    <td>
* '''inequality''' : Defines a cutoff. If inequality is defined in columnwise constraints, all elements of that column will be > options.inequality.scalar. Thus, when set to zero, nonnegativity is imposed.
      <div align="center">5.5</div>
* '''nonnegativity''': defines which algorithm to use for imposing nonnegativity when options.type = 'nonnegativity'. If set to 0, the default NNLS algorithm is used. If set to 1, a faster columnwise update is used which only improves the current least squares fit, if set to 2, an ad hoc approach is used where '''A''' is estimated in a least squares sense and then negative numbers are set to zero. This will not provide a well-defined solution in terms of the least squares loss function. If set to 3, the NMF algorithm is used. This requires that all elements of the data array are nonnegative in order to work properly.
    </td>
* '''smoothness''': defines how much smoothness is imposed when smoothness is imposed as a columnconstraint. smoothness.alpha is a number between 0 (no smoothness) and 1 (full smoothness)
  </tr>
* '''fixed''': options.fixed.values is a matrix of the same size as the loading matrix ('''A''') with the actual numbers to be fixed in the positions corresponding to the position in A. The remaining positions must be NaN. The degree to which elements are fixed is set in options.fixed.weight (0<weight<1). Zero means not imposed whereas one means completely fixed.
  <tr>
* '''advanced''': In the field advanced.linearconstraints, settings for options.type = 'rightprod' are set. If '''A''' is IxF, then linearconstraint.matrix must be and SxF matrix '''D''''. '''A''' is then found as '''F*D'''. E.g. if '''A''' has three columns, set the predefined matrix D = [1 1 0; 0 0 1], then the first and second of the three columns in A will be identical (F*D where F is to be estimated).  
    <td>
* '''equality''': Settings for using options.type = 'equality'. Two fields are held in equality, C and d. When imposed, CONSTRAINFIT solves for loading matrix A subject to A(i,:)*C' = d for all i. Hence if you want to impose closure and have three factors, set C=[1 1 1] and d=1.
      <div align="center">2.0</div>
 
    </td>
* '''unimodality''': Set weight in options.unimodality.weight. weight==1: exact unimodality. weight==0: no unimodality
    <td>
* '''functional''': For functional constrains (see above)
      <div align="center">5.2</div>
* '''definitions''': @optiondefs
    </td>
 
  </tr>
===Example===
  <tr>  
 
    <td>  
 
      <div align="center">1.0.2</div>
<pre>
    </td>
>>This is an example on the use of CONSTRAINFIT in PARAFAC
    <td>
% Make a noisy dataset such that PARAFAC gives noisy loadings
      <div align="center">5.0</div>
load aminoacids
    </td>
x = X.data;
  </tr>
x = x+randn(size(x))*100;
  <tr>
 
    <td>
% define parafac options
      <div align="center">1.0.1</div>
op=parafac('options');
    </td>
 
    <td>
% set constraints in second mode to be defined columnwise
      <div align="center">4.2</div>
op.constraints{2}.type='columnwise';
    </td>
 
  </tr>
% Define that first column is smooth, second and third unconstrained
  <tr>
op.constraints{2}.columnconstraints={4 0 0};
    <td>
 
      <div align="center">1.0</div>
% Fit model
    </td>
model = parafac(x,3,op);
    <td>
 
      <div align="center">2.1 - 4.1</div>
Note how the first loading in the second mode is more smooth than the rest
    </td>
 
  </tr>
if needed smoothness can be turned up (to one) and down (to zero) using
</table>
op.constraints{2}.smoothness.alpha=0.6
 
</pre>
 
===See Also===
 
[[parafac]]

Revision as of 14:51, 23 February 2018

Release Notes

The following are the release notes (i.e. whats new / whats changed) for the current and past versions.

Solo_Predictor and PLS_Toolbox/Solo Compatibility Table

The Solo_Predictor version in the first column is the minimum required to use a model from the PLS_Toolbox/Solo version listed in the second column. A given Solo_Predictor version can read models from any older version of PLS_Toolbox/Solo (read each line as "Solo_Predictor >= ___ for PLS_Toolbox/Solo <= ___".)

Solo_Predictor
PLS_Toolbox/Solo
3.9.3
8.6
3.9
8.5
3.8
8.2
3.7
8.1
3.6
8.0
3.5
7.9
3.1
7.8
3.0
7.5
2.9
7.3
2.8
7.0
2.7
6.7
2.5
6.5
2.4
6.2
2.3
6.0
2.2
5.8
2.1
5.5
2.0
5.2
1.0.2
5.0
1.0.1
4.2
1.0
2.1 - 4.1