Custom mzml index pattern definition

custom-mzml-index-pattern-definition

Summary

Define and apply custom regular expression patterns with named capture groups ('ID' and 'offset') to parse non-standard mzML index formats, enabling random-access spectrum retrieval from mzML files that do not conform to the standard index schema.

When to use

Your mzML file contains custom or non-standard spectrum index identifiers that do not follow the default mzML indexing convention, and you need random-access retrieval of spectra by these identifiers. This arises when files are generated by custom mass spectrometry software or databases that assign their own identifier schemes (e.g., Manuels_customs_ids.mzML).

When NOT to use

• The mzML file uses the standard mzML index format; use default Reader instantiation instead.
• The custom identifier scheme does not have a regular structure that can be captured by a single regex pattern.
• You only need sequential iteration through spectra; the overhead of custom index parsing is not justified.

Inputs

• mzML file with non-standard custom index identifiers
• regular expression pattern string with named groups 'ID' and 'offset'

Outputs

• pymzML.run.Reader instance configured with custom index parsing
• Spectrum objects accessible via bracket notation using custom identifiers

How to apply

Construct a regular expression pattern that matches the custom identifier structure in your mzML file, ensuring it includes two named groups: 'ID' (capturing the spectrum identifier) and 'offset' (capturing the byte offset in the file). Pass this regex pattern as the index_regex parameter when instantiating pymzML.run.Reader. During initialization, pymzML applies the regex to the index section of the mzML file to extract identifiers and offsets. Verify successful parsing by invoking bracket-notation access (e.g., run[custom_id]) to retrieve a Spectrum object and confirm its ID and XML element attributes match your custom identifiers.

Related tools

• pymzML (Provides the Reader class accepting index_regex parameter and bracket-notation getitem random-access function for parsing custom-indexed mzML files) — https://github.com/pymzml/pymzML
• Python (Runtime environment for constructing regex patterns and invoking pymzML Reader with custom index_regex)

Examples

import re
from pymzML.run import Reader
index_regex = r'(?P<ID>spectrum_\d+).*offset=(?P<offset>\d+)'
run = Reader('Manuels_customs_ids.mzML', index_regex=index_regex)
spectrum = run['spectrum_1']

Evaluation signals

• The Reader instance initializes without exceptions when passed the custom index_regex parameter.
• Bracket-notation access run[custom_id] returns a valid Spectrum object (not None or error).
• The returned Spectrum object's ID attribute matches the custom identifier captured by the 'ID' named group.
• The XML element attribute of the Spectrum object corresponds to the correct position in the file as specified by the 'offset' named group.
• Sequential and random access to multiple custom-identified spectra yield consistent, non-overlapping data blocks.

Limitations

• The regex pattern must exactly match the structure of the custom index in the mzML file; mismatched patterns will fail silently or raise parsing errors.
• Complex or inconsistent identifier schemes that cannot be expressed as a single regex pattern are not supported.
• Custom index parsing may incur additional initialization overhead compared to standard mzML files, though random access remains efficient after parsing.

Evidence

• [other] pymzML.run.Reader accepts an index_regex parameter containing named groups 'ID' and 'offset' to parse custom index formats: "pymzML.run.Reader accepts an index_regex parameter containing named groups 'ID' and 'offset' to parse custom index formats; the regex pattern is applied during initialization to extract spectrum"
• [readme] Random access in compressed files is supported: "pymzML is an extension to Python that offers ... d) random access in compressed files"
• [other] Bracket notation enables indexing: "access the chapters conveniently by the python bracket notation ([])"
• [other] Spectrum retrieval via bracket notation: "Invoke the bracket notation run[1] to retrieve the spectrum at custom index 1 using the getitem random-access function"
• [readme] Parser supports custom file formats: "In order to make pymzML accept other kinds of mzML data (e.g databases), one can implement an own wrapper"