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)
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.

MSChromatogram¶

Mass-spectrometry chromatogram container.

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.

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

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,
    **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,
    **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,
)