Peak Data and Chromatograms¶
This page highlights the most often used API functionalities and is not complete.
It covers PeakMap, MSChromatogram,
Spectrum, and the feature-finding helper functions.
For complete coverage, see the API Reference.
PeakMap¶
Primary LC-MS container. Functional loading alternative: emzed.io.load_peak_map(path).
Usage pattern (class method vs instance methods):
import emzed
# class method
pm = emzed.PeakMap.load("sample.mzML")
# functional alternative (same resulting object type)
pm = emzed.io.load_peak_map("sample.mzML")
# instance methods
pm2 = pm.extract(rtmin=60.0, rtmax=300.0, mslevelmin=1, mslevelmax=1)
rt_lo, rt_hi = pm.rt_range()
mz_lo, mz_hi = pm.mz_range()
chrom = pm.chromatogram(mzmin=255.0, mzmax=256.0, ms_level=1)
submaps = pm.split_by_precursors(mz_tol=0.01) # binning (default)
summary = pm.summary()
print(summary)
Example output:
PeakMap info:
source: sample.mzML
spectra: 1321
ms_levels: [1, 2]
rt_range: (6.24, 1220.51)
mz_range: (70.0, 1500.0)
polarities: {'+'}
In-memory vs on-disk¶
A PeakMap can live in RAM or on disk, backed by a SQLite database file.
PeakMap.load(path)converts an mzML/mzXML source file. Withouttarget_db_file, the converted peak map is kept in memory.- Pass
target_db_file=...to write the converted database to disk; thenPeakMap.open(target_db_file)returns a lightweight on-disk handle without loading spectra into RAM.
Use pm.is_in_memory() to check which mode the peak map is in, and
pm.close() to release the file handle when done. Operations like
pm.extract(...) return views that stay on disk; iterating fetches spectra
on demand.
load(path, *, target_db_file=None, overwrite=False)
classmethod
¶
Load an mzML or mzXML file into an emzed peak-map database.
This is a class method, so call it on the class (for example
emzed.PeakMap.load(...)), not on an existing instance.
Example: pm = emzed.PeakMap.load("sample.mzML").
Functional alternative: pm = emzed.io.load_peak_map("sample.mzML").
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
source mass-spectrometry file. |
required | |
target_db_file
|
optional output database path. If omitted, an in-memory database is used. |
None
|
|
overwrite
|
overwrite |
False
|
Returns:
| Type | Description |
|---|---|
|
|
extract(mzmin=None, mzmax=None, rtmin=None, rtmax=None, imin=None, imax=None, mslevelmin=None, mslevelmax=None, precursormzmin=None, precursormzmax=None, polarity=None, *, target_db_file=None)
¶
Extract a sub-peakmap using RT, m/z, intensity, precursor, and polarity limits.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mzmin
|
minimum fragment m/z to keep. |
None
|
|
mzmax
|
maximum fragment m/z to keep. |
None
|
|
rtmin
|
minimum retention time in seconds. |
None
|
|
rtmax
|
maximum retention time in seconds. |
None
|
|
imin
|
minimum intensity to keep. |
None
|
|
imax
|
maximum intensity to keep. |
None
|
|
mslevelmin
|
minimum MS level to keep. |
None
|
|
mslevelmax
|
maximum MS level to keep. |
None
|
|
precursormzmin
|
minimum precursor m/z to keep for MSn spectra. |
None
|
|
precursormzmax
|
maximum precursor m/z to keep for MSn spectra. |
None
|
|
polarity
|
optional polarity filter, either |
None
|
|
target_db_file
|
optional output database path for the extracted result. |
None
|
Returns:
| Type | Description |
|---|---|
|
|
rt_range(ms_level=None)
¶
Return the retention-time range for one MS level or for the full peak map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ms_level
|
optional MS level. |
None
|
mz_range(ms_level=None)
¶
Return the m/z range for one MS level or for the full peak map.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ms_level
|
optional MS level. |
None
|
ms_levels()
¶
Return the MS levels present in the peak map.
polarities()
¶
Return the set of ion polarities present in the peak map.
summary()
¶
Return a compact table summarizing RT, m/z, scan counts, and polarities.
chromatogram(mzmin=None, mzmax=None, rtmin=None, rtmax=None, ms_level=None, precursormzmin=None, precursormzmax=None, polarity=None)
¶
Integrate a chromatogram over the given extraction window.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mzmin
|
minimum fragment m/z included in the chromatogram. |
None
|
|
mzmax
|
maximum fragment m/z included in the chromatogram. |
None
|
|
rtmin
|
minimum retention time in seconds. |
None
|
|
rtmax
|
maximum retention time in seconds. |
None
|
|
ms_level
|
MS level to extract. If omitted, the lowest present level is used. |
None
|
|
precursormzmin
|
minimum precursor m/z for MSn extraction. |
None
|
|
precursormzmax
|
maximum precursor m/z for MSn extraction. |
None
|
|
polarity
|
optional polarity filter, either |
None
|
Returns:
| Type | Description |
|---|---|
|
|
Precursor splitting¶
An MSn spectrum can have zero, one, or several precursors:
- MS1 spectra have none.
- A normal DDA MS2 spectrum has one: the ion that was fragmented.
- An MS3 spectrum has one: the MS2 fragment selected for further fragmentation.
- A multiplexed (MSX) MS2 spectrum has several: the ions that were co-fragmented in the same scan.
Each precursor is stored as an (mz, intensity, charge) row linked to the
spectrum's scan number. Splitting uses only the m/z values. The key for a
spectrum is its precursor m/z tuple: the sorted precursor m/z values,
one entry per precursor. Intensities, charges, and retention time are not
part of the key, so tuple lengths may differ between spectra.
For example, a multiplexed MS2 scan with four precursors (m/z 378.33, 473.17, 631.23, and 947.10) is keyed as:
split_by_precursors groups spectra with similar keys and returns one
sub-peakmap per group:
method="binning" (default) |
method="clustering" |
|
|---|---|---|
| Grouping | rounds each precursor m/z into mz_tol bins |
complete-linkage clustering per precursor |
mz_tol |
bin width | maximum m/z span per precursor |
| Spectrum membership | can appear in several sub-peakmaps | exactly one sub-peakmap |
| Result keys | bin tuple, or exact precursor tuple if mz_tol == 0 |
representative member tuple, closest to the per-index mean m/z |
Only MSn spectra with at least one precursor participate. MS1 spectra and unannotated MSn spectra are not part of any group.
split_by_precursors(mz_tol=0.0, *, method='binning')
¶
Split the peak map into sub-peakmaps grouped by precursor m/z tuples.
An MSn spectrum may have one or several precursors. The key for a
spectrum is the sorted tuple of its precursor m/z values, one entry per
precursor. Intensities, charges, and retention time are not part of
the key, so tuple lengths may differ between spectra and are never
mixed. This differs from Spectrum.precursors, which returns
(mz, intensity, charge) rows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mz_tol
|
bin width in |
0.0
|
|
method
|
grouping strategy, see Notes. |
'binning'
|
Returns:
| Type | Description |
|---|---|
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
if Notes:
- |
merge(other)
¶
Merge another mutable peak map into this one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
other
|
peak map with non-overlapping scan numbers. |
required |
MSChromatogram¶
Mass-spectrometry chromatogram container.
rt_range()
¶
Return the chromatogram retention-time range.
Attributes¶
available_types: list[str]List of supported chromatogram type names.type: strChromatogram type name.mz: float | NoneTarget m/z of the chromatogram.precursor_mz: float | NonePrecursor m/z associated with the chromatogram, if any.rts: np.ndarrayRetention times.intensities: np.ndarrayIntensity values.
Raw-data access example:
import emzed
pm = emzed.io.load_peak_map("sample.mzML")
chrom = pm.ms_chromatograms[0]
print(chrom.type, chrom.mz, chrom.precursor_mz)
print(chrom.rt_range())
print(chrom.rts[:5])
print(chrom.intensities[:5])
Spectrum¶
Detached in-memory spectrum record.
For example, pm.spectra[0] returns a bound spectrum view from a peak map.
Call .unbind() only when you specifically need a detached in-memory
Spectrum.
unbind()
¶
dettaches spectrum from peakmap
Raw-data access and modification model:
pm.spectra[i]returns a bound (DB-backed) spectrum view.- Bound spectra are read-only unless you use
pm.spectra_for_modification(). pm.spectra[i].unbind()returns a detached in-memorySpectrum.
import emzed
pm = emzed.io.load_peak_map("sample.mzML")
bound_spec = pm.spectra[0] # bound, DB-backed view
# pure read access: use bound spectrum directly
print(bound_spec.scan_number, bound_spec.ms_level, bound_spec.rt, bound_spec.polarity)
print(bound_spec.mzs[:5], bound_spec.intensities[:5])
# optional: create detached in-memory Spectrum
spec = bound_spec.unbind()
# To modify spectra in the peak map, use the dedicated context manager:
with pm.spectra_for_modification() as spectra:
spectra[0].rt = spectra[0].rt + 1.0
Related Functions¶
run_feature_finder_metabo¶
emzed wrapper around OpenMS FeatureFinderMetabo.
Signature:
run_feature_finder_metabo(
peak_map,
ms_level=None,
verbose=True,
run_feature_grouper=True,
split_by_precursors_mz_tol=0.0,
split_by_precursors_method="binning",
**parameters,
)
run_feature_finder_metabo_on_folder¶
Run feature finding on all matching files in a folder and save one
*_peaks.table per input file.
Signature:
run_feature_finder_metabo_on_folder(
in_folder,
file_patterns=None,
out_folder=None,
ms_level=None,
n_cores=1,
verbose=False,
run_feature_grouper=True,
split_by_precursor_mz_tol=0.0,
overwrite=False,
split_by_precursor_method="binning",
**parameters,
)
Example: