# Mass Spectrometry Data Object Instantiation

> Use when when you have mass spectrometry data stored in non-standard formats (SQLite, HDF5, custom binary) that pymzML does not natively support, and you want to enable random-access and sequential parsing of spectra without converting to mzML first.

- Skill: `holobiomicslab/mass-spectrometry-data-object-instantiation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/mass-spectrometry-data-object-instantiation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/mass-spectrometry-data-object-instantiation/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/mass-spectrometry-data-object-instantiation

---


# mass-spectrometry-data-object-instantiation

## Summary

Implement a custom file handler class that wraps mass spectrometry data stored in alternative formats (e.g., SQLite databases) by implementing the `__getitem__()` and `read()` interface methods, then register it with pymzML's FileInterface to enable transparent spectrum/chromatogram object construction during parsing.

## When to use

When you have mass spectrometry data stored in non-standard formats (SQLite, HDF5, custom binary) that pymzML does not natively support, and you want to enable random-access and sequential parsing of spectra without converting to mzML first. Triggers include: file extension not recognized by FileInterface, need for database-backed storage to reduce file size, or requirement for indexed access patterns incompatible with direct mzML parsing.

## When NOT to use

- Input data is already in standard mzML or mzML.gz format — use pymzML's built-in parser directly.
- Data store does not have stable, queryable spectrum indexing — the handler requires predictable key-to-record mapping.
- Performance-critical application requiring sub-millisecond spectrum access — database queries may introduce latency compared to indexed gzip seeking.

## Inputs

- SQLite database file (.db) or alternative data store with indexed spectrum records
- File path string pointing to the data store
- Spectrum ID (integer or string key) for random access

## Outputs

- Spectrum object (pymzML.spec.Spectrum) or Chromatogram object (pymzML.spec.Chromatogram)
- XML string representation of spectrum metadata and data
- Integer count of spectra in the data store

## How to apply

First, create or populate a data store (e.g., SQLite database with a 'Spectra' table containing spectrum ID and XML element columns) from an existing mzML file using sqlite3. Second, implement a connector class with `__init__` (accepting file path), `__getitem__(key)` (executing queries and parsing XML strings into Spectrum or Chromatogram objects via pymzML.spec), `get_spectrum_count()` returning the total number of entries, and `read()` returning XML strings sequentially. Import ElementTree to parse XML retrieved from the store into Element objects. Third, modify FileInterface._open() to add an elif clause that detects the target file extension (e.g., `path.endswith('.db')`) and instantiates your connector class, assigning the instance to the file_handler variable. Finally, instantiate pymzML.Reader with a path to the new format; it will dispatch to your handler transparently.

## Related tools

- **pymzML** (Parsing framework; provides spec module for Spectrum/Chromatogram object construction and FileInterface dispatch logic) — https://github.com/pymzml/pymzML
- **sqlite3** (Creating and querying the spectrum data store; retrieving indexed XML elements)
- **ElementTree** (Parsing XML strings retrieved from the database into Element objects for spectrum construction)
- **black** (Code style enforcement for maintaining consistent formatting in the connector class implementation) — https://github.com/psf/black

## Examples

```
from pymzml import run; import sqlite3; conn = sqlite3.connect('spectra.db'); conn.execute('CREATE TABLE Spectra (id TEXT, xml TEXT)'); run(Reader('spectra.db'))
```

## Evaluation signals

- FileInterface._open() successfully routes .db file paths to the new handler class without raising KeyError or AttributeError.
- Calling `handler[0]` and `handler[1]` returns valid pymzML Spectrum or Chromatogram objects with populated m/z and intensity arrays.
- Sequential iteration via repeated `read()` calls returns non-empty XML strings in order, covering all spectra in the store.
- `get_spectrum_count()` matches the row count of the underlying data store (SELECT COUNT(*) FROM Spectra).
- pymzML.Reader instantiated with the .db file path successfully iterates spectra and produces identical m/z values compared to parsing the source mzML file directly.

## Limitations

- Database query latency may degrade performance for interactive visualization or real-time processing compared to native indexed gzip access.
- The handler assumes a fixed schema (spectrum ID and XML element columns); custom data stores with different layouts require rewriting __getitem__ and read() logic.
- No built-in support for partial spectrum loading or streaming; __getitem__ must reconstruct the entire Spectrum object on each access.
- XML parsing via ElementTree requires the full XML string to be in memory; very large spectra or chromatograms may cause memory overhead.

## Evidence

- [other] The SQLiteDatabase connector class implements __getitem__(key) to execute SQL queries and return Spectrum or Chromatogram objects parsed from XML elements: "The SQLiteDatabase connector class implements __getitem__(key) to execute SQL queries and return Spectrum or Chromatogram objects"
- [other] FileInterface._open() function dispatches .db file paths via an elif condition checking path.endswith('.db'): "FileInterface._open() function dispatches .db file paths to this handler via an elif condition checking path.endswith('.db')"
- [intro] a new class needs to be written, which implements a `read` and a `__getitem__` function: "a new class needs to be written, which implements a `read` and a `__getitem__` function"
- [other] In order to make pymzML accept other kinds of mzML data (e.g databases), one can implement an own wrapper: "In order to make pymzML accept other kinds of mzML data (e.g databases), one can implement an own wrapper"
- [other] a read function used to sequentially read in data for iterating the database. In this simple approach, the read function always returns a whole spectra xml string: "a read function used to sequentially read in data for iterating the database. In this simple approach, the read function always returns a whole spectra xml string"
- [other] Create a SQLite database from an mzML file using sqlite3, storing spectrum ID and XML element pairs in a 'Spectra' table with two columns: "Create a SQLite database from an mzML file using sqlite3, storing spectrum ID and XML element pairs in a 'Spectra' table with two columns"