`pyms.Peak`

Table of Contents

pyms.Peak

Functions for modelling signal peaks.

`pyms.Peak.Class`

Provides a class to model signal peak.

Classes:

`AbstractPeak`([rt, minutes, outlier])	Models a signal peak.
`ICPeak`([rt, mass, minutes, outlier])	Subclass of `Peak` representing a peak in an ion chromatogram for a single mass.
`Peak`()	Subclass of `Peak` representing a peak in a mass spectrum.

class AbstractPeak(rt=0.0, minutes=False, outlier=False)[source]

Bases: pymsBaseClass

Models a signal peak.

Parameters

rt (Union[int, float]) – Retention time. Default 0.0.
minutes (bool) – Retention time units flag. If True, retention time is in minutes; if False retention time is in seconds. Default False.
outlier (bool) – Whether the peak is an outlier. Default False.

Authors

Vladimir Likic, Andrew Isaac, Dominic Davis-Foster (type assertions and properties), David Kainer (outlier flag)

New in version 2.3.0.

Attributes:

`UID`	Return the unique peak ID (UID), either:
`area`	The area under the peak.
`bounds`	The peak boundaries in points.
`ion_areas`	Returns a copy of the ion areas dict.
`rt`	The retention time of the peak, in seconds.

Methods:

`__eq__`(other)	Return whether this Peak object is equal to another object.
`dump`(file_name[, protocol])	Dumps an object to a file through `pickle.dump()`.
`get_ion_area`(ion)	Returns the area of a single ion chromatogram under the peak.
`make_UID`()	Create a unique peak ID (UID).
`set_bounds`(left, apex, right)	Sets peak boundaries in points.
`set_ion_area`(ion, area)	Sets the area for a single ion.

property UID

Return the unique peak ID (UID), either:

Integer masses of top two intensities and their ratio (as Mass1-Mass2-Ratio*100); or
the single mass as an integer and the retention time.

Return type: str
Returns: UID string
Author: Andrew Isaac

__eq__(other)[source]

Return whether this Peak object is equal to another object.

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

property area

The area under the peak.

Author: Andrew Isaac
Return type: Optional[float]

property bounds

The peak boundaries in points.

Return type: Optional[Tuple[int, int, int]]
Returns: A 3-element tuple containing the left, apex, and right peak boundaries in points. Left and right are offsets.
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_ion_area(ion)[source]

Returns the area of a single ion chromatogram under the peak.

Parameters: ion (float) – The ion to calculate the area for.
Return type: Optional[float]
Returns: The area of the ion under this peak.

property ion_areas

Returns a copy of the ion areas dict.

Return type: Dict
Returns: The dictionary of ion: ion area pairs

make_UID()[source]

Create a unique peak ID (UID).

The UID comprises the retention time of the peak to two decimal places. Subclasses may define a more unique ID.

Author: Andrew Isaac

property rt

The retention time of the peak, in seconds.

Return type: float

set_bounds(left, apex, right)[source]

Sets peak boundaries in points.

Parameters

left (int) – Left peak boundary, in points offset from apex
apex (int) – Apex of the peak, in points
right (int) – Right peak boundary, in points offset from apex

set_ion_area(ion, area)[source]

Sets the area for a single ion.

Parameters

ion (int) – the ion whose area is being entered.
area (float) – the area under the IC of ion.

Author

Sean O’Callaghan

class ICPeak(rt=0.0, mass=None, minutes=False, outlier=False)[source]

Bases: AbstractPeak

Subclass of Peak representing a peak in an ion chromatogram for a single mass.

Parameters

rt (Union[int, float]) – Retention time. Default 0.0.
mass (Optional[float]) – The mass of the ion. Default None.
minutes (bool) – Retention time units flag. If True, retention time is in minutes; if False retention time is in seconds. Default False.
outlier (bool) – Whether the peak is an outlier. Default False.

Authors

Vladimir Likic, Andrew Isaac, Dominic Davis-Foster (type assertions and properties), David Kainer (outlier flag)

New in version 2.3.0.

Attributes:

`UID`	Return the unique peak ID (UID), either:
`area`	The area under the peak.
`bounds`	The peak boundaries in points.
`ic_mass`	The mass for a single ion chromatogram peak.
`ion_areas`	Returns a copy of the ion areas dict.
`rt`	The retention time of the peak, in seconds.

Methods:

`__eq__`(other)	Return whether this Peak object is equal to another object.
`dump`(file_name[, protocol])	Dumps an object to a file through `pickle.dump()`.
`get_ion_area`(ion)	Returns the area of a single ion chromatogram under the peak.
`make_UID`()	Create a unique peak ID (UID):
`set_bounds`(left, apex, right)	Sets peak boundaries in points.
`set_ion_area`(ion, area)	Sets the area for a single ion.

property UID

Return the unique peak ID (UID), either:

Integer masses of top two intensities and their ratio (as Mass1-Mass2-Ratio*100); or
the single mass as an integer and the retention time.

Return type: str
Returns: UID string
Author: Andrew Isaac

__eq__(other)[source]

Return whether this Peak object is equal to another object.

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

property area

The area under the peak.

Author: Andrew Isaac
Return type: Optional[float]

property bounds

The peak boundaries in points.

Return type: Optional[Tuple[int, int, int]]
Returns: A 3-element tuple containing the left, apex, and right peak boundaries in points. Left and right are offsets.
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_ion_area(ion)

Returns the area of a single ion chromatogram under the peak.

Parameters: ion (float) – The ion to calculate the area for.
Return type: Optional[float]
Returns: The area of the ion under this peak.

property ic_mass

The mass for a single ion chromatogram peak.

Return type: Optional[float]
Returns: The mass of the single ion chromatogram that the peak is from

property ion_areas

Returns a copy of the ion areas dict.

Return type: Dict
Returns: The dictionary of ion: ion area pairs

make_UID()[source]

Create a unique peak ID (UID):

the single mass as an integer and the retention time.

Author: Andrew Isaac

property rt

The retention time of the peak, in seconds.

Return type: float

set_bounds(left, apex, right)

Sets peak boundaries in points.

Parameters

left (int) – Left peak boundary, in points offset from apex
apex (int) – Apex of the peak, in points
right (int) – Right peak boundary, in points offset from apex

set_ion_area(ion, area)

Sets the area for a single ion.

Parameters

ion (int) – the ion whose area is being entered.
area (float) – the area under the IC of ion.

Author

Sean O’Callaghan

class Peak(rt: float, ms: Optional[pyms.Spectrum.MassSpectrum], minutes: bool = ..., outlier: bool = ...)[source]

class Peak(rt: float, ms: float, minutes: bool = ..., outlier: bool = ...)

Bases: AbstractPeak

Subclass of Peak representing a peak in a mass spectrum.

Parameters

rt (Union[int, float]) – Retention time. Default 0.0.
ms (Union[float, MassSpectrum, None]) – The mass spectrum at the apex of the peak. Default None.
minutes (bool) – Retention time units flag. If True, retention time is in minutes; if False retention time is in seconds. Default False.
outlier (bool) – Whether the peak is an outlier. Default False.

Authors

Vladimir Likic, Andrew Isaac, Dominic Davis-Foster (type assertions and properties), David Kainer (outlier flag)

Changed in version 2.3.0: Functionality related to single ion peaks has moved to the ICPeak class. The two classes share a common base class, AbstractPeak, which can be used in type checks for functions that accept either type of peak.

Changed in version 2.3.0: If the ms argument is unset an empty mass spectrum is used, rather than None in previous versions.

Attributes:

`UID`	Return the unique peak ID (UID), either:
`area`	The area under the peak.
`bounds`	The peak boundaries in points.
`ion_areas`	Returns a copy of the ion areas dict.
`mass_spectrum`	The mass spectrum at the apex of the peak.
`rt`	The retention time of the peak, in seconds.

Methods:

`__eq__`(other)	Return whether this Peak object is equal to another object.
`crop_mass`(mass_min, mass_max)	Crops mass spectrum.
`dump`(file_name[, protocol])	Dumps an object to a file through `pickle.dump()`.
`find_mass_spectrum`(data[, from_bounds])
`get_int_of_ion`(ion)	Returns the intensity of a given ion in this peak.
`get_ion_area`(ion)	Returns the area of a single ion chromatogram under the peak.
`get_third_highest_mz`()	Returns the m/z value with the third highest intensity.
`make_UID`()	Create a unique peak ID (UID):
`null_mass`(mass)	Ignore given mass in spectra.
`set_bounds`(left, apex, right)	Sets peak boundaries in points.
`set_ion_area`(ion, area)	Sets the area for a single ion.
`top_ions`([num_ions])	Computes the highest #num_ions intensity ions.

property UID

Return the unique peak ID (UID), either:

Integer masses of top two intensities and their ratio (as Mass1-Mass2-Ratio*100); or
the single mass as an integer and the retention time.

Return type: str
Returns: UID string
Author: Andrew Isaac

__eq__(other)[source]

Return whether this Peak object is equal to another object.

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

property area

The area under the peak.

Author: Andrew Isaac
Return type: Optional[float]

property bounds

The peak boundaries in points.

Return type: Optional[Tuple[int, int, int]]
Returns: A 3-element tuple containing the left, apex, and right peak boundaries in points. Left and right are offsets.
Author: Andrew Isaac

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)

find_mass_spectrum(data, from_bounds=False)[source]

Sets the peak’s mass spectrum from the data.

Clears the single ion chromatogram mass.

Parameters

data (BaseIntensityMatrix)
from_bounds (float) – Whether to use the attribute pyms.Peak.Class.Peak.pt_bounds or to find the peak apex from the peak retention time. Default False.

get_int_of_ion(ion)[source]

Returns the intensity of a given ion in this peak.

Parameters: ion (int) – The m/z value of the ion of interest
Return type: float

get_ion_area(ion)

Returns the area of a single ion chromatogram under the peak.

Parameters: ion (float) – The ion to calculate the area for.
Return type: Optional[float]
Returns: The area of the ion under this peak.

get_third_highest_mz()[source]

Returns the m/z value with the third highest intensity.

Return type: int

property ion_areas

Returns a copy of the ion areas dict.

Return type: Dict
Returns: The dictionary of ion: ion area pairs

make_UID()[source]

Create a unique peak ID (UID):

Integer masses of top two intensities and their ratio (as Mass1-Mass2-Ratio*100); or

Author: Andrew Isaac

property mass_spectrum

The mass spectrum at the apex of the peak.

Return type: MassSpectrum

null_mass(mass)[source]

Ignore given mass in spectra.

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

property rt

The retention time of the peak, in seconds.

Return type: float

set_bounds(left, apex, right)

Sets peak boundaries in points.

Parameters

left (int) – Left peak boundary, in points offset from apex
apex (int) – Apex of the peak, in points
right (int) – Right peak boundary, in points offset from apex

set_ion_area(ion, area)

Sets the area for a single ion.

Parameters

ion (int) – the ion whose area is being entered.
area (float) – the area under the IC of ion.

Author

Sean O’Callaghan

top_ions(num_ions=5)[source]

Computes the highest #num_ions intensity ions.

Parameters: num_ions (int) – The number of ions to be recorded. Default 5.
Return type: List[float]
Returns: A list of the ions with the highest intensity.
Authors: Sean O’Callaghan, Dominic Davis-Foster (type assertions)

`pyms.Peak.Function`

Functions related to Peak modification.

Functions:

`half_area`(ia[, max_bound, tol])	Find bound of peak by summing intensities until change in sum is less than `tol` percent of the current area.
`ion_area`(ia, apex[, max_bound, tol])	Find bounds of peak by summing intensities until change in sum is less than `tol` percent of the current area.
`median_bounds`(im, peak[, shared])	Calculates the median of the left and right bounds found for each apexing peak mass.
`peak_pt_bounds`(im, peak)	Approximate the peak bounds (left and right offsets from apex).
`peak_sum_area`(im, peak[, single_ion, max_bound])	Calculate the sum of the raw ion areas based on detected boundaries.
`peak_top_ion_areas`(im, peak[, n_top_ions, …])	Calculate and return the ion areas of the five most abundant ions in the peak.
`top_ions_v1`(peak[, num_ions])	Computes the highest 5 intensity ions.
`top_ions_v2`(peak[, num_ions])	Computes the highest #num_ions intensity ions.

half_area(ia, max_bound=0, tol=0.5)[source]

Find bound of peak by summing intensities until change in sum is less than tol percent of the current area.

Parameters

ia (List) – List of intensities from Peak apex for a given mass.
max_bound (int) – Optional value to limit size of detected bound. Default 0.
tol (float) – Percentage tolerance of added area to current area. Default 0.5.

Return type

Tuple[float, float, float]

Returns

Half peak area, boundary offset, shared (True if shared ion).

Authors

Andrew Isaac, Dominic Davis-Foster (type assertions)

ion_area(ia, apex, max_bound=0, tol=0.5)[source]

Find bounds of peak by summing intensities until change in sum is less than tol percent of the current area.

Parameters

ia (List) – List of intensities for a given mass.
apex (int) – Index of the peak apex.
max_bound (int) – Optional value to limit size of detected bound. Default 0.
tol (float) – Percentage tolerance of added area to current area. Default 0.5.

Return type

Tuple[float, float, float, float, float]

Returns

Area, left and right boundary offset, shared left, shared right.

Authors

Andrew Isaac, Dominic Davis-Foster (type assertions)

median_bounds(im, peak, shared=True)[source]

Calculates the median of the left and right bounds found for each apexing peak mass.

Parameters

im (BaseIntensityMatrix) – The originating IntensityMatrix object.
peak (Peak)
shared (bool) – Include shared ions shared with neighbouring peak. Default True.

Return type

Tuple[float, float]

Returns

Median left and right boundary offset in points.

Authors

Andrew Isaac, Dominic Davis-Foster

peak_pt_bounds(im, peak)[source]

Approximate the peak bounds (left and right offsets from apex).

Parameters

im (BaseIntensityMatrix) – The originating IntensityMatrix object
peak (Peak)

Return type

Tuple[int, int]

Returns

Sum of peak apex ions in detected bounds

Authors

Andrew Isaac, Sean O’Callaghan, Dominic Davis-Foster

peak_sum_area(im, peak, single_ion=False, max_bound=0)[source]

Calculate the sum of the raw ion areas based on detected boundaries.

Parameters

im (BaseIntensityMatrix) – The originating IntensityMatrix object.
peak (Peak)
single_ion (bool) – whether single ion areas should be returned. Default False.
max_bound (int) – Optional value to limit size of detected bound. Default 0.

Return type

Union[float, Tuple[float, Dict[float, float]]]

Returns

Sum of peak apex ions in detected bounds.

Overloads

peak_sum_area(im, peak, single_ion: Literal[True], max_bound = … ) -> Tuple[float, Dict[float, float]]
peak_sum_area(im, peak, single_ion: Literal[False] = …, max_bound = … ) -> float

Authors

Andrew Isaac, Dominic Davis-Foster (type assertions)

peak_top_ion_areas(im, peak, n_top_ions=5, max_bound=0)[source]

Calculate and return the ion areas of the five most abundant ions in the peak.

Parameters

im (IntensityMatrix) – The originating IntensityMatrix object.
peak (Peak)
n_top_ions (int) – Number of top ions to return areas for. Default 5.
max_bound (int) – Optional value to limit size of detected bound. Default 0.

Return type

Dict[float, float]

Returns

Dictionary of ion : ion_area pairs.

Authors

Sean O’Callaghan, Dominic Davis-Foster (type assertions)

top_ions_v1(peak, num_ions=5)[source]

Computes the highest 5 intensity ions.

Parameters

peak (Peak) – the peak to be processed.
num_ions (int) – The number of ions to be recorded. Default 5.

Return type

List[float]

Returns

A list of the top 5 highest intensity ions

Authors

Sean O’Callaghan, Dominic Davis-Foster (type assertions)

Deprecated since version 2.0.0: This will be removed in 2.4.0. Use pyms.Peak.Function.top_ions_v2() instead

top_ions_v2(peak, num_ions=5)[source]

Computes the highest #num_ions intensity ions.

Parameters

peak (Peak) – The peak to be processed
num_ions (int) – The number of ions to be recorded. Default 5.

Return type

List[float]

Returns

A list of the num_ions highest intensity ions

Authors

Sean O’Callaghan, Dominic Davis-Foster (type assertions)

Deprecated since version 2.1.2: This will be removed in 2.5.0. Use pyms.Peak.Class.Peak.top_ions() instead

`pyms.Peak.List`

Functions for modelling peak lists.

`pyms.Peak.List.Function`

Functions related to Peak modification.

Functions:

`composite_peak`(peak_list[, ignore_outliers])	Create a peak that consists of a composite spectrum from all spectra in the list of peaks.
`fill_peaks`(data, peak_list, D[, minutes])	Gets the best matching Retention Time and spectra from ‘data’ for each peak in the peak list.
`is_peak_list`(peaks)	Returns whether `peaks` is a valid peak list.
`sele_peaks_by_rt`(peaks, rt_range)	Selects peaks from a retention time range.

composite_peak(peak_list, ignore_outliers=False)[source]

Create a peak that consists of a composite spectrum from all spectra in the list of peaks.

Parameters

peak_list (List[Peak]) – A list of peak objects
ignore_outliers (bool) – Default False.

Return type

Optional[Peak]

Returns

The composite peak

Authors

Andrew Isaac, Dominic Davis-Foster (type assertions)

fill_peaks(data, peak_list, D, minutes=False)[source]

Gets the best matching Retention Time and spectra from ‘data’ for each peak in the peak list.

Parameters

data (BaseIntensityMatrix) – A data IntensityMatrix that has the same mass range as the peaks in the peak list
peak_list (List[Peak]) – A list of peak objects
D (float) – Peak width standard deviation in seconds. Determines search window width.
minutes (bool) – Return retention time as minutes. Default False.

Return type

List[Peak]

Returns

List of Peak Objects

Authors

Andrew Isaac, Dominic Davis-Foster (type assertions)

is_peak_list(peaks)[source]

Returns whether peaks is a valid peak list.

Author: Dominic Davis-Foster
Return type: bool

sele_peaks_by_rt(peaks, rt_range)[source]

Selects peaks from a retention time range.

Parameters

peaks (Union[Sequence[Peak], ndarray]) – A list of peak objects
rt_range (Sequence[str]) – A list of two time strings, specifying lower and upper retention times.

Return type

List[Peak]

Returns

A list of peak objects

`pyms.Peak.List.IO`

Functions related to storing and loading a list of Peak objects.

Functions:

`load_peaks`(file_name)	Loads the peak_list stored with `store_peaks()`.
`store_peaks`(peak_list, file_name[, protocol])	Store the list of peak objects.

load_peaks(file_name)[source]

Loads the peak_list stored with store_peaks().

Parameters: file_name (Union[str, Path, PathLike]) – File name of peak list
Return type: List[Peak]
Returns: The list of Peak objects
Authors: Andrew Isaac, Dominic Davis-Foster (pathlib support)

store_peaks(peak_list, file_name, protocol=1)[source]

Store the list of peak objects.

Parameters

peak_list (Sequence[Peak]) – A list of peak objects.
file_name (Union[str, Path, PathLike]) – File name to store peak list.
protocol (int) – The pickle protocol to use. Default 1.

Authors

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

pyms.Peak

pyms.Peak.Class

pyms.Peak.Function

pyms.Peak.List

pyms.Peak.List.Function

pyms.Peak.List.IO

`pyms.Peak`

`pyms.Peak.Class`

`pyms.Peak.Function`

`pyms.Peak.List`

`pyms.Peak.List.Function`

`pyms.Peak.List.IO`