HolobiomicsLab 
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"