Als sit: Difference between revisions

From Eigenvector Research Documentation Wiki
Jump to navigation Jump to search
(Created page with "===Purpose=== ALS_SIT Alternating least squares with shift invariant tri-linearity ===Synopsis=== :model = als_sit(x,ncomp); % identifies model with default optio...")
 
No edit summary
 
Line 5: Line 5:
===Synopsis===
===Synopsis===


:model  = als_sit(x,ncomp);        % identifies model with default options (calibration step)
:[model,xo]   = als_sit(x,ncomp);        % identifies model with default options (calibration step)
:model  = als_sit(x,ncomp,options); % identifies model (calibration step)
:[model, xo]   = als_sit(x,ncomp,options); % identifies model (calibration step)
:options = als_sit('options');      % returns a default options structure
:options = als_sit('options');      % returns a default options structure
:pred    = als_sit(xnew,model);      % find scores for new samples given old model
:pred    = als_sit(xnew,model);      % find scores for new samples given old model
Line 12: Line 12:


===Description===
===Description===
ALS_SIT employs an MCR-like model to employ a tri-linearity constraint to factors that may shift (e.g., GC/LC elution profiles). See:  
ALS_SIT employs an MCR-like model to employ a tri-linearity constraint to factors that may shift (e.g., GC/LC elution profiles). See:  
:Schneide, P.-A., Bro, R., Gallagher, N., "Shift-invariant tri-linearity (SIT) - A new model for resolving untargeted GC-MS data," J Chemom (2023).
:Schneide, P.-A., Bro, R., Gallagher, N., "Shift-invariant tri-linearity (SIT) - A new model for resolving untargeted GC-MS data," J Chemom (2023).
Line 24: Line 25:


* '''x''' = multi-way array to be decomposed
* '''x''' = multi-way array to be decomposed
::If '''X''' is a ''I''x''J''x''K'' array (all ''K'' slabs have similar size) then this is similar to an input for PARAFAC.
::If '''x''' is a ''I''x''J''x''K'' array (all ''K'' slabs have similar size) then this is similar to an input for PARAFAC.
::If the ''K'' slabs have different size then '''X''' is input as a cell array e.g., X{1} = X1; X{2} = X2; (note the curly brackets). Mode 1 of the X{k} can shift and/or have different dimensions [i.e., size(X{k},1)] can vary, but Mode dimension [size(X{k},2] is the same for all X{k}, k=1,...,K.
::If the ''K'' slabs have different size then '''x''' is input as a cell array e.g., x{1} = X1; x{2} = X2; (note the curly brackets). Mode 1 of the x{k} can shift and/or have different dimensions [i.e., size(x{k},1)] can vary, but Mode dimension [size(x{k},2] is the same for all x{k}, k=1,...,K.
* '''ncomp''' = the number of components to estimate
* '''ncomp''' = the number of components to estimate


The outputs are the estimated matrices '''C''', (c), (''M'' by ''K'') and '''S''', (s), (''K'' by ''N''). For a typical decomposition, (c) is a matrix of contributions and (s) is a matrix of spectra. The function
====Outputs====
* '''model'''     = standard model object, or
* '''pred'''      = standard prediction object.
::model.sitsmodel has the following fields (see SHIFTMAP):
::* '''p''' = (''Np''x''K'') loadings: ''p'' = ''Pb'' for SIST.
::* '''a0''' = standard phase spectrum.
::* '''t''' = ''M''x''K'' scores: Tb for SIST.
* '''xo''' = bi-linear form of input(x) used w/in ALS_SIT.


===Options===


===Options===
options = structure array with the following fields:


====Display and Plotting====
====Display and Plotting====
* '''display''':  [ 'off' | {'on'} ]  governs level of display to command window.
* '''display''':  [ 'off' | {'on'} ]  governs level of display to command window.
* '''plots''':  [ 'none' | {'final'} ]  governs level of plotting.
* '''plots''':  [ 'none' | {'final'} ]  governs level of plotting.
* '''waitbar''': [ 'off' | 'on' | {'auto'} ] governs use of waitbar,
* '''waitbar''': [ 'off' | 'on' | {'auto'} ] governs use of waitbar,


====Convergence and Conditions====
====Convergence and Conditions====


* '''normorder''': [ {2} ] order of normalization applied to spectra (required to assure convergence). Typical settings are:
* '''ittol''': [ {1e-8} ]  relative change in model residuals,
::1  = normalize to unit area (1-norm)
* '''itolabs''': [ {1e-6} ]  absolute change in model residuals,
::2  = normalize to unit length (2-norm) {default}
::inf = normalize to unit maximum (inf-norm)
:This normalization is only applied to non-equality constrained components as these are the ones with a multiplicative ambiguity.
 
* '''condition''': [{'none'}| 'norm' ] type of conditioning to perform on S and C before each regression step. 'norm' conditions each spectrum or contribution to its own norm. Conditioning can help stabilize the regression whenfactors are significantly different in magnitude.
 
* '''tolc''': [ {1e-5} ]  tolerance on non-negativity for contributions,
 
* '''tols''': [ {1e-5} ]  tolerance on non-negativity for spectra,
 
* '''ittol''': [ {1e-8} ]  convergence tolerance,
 
* '''itmax''': [ {100} ]  maximum number of iterations,
* '''itmax''': [ {100} ]  maximum number of iterations,
* '''timemax''': [ {3600} ]  maximum time for iterations (s),


* '''timemax''': [ {3600} ]  maximum time for iterations,
====Shiftmap Options====
 
* '''shiftmap''' = SHIFTMAP options, structure array with the following fields:
 
:: (see SHIFTMAPfor a complete listing)
===Examples===
:* '''ncomp''' = 0.95 {default} scalar number of PCs, ''K'', for PCA of the amplitude spectra in SIST or SIT.
 
:: If 0<ncomp<1 then this is fraction variance captured,
To decompose a matrix (x) without non-negativity constraints use:
:: if ncomp>1 this is the number of PCs, or
 
:: if ncomp==1, then the algoritm is SIT.
:options = als('options');
:: Note that (ncomp) can be a 1xK vector allowing a
 
:: different number of PCs for each of the K factors.
:options.ccon = 'none';
:: (ncomp) is not used for factors w/ sitconstraint = 0.
 
:* '''options.als''' = ALS options, structure array with the following fields:
:options.scon = 'none';
:: (see ALS for a complete listing)
:* '''itmax''' = 2 {default} maximum number of iterations in the alternating constrained least squares algorithm.


===See Also===
===See Also===


[[als]], [[mcr]], [[parafac]], [[parafac2]], [[shiftmap]], [[tld]], [[tucker]], [[unfoldm]]
[[als]], [[mcr]], [[parafac]], [[parafac2]], [[shiftmap]], [[tld]], [[tucker]], [[unfoldm]]

Latest revision as of 16:00, 8 December 2023

Purpose

ALS_SIT Alternating least squares with shift invariant tri-linearity

Synopsis

[model,xo] = als_sit(x,ncomp);  % identifies model with default options (calibration step)
[model, xo] = als_sit(x,ncomp,options); % identifies model (calibration step)
options = als_sit('options');  % returns a default options structure
pred = als_sit(xnew,model);  % find scores for new samples given old model
als_sit demo

Description

ALS_SIT employs an MCR-like model to employ a tri-linearity constraint to factors that may shift (e.g., GC/LC elution profiles). See:

Schneide, P.-A., Bro, R., Gallagher, N., "Shift-invariant tri-linearity (SIT) - A new model for resolving untargeted GC-MS data," J Chemom (2023).
Schneide, P.-A., Bro, R., Gallagher, N., "Soft shift-invariant tri-linearity: modelling shifts and shape changes in gas-chromatography coupled mass spectrometry," [in progress] (2023).

It can also be use for non-shifting profiles:

Tauler, R., Marques, I., Casassas, E., J Chemom, 12(1), 55–75 (1998),

The convention for ALS_SIT is that samples are in the last mode and the shifting profiles are in the first mode. E.g. if the samples for input (x) are in Mode 1, and the shifting mode is Mode 2, the call to ALS_SIT is

model = als_sit(permute(x,[2,3,1]),ncomp);

Inputs

  • x = multi-way array to be decomposed
If x is a IxJxK array (all K slabs have similar size) then this is similar to an input for PARAFAC.
If the K slabs have different size then x is input as a cell array e.g., x{1} = X1; x{2} = X2; (note the curly brackets). Mode 1 of the x{k} can shift and/or have different dimensions [i.e., size(x{k},1)] can vary, but Mode dimension [size(x{k},2] is the same for all x{k}, k=1,...,K.
  • ncomp = the number of components to estimate

Outputs

  • model = standard model object, or
  • pred = standard prediction object.
model.sitsmodel has the following fields (see SHIFTMAP):
  • p = (NpxK) loadings: p = Pb for SIST.
  • a0 = standard phase spectrum.
  • t = MxK scores: Tb for SIST.
  • xo = bi-linear form of input(x) used w/in ALS_SIT.

Options

options = structure array with the following fields:

Display and Plotting

  • display: [ 'off' | {'on'} ] governs level of display to command window.
  • plots: [ 'none' | {'final'} ] governs level of plotting.
  • waitbar: [ 'off' | 'on' | {'auto'} ] governs use of waitbar,

Convergence and Conditions

  • ittol: [ {1e-8} ] relative change in model residuals,
  • itolabs: [ {1e-6} ] absolute change in model residuals,
  • itmax: [ {100} ] maximum number of iterations,
  • timemax: [ {3600} ] maximum time for iterations (s),

Shiftmap Options

  • shiftmap = SHIFTMAP options, structure array with the following fields:
(see SHIFTMAPfor a complete listing)
  • ncomp = 0.95 {default} scalar number of PCs, K, for PCA of the amplitude spectra in SIST or SIT.
If 0<ncomp<1 then this is fraction variance captured,
if ncomp>1 this is the number of PCs, or
if ncomp==1, then the algoritm is SIT.
Note that (ncomp) can be a 1xK vector allowing a
different number of PCs for each of the K factors.
(ncomp) is not used for factors w/ sitconstraint = 0.
  • options.als = ALS options, structure array with the following fields:
(see ALS for a complete listing)
  • itmax = 2 {default} maximum number of iterations in the alternating constrained least squares algorithm.

See Also

als, mcr, parafac, parafac2, shiftmap, tld, tucker, unfoldm

Retrieved from "https://www.wiki.eigenvector.com/index.php?title=Als_sit&oldid=12155"