# Proteomics Data Structure Design

> Use when when building a mass-spectrometry analysis pipeline that must support multiple vendor and open formats (mzML, mzXML, Thermo, Agilent, Bruker, etc.) and you need to shield downstream tools from format-specific parsing logic.

- Skill: `holobiomicslab/proteomics-data-structure-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/proteomics-data-structure-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/proteomics-data-structure-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/proteomics-data-structure-design

---


# proteomics-data-structure-design

## Summary

Design and implement a unified, vendor-agnostic spectrum data structure that normalizes mass-spectrometry data from heterogeneous file formats (mzML, mzXML, vendor binary) into a single in-memory representation. This skill enables a single API to transparently read and expose normalized spectra regardless of input format.

## When to use

When building a mass-spectrometry analysis pipeline that must support multiple vendor and open formats (mzML, mzXML, Thermo, Agilent, Bruker, etc.) and you need to shield downstream tools from format-specific parsing logic. Specifically when you have raw or vendor-specific mass-spec files and must expose them through a uniform data interface.

## When NOT to use

- Input is already in a standardized format (mzML) and downstream tools natively support it without needing a unified layer.
- You require format-specific features or vendor-proprietary metadata that would be lost during normalization.
- Performance is critical and the overhead of abstraction and normalization exceeds the benefit of format transparency.

## Inputs

- Raw mass-spectrometry data files (mzML, mzXML, vendor binary formats)
- Format metadata and schema definitions
- Format-specific parser libraries or bindings

## Outputs

- Unified spectrum data structure (in-memory representation)
- Normalized spectrum metadata (scan ID, retention time, m/z, intensity, precursor m/z, charge state)
- Single API interface for spectrum access (iterator or query methods)

## How to apply

First, design a unified spectrum data structure schema that captures essential metadata: scan ID, retention time, m/z array, intensity array, precursor m/z, and charge state. Implement file format detection and routing logic to identify the input file type. Integrate or wrap existing format-specific parsers (e.g., ProteoWizard libraries or vendor-provided readers) to read raw spectra. Normalize parsed spectra into the unified in-memory representation, handling format-specific conventions and metadata extraction rules. Finally, expose normalized spectra through a single API interface (iterator, random-access getter, or query methods) that hides format details from the caller. Use the pluggable framework approach to allow new format support without modifying core normalization logic.

## Related tools

- **ProteoWizard Library and Tools** (Provides robust, pluggable development framework and format-specific parsers for unifying mass-spec data file access) — https://github.com/ProteoWizard/pwiz
- **pwiz** (Core library implementing reference implementation of HUPO-PSI mzML standard and vendor format support) — https://github.com/ProteoWizard/pwiz

## Evaluation signals

- All input spectra from different formats (mzML, mzXML, vendor binary) can be read and produce identical normalized output when the same raw data is used.
- Unified data structure contains all required fields (scan ID, retention time, m/z array, intensity array, precursor m/z, charge state) with no null or missing values for valid spectra.
- Single API interface successfully returns spectra without caller needing to know or specify the input format.
- Format-specific metadata is correctly preserved or mapped into the normalized schema without loss of essential information.
- Performance overhead of normalization layer is acceptable relative to the benefit of format abstraction (typically < 10–20% overhead).

## Limitations

- Vendor binary format support on Windows only; cross-platform pipelines may be limited to mzML/mzXML or require format conversion on non-Windows systems.
- Normalization may lose vendor-specific or proprietary metadata that is not part of the HUPO-PSI mzML standard.
- Pluggable framework requires maintenance when vendor formats change or new formats are introduced.
- No changelog or versioning information is available for tracking API or schema changes over time.

## Evidence

- [other] Design a unified spectrum data structure that captures essential metadata (scan ID, retention time, m/z values, intensity values, precursor m/z, charge state) and supports multiple vendor and open formats.: "Design a unified spectrum data structure that captures essential metadata (scan ID, retention time, m/z values, intensity values, precursor m/z, charge state) and supports multiple vendor and open"
- [other] Normalize parsed spectra into the unified in-memory representation, handling format-specific conventions and metadata extraction.: "Normalize parsed spectra into the unified in-memory representation, handling format-specific conventions and metadata extraction."
- [other] Expose the normalized spectra through a single API interface (e.g., iterator, random-access getter, or query methods) that hides format-specific details from the caller.: "Expose the normalized spectra through a single API interface (e.g., iterator, random-access getter, or query methods) that hides format-specific details from the caller."
- [readme] The libraries provide a robust, pluggable development framework that simplifies and unifies data file access: "provide a robust, pluggable development framework that simplifies and unifies data file access"
- [readme] supports reading directly from many vendor raw data formats (on Windows): "supports reading directly from many vendor raw data formats (on Windows)"