`pyms.IntensityMatrix`¶

Class to model Intensity Matrix.

Classes:

`AsciiFiletypes`(value)	Enumeration of supported ASCII filetypes for `export_ascii()`.
`BaseIntensityMatrix`(time_list, mass_list, ...)	Base class for intensity matrices of binned raw data.
`IntensityMatrix`(time_list, mass_list, ...)	Intensity matrix of binned raw data.

Functions:

`build_intensity_matrix`(data[, bin_interval, ...])	Sets the full intensity matrix with flexible bins.
`build_intensity_matrix_i`(data[, bin_left, ...])	Sets the full intensity matrix with integer bins.
`import_leco_csv`(file_name)	Imports data in LECO CSV format.

enum AsciiFiletypes(value)[source]¶

Bases: IntEnum

Enumeration of supported ASCII filetypes for export_ascii().

New in version 2.3.0.

Member Type:: int

Valid values are as follows:

ASCII_DAT = <AsciiFiletypes.ASCII_DAT: 1>¶: Tab-delimited ASCII file

ASCII_CSV = <AsciiFiletypes.ASCII_CSV: 0>¶: Comma-separated values file

class BaseIntensityMatrix(time_list, mass_list, intensity_array)[source]¶

Bases: pymsBaseClass, TimeListMixin, MassListMixin, IntensityArrayMixin, GetIndexTimeMixin

Base class for intensity matrices of binned raw data.

Parameters:

time_list (Sequence[float]) – Retention time values
mass_list (Sequence[float]) – Binned mass values
intensity_array (Union[Sequence[Sequence[float]], ndarray]) – List of lists of binned intensity values per scan

Authors:

Andrew Isaac, Dominic Davis-Foster (type assertions and properties)

Methods:

`__eq__`(other)	Return whether this intensity matrix object is equal to another object.
`__len__`()	Returns the number of scans in the intensity matrix.
`crop_mass`(mass_min, mass_max)	Crops mass spectrum.
`dump`(file_name[, protocol])	Dumps an object to a file through `pickle.dump()`.
`get_ic_at_index`(ix)	Returns the ion chromatogram at the specified index.
`get_index_at_time`(time)	Returns the nearest index corresponding to the given time.
`get_index_of_mass`(mass)	Returns the index of the nearest binned mass to the given mass.
`get_mass_at_index`(ix)	Returns binned mass at index.
`get_ms_at_index`(ix)	Returns a mass spectrum for a given scan index.
`get_scan_at_index`(ix)	Returns the spectral intensities for scan index.
`get_time_at_index`(ix)	Returns time at given index.
`iter_ic_indices`()	Iterate over column indices.
`iter_ms_indices`()	Iterates over row indices.
`null_mass`(mass)	Ignore given (closest) mass in spectra.
`reduce_mass_spectra`([n_intensities])	Reduces the mass spectra by retaining the top n_intensities, discarding all other intensities.
`set_ic_at_index`(ix, ic)	Sets the intensity of the mass at index `ix` in each scan to a new value.

Attributes:

`intensity_array`	Returns a copy of the intensity array.
`intensity_array_list`	Returns a copy of the intensity array as a list of lists of floats.
`intensity_matrix`	Returns a copy of the intensity matrix.
`mass_list`	Returns a list of the masses.
`matrix_list`	Returns the intensity matrix as a list of lists of floats.
`max_mass`	Returns the maximum m/z value in the spectrum.
`min_mass`	Returns the minimum m/z value in the spectrum.
`size`	Gets the size of intensity matrix.
`time_list`	Returns a copy of the time list.

__eq__(other)[source]¶

Return whether this intensity matrix object is equal to another object.

Parameters:: other – The other object to test equality with.
Return type:: bool

__len__()[source]¶

Returns the number of scans in the intensity matrix.

Return type:: int

crop_mass(mass_min, mass_max)[source]¶

Crops mass spectrum.

Parameters:

mass_min (float) – Minimum mass value
mass_max (float) – Maximum mass value

Author:

Andrew Isaac

dump(file_name, protocol=3)¶

Dumps an object to a file through pickle.dump().

Parameters:

file_name (Union[str, Path, PathLike]) – Filename to save the dump as.
protocol (int) – The pickle protocol to use. Default 3.

Authors:

Vladimir Likic, Dominic Davis-Foster (pathlib and pickle protocol support)

get_ic_at_index(ix)[source]¶

Returns the ion chromatogram at the specified index.

Parameters:: ix (int) – Index of an ion chromatogram in the intensity data matrix.
Return type:: IonChromatogram
Returns:: Ion chromatogram at given index.
Authors:: Qiao Wang, Andrew Isaac, Vladimir Likic

get_index_at_time(time)¶

Returns the nearest index corresponding to the given time.

Parameters:: time (float) – Time in seconds
Return type:: int
Returns:: Nearest index corresponding to given time
Authors:: Lewis Lee, Tim Erwin, Vladimir Likic

Changed in version 2.3.0: Now returns -1 if no index is found.

get_index_of_mass(mass)[source]¶

Returns the index of the nearest binned mass to the given mass.

Parameters:: mass (float) – Mass to lookup in list of masses
Author:: Andrew Isaac
Return type:: int

get_mass_at_index(ix)[source]¶

Returns binned mass at index.

Parameters:: ix (int) – Index of binned mass
Return type:: float
Returns:: Binned mass
Author:: Andrew Isaac

get_ms_at_index(ix)[source]¶

Returns a mass spectrum for a given scan index.

Parameters:: ix (int) – The index of the scan.
Author:: Andrew Isaac
Return type:: MassSpectrum

get_scan_at_index(ix)[source]¶

Returns the spectral intensities for scan index.

Parameters:: ix (int) – The index of the scan
Return type:: List[float]
Returns:: Intensity values of scan spectra
Author:: Andrew Isaac

get_time_at_index(ix)¶

Returns time at given index.

Parameters:: ix (int)
Authors:: Lewis Lee, Vladimir Likic
Return type:: float

property intensity_array¶

Returns a copy of the intensity array.

Return type:: ndarray
Returns:: Matrix of intensity values.
Authors:: Andrew Isaac, Lewis Lee

property intensity_array_list¶

Returns a copy of the intensity array as a list of lists of floats.

Return type:: List[List[float]]
Returns:: Matrix of intensity values.
Author:: Andrew Isaac

property intensity_matrix¶

Returns a copy of the intensity matrix.

Return type:: ndarray
Returns:: Matrix of intensity values.
Author:: Andrew Isaac

iter_ic_indices()[source]¶

Iterate over column indices.

Return type:: Iterator[int]

iter_ms_indices()[source]¶

Iterates over row indices.

Return type:: Iterator[int]

property mass_list¶

Returns a list of the masses.

Authors:: Qiao Wang, Andrew Isaac, Vladimir Likic
Return type:: List[float]

property matrix_list¶

Returns the intensity matrix as a list of lists of floats.

Return type:: ndarray
Returns:: Matrix of intensity values
Author:: Andrew Isaac

property max_mass¶

Returns the maximum m/z value in the spectrum.

Author:: Andrew Isaac
Return type:: Optional[float]

property min_mass¶

Returns the minimum m/z value in the spectrum.

Author:: Andrew Isaac
Return type:: Optional[float]

null_mass(mass)[source]¶

Ignore given (closest) mass in spectra.

Parameters:: mass (float) – Mass value to remove
Author:: Andrew Isaac

reduce_mass_spectra(n_intensities=5)[source]¶

Reduces the mass spectra by retaining the top n_intensities, discarding all other intensities.

Parameters:: n_intensities (int) – The number of top intensities to keep. Default 5.
Author:: Vladimir Likic

set_ic_at_index(ix, ic)[source]¶

Sets the intensity of the mass at index ix in each scan to a new value.

Parameters:

ix (int) – Index of an ion chromatogram in the intensity data matrix to be set
ic (IonChromatogram) – Ion chromatogram that will be copied at position ix in the data matrix

The length of the ion chromatogram must match the appropriate dimension of the intensity matrix.

Author:: Vladimir Likic

property size¶

Gets the size of intensity matrix.

Return type:: Tuple[int, int]
Returns:: Number of rows and cols
Authors:: Qiao Wang, Andrew Isaac, Luke Hodkinson, Vladimir Likic

property time_list¶

Returns a copy of the time list.

Return type:: List[float]
Returns:: List of retention times
Authors:: Andrew Isaac, Lewis Lee, Vladimir Likic

class IntensityMatrix(time_list, mass_list, intensity_array)[source]¶

Bases: BaseIntensityMatrix

Intensity matrix of binned raw data.

Parameters:

time_list (Sequence[float]) – Retention time values
mass_list (Sequence[float]) – Binned mass values
intensity_array (Union[Sequence[Sequence[float]], ndarray]) – List of lists of binned intensity values per scan

Authors:

Andrew Isaac, Dominic Davis-Foster (type assertions and properties)

Methods:

`__eq__`(other)	Return whether this intensity matrix object is equal to another object.
`__len__`()	Returns the number of scans in the intensity matrix.
`crop_mass`(mass_min, mass_max)	Crops mass spectrum.
`dump`(file_name[, protocol])	Dumps an object to a file through `pickle.dump()`.
`export_ascii`(root_name[, fmt])	Exports the intensity matrix, retention time vector, and m/z vector to the ascii format.
`export_leco_csv`(file_name)	Exports data in LECO CSV format.
`get_ic_at_index`(ix)	Returns the ion chromatogram at the specified index.
`get_ic_at_mass`([mass])	Returns the ion chromatogram for the nearest binned mass to the specified mass.
`get_index_at_time`(time)	Returns the nearest index corresponding to the given time.
`get_index_of_mass`(mass)	Returns the index of the nearest binned mass to the given mass.
`get_mass_at_index`(ix)	Returns binned mass at index.
`get_ms_at_index`(ix)	Returns a mass spectrum for a given scan index.
`get_scan_at_index`(ix)	Returns the spectral intensities for scan index.
`get_time_at_index`(ix)	Returns time at given index.
`iter_ic_indices`()	Iterate over local column indices.
`iter_ms_indices`()	Iterates over the local row indices.
`null_mass`(mass)	Ignore given (closest) mass in spectra.
`reduce_mass_spectra`([n_intensities])	Reduces the mass spectra by retaining the top n_intensities, discarding all other intensities.
`set_ic_at_index`(ix, ic)	Sets the intensity of the mass at index `ix` in each scan to a new value.

Attributes:

`bpc`	Constructs a Base Peak Chromatogram from the data.
`intensity_array`	Returns a copy of the intensity array.
`intensity_array_list`	Returns a copy of the intensity array as a list of lists of floats.
`intensity_matrix`	Returns a copy of the intensity matrix.
`local_size`	Gets the local size of intensity matrix.
`mass_list`	Returns a list of the masses.
`matrix_list`	Returns the intensity matrix as a list of lists of floats.
`max_mass`	Returns the maximum m/z value in the spectrum.
`min_mass`	Returns the minimum m/z value in the spectrum.
`size`	Gets the size of intensity matrix.
`tic`	Returns the TIC of the intensity matrix.
`time_list`	Returns a copy of the time list.

__eq__(other)¶

Return whether this intensity matrix object is equal to another object.

Parameters:: other – The other object to test equality with.
Return type:: bool

__len__()¶

Returns the number of scans in the intensity matrix.

Return type:: int

property bpc¶

Constructs a Base Peak Chromatogram from the data.

This represents the most intense ion for each scan.

Authors:: Dominic Davis-Foster

New in version 2.3.0.

Return type:: IonChromatogram

crop_mass(mass_min, mass_max)¶

Crops mass spectrum.

Parameters:

mass_min (float) – Minimum mass value
mass_max (float) – Maximum mass value

Author:

Andrew Isaac

dump(file_name, protocol=3)¶

Dumps an object to a file through pickle.dump().

Parameters:

file_name (Union[str, Path, PathLike]) – Filename to save the dump as.
protocol (int) – The pickle protocol to use. Default 3.

Authors:

Vladimir Likic, Dominic Davis-Foster (pathlib and pickle protocol support)

export_ascii(root_name, fmt=AsciiFiletypes.ASCII_DAT)[source]¶

Exports the intensity matrix, retention time vector, and m/z vector to the ascii format.

By default, export_ascii(“NAME”) will create NAME.im.dat, NAME.rt.dat, and NAME.mz.dat where these are the intensity matrix, retention time vector, and m/z vector in tab delimited format.

If format == <AsciiFiletypes.ASCII_CSV>, the files will be in the CSV format, named NAME.im.csv, NAME.rt.csv, and NAME.mz.csv.

Parameters:

root_name (Union[str, Path, PathLike]) – Root name for the output files
fmt (AsciiFiletypes) – Format of the output file, either <AsciiFiletypes.ASCII_DAT> or <AsciiFiletypes.ASCII_CSV>. Default <AsciiFiletypes.ASCII_DAT: 1>.

Authors:

Milica Ng, Andrew Isaac, Vladimir Likic, Dominic Davis-Foster (pathlib support)

export_leco_csv(file_name)[source]¶

Exports data in LECO CSV format.

Parameters:: file_name (Union[str, Path, PathLike]) – The name of the output file.
Authors:: Andrew Isaac, Vladimir Likic, Dominic Davis-Foster (pathlib support)

get_ic_at_index(ix)¶

Returns the ion chromatogram at the specified index.

Parameters:: ix (int) – Index of an ion chromatogram in the intensity data matrix.
Return type:: IonChromatogram
Returns:: Ion chromatogram at given index.
Authors:: Qiao Wang, Andrew Isaac, Vladimir Likic

get_ic_at_mass(mass=None)[source]¶

Returns the ion chromatogram for the nearest binned mass to the specified mass.

If no mass value is given, the function returns the total ion chromatogram.

Parameters:: mass (Optional[float]) – Mass value of an ion chromatogram. Default None.
Return type:: IonChromatogram
Returns:: Ion chromatogram for given mass
Authors:: Andrew Isaac, Vladimir Likic

get_index_at_time(time)¶

Returns the nearest index corresponding to the given time.

Parameters:: time (float) – Time in seconds
Return type:: int
Returns:: Nearest index corresponding to given time
Authors:: Lewis Lee, Tim Erwin, Vladimir Likic

Changed in version 2.3.0: Now returns -1 if no index is found.

get_index_of_mass(mass)¶

Returns the index of the nearest binned mass to the given mass.

Parameters:: mass (float) – Mass to lookup in list of masses
Author:: Andrew Isaac
Return type:: int

get_mass_at_index(ix)¶

Returns binned mass at index.

Parameters:: ix (int) – Index of binned mass
Return type:: float
Returns:: Binned mass
Author:: Andrew Isaac

get_ms_at_index(ix)¶

Returns a mass spectrum for a given scan index.

Parameters:: ix (int) – The index of the scan.
Author:: Andrew Isaac
Return type:: MassSpectrum

get_scan_at_index(ix)¶

Returns the spectral intensities for scan index.

Parameters:: ix (int) – The index of the scan
Return type:: List[float]
Returns:: Intensity values of scan spectra
Author:: Andrew Isaac

get_time_at_index(ix)¶

Returns time at given index.

Parameters:: ix (int)
Authors:: Lewis Lee, Vladimir Likic
Return type:: float

property intensity_array¶

Returns a copy of the intensity array.

Return type:: ndarray
Returns:: Matrix of intensity values.
Authors:: Andrew Isaac, Lewis Lee

property intensity_array_list¶

Returns a copy of the intensity array as a list of lists of floats.

Return type:: List[List[float]]
Returns:: Matrix of intensity values.
Author:: Andrew Isaac

property intensity_matrix¶

Returns a copy of the intensity matrix.

Return type:: ndarray
Returns:: Matrix of intensity values.
Author:: Andrew Isaac

iter_ic_indices()[source]¶

Iterate over local column indices.

Author:: Luke Hodkinson
Return type:: Iterator[int]

iter_ms_indices()[source]¶

Iterates over the local row indices.

Author:: Luke Hodkinson
Return type:: Iterator[int]

property local_size¶

Gets the local size of intensity matrix.

Returns:: Number of rows and cols
Return type:: int
Author:: Luke Hodkinson

property mass_list¶

Returns a list of the masses.

Authors:: Qiao Wang, Andrew Isaac, Vladimir Likic
Return type:: List[float]

property matrix_list¶

Returns the intensity matrix as a list of lists of floats.

Return type:: ndarray
Returns:: Matrix of intensity values
Author:: Andrew Isaac

property max_mass¶

Returns the maximum m/z value in the spectrum.

Author:: Andrew Isaac
Return type:: Optional[float]

property min_mass¶

Returns the minimum m/z value in the spectrum.

Author:: Andrew Isaac
Return type:: Optional[float]

null_mass(mass)¶

Ignore given (closest) mass in spectra.

Parameters:: mass (float) – Mass value to remove
Author:: Andrew Isaac

reduce_mass_spectra(n_intensities=5)¶

Reduces the mass spectra by retaining the top n_intensities, discarding all other intensities.

Parameters:: n_intensities (int) – The number of top intensities to keep. Default 5.
Author:: Vladimir Likic

set_ic_at_index(ix, ic)¶

Sets the intensity of the mass at index ix in each scan to a new value.

Parameters:

ix (int) – Index of an ion chromatogram in the intensity data matrix to be set
ic (IonChromatogram) – Ion chromatogram that will be copied at position ix in the data matrix

The length of the ion chromatogram must match the appropriate dimension of the intensity matrix.

Author:: Vladimir Likic

property size¶

Gets the size of intensity matrix.

Return type:: Tuple[int, int]
Returns:: Number of rows and cols
Authors:: Qiao Wang, Andrew Isaac, Luke Hodkinson, Vladimir Likic

property tic¶

Returns the TIC of the intensity matrix.

New in version 2.3.0.

Return type:: IonChromatogram

property time_list¶

Returns a copy of the time list.

Return type:: List[float]
Returns:: List of retention times
Authors:: Andrew Isaac, Lewis Lee, Vladimir Likic

build_intensity_matrix(data, bin_interval=1, bin_left=0.5, bin_right=0.5, min_mass=None)[source]¶

Sets the full intensity matrix with flexible bins.

The first bin is centered around min_mass, and subsequent bins are offset by bin_interval.

Parameters:

data (GCMS_data) – Raw GCMS data
bin_interval (float) – interval between bin centres. Default 1.
bin_left (float) – left bin boundary offset. Default 0.5.
bin_right (float) – right bin boundary offset. Default 0.5.
min_mass (Optional[float]) – Minimum mass to bin (default minimum mass from data). Default None.

Return type:

IntensityMatrix

Returns:

Binned IntensityMatrix object

Authors:

Qiao Wang, Andrew Isaac, Vladimir Likic

build_intensity_matrix_i(data, bin_left=0.3, bin_right=0.7)[source]¶

Sets the full intensity matrix with integer bins.

Parameters:

data (GCMS_data) – Raw GCMS data
bin_left (float) – left bin boundary offset. Default 0.3.
bin_right (float) – right bin boundary offset. Default 0.7.

Return type:

IntensityMatrix

Returns:

Binned IntensityMatrix object

Authors:

Qiao Wang, Andrew Isaac, Vladimir Likic

import_leco_csv(file_name)[source]¶

Imports data in LECO CSV format.

Parameters:: file_name (Union[str, Path, PathLike]) – Path of the file to read.
Return type:: IntensityMatrix
Returns:: Data as an IntensityMatrix.
Authors:: Andrew Isaac, Dominic Davis-Foster (pathlib support)

pyms.IntensityMatrix¶

`pyms.IntensityMatrix`¶