Skip to content

emzed.ms_data

ImmutablePeakMap

Bases: DbBackedModel

Immutable LCMS experiment wrapper backed by a SQLite database.

unique_id property

Stable content-based identifier for the peak map.

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.

close()

Close the underlying database connection.

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.

extract_for_precursors(mzs, mz_tol, *, target_db_file=None)

Extract MSn spectra whose precursor windows match the given m/z values.

Parameters:

Name Type Description Default
mzs

precursor m/z values to match.

required
mz_tol

absolute m/z tolerance used for matching.

required
target_db_file

optional output database path for the extracted result.

None

Returns:

Type Description

PeakMap.

filter(predicate, target_db_file=None)

Create a new peak map containing spectra that match a predicate.

Parameters:

Name Type Description Default
predicate

callable receiving a spectrum and returning True for spectra to keep.

required
target_db_file

optional output database path for the filtered result.

None

Returns:

Type Description

PeakMap.

get_dominating_peak_map()

Return the lowest MS-level sub-peakmap as an MS1-style peak map.

get_precursors_mzs()

Return the unique precursor m/z tuples of all annotated MSn spectra.

Each tuple holds the sorted precursor m/z values of one spectrum.

is_in_memory()

Return True if the peak map is backed by an in-memory database.

is_open()

Return True if the underlying database connection is open.

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.

ms_levels()

Return the MS levels present in the peak map.

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

mz_ranges(ms_level=None)

Return the m/z ranges indexed by MS level.

open(path) classmethod

Open a peak map database without copying it into memory.

Parameters:

Name Type Description Default
path

path to an emzed peak-map database file.

required

Returns:

Type Description

ImmutablePeakMap.

polarities()

Return the set of ion polarities present in the peak map.

representing_mz_peak(mzmin, mzmax, rtmin, rtmax, ms_level=1)

Return an intensity-weighted representative m/z inside a 2D window.

Parameters:

Name Type Description Default
mzmin

minimum m/z bound.

required
mzmax

maximum m/z bound.

required
rtmin

minimum retention time in seconds.

required
rtmax

maximum retention time in seconds.

required
ms_level

MS level to inspect.

1

Returns:

Type Description

representative m/z as float or None if no peak matches.

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

rt_ranges(ms_level=None)

Return the retention-time ranges indexed by MS level.

save(path, *, overwrite=False)

Write the peak map to mzML or mzXML.

Parameters:

Name Type Description Default
path

target output path.

required
overwrite

overwrite an existing output file.

False

scan_counts()

Return the number of scans grouped by MS level.

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.

summary()

Return a compact table summarizing RT, m/z, scan counts, and polarities.

MSChromatogram

Mass-spectrometry chromatogram with optional precursor annotation.

available_types property

Return the list of supported chromatogram type names.

intensities property

Intensity values of the chromatogram.

mz property

Target m/z of the chromatogram.

precursor_mz property

Precursor m/z associated with the chromatogram, if any.

rts property

Retention times of the chromatogram.

type property

Return the chromatogram type name.

rt_range()

Return the chromatogram retention-time range.

PeakMap

Bases: ImmutablePeakMap

Mutable variant of ImmutablePeakMap.

add_spectrum(spectrum)

Reject direct mutation on immutable peak maps.

Parameters:

Name Type Description Default
spectrum

spectrum that would otherwise be appended.

required

from_(clz, pm, *, target_db_file=None) classmethod

Copy a peak map into a mutable database-backed instance.

Parameters:

Name Type Description Default
pm

source peak map.

required
target_db_file

optional target database path for the copy.

None

Returns:

Type Description

PeakMap.

merge(other)

Merge another mutable peak map into this one.

Parameters:

Name Type Description Default
other

peak map with non-overlapping scan numbers.

required

spectra_for_modification()

contextmanager. in this context one can change spectra attributes like rt, ms_level, peaks or polarity

Spectrum

Detached in-memory spectrum record.

unbind()

dettaches spectrum from peakmap