Flucut: Difference between revisions

From Eigenvector Research Documentation Wiki
Jump to navigation Jump to search
imported>Scott
No edit summary
imported>Rasmus
m (→‎Options: Fixed so that the help says that Interpolation is on per default)
 
(20 intermediate revisions by 4 users not shown)
Line 1: Line 1:
===Purpose===
===Purpose===


Remove scatter from fluorescence EEM data.
Corrects fluorescence EEM data for Rayleigh and Raman scattering.


===Synopsis===
===Synopsis===


:code here
:Xnew = flucut(X,Rayl1,Rayl2,options);


===Description===
===Description===


FLUCUT inserts a mixture of NaN and 0 values outside the data area of interest in an EEM (Excitation-Emission Matrix). FLUCUT may also be used to generate weights that can be used for deweighting scatter areas.
FLUCUT Removes Rayleigh (and possibly Raman) scattering by setting these regions to be missing. FLUCUT does this by inserting NaN and 0 values in Excitation-Emission Matrices (EEMs) where the Rayleigh bands bands are. Alternatively, FLUCUT may also be used to generate weights that can be used for deweighting (instead of eliminating) these regions. FLUCUT can also be used to subtracts a blank to remove Raman and correct for inner filter effects.
====Inputs====
 
* '''first''' = first input is this.
Scattering includes bands around the primary and secondary scattering emission==excitation [First order Rayleigh - input Rayl1] and emis==2*exci [Second order Rayleigh - input Rayl2].
 
The following actions are performed by FLUCUT:
Bands around the Rayleigh scatter are set to NaN to avoid bias in least-squares modelling. This is controlled by the options (Rayl1) and (Rayl2).
 
Zeros can be included below the primary scatter and above the secondary scatter to improve speed and robustness in subsequent PARAFAC modeling. This is defined using the options (LowZero) and (TopZero).


* '''X''' = X-array of EEMs. X is size IxJxK, where I is number of samples, J emissions and K excitations. X has to be a DataSet object where the axisscales contain wavelengths where X.axisscale{2} corresponds to emissions (emi) in nm and X.axisscale{3} corresponds to excitations (exci) in nm.
Bands around the first and possibly second order Raman signal can be set to missing by using the Raman related parts of the (options) input.


* '''LowZero''' = Wavelength (nm): X(emi < exci-LowZero) are set to zero. Zeros here are good for speeding up, but can lead to artifacts if the zeros are too close to the emi==exci line. Use LowMiss.
Alternatively FLUCUT may also be used to generate weights that can be used for deweighting scatter areas [see input (options)].
* '''LowMiss''' = Wavelength (nm): the region where emi <= exci+LowMiss(1) are set to missing (i.e., NaN) to remove scatter. If LowMiss is a 2 element vector, then only the region down to emi >= exci-LowMiss(2) are also set to missing. However, the zeros set by LowZero supercede the missing setting.
* '''TopZero''' = nm above emi==2*exci which is set to zero {default is NaN meaning no zeros (to avoid second order signal to be biased to be zero)}.
* '''TopMiss''' = Similar to LowMiss but for emi==2*exci.


====Inputs====
* '''X''' = DataSet object containing an array of EEMs. (X) is size IxJxK, where I is number of samples, J emissions and K excitations. (X) must be a DataSet object with appropriate axisscales: X.axisscale{2} corresponds to emissions (emi) in nm and X.axisscale{3} corresponds to excitations (exci) in nm.
* '''Rayl1''' = 1 or 2 element vector describing filtering of the band about the Rayleigh line (the 1:1 line where emission=excitation) (Rayl1(1)) [nm]: defines to how far ABOVE the 1:1 Rayleigh line to mark as "missing" (i.e. NaN) in each emission spectrum. All emission wavelengths shorter than this value will be marked as missing (down to Ex-Rayl1(2)) (Rayl1(2)) [nm]: defines how far BELOW the 1:1 Rayleigh line to mark as missing. If omitted, all emission wavelengths lower than ex+Rayl1(1) will be marked as missing. If Rayl1==NaN, then it is not used. Zeros set by the LowZero option (see below) supercede the (Rayl1(2)) missing setting.
* '''Rayl2''' = 1 or 2 element vector to describe the band about emis==2*exci. Usage is similar to (Rayl1).
<br>
'''NOTE''': In general, for all the above, setting the input to NaN, implies that the functionality is not imposed.
'''NOTE''': In general, for all the above, setting the input to NaN, implies that the functionality is not imposed.
<br>
'''NOTE''': The following inputs govern how data are set to missing and zero.
'''NOTE''': The following inputs govern how data are set to missing and zero.
: '''Rayl1''' is used to account for first rder Rayleigh scatter, and
: '''Rayl2''' is used to accound for second order scatter.


: '''LowZero''' and '''LowMiss''' are used to account for Rayleigh scatter, and
: '''TopZero''' and '''TopMiss''' are used to accound for 2nd order scatter.
====Optional Inputs====
* '''MakeWts''' = If 0 or [] empty, no weights are calculated. Otherwise, weights will be given that can be used to downweight areas of scatter e.g., in PARAFAC models. The weights will be held in the output dataset field 'userdata'. {default = 0, do not make weights}
* '''plots''' = governs plotting. If 0 not plots are made, default == 1.
====Outputs====
====Outputs====
* '''Xnew''' =  New X-array with inserted NaN (for missing) and 0-values. Columns with only missing values are removed.
* '''Xnew''' =  New X-array with inserted NaN (for missing) and 0-values. Columns with only missing values are removed.
===Options===
''options'' =  a structure array  the following fields:
* '''LowZero''': [ {'off'} | 'on' ]: If 'on', the values below Rayleigh are set to zero. Zeros well below Rayleigh are better than missing values and stabilizes the model. It can lead to bias and artifacts if the zeros are too close to the Rayleigh scatter ridge.
* '''TopZero''': [ {'off'} | 'on' ]: If 'on', the values above the 2nd order Rayleigh are set to zero.
* '''Blank''':  If the option Blank is set to an integer, the corresponding sample will  assumed to  a blank (e.g. water). The sample will  subtracted from all the remaining samples and the blank itself will  soft-deleted (so that it is not used for fitting the model).
* '''Interpolate''': [ 'off' | {'on'} ]. If 'on', the missing values are replaced with interpolated values.
* '''RamanCorrect''': [ {'off'} | 'on' ]. Set to 'on' in order to also remove first order Raman scattering.
* '''RamanWidth''': [10] Width in nanometers that should  removed above and below the Raman scattering.
* '''RamanShift''': [3382] Raman shift (in wavenumbers) at which a solvent band should  expected and removed. Default is for the primary Raman water band. Alternatives are Hexane: 2990; THF: 3000; Methanol: 3090; Isopropanol: 3050
* '''MakeWts''': [ {'off'} | 'on' ] If 'on', weights will  given that can  used to downweight areas of scatter e.g., in PARAFAC models. The weights will  held in the output dataset field 'userdata'. {default = 'off', do not make weights}
* '''RemoveMissing''': [ {'off'} | 'on' ]. Governs removal of wavelengths which contain only missing data (all data removed).
* '''innerfilter.use''': [ {'off'} | 'on' ]. Correct for inner filter effects. Requires an absorption spectrum for each sample including the wavelength axis. The correction is performed in accordance  Lakowicz but allowing for varying pathlengths (set in innerfilter.options).
* '''innerfilter.options''': Settings for inner filter correction [not currently active].
* '''innerfilter.spectra''': Absorbance spectra covering from lowest excitation to highest emission. Extrapolation may occur if the range is not sufficient. Each row in innerfilter.spectra must contain the absorbance of the corresponding row in the data.
* '''innerfilter.wavelengths''': Wavelength for the spectra (a vector).
* '''plots''': [ 'off' | {'on'} ], governs level of plotting.
===Example===
===Example===


Line 36: Line 59:
load dorrit
load dorrit


Xnew = flucut(EEM,20,[20 20],NaN,NaN,0);
Xnew = flucut(EEM,20,[20 20]);


</pre>
</pre>

Latest revision as of 22:50, 5 June 2019

Purpose

Corrects fluorescence EEM data for Rayleigh and Raman scattering.

Synopsis

Xnew = flucut(X,Rayl1,Rayl2,options);

Description

FLUCUT Removes Rayleigh (and possibly Raman) scattering by setting these regions to be missing. FLUCUT does this by inserting NaN and 0 values in Excitation-Emission Matrices (EEMs) where the Rayleigh bands bands are. Alternatively, FLUCUT may also be used to generate weights that can be used for deweighting (instead of eliminating) these regions. FLUCUT can also be used to subtracts a blank to remove Raman and correct for inner filter effects.

Scattering includes bands around the primary and secondary scattering emission==excitation [First order Rayleigh - input Rayl1] and emis==2*exci [Second order Rayleigh - input Rayl2].

The following actions are performed by FLUCUT: Bands around the Rayleigh scatter are set to NaN to avoid bias in least-squares modelling. This is controlled by the options (Rayl1) and (Rayl2).

Zeros can be included below the primary scatter and above the secondary scatter to improve speed and robustness in subsequent PARAFAC modeling. This is defined using the options (LowZero) and (TopZero).

Bands around the first and possibly second order Raman signal can be set to missing by using the Raman related parts of the (options) input.

Alternatively FLUCUT may also be used to generate weights that can be used for deweighting scatter areas [see input (options)].

Inputs

  • X = DataSet object containing an array of EEMs. (X) is size IxJxK, where I is number of samples, J emissions and K excitations. (X) must be a DataSet object with appropriate axisscales: X.axisscale{2} corresponds to emissions (emi) in nm and X.axisscale{3} corresponds to excitations (exci) in nm.
  • Rayl1 = 1 or 2 element vector describing filtering of the band about the Rayleigh line (the 1:1 line where emission=excitation) (Rayl1(1)) [nm]: defines to how far ABOVE the 1:1 Rayleigh line to mark as "missing" (i.e. NaN) in each emission spectrum. All emission wavelengths shorter than this value will be marked as missing (down to Ex-Rayl1(2)) (Rayl1(2)) [nm]: defines how far BELOW the 1:1 Rayleigh line to mark as missing. If omitted, all emission wavelengths lower than ex+Rayl1(1) will be marked as missing. If Rayl1==NaN, then it is not used. Zeros set by the LowZero option (see below) supercede the (Rayl1(2)) missing setting.
  • Rayl2 = 1 or 2 element vector to describe the band about emis==2*exci. Usage is similar to (Rayl1).


NOTE: In general, for all the above, setting the input to NaN, implies that the functionality is not imposed.
NOTE: The following inputs govern how data are set to missing and zero.

Rayl1 is used to account for first rder Rayleigh scatter, and
Rayl2 is used to accound for second order scatter.

Outputs

  • Xnew = New X-array with inserted NaN (for missing) and 0-values. Columns with only missing values are removed.

Options

options = a structure array the following fields:

  • LowZero: [ {'off'} | 'on' ]: If 'on', the values below Rayleigh are set to zero. Zeros well below Rayleigh are better than missing values and stabilizes the model. It can lead to bias and artifacts if the zeros are too close to the Rayleigh scatter ridge.
  • TopZero: [ {'off'} | 'on' ]: If 'on', the values above the 2nd order Rayleigh are set to zero.
  • Blank: If the option Blank is set to an integer, the corresponding sample will assumed to a blank (e.g. water). The sample will subtracted from all the remaining samples and the blank itself will soft-deleted (so that it is not used for fitting the model).
  • Interpolate: [ 'off' | {'on'} ]. If 'on', the missing values are replaced with interpolated values.
  • RamanCorrect: [ {'off'} | 'on' ]. Set to 'on' in order to also remove first order Raman scattering.
  • RamanWidth: [10] Width in nanometers that should removed above and below the Raman scattering.
  • RamanShift: [3382] Raman shift (in wavenumbers) at which a solvent band should expected and removed. Default is for the primary Raman water band. Alternatives are Hexane: 2990; THF: 3000; Methanol: 3090; Isopropanol: 3050
  • MakeWts: [ {'off'} | 'on' ] If 'on', weights will given that can used to downweight areas of scatter e.g., in PARAFAC models. The weights will held in the output dataset field 'userdata'. {default = 'off', do not make weights}
  • RemoveMissing: [ {'off'} | 'on' ]. Governs removal of wavelengths which contain only missing data (all data removed).
  • innerfilter.use: [ {'off'} | 'on' ]. Correct for inner filter effects. Requires an absorption spectrum for each sample including the wavelength axis. The correction is performed in accordance Lakowicz but allowing for varying pathlengths (set in innerfilter.options).
  • innerfilter.options: Settings for inner filter correction [not currently active].
  • innerfilter.spectra: Absorbance spectra covering from lowest excitation to highest emission. Extrapolation may occur if the range is not sufficient. Each row in innerfilter.spectra must contain the absorbance of the corresponding row in the data.
  • innerfilter.wavelengths: Wavelength for the spectra (a vector).
  • plots: [ 'off' | {'on'} ], governs level of plotting.

Example

load dorrit

Xnew = flucut(EEM,20,[20 20]);

See Also

parafac

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