Skip to content

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. Without target_db_file, the converted peak map is kept in memory.
  • Pass target_db_file=... to write the converted database to disk; then PeakMap.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 target_db_file if it already exists.

False

Returns:

Type Description

ImmutablePeakMap.

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 "+" or "-".

None
target_db_file

optional output database path for the extracted result.

None

Returns:

Type Description

PeakMap.

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 returns the full-range summary.

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 returns the full-range summary.

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 "+" or "-".

None

Returns:

Type Description

Chromatogram.

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:

(378.33, 473.17, 631.23, 947.10)

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 "binning" mode; maximum m/z span per precursor in "clustering" mode.

0.0
method

grouping strategy, see Notes.

'binning'

Returns:

Type Description

dict mapping group keys to PeakMap objects; see Notes for the key types.

Raises:

Type Description
ValueError

if mz_tol is negative or not finite, or if method is not "binning" or "clustering".

Notes: - method="binning" (default) keeps the legacy behaviour: each precursor m/z is rounded into mz_tol-sized bins. Overlapping tolerance windows can assign one MSn spectrum to several sub-peakmaps. The key is the bin tuple, or the exact precursor tuple when mz_tol == 0. - method="clustering" uses complete-linkage clustering. For a spectrum with several precursors, mz_tol applies to each precursor m/z independently. Each MSn spectrum belongs to exactly one sub-peakmap, and within a group each precursor's m/z span is at most mz_tol. The key is a representative member tuple: the one 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.

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: str Chromatogram type name.
  • mz: float | None Target m/z of the chromatogram.
  • precursor_mz: float | None Precursor m/z associated with the chromatogram, if any.
  • rts: np.ndarray Retention times.
  • intensities: np.ndarray Intensity 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-memory Spectrum.
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

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:

import emzed

emzed.run_feature_finder_metabo_on_folder(
    "raw_data",
    file_patterns=["*.mzML"],
    out_folder="peaks",
    ms_level=1,
    n_cores=4,
    overwrite=True,
)