HolobiomicsLab 
mass-spectrometry-data-processing
Summary
Convert vendor-specific mass spectrometry file formats (RAW, mzML, jcamp) into standardized internal representations with extracted metadata and peak tables. This skill enables interoperable MS data processing within spectral analysis workflows by normalizing heterogeneous instrument outputs.
When to use
You have raw mass spectrometry data in vendor-specific formats (Thermo RAW, Waters RAW, or open formats like mzML/jcamp) that need to be ingested, validated, and converted to a standardized representation for downstream peak detection, quantification, or integration with other NMR/IR/MS spectral data in a unified backend service.
When NOT to use
- Input is already in a validated, standardized format ready for downstream analysis (e.g., vendor software has already performed conversion and QC)
- You need real-time streaming MS data ingestion; this workflow is synchronous POST-based batch conversion
- Input file is corrupted or truncated and cannot be parsed by proteowizard/pwiz-skyline
Inputs
- RAW spectral file (Thermo/Waters vendor format)
- mzML file (open XML-based mass spectrometry format)
- jcamp file (JCAMP-DX spectral format)
Outputs
- Standardized jcamp file with extracted metadata
- Peak table (m/z, intensity, retention time)
- Spectral metadata object (instrument, acquisition parameters)
How to apply
Submit the MS file (RAW, mzML, or jcamp) via HTTP POST to the /api/v1/chemspectra/file/convert endpoint. The backend service validates the input format using proteowizard/pwiz-skyline, which runs as a Docker service (msconvert_docker) to handle vendor-specific RAW format nuances that cannot be parsed by pure Python. The converter extracts spectral parameters, metadata (acquisition conditions, instrument info), and peak data, then serializes the output as jcamp format with normalized peak tables. Verify successful conversion by inspecting the HTTP response for the converted jcamp artifact and confirm metadata extraction (retention time, m/z ranges, scan metadata) is present and sensible.
Related tools
- proteowizard/pwiz-skyline (Vendor-agnostic MS file parser and converter; executes as Docker service to handle proprietary RAW format decoding) — https://github.com/ComPlat/chem-spectra-app
- Flask (REST API web framework hosting the /api/v1/chemspectra/file/convert endpoint) — https://github.com/ComPlat/chem-spectra-app
- Docker (msconvert_docker service) (Container runtime for proteowizard/pwiz-skyline to isolate vendor library dependencies) — https://github.com/ComPlat/chem-spectra-app
- Python 3 (Backend service runtime; parses output from proteowizard and serializes to jcamp) — https://github.com/ComPlat/chem-spectra-app
Examples
curl -X POST -F "file=@sample.raw" http://localhost:3007/api/v1/chemspectra/file/convert
Evaluation signals
- HTTP 200 response returned with jcamp artifact in response body; HTTP 4xx/5xx indicates parse/conversion failure
- Output jcamp file contains valid JCAMP-DX header, metadata fields (##ORIGIN, ##OWNER, ##DATE, ##TIME), and ##PEAK= entry with m/z–intensity pairs
- Metadata extraction: verify ##TITLE, instrument info, and acquisition parameters are populated from input file
- Peak table integrity: m/z values are within expected mass range for target analyte; intensity values are positive and non-zero
- Round-trip consistency: re-ingesting converted jcamp should preserve peak positions and metadata within floating-point tolerance
Limitations
- Requires Docker and proteowizard/pwiz-skyline container to be running; vendor RAW formats cannot be parsed by pure Python libraries
- Conversion fidelity depends on proteowizard's support for the specific RAW file variant (Thermo vs. Waters vs. others); some legacy or proprietary formats may fail silently or lose metadata
- No changelog documented; version compatibility between proteowizard, Docker, and the ChemSpectra backend is not explicitly tracked
Evidence
- [other] The ChemSpectra App backend web service accepts and processes three spectral file formats: jcamp, RAW, and mzML files for NMR/IR/MS data.: "Backend web service provides NMR/IR/MS processing for jcamp/RAW/mzML files"
- [other] Parse and validate the input file format using proteowizard/pwiz-skyline via the Docker msconvert_docker service to handle vendor-specific RAW formats.: "Parse and validate the input file format using proteowizard/pwiz-skyline via the Docker msconvert_docker service to handle vendor-specific RAW formats"
- [other] Convert the spectral file to a standardized internal representation, extracting metadata and spectral parameters.: "Convert the spectral file to a standardized internal representation, extracting metadata and spectral parameters"
- [other] Serialize the converted file to jcamp output format with peak tables and metadata.: "Serialize the converted file to jcamp output format with peak tables and metadata"
- [other] Receive HTTP POST request containing an uploaded spectral file (jcamp, RAW, or mzML format) at the /api/v1/chemspectra/file/convert endpoint.: "Receive HTTP POST request containing an uploaded spectral file (jcamp, RAW, or mzML format) at the /api/v1/chemspectra/file/convert endpoint"