Class representing a spectral image generated from a Secondary Ion Mass Spectrometry instrument. More...
#include <SIMSpecImage.hpp>
Public Member Functions | |
| SIMSpecImage (const std::string &tofs, const std::string &coords="", const std::string &scans="", const std::string &props="", int SF=0, int K0=0, int nwin=66, int npp=0, uint32_t xBin=1, uint32_t yBin=1, uint32_t zBin=1, uint32_t tofsBin=1, size_t mem=0) | |
| Constructor: construct by passing filenames directly without peak selection limits. More... | |
| SIMSpecImage (std::vector< uint32_t > &limits, const std::string &tofs, const std::string &coords="", const std::string &scans="", const std::string &props="", int SF=0, int K0=0, int nwin=66, int npp=0, uint32_t xBin=1, uint32_t yBin=1, uint32_t zBin=1, uint32_t tofsBin=1, size_t mem=0) | |
| Constructor: construct by passing filenames directly with peak selection limits expressed as ToF values. More... | |
| SIMSpecImage (std::vector< FPType > &limits, const std::string &tofs, const std::string &coords="", const std::string &scans="", const std::string &props="", int SF=0, int K0=0, int nwin=66, int npp=0, uint32_t xBin=1, uint32_t yBin=1, uint32_t zBin=1, uint32_t tofsBin=1, size_t mem=0) | |
| Constructor: construct by passing filenames directly with peak selection limits expressed as m/z values. More... | |
| SIMSpecImage (int SF, int K0, int nwin, int npp, uint32_t *x, uint32_t *y, uint32_t *scans, uint32_t *tofs, size_t len, uint32_t xBin, uint32_t yBin, uint32_t zBin, uint32_t tofsBin, size_t mem, uint32_t *limits, size_t len_limits) | |
| Constructor used by Factory interface - not intended for use otherwise. More... | |
| SIMSpecImage (int SF, int K0, int nwin, int npp, uint32_t *x, uint32_t *y, uint32_t *scans, uint32_t *tofs, size_t len, uint32_t xBin, uint32_t yBin, uint32_t zBin, uint32_t tofsBin, size_t mem, FPType *limits, size_t len_limits) | |
| Constructor used by Factory interface - not intended for use otherwise. More... | |
| void | advancedDeadTimeCorrection () |
| Advanced dead-time correction preprocessing. More... | |
| void | scaleMatrix () |
| Scale the image matrix. More... | |
| void | scaleMatrix (const std::vector< FPType > &g, const std::vector< FPType > &h) |
| Scale the image matrix. More... | |
| int | getK0 () |
| Return the SIMS calibration parameter K0. More... | |
| int | getSF () |
| Return the SIMS calibration parameter SF. More... | |
| void | setLimits (const std::vector< uint32_t > &limits) |
| Set the limits to use during nag::SpecImage::peakSelect. More... | |
 Public Member Functions inherited from nag::SpecImage< FPType > | |
| SpecImage () | |
| Default constructor. More... | |
| SpecImage (const csr_mat_t< FPType > &matrix, const FPType *mzvals=NULL) | |
| Constructor: construct a nag::SpecImage object from a sparse matrix and optionally provide m/z values. More... | |
| SpecImage (size_t m, size_t n, const FPType *matrix, const FPType *mzvals=NULL) | |
| Constructor: construct a nag::SpecImage object from a dense column-major matrix and optionally provide m/z values. More... | |
| virtual | ~SpecImage () |
| Destructor. More... | |
| void | peakSelect () |
| Perform peak selection. More... | |
| pca_results_t< FPType > | pca (uint32_t k, pca_mat_t t=Covariance) |
| Principal component analysis. More... | |
| kmeans_results_t< FPType > | kmeans (uint32_t k, FPType *initial_cmeans=NULL, kmeans_metric_t metric=Cosine) |
| k-means clustering analysis More... | |
| nmf_results_t< FPType > | nmf (uint32_t k, FPType *initial_W=NULL, FPType *initial_H=NULL, FPType tol=1.e-2, uint32_t max_iter=200) |
| Non-negative matrix factorization. More... | |
| cwt_results_t< FPType > | cwt (const std::vector< uint32_t > &scales, const std::vector< size_t > &pixels, wavelet_t wav=Haar, wavelet_extension_t ext=Periodic) |
| Batched one-dimensional real continuous wavelet transform. More... | |
| tsne_results_t< FPType > | tsne (uint32_t k, pca_results_t< FPType > *data=NULL, FPType *embedding=NULL, FPType perplexity=50, FPType theta=0.3, uint32_t max_iter=1000, uint32_t verbosity=50, FPType min_grad_norm=1.0e-5, uint32_t n_unimproved_iter=30, FPType learning_rate=100, FPType early_exaggeration=4.0, uint32_t exaggerated_iter=50) |
| t-SNE analysis More... | |
| csr_mat_t< FPType > | getSparseMatrix (matrix_ordering_t order=PixelsByChannels) |
| Retrieve a copy of the image matrix in sparse storage format. More... | |
| std::unique_ptr< FPType[]> | getDenseMatrix (matrix_ordering_t order=PixelsByChannels) |
| Retrieve a copy of the image matrix in dense storage format. More... | |
| std::vector< FPType > | getSinglePeak (FPType minmz, FPType maxmz) |
| Return a single peak. A lower limit minmz and an upper limit maxmz are used to reduce the number of channels (columns) in the image matrix to 1. The original image matrix is left unchanged when the single channel is extracted. This allows multiple peaks of interest to be quickly investigated before final peak selection is performed on the data. More... | |
| size_t | getM () |
| Return the number of rows in the matrix. More... | |
| size_t | getN () |
| Return the number of columns in the matrix. More... | |
| size_t | getNNZ () |
| Return the number of non-zero elements in the matrix. More... | |
| int | getXDim () |
| Return the number of pixels in the image in the \(x\) dimension. More... | |
| int | getYDim () |
| Return the number of pixels in the image in the \(y\) dimension. More... | |
| int | getZDim () |
| Return the number of pixels in the image in the \(z\) dimension. More... | |
| std::vector< FPType > | getMZVals () |
| Return the mass-to-charge values which label the channels in the image matrix. More... | |
| void | setLimits (const std::vector< FPType > &limits) |
| Set the limits to use during nag::SpecImage::peakSelect. More... | |
| source_t | getSource () |
| Determine the type of the object. More... | |
Additional Inherited Members | |
| Protected Attributes inherited from nag::SpecImage< FPType > | |
| void * | _imgh |
| Opaque handle to internal library data structure. More... | |
| source_t | _source_type |
| Encodes what the underlying type is: nag::SIMSpecImage (value: SIMS), nag::MALDISpecImage (value: MALDI) or nag::SpecImage (value: none). More... | |
Detailed Description
template<class FPType>
class nag::SIMSpecImage< FPType >
Class representing a spectral image generated from a Secondary Ion Mass Spectrometry instrument.
Limited Memory Construction
Construction may proceed using out-of-core techniques, in which case construction takes place within a specified memory footprint given by the mem argument to the constructors. Note that selecting this option (i.e. setting mem to a non-zero value) causes performance degradation. The option applies to construction, preprocessing and peak selection only. Attempting to perform an analysis function such as nag::SpecImage::pca or nag::SpecImage::nmf on a nag::SIMSpecImage that has been constructed using this option and has not yet been fully loaded into memory via peak selection will return an error.
Constructor & Destructor Documentation
| nag::SIMSpecImage< FPType >::SIMSpecImage | ( | const std::string & | tofs, |
| const std::string & | coords = "", |
||
| const std::string & | scans = "", |
||
| const std::string & | props = "", |
||
| int | SF = 0, |
||
| int | K0 = 0, |
||
| int | nwin = 66, |
||
| int | npp = 0, |
||
| uint32_t | xBin = 1, |
||
| uint32_t | yBin = 1, |
||
| uint32_t | zBin = 1, |
||
| uint32_t | tofsBin = 1, |
||
| size_t | mem = 0 |
||
| ) |
Constructor: construct by passing filenames directly without peak selection limits.
The type of image which is constructed depends on the arguments provided. The three raw binary file types, tofs, coords and scans contain, respectively, time-of-flight values, corresponding coordinate positions, and corresponding depth (z-values). These plus the text properties props file are as provided by a SIMS instrument. A tofs file is mandatory. Supplying a tofs file alone will generate a whole-image spectrum (i.e. the image "matrix" is actually a vector). Supplying a coords file and not a scans file will generate a 2D image with a z-depth of 1. Supplying a scans file and a coords file will generate a 3D image. To omit a file, supply the option as an empty string.
- Parameters
-
[in] tofs Name of the SIMS binary data file containing time-of-flight values. [in] coords Name of the SIMS binary data file containing coordinate values. [in] scans Name of the SIMS binary data file containing scans values (z-depth). [in] props Name of the SIMS text file containing properties information. [in] SF The SIMS calibration constant SF. See nag::SIMSpecImage::getSF. The value given here is overridden by that given in the properties file, props, if provided. [in] K0 The SIMS calibration constant K0. See nag::SIMSpecImage::getK0. The value given here is overridden by that given in the properties file, props, if provided. [in] nwin The duration, in nanoseconds, of the dead-time window of the SIMS instrument. See nag::SIMSpecImage::advancedDeadTimeCorrection. The value given here is overridden by that given in the properties file, props, if provided. [in] npp The sum total number of primary pulses over the whole image. The value given here is overridden by that given in the properties file, props, if provided. [in] xBin The amount by which to bin pixels in the x-dimension. Note that this value must be a factor of the number of pixels in the x-dimension. [in] yBin The amount by which to bin pixels in the y-dimension. Note that this value must be a factor of the number of pixels in the y-dimension. [in] zBin The amount by which to bin pixels in the z-dimension. Note that this value must be a factor of the number of pixels in the z-dimension. [in] tofsBin The amount by which to bin time-of-flight values. [in] mem Construct the image without exceeding the number of bytes given. Note that setting mem >0 degrades performance since this triggers out-of-core construction. See the Limited Memory Construction information above.
| nag::SIMSpecImage< FPType >::SIMSpecImage | ( | std::vector< uint32_t > & | limits, |
| const std::string & | tofs, | ||
| const std::string & | coords = "", |
||
| const std::string & | scans = "", |
||
| const std::string & | props = "", |
||
| int | SF = 0, |
||
| int | K0 = 0, |
||
| int | nwin = 66, |
||
| int | npp = 0, |
||
| uint32_t | xBin = 1, |
||
| uint32_t | yBin = 1, |
||
| uint32_t | zBin = 1, |
||
| uint32_t | tofsBin = 1, |
||
| size_t | mem = 0 |
||
| ) |
Constructor: construct by passing filenames directly with peak selection limits expressed as ToF values.
The type of image which is constructed depends on the arguments provided. The three raw binary file types, tofs, coords and scans contain, respectively, time-of-flight values, corresponding coordinate positions, and corresponding depth (z-values). These plus the text properties props file are as provided by a SIMS instrument. A tofs file is mandatory. Supplying a tofs file alone will generate a whole image spectrum (i.e. the image "matrix" is actually a vector). Supplying a coords file and not a scans file will generate a 2D image with a z-depth of 1. Supplying a scans file and a coords file will generate a 3D image. To omit a file supply the option as an empty string.
- Parameters
-
[in] limits A vector of time-of-flight values such that neighbouring pairs define a peak selection interval - i.e. the vector defines len_limits/2peaks[limits[i],limits[i+1]]fori = 0, 2, ... n-2.[in] tofs Name of the SIMS binary data file containing time-of-flight values. [in] coords Name of the SIMS binary data file containing coordinate values. [in] scans Name of the SIMS binary data file containing scans values (z-depth). [in] props Name of the SIMS text file containing properties information. [in] SF The SIMS calibration constant SF. See nag::SIMSpecImage::getSF. The value given here is overridden by that given in the properties file, props, if provided. [in] K0 The SIMS calibration constant K0. See nag::SIMSpecImage::getK0. The value given here is overridden by that given in the properties file, props, if provided. [in] nwin The duration, in nanoseconds, of the dead-time window of the SIMS instrument. See nag::SIMSpecImage::advancedDeadTimeCorrection. The value given here is overridden by that given in the properties file, props, if provided. [in] npp The sum total number of primary pulses over the whole image. The value given here is overridden by that given in the properties file, props, if provided. [in] xBin The amount by which to bin pixels in the x-dimension. Note that this value must be a factor of the number of pixels in the x-dimension. [in] yBin The amount by which to bin pixels in the y-dimension. Note that this value must be a factor of the number of pixels in the y-dimension. [in] zBin The amount by which to bin pixels in the z-dimension. Note that this value must be a factor of the number of pixels in the z-dimension. [in] tofsBin The amount by which to bin time-of-flight values. [in] mem Construct the image without exceeding the number of bytes given. Note that setting mem >0 degrades performance since this triggers out-of-core construction. See the Limited Memory Construction information above.
| nag::SIMSpecImage< FPType >::SIMSpecImage | ( | std::vector< FPType > & | limits, |
| const std::string & | tofs, | ||
| const std::string & | coords = "", |
||
| const std::string & | scans = "", |
||
| const std::string & | props = "", |
||
| int | SF = 0, |
||
| int | K0 = 0, |
||
| int | nwin = 66, |
||
| int | npp = 0, |
||
| uint32_t | xBin = 1, |
||
| uint32_t | yBin = 1, |
||
| uint32_t | zBin = 1, |
||
| uint32_t | tofsBin = 1, |
||
| size_t | mem = 0 |
||
| ) |
Constructor: construct by passing filenames directly with peak selection limits expressed as m/z values.
The type of image which is constructed depends on the arguments provided. The three raw binary file types, tofs, coords and scans contain, respectively, time-of-flight values, corresponding coordinate positions, and corresponding depth (z-values). These plus the text properties props file are as provided by a SIMS instrument. A tofs file is mandatory. Supplying a tofs file alone will generate a whole image spectrum (i.e. the image "matrix" is actually a vector). Supplying a coords file and not a scans file will generate a 2D image with a z-depth of 1. Supplying a scans file and a coords file will generate a 3D image. To omit a file supply the option as an empty string.
- Parameters
-
[in] limits A vector of mass-to-charge values such that neighbouring pairs define a peak selection interval - i.e. the vector defines len_limits/2peaks[limits[i],limits[i+1]]fori = 0, 2, ... n-2.[in] tofs Name of the SIMS binary data file containing time-of-flight values. [in] coords Name of the SIMS binary data file containing coordinate values. [in] scans Name of the SIMS binary data file containing scans values (z-depth). [in] props Name of the SIMS text file containing properties information. [in] SF The SIMS calibration constant SF. See nag::SIMSpecImage::getSF. The value given here is overridden by that given in the properties file, props, if provided. [in] K0 The SIMS calibration constant K0. See nag::SIMSpecImage::getK0. The value given here is overridden by that given in the properties file, props, if provided. [in] nwin The duration, in nanoseconds, of the dead-time window of the SIMS instrument. See nag::SIMSpecImage::advancedDeadTimeCorrection. The value given here is overridden by that given in the properties file, props, if provided. [in] npp The sum total number of primary pulses over the whole image. The value given here is overridden by that given in the properties file, props, if provided. [in] xBin The amount by which to bin pixels in the x-dimension. Note that this value must be a factor of the number of pixels in the x-dimension. [in] yBin The amount by which to bin pixels in the y-dimension. Note that this value must be a factor of the number of pixels in the y-dimension. [in] zBin The amount by which to bin pixels in the z-dimension. Note that this value must be a factor of the number of pixels in the z-dimension. [in] tofsBin The amount by which to bin time-of-flight values. [in] mem Construct the image without exceeding the number of bytes given. Note that setting mem >0 degrades performance since this triggers out-of-core construction. See the Limited Memory Construction information above.
| nag::SIMSpecImage< FPType >::SIMSpecImage | ( | int | SF, |
| int | K0, | ||
| int | nwin, | ||
| int | npp, | ||
| uint32_t * | x, | ||
| uint32_t * | y, | ||
| uint32_t * | scans, | ||
| uint32_t * | tofs, | ||
| size_t | len, | ||
| uint32_t | xBin, | ||
| uint32_t | yBin, | ||
| uint32_t | zBin, | ||
| uint32_t | tofsBin, | ||
| size_t | mem, | ||
| uint32_t * | limits, | ||
| size_t | len_limits | ||
| ) |
Constructor used by Factory interface - not intended for use otherwise.
| nag::SIMSpecImage< FPType >::SIMSpecImage | ( | int | SF, |
| int | K0, | ||
| int | nwin, | ||
| int | npp, | ||
| uint32_t * | x, | ||
| uint32_t * | y, | ||
| uint32_t * | scans, | ||
| uint32_t * | tofs, | ||
| size_t | len, | ||
| uint32_t | xBin, | ||
| uint32_t | yBin, | ||
| uint32_t | zBin, | ||
| uint32_t | tofsBin, | ||
| size_t | mem, | ||
| FPType * | limits, | ||
| size_t | len_limits | ||
| ) |
Constructor used by Factory interface - not intended for use otherwise.
Member Function Documentation
| void nag::SIMSpecImage< FPType >::advancedDeadTimeCorrection | ( | ) |
Advanced dead-time correction preprocessing.
Advanced dead-time correction for SIMS data is defined by:
\[C^a_k = -N \ln(1 - \frac{X_k}{n_k}),\]
where:
\[n_k = N - \sum\limits_{i=k - nwin}^{k-1} X_i.\]
Here \(nwin\) is the number of channels in the dead-time window (usually 66ns), \(X_i\) is the measured intensity at time point (ToF channel) \(k\), \(N\) is the number of primary ion pulses and \(C_k^a\) is the corrected intensity at time point \(k\).
This routine assumes a 50ps channel resolution, so e.g. if \(nwin = 66\) there will be 1320 channels in the dead-time window.
Reference: The accuracy and precision of the advanced Poisson dead-time correction and its importance for multivariate analysis of high mass resolution ToF-SIMS data by Bonnie J. Tyler, Surf. Interface Anal. 2014, 46, 581-590.
| int nag::SIMSpecImage< FPType >::getK0 | ( | ) |
Return the SIMS calibration parameter K0.
Mass-to-charge (m/z) values are set according to the formula: \(m/z = (\frac{(T - K0)}{SF})^2\), where \(T\) is the time-of-flight (ToF) value.
| int nag::SIMSpecImage< FPType >::getSF | ( | ) |
Return the SIMS calibration parameter SF.
Mass-to-charge (m/z) values are set according to the formula: \(m/z = (\frac{(T - K0)}{SF})^2\), where \(T\) is the time-of-flight (ToF) value.
| void nag::SIMSpecImage< FPType >::scaleMatrix | ( | ) |
Scale the image matrix.
The scaling operation is defined by pre- and post-multiplication of the (corrected) image matrix \(C\) with diagonal matrices \(G\) and \(H\):
\[C_{new} = GCH,\]
where \(G\) is the diagonal matrix whose element \(i,i\) is the mean of
\[\frac{1}{\sqrt{CF}}\]
along row \(i\), and \(H\) is the diagonal matrix whose element \(i,i\) is defined in the same way along column \(i\). The matrix \(F\) is given by \(F = C/X\), where \(X\) is the matrix of the original uncorrected values.
Reference: The accuracy and precision of the advanced Poisson dead-time correction and its importance for multivariate analysis of high mass resolution ToF-SIMS data by Bonnie J. Tyler, Surf. Interface Anal. 2014, 46, 581-590.
| void nag::SIMSpecImage< FPType >::scaleMatrix | ( | const std::vector< FPType > & | g, |
| const std::vector< FPType > & | h | ||
| ) |
Scale the image matrix.
The scaling operation is defined by pre- and post-multiplication of the (corrected) image matrix \(C\) with diagonal matrices \(G\) and \(H\):
\[C_{new} = GCH.\]
Reference: The accuracy and precision of the advanced Poisson dead-time correction and its importance for multivariate analysis of high mass resolution ToF-SIMS data by Bonnie J. Tyler, Surf. Interface Anal. 2014, 46, 581-590.
- Parameters
-
[in] g A vector of length \(m\), where \(m\) is the number of pixels in the image, defining the diagonal elements of the matrix \(G\) as described above. [in] h A vector of length \(n\), where \(n\) is the number of channels in the image, defining the diagonal elements of the matrix \(H\) as described above.
| void nag::SIMSpecImage< FPType >::setLimits | ( | const std::vector< uint32_t > & | limits | ) |
Set the limits to use during nag::SpecImage::peakSelect.
- Parameters
-
[in] limits A vector of time-of-flight values such that neighbouring pairs define a peak selection interval - i.e. the vector defines len_limits/2peaks[limits[i],limits[i+1]]fori = 0, 2, ... n-2.
The documentation for this class was generated from the following file:
