# Vendor Format Abstraction

> Use when you have mass-spectrometry raw data files from multiple vendors (e.g., Thermo, Waters, Bruker, Sciex) and/or mixed standard formats (mzML, mzXML) that must be processed by a single analysis pipeline.

- Skill: `holobiomicslab/vendor-format-abstraction` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/vendor-format-abstraction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/vendor-format-abstraction/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- 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/vendor-format-abstraction

---


# vendor-format-abstraction

## Summary

Unifies access to mass-spectrometry data files across heterogeneous vendor binary formats, mzML, mzXML, and other formats through a single pluggable API layer that normalizes spectra into a common in-memory representation. This skill is essential when handling proteomics datasets from multiple instrument vendors or format standards, eliminating the need for format-specific parsing logic in downstream analysis.

## When to use

You have mass-spectrometry raw data files from multiple vendors (e.g., Thermo, Waters, Bruker, Sciex) and/or mixed standard formats (mzML, mzXML) that must be processed by a single analysis pipeline. Use this skill when you need to expose heterogeneous input files through a uniform programmatic interface without rewriting parsers for each vendor or format variant.

## When NOT to use

- Input is already a normalized feature table or matrix (e.g., peptide quantification, peak picking already performed)—abstraction operates at the raw spectrum level, not aggregated data.
- You require vendor-specific metadata or features not present in the unified schema (e.g., instrument-proprietary tuning parameters, vendor-specific auxiliary spectra)—abstraction by design discards format-specific details.
- Performance is critical and vendor binary reading on non-Windows platforms is necessary—direct vendor format support is limited to Windows; mzML/mzXML are cross-platform alternatives.

## Inputs

- vendor binary mass-spectrometry raw data files (e.g., .raw, .d, .wiff)
- mzML standard format mass-spectrometry data files
- mzXML standard format mass-spectrometry data files
- file path or stream pointing to any supported mass-spectrometry data format

## Outputs

- normalized in-memory spectrum objects with unified metadata (scan ID, retention time, m/z array, intensity array, precursor m/z, charge state)
- spectrum iterator or random-access interface hiding vendor/format details
- LCMS dataset object with standard chemistry computations pre-applied

## How to apply

Design a unified spectrum data structure that captures essential metadata (scan ID, retention time, m/z values, intensity values, precursor m/z, charge state) invariant across formats. Implement file format detection and routing logic to identify input file type (mzML, mzXML, vendor binary, etc.). Integrate or wrap existing vendor-specific parsers and standard format libraries into a pluggable framework. Normalize parsed spectra into the unified in-memory representation, handling vendor-specific conventions and metadata extraction. Expose the normalized spectra through a single API interface (iterator, random-access getter, or query methods) that hides format-specific implementation details from the caller. Test that spectra read from different formats produce identical normalized outputs for the same underlying instrument run.

## Related tools

- **ProteoWizard Library and Tools** (Provides the reference implementation of the pluggable development framework, vendor parser integrations, and unified spectrum API for reading mass-spectrometry data files across formats) — https://github.com/ProteoWizard/pwiz
- **pwiz** (Core C++ library and command-line tools (e.g., msconvert) that implement the vendor-format abstraction layer and expose spectrum normalization) — https://github.com/ProteoWizard/pwiz

## Evaluation signals

- Spectra read from vendor binary format and equivalent mzML/mzXML produce byte-identical or schema-validated equivalent normalized outputs (scan ID, retention time, m/z, intensity, precursor m/z, charge state all match within floating-point tolerance).
- A single code path successfully reads spectra from files of different formats without conditional branching on format type.
- Downstream analysis tools receive spectrum objects with consistent field types and value ranges regardless of input file format origin.
- File format detection correctly routes input to the appropriate parser without user specification of format type.
- All vendor-specific metadata and parsing errors are gracefully handled; no crashes on unsupported vendor variants or corrupt format-specific headers.

## Limitations

- Direct vendor raw data format support is limited to Windows; cross-platform access requires conversion to mzML or mzXML via msconvert or equivalent offline step.
- Vendor-specific proprietary metadata (e.g., instrument tuning parameters, vendor-specific spectra types) are either discarded or incompletely mapped into the unified schema; custom wrappers may be needed to preserve such data.
- Unified schema supports only the most common spectrum metadata (scan ID, retention time, m/z, intensity, precursor m/z, charge state); less common vendor-specific fields require extension or custom handling.

## Evidence

- [other] Unified data structure design rationale: "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] Format detection and routing mechanism: "Implement file format detection and routing logic to identify the input file type (mzML, mzXML, vendor binary, etc.)."
- [other] Abstraction API exposure: "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] ProteoWizard framework design principle: "provide a robust, pluggable development framework that simplifies and unifies data file access"
- [readme] mzML standard implementation and cross-platform support: "reference implementation of HUPO-PSI mzML standard mass spectrometry data format"
- [readme] Vendor format support scope: "supports reading directly from many vendor raw data formats (on Windows)"