chem-nmr-analysis

Files (43)

• SKILL.md
• README.md · examples/deconvolution/
• borneol.csv · examples/deconvolution/
• crude.csv · examples/deconvolution/
• isoborneol.csv · examples/deconvolution/
• deconvolution_result_fit.png · examples/deconvolution/output/full_range/
• deconvolve_result.json · examples/deconvolution/output/full_range/
• input_configs.yaml · examples/deconvolution/output/full_range/
• deconvolution_result.png · examples/deconvolution/output/h2_window/
• deconvolution_result_fit.png · examples/deconvolution/output/h2_window/
• deconvolve_result.json · examples/deconvolution/output/h2_window/
• input_configs.yaml · examples/deconvolution/output/h2_window/
• deconvolution_result_fit.png · examples/deconvolution/output/legacy_min/
• deconvolve_result.json · examples/deconvolution/output/legacy_min/
• input_configs.yaml · examples/deconvolution/output/legacy_min/
• input_configs.yaml · examples/deconvolution/output/overlay/
• spectra_overview.png · examples/deconvolution/output/overlay/
• README.md · examples/kinetics/
• input_configs.yaml · examples/kinetics/output/legacy_min/
• kinetics.csv · examples/kinetics/output/legacy_min/
• kinetics_plot.png · examples/kinetics/output/legacy_min/
• input_configs.yaml · examples/kinetics/output/validation/
• validation.json · examples/kinetics/output/validation/
• validation.png · examples/kinetics/output/validation/
• validation_summary.txt · examples/kinetics/output/validation/
• input_configs.yaml · examples/kinetics/output/window_baseline/
• kinetics.csv · examples/kinetics/output/window_baseline/
• kinetics_plot.png · examples/kinetics/output/window_baseline/
• t000min.csv · examples/kinetics/
• t005min.csv · examples/kinetics/
• t010min.csv · examples/kinetics/
• t020min.csv · examples/kinetics/
• t030min.csv · examples/kinetics/
• t045min.csv · examples/kinetics/
• t060min.csv · examples/kinetics/
• t090min.csv · examples/kinetics/
• validate_kinetics.py · examples/kinetics/
• named_reactions.json · reference/
• deconvolve.py · scripts/
• kinetics.py · scripts/
• plot.py · scripts/
• predict_products.py · scripts/
• spectra.py · scripts/

SKILL.md (first lines)

# NMR Mixture Analysis

## When to Use This Skill

The agent should use this skill's scripts when:
- A workflow (e.g., `reaction-to-nmr-quantification.md` or `nmr-reaction-kinetics.md`) calls for deconvolution, product prediction, kinetics analysis, or spectral plotting.
- The user already has reference spectra and a mixture spectrum and wants to quantify component proportions directly.
- The user has multiple time-point spectra and wants to track reaction progress via NMR.

For end-to-end workflows that chain this skill with other skills, see: `.agents/workflows/reaction-to-nmr-quantification.md` and `.agents/workflows/nmr-reaction-kinetics.md`.

## When NOT to Use This Skill

- **13C NMR, 2D NMR (COSY, HSQC, etc.), or solid-state NMR** -- this skill handles 1H solution-state NMR only.
- **Structure elucidation of unknown compounds** -- this skill requires knowing (or predicting) what compounds are in the mixture. It does not identify unknowns from scratch.
- **Pure compound characterization** -- if the user has a single pure compound and just wants to assign peaks, this skill is not appropriate. The agent should interpret the spectrum directly.
- **Mass spectrometry data** -- despite the Wasserstein algorithm's origins in mass spec, this skill operates on NMR chemical shift axes only.
- **Digitizing spectrum images** -- the agent should use the `general-plot-digitizer` skill for that step.
- **Predicting NMR spectra from SMILES** -- the agent should use the `chem-nmr-predict` skill for that step.
- **Resolving compound names to SMILES** -- the agent should use the `drug-db-pubchem` skill for that step.

---

## Scripts Reference

| Script | Purpose | Key Inputs | Key Outputs |
|---|---|---|---|
| `predict_products.py` | Predict reaction products via ReactionT5 (HuggingFace API) | `--reactant_smiles`, `--reagent_smiles` | JSON with predicted product SMILES |
| `deconvolve.py` | Wasserstein deconvolution of mixture against references | mixture file + reference files + `--protons` | proportions, Wasserstein distance, plot |
| `kinetics.py` | Time-series deconvolution across multiple time points | `--refs`, `--timepoints`, `--times` | `kinetics.csv` + `kinetics_plot.png` |
| `plot.py` | Overlay or stack NMR spectra for visual comparison | spectrum files + `--labels` | plot image |
| `spectra.py` | I/O utilities (imported by other scripts, not called directly) | -- | -- |

### predict_products.py

The agent should use this script to predict reaction products from reactant and reagent SMILES via the ReactionT5 model.

```bash
export HF_TOKEN=<token>
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/predict_products.py \
  --reactant_smiles "C1CCC(=O)C1" \
  --reagent_smiles "[BH3-]" \
  --output <research_dir>/predicted_products.json
```

### deconvolve.py

The agent should use this script to determine mole fractions of known components in a mixture spectrum via Wasserstein-distance deconvolution.

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/deconvolve.py \
  mixture.csv ref_borneol.xy ref_isoborneol.xy \
  --protons 18 18 \
  --names "borneol" "isoborneol" \
  --baseline-window 3.70 3.94 \
  --ppm-range 3.50 4.10 \
  --range-protons 1 1 \
  --plot <research_dir>/deconvolution_result.png \
  --json
```

Choose `--baseline-window` from the overlay plot: a stretch with no signal in the
mixture or any reference, preferably close to the peaks being quantified. Add
`--baseline-stat max` when the baseline is a one-sided floor rather than noise (e.g.
digitized spectra, whose traced flat line leaves a small positive residue). Use
`--ppm-range` to fit only a region where each component has an isolated diagnostic
signal; omit it to fit the full spectrum. A restricted fit only sees the protons whose
signals lie in the range, so give their number per component with `--range-protons`
(here 1 1: one H2 proton in each isomer). Without it, each `--protons` count is scaled
by the fraction of the reference's area inside the range, which is only as reliable as
the reference spectrum's full-range integrals.

### kinetics.py

The agent should use this script when the user has crude NMR spectra recorded at multiple time points during a reaction.

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/kinetics.py \
  --refs ref1.xy ref2.xy \
  --timepoints t0.csv t10.csv t20.csv \
  --times 0 10 20 \
  --time_unit min \
  --protons 18 18 \
  --names "reactant" "product" \
  --baseline_window 2.40 3.40 \
  --output_dir <research_dir>/kinetics/
```

`kinetics.py` takes the same baseline and range options as `deconvolve.py`, spelled
with underscores (`--baseline_window`, `--baseline_stat`, `--ppm_range`, `--range_protons`).
`kinetics.csv` also records the noise fraction and the subtracted baseline of every
time point.

### plot.py

The agent should use this script to overlay or stack spectra for visual inspection before or after deconvolution.

```bash
${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/plot.py \
  mixture.csv ref_borneol.xy ref_isoborneol.xy \
  --labels "Mixture" "borneol" "isoborneol" \
  --title "Mixture vs References" \
  --output <research_dir>/spectra_overview.png
```

---

## Key Arguments for deconvolve.py

`kinetics.py` accepts the same baseline and range options with underscores
(`--baseline_window`, `--baseline_stat`, `--ppm_range`, `--range_protons`, `--baseline_correct`).

| Argument | Required | Description |
|---|---|---|
| `--protons` | Yes | Number of 1H protons per molecule for each reference component. Critical for converting area fractions to mole fractions. The agent must look this up from the molecular formula or count from the SMILES. |
| `--names` | No | Human-readable labels matching the order of reference files. The agent should always provide these for interpretable output. |
| `--baseline-window LO HI` | Recommended | Signal-free ppm window. Its `--baseline-stat` is subtracted from the mixture and every reference, and negatives are clipped to 0. If a spectrum has no samples in the window (dropped zero runs), the points bounding the gap are used. The agent should use this for any spectrum with noise or a baseline offset. |
| `--baseline-stat` | No | `median` (default) for noisy or offset baselines; `max` for one-sided floors such as the residue of a digitized flat line, which a median only half removes. `max` subtracts about 3σ from every peak of a noisy spectrum, so do not use it there. |
| `--ppm-range LO HI` | No | Deconvolve only this range, applied after the baseline step. Use it to fit isolated diagnostic signals. |

From learningmatter-mit/AtomisticSkills, MIT.

More from learningmatter-mit/AtomisticSkills