Custom Mzml Index Pattern Definition

---
name: custom-mzml-index-pattern-definition
description: Use when 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.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3357
  edam_topics:
  - http://edamontology.org/topic_3520
  - http://edamontology.org/topic_0121
  tools:
  - pymzML
  - Python
  techniques:
  - mass-spectrometry
derived_from:
- doi: 10.1093/bioinformatics/bty046
  title: pymzml
evidence_spans: []
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_pymzml_cq
    doi: 10.1093/bioinformatics/bty046
    title: pymzml
  dedup_kept_from: coll_pymzml_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1093/bioinformatics/bty046
  all_source_dois:
  - 10.1093/bioinformatics/bty046
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

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