Nmr Spectral Processing

nmr-spectral-processing

Summary

Convert and standardize NMR spectral files (jcamp, RAW, mzML formats) to a unified internal representation, extracting metadata and peak tables for downstream analysis and visualization. This skill handles vendor-specific binary formats through containerized proteowizard conversion and outputs normalized jcamp artifacts.

When to use

You have raw NMR/IR/MS spectral data in vendor-specific (RAW), open (jcamp), or mass spectrometry (mzML) formats and need to parse, validate, and convert them to a standardized internal representation with extracted metadata and peak tables for visualization or further analysis in ChemSpectra.

When NOT to use

• Input spectral data is already in validated jcamp format and requires only visualization, not re-conversion or metadata extraction.
• The raw file requires custom vendor-specific processing beyond standard proteowizard capabilities (e.g., proprietary closed-source instrument formats not supported by pwiz-skyline).
• You need to process gigabyte-scale batch datasets without access to the Docker/msconvert infrastructure or adequate compute resources.

Inputs

• jcamp spectral file (text-based NMR/IR format)
• RAW spectral file (vendor-specific binary format from mass spectrometers)
• mzML spectral file (mass spectrometry markup language format)

Outputs

• Converted jcamp file with extracted metadata
• Peak table (tabular representation of spectral peaks)
• Normalized spectral parameters and metadata

How to apply

Submit the spectral file (jcamp, RAW, or mzML) via HTTP POST to the /api/v1/chemspectra/file/convert endpoint on the ChemSpectra backend service. The backend validates the input format and uses a Docker-containerized proteowizard/pwiz-skyline service (msconvert_docker) to handle vendor-specific binary formats like RAW. The conversion pipeline parses the file, extracts spectral metadata and peak parameters, and serializes the output to jcamp format with normalized peak tables. Verify successful conversion by checking the HTTP response contains valid jcamp output and that metadata fields (e.g., acquisition parameters, solvent, pulse sequence) are correctly populated.

Related tools

• proteowizard/pwiz-skyline (Docker-containerized service (msconvert_docker) for parsing and converting vendor-specific RAW spectral formats to standardized representations) — https://github.com/ProteoWizard/pwiz
• Flask (Web framework hosting the /api/v1/chemspectra/file/convert endpoint and managing HTTP request/response lifecycle)
• Docker (Container runtime for isolating and executing proteowizard conversion service with vendor library dependencies)
• Python 3.12 (Primary language for parsing, validation, metadata extraction, and jcamp serialization logic) — https://github.com/ComPlat/chem-spectra-app
• chem-spectra-client (Frontend JavaScript/React interface for user submission of spectral files and visualization of converted results) — https://github.com/ComPlat/chem-spectra-client

Examples

curl -X POST -F 'file=@spectrum.raw' http://localhost:3007/api/v1/chemspectra/file/convert

Evaluation signals

• HTTP response status is 200 OK and response body contains valid jcamp-formatted text with JCAMP-DX header and spectral data blocks.
• Extracted metadata fields (acquisition date, instrument type, solvent, pulse sequence, chemical shift reference) are non-empty and match values in the original raw file.
• Peak table is present and contains expected number of peaks with chemical shift (ppm), intensity, and integration values within typical NMR ranges (e.g., 0–12 ppm for 1H NMR).
• File size of converted jcamp output is reasonable relative to input (significant compression expected for binary RAW → text jcamp conversion indicates potential parsing failure).
• Round-trip validation: re-ingesting the converted jcamp file produces consistent peak positions and metadata without data loss.

Limitations

• Vendor-specific RAW format support is limited to instruments covered by proteowizard/pwiz-skyline (primarily Waters, Agilent, Bruker, Thermo); proprietary or legacy formats may not be recognized.
• The msconvert_docker service requires Docker daemon availability and appropriate system resources; conversion may fail or timeout on very large spectral files or resource-constrained environments.
• Metadata extraction fidelity depends on compliance of the input file with JCAMP-DX or mzML standards; malformed or non-standard files may produce incomplete or incorrect metadata.
• No changelog provided in repository; version compatibility and breaking changes between updates are not explicitly documented.

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.: "The ChemSpectra App backend web service accepts and processes three spectral file formats: jcamp, RAW, and mzML files for NMR/IR/MS data."
• [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."
• [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."
• [readme] This backend web service provides NMR/IR/MS processing for jcamp/RAW/mzML files.: "This backend web service provides NMR/IR/MS processing for jcamp/RAW/mzML files."