# Custom Mzml Index Pattern Definition

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

- Skill: `holobiomicslab/custom-mzml-index-pattern-definition` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/custom-mzml-index-pattern-definition`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/custom-mzml-index-pattern-definition/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/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"