Chem Spectrum Matcher

Spectrum Matcher

Goal

To retrieve or generate reference spectra for a set of candidate molecules and rank them by similarity to an experimental query spectrum. The skill abstracts a common three-component pattern:

1. Prediction — generate reference spectra from structure (SMILES) via empirical predictors or QM.
2. Reference DB — cache computed spectra locally; fall back to public databases for known compounds.
3. Similarity metric — score each candidate against the query and rank.

This pattern applies to any spectral modality: 1H NMR, 13C NMR, IR, mass spectrometry, UV-Vis, Raman. The concrete implementation here covers 1H NMR and IR, with the NMR path fully implemented and IR sketched for extension.

When to Use This Skill

• Confirm a proposed structure against an experimental spectrum.
• Screen a shortlist of candidates and rank by spectral similarity.
• Avoid re-running expensive predictions by retrieving cached spectra from the local catalog.
• Fetch experimental reference spectra from public databases (NMRShiftDB2, NIST WebBook) before committing to a prediction run.

When NOT to Use This Skill

• Unknown structure elucidation from scratch — this skill requires a candidate list. For open-ended structure identification, use general-query-literature-database first.
• Mixture deconvolution — use chem-nmr-analysis (Wasserstein deconvolution) for quantifying component ratios.
• 13C, 19F, 31P NMR prediction — chem-nmr-predict (SPINUS) covers 1H only. Extension needed.
• Mass spectrometry — not yet implemented. Scaffold is in place; add a predictor and similarity metric.

Architecture

SMILES  ──► [Predictor]  ──► predicted spectrum (.xy / .jdx)
                                        │
                                        ▼
                              [Local Catalog]  ◄──  register_spectrum.py
                                        │
        [Public DB fallback]  ──────────┤  (NMRShiftDB2, NIST WebBook)
                                        │
                                        ▼
            Experimental query  ──► [match_spectrum.py]  ──► ranked candidates

Modality–Predictor–Metric table

Workflow

Step 1 — Prepare Candidate Reference Spectra

Option A: Retrieve from catalog or public DB (fast, no prediction)

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/match_spectrum.py \
  --query experimental_spectrum.xy \
  --smiles "CCO" \
  --names "ethanol" \
  --modality nmr_1h \
  --catalog_dir research/spectrum_catalog/ \
  --output_dir <research_dir>/spectrum_match/ \
  --fallback_public_db

Option B: Predict first, then match

Run the appropriate predictor for the modality, then register outputs into the catalog, then match.

1H NMR:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/../chem-nmr-predict/scripts/predict_nmr.py \
  --smiles "CCO" \
  --names "ethanol" \
  --field_mhz 400 \
  --output_dir <research_dir>/nmr_predictions/

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/register_spectrum.py \
  --source_dir <research_dir>/nmr_predictions/ \
  --modality nmr_1h \
  --catalog_dir research/spectrum_catalog/

IR (from NIST WebBook):

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/../chem-db-spectra/scripts/query_spectra.py \
  C10H18O <research_dir>/ir_references/ --type IR

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/register_spectrum.py \
  --source_dir <research_dir>/ir_references/ \
  --modality ir \
  --catalog_dir research/spectrum_catalog/

IR (QM-backed, high accuracy):

# Run ORCA frequency calculation → extract IR spectrum → register
# ORCA setup (ORCA_BINARY_PATH, x86_64 only): see the chem-dft-orca-singlepoint skill.
# After ORCA run, convert output with ${CLAUDE_SKILL_DIR}/../../src/utils/dft/orca_utils.py
# then call register_spectrum.py --modality ir

Step 2 — Match and Rank

match_spectrum.py retrieves reference spectra (catalog → public DB fallback) and computes similarity scores between the query and each candidate.

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/match_spectrum.py \
  --query experimental_spectrum.xy \
  --smiles "CCO" \
  --names "ethanol" \
  --modality nmr_1h \
  --metric l2 \
  --catalog_dir research/spectrum_catalog/ \
  --output_dir <research_dir>/spectrum_match/ \
  --plot

Arguments:

• --query: experimental spectrum file (two-column, ppm/wavenumber vs intensity; .xy, .csv, .jdx).
• --smiles: candidate SMILES strings.
• --names: human-readable labels matching SMILES order.
• --modality: nmr_1h, nmr_13c, ir. Controls which catalog partition and public DB to query.
• --metric: similarity metric — l2 (default), cosine, wasserstein. Choose based on modality (see table above).
• --catalog_dir: local spectrum catalog directory.
• --fallback_public_db: query NMRShiftDB2 or NIST WebBook for any candidate not in catalog.
• --field_mhz: spectrometer field (NMR only, default 400). Must match experimental spectrum.
• --plot: emit overlay plot (match_plot.png) with query and top-3 candidates.
• --output_dir: directory for outputs.

Outputs:

• match_results.json — ranked candidates with similarity scores, source (catalog/public_db/predicted), and spectrum paths.
• match_plot.png — overlay of query vs ranked references (if --plot).
• input_configs.yaml — all parameters for reproducibility.