Chem Tools

Chem Tools

Use this skill when the user asks to:

• featurize molecules from SMILES, CSV, TSV, or text inputs
• use DeepChem for molecular ML preprocessing, fingerprints, or dataset preparation
• use PySCF for small-molecule HF or DFT calculations
• run ADMET triage or structural alert screening
• normalize ChEMBL, BindingDB, MoleculeNet, or generic assay tables into DrugClaw-ready datasets
• adapt PDBbind-style structure datasets into benchmark-ready CSV tables
• benchmark QSAR baselines with scaffold or random splits
• train or apply ligand binding-affinity models from labeled SMILES
• train or apply structure-aware protein-ligand affinity models from complexes
• benchmark structure-aware protein-ligand models on grouped or random splits
• train or apply bioactivity models from labeled SMILES
• rank a library for virtual screening with chemistry, activity, affinity, and docking signals
• search DrugBank from a local export or the online discovery API, export the matched drug structure, or read drug descriptive properties
• compute chemistry follow-up checks on docking hits
• inspect small-molecule descriptors, simple QM sanity checks, or ligand ranking features

Environment Check

Do not assume the chemistry stack is available. Check first.

which python3 || true
python3 - <<'PY'
mods = ["deepchem", "pyscf", "rdkit", "numpy", "pandas", "sklearn"]
for name in mods:
    try:
        __import__(name)
        print(f"{name}: ok")
    except Exception as exc:
        print(f"{name}: missing ({exc})")
PY

If key modules are missing, say so immediately and recommend the unified drug-sandbox image documented in docs/operations/science-runtime.md.

Bundled Assets

• templates/deepchem_featurize.py
• templates/pyscf_single_point.py
• templates/rdkit_descriptors.py
• templates/admet_screen.py
• templates/assay_data_prepare.py
• templates/pdbbind_prepare.py
• templates/binding_affinity_predict.py
• templates/bioactivity_predict.py
• templates/drugbank_lookup.py
• templates/protein_ligand_affinity.py
• templates/protein_ligand_benchmark.py
• templates/qsar_benchmark.py
• templates/virtual_screen.py

Use these templates instead of rewriting the same chemistry scripts from scratch.

Preferred Workflow

1. Identify the input type: inline SMILES, CSV/TSV, text list, XYZ, or inline atom string.
2. Run the smallest deterministic template first.
3. For predictive work, separate descriptive heuristics from supervised models.
4. Save structured outputs such as .npy, .csv, .joblib, or .json.
5. Benchmark supervised models with scaffold or external splits before treating them as useful.
6. Report the exact featurizer, basis set, method, model algorithm, label definition, split strategy, and whether convergence or training succeeded.
7. Call out whether a model is ligand-only or structure-aware.
8. State clearly whether the result is descriptive, predictive, or quantum-mechanical.

DeepChem

Use templates/deepchem_featurize.py for:

• circular fingerprints
• MACCS keys
• Mol2Vec fingerprints
• quick dataset preparation for downstream ML

Quick start:

python3 templates/deepchem_featurize.py \
  --smiles "CCO" "c1ccccc1" \
  --featurizer circular \
  --output-prefix chem/deepchem/demo

CSV input example:

python3 templates/deepchem_featurize.py \
  --input ligands.csv \
  --smiles-column smiles \
  --id-column ligand_id \
  --featurizer maccs \
  --output-prefix chem/deepchem/ligands

Deliverables:

• .npy feature matrix
• .summary.csv with per-molecule stats
• .json metadata with featurizer and shape

If the user asks for actual DeepChem neural models, verify the required backend first. Do not assume TensorFlow or PyTorch models are available just because deepchem imports.

RDKit

Use templates/rdkit_descriptors.py for:

• common molecular descriptors
• Lipinski and Veber rule flags
• quick ligand triage before docking or QM follow-up

Quick start:

python3 templates/rdkit_descriptors.py \
  --smiles "CCO" "c1ccccc1O" \
  --output chem/rdkit/descriptors.csv \
  --summary chem/rdkit/summary.json

CSV input example:

python3 templates/rdkit_descriptors.py \
  --input ligands.csv \
  --smiles-column smiles \
  --id-column ligand_id \
  --output chem/rdkit/ligands.csv \
  --summary chem/rdkit/ligands.json

Deliverables:

• descriptor CSV
• summary JSON
• explicit invalid-SMILES list when parsing fails

ADMET

Use templates/admet_screen.py for:

• fast oral-drug-likeness triage
• Lipinski, Veber, and Egan filters
• BBB-likeness heuristics
• PAINS or BRENK structural alerts when RDKit filter catalogs are available
• simple ADMET prioritization before docking or QSAR

Quick start:

python3 templates/admet_screen.py \
  --smiles "CCO" "CC(=O)Oc1ccccc1C(=O)O" \
  --output chem/admet/screen.csv \
  --summary chem/admet/summary.json

CSV input example:

python3 templates/admet_screen.py \
  --input ligands.csv \
  --smiles-column smiles \
  --id-column ligand_id \
  --output chem/admet/ligands.csv \
  --summary chem/admet/ligands.json

Deliverables:

• per-ligand ADMET CSV with descriptors and pass or warn flags
• summary JSON with valid and invalid counts

Treat this as heuristic triage. It is not a clinically validated ADMET predictor.

Assay Data

Use templates/assay_data_prepare.py for:

• normalizing ChEMBL exports into a compact id, smiles, target style table
• extracting BindingDB potency columns into a cleaner training dataset
• adapting MoleculeNet or generic CSV data before QSAR work
• optional numeric-to-class conversion for active or inactive labeling

Example:

python3 templates/assay_data_prepare.py \
  --input chembl_export.csv \
  --source chembl \
  --task regression \
  --convert-nm-to-pactivity \
  --output chem/data/chembl_normalized.csv \
  --summary chem/data/chembl_normalized.json

BindingDB classification example:

python3 templates/assay_data_prepare.py \
  --input bindingdb_hits.tsv \
  --source bindingdb \
  --task classification \
  --activity-threshold 1000 \
  --threshold-direction "<=" \
  --label-positive binder \
  --label-negative non_binder \
  --output chem/data/bindingdb_binary.csv \
  --summary chem/data/bindingdb_binary.json

Deliverables:

• normalized CSV ready for the downstream templates
• summary JSON with source detection, threshold policy, and invalid-row counts

Do not silently mix incompatible assays or units. If the export combines unrelated targets or endpoints, split it first.

Structure Dataset Prep

Use templates/pdbbind_prepare.py for:

• normalizing PDBbind-style index files into complex_path or receptor_path + ligand_path tables
• merging extra metadata such as target family, protein id, or SMILES into the normalized output
• preparing benchmark inputs for protein_ligand_affinity.py or protein_ligand_benchmark.py

Example:

python3 templates/pdbbind_prepare.py \
  --root pdbbind/refined-set \
  --index pdbbind/index/INDEX_refined_data.2020 \
  --metadata pdbbind/pocket_groups.csv \
  --output chem/data/pdbbind_normalized.csv \
  --summary chem/data/pdbbind_normalized.json

Deliverables:

• normalized CSV with structure paths and affinity
• summary JSON with path coverage and invalid rows

Benchmarking

Use templates/qsar_benchmark.py for:

• scaffold-split or random-split QSAR benchmarking
• baseline regression or classification sanity checks
• holdout prediction exports with optional ensemble uncertainty
• refitting a model bundle after benchmark validation

Example:

python3 templates/qsar_benchmark.py \
  --input chem/data/chembl_normalized.csv \
  --target-column target \
  --task regression \
  --split scaffold \
  --feature-backend rdkit-morgan \
  --algorithm rf \
  --include-descriptors \
  --metrics-output chem/benchmarks/affinity_metrics.json \
  --predictions-output chem/benchmarks/affinity_predictions.csv \
  --folds-output chem/benchmarks/affinity_folds.csv \
  --model-output chem/models/affinity_from_benchmark.joblib

Deliverables:

• benchmark metrics JSON
• holdout prediction CSV
• fold-level metrics CSV
• optional refit model bundle

Use scaffold split by default when chemical series leakage is a real risk.

Binding Affinity

Use templates/binding_affinity_predict.py for:

• local ligand-only affinity regression from labeled SMILES tables
• quick QSAR baselines before docking or after docking hit expansion
• reusable model bundles that can score new ligand libraries

Training example:

python3 templates/binding_affinity_predict.py \
  --train affinity_train.csv \
  --smiles-column smiles \
  --id-column ligand_id \
  --target-column affinity \
  --feature-backend deepchem-circular \
  --algorithm et \
  --include-descriptors \
  --model-output chem/models/affinity.joblib \
  --metrics-output chem/models/affinity_metrics.json

Inference example:

python3 templates/binding_affinity_predict.py \
  --model-input chem/models/affinity.joblib \
  --predict screening_library.csv \
  --smiles-column smiles \
  --id-column ligand_id \
  --predictions-output chem/predictions/affinity.csv

Deliverables:

• .joblib model bundle
• metrics JSON with regression scores
• prediction CSV with per-ligand affinity estimates

Assumptions:

• this is ligand-only prediction from chemistry features
• labeled training data must already exist
• affinity direction must be reported explicitly if lower values are better in the source assay

Protein-Ligand Affinity

Use templates/protein_ligand_affinity.py for:

• structure-aware affinity regression from receptor-ligand complexes
• feature extraction from complex_path or receptor_path + ligand_path
• docking follow-up when you want contact geometry, pocket composition, and atom-pair features instead of ligand-only fingerprints

Training example:

python3 templates/protein_ligand_affinity.py \
  --train structure_affinity_train.csv \
  --id-column id \
  --complex-path-column complex_path \
  --smiles-column smiles \
  --target-column affinity \
  --algorithm rf \
  --metrics-output chem/benchmarks/protein_affinity_metrics.json \
  --features-output chem/benchmarks/protein_affinity_features.csv \
  --model-output chem/models/protein_affinity.joblib

Prediction example on docking outputs:

python3 templates/protein_ligand_affinity.py \
  --model-input chem/models/protein_affinity.joblib \
  --predict docking/results/analysis/docking_summary.csv \
  --id-column ligand_slug \
  --complex-path-column complex_path \
  --predictions-output chem/predictions/protein_affinity.csv

Deliverables:

• structure feature CSV
• metrics JSON
• prediction CSV with optional uncertainty for ensemble models

Treat this as a structure-aware baseline. It is still limited by complex quality and docking pose quality.