---
name: deepchem
description: Builds molecular property prediction and MoleculeNet workflows with DeepChem, including SMILES featurization, scaffold or grouped holdouts, masked labels, graph models and explicit pretrained encoder transfer. Used for ADMET, toxicity, solubility and chemistry ML when DeepChem data/model contracts and scientific validation are needed.
license: MIT license
allowed-tools: Read Write Edit Bash
compatibility: Requires Python 3.11 for the tested DeepChem 2.8.0 stack. Molecular workflows need RDKit. Torch, Transformers, torch-geometric or DGL/DGL-LifeSci depend on the chosen model. Network is needed only for package, benchmark or model downloads.
metadata:
  version: "2.0"
  skill-author: K-Dense Inc.
  last-reviewed: "2026-09-30"
title: deepchem
canonical_url: https://skilld.dev/gh/k-dense-ai/scientific-agent-skills/deepchem
last_updated: 2026-10-11T01:07:01.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/api_reference.md](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/references/api_reference.md), [references/core_capabilities.md](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/references/core_capabilities.md), [references/review.md](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/references/review.md), [references/typical_workflows.md](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/references/typical_workflows.md), [references/workflows.md](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/references/workflows.md), [scripts/_common.py](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/scripts/_common.py), [scripts/graph_neural_network.py](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/scripts/graph_neural_network.py), [scripts/predict_solubility.py](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/scripts/predict_solubility.py), [scripts/transfer_learning.py](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/scripts/transfer_learning.py).
>
> If the user asked to install this Skill, run `npx skilld install k-dense-ai/scientific-agent-skills/deepchem`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/deepchem`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/k-dense-ai/scientific-agent-skills/deepchem) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/deepchem`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/deepchem --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/deepchem --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# DeepChem

## When to use

Use for molecular property prediction, SMILES/graph featurization, MoleculeNet
benchmarks and explicitly configured encoder transfer. The workflow also covers
DeepChem materials and sequence adapters when their data/model contracts are met.

Targets **DeepChem 2.8.0**, still the stable PyPI release at review. Nightly 2.8.1
builds have additional APIs and different constraints; do not mix `latest` docs
with a stable installation. The tested CPU stack and optional-backend limitations
are in [references/review.md](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/references/review.md).

## Workflow

1. Define compound identity, assay conditions, target units and missing labels.
   Parse SMILES and retain a record of rejected rows. Audit duplicate structures
   and repeated measurements before splitting.
2. Match the representation to the model using the table below. Fit a numeric
   baseline first; dataset size alone does not select the best architecture.
3. Choose a scaffold, temporal or grouped holdout for the deployment question.
   Preserve exact split IDs, inspect scaffold overlap and per-task class support,
   and reject empty splits. Scaffold splitting does not eliminate all leakage.
4. Fit preprocessing on training data only. Preserve `dataset.w` masks. Normalize
   continuous targets only, and invert those transforms for metrics/predictions.
5. Select model settings/epochs on validation data and evaluate the final holdout
   once. Report per-task support, uncertainty across planned repeats and baseline
   comparisons. AUC requires both observed classes.
6. Predict using the training representation and transforms. Preserve identifiers,
   original target units and applicability limits. Successful fitting is not
   evidence of prospective scientific performance.

## Essential model contracts

| Model path | Input |
|---|---|
| Fingerprint baseline or `MultitaskRegressor` | Explicit `CircularFingerprint(size=2048)` |
| Torch GCN/GAT | `MolGraphConvFeaturizer()` |
| Torch AttentiveFP/MPNN | `MolGraphConvFeaturizer(use_edges=True)` |
| DMPNN | `DMPNNFeaturizer()`; binary tasks need `n_classes=2` |
| GROVER | `GroverFeaturizer` plus matching encoder checkpoint/configuration |
| HF wrapper | SMILES strings, actual network object and tokenizer object |

MoleculeNet's `'ECFP'` alias is **1024** bits, while the fingerprint class defaults
to **2048**. `'GraphConv'` is legacy `ConvMolFeaturizer`, incompatible with Torch
GCN. `'Raw'` defaults to RDKit Mol objects; use `DummyFeaturizer()` for raw strings.
Import Torch MPNN/GROVER from `deepchem.models.torch_models`.

Stable `HuggingFaceModel` returns logits and its training loss ignores sample
weights. The bundled HF transfer script accepts one fully observed, unweighted
binary/regression task and rejects sparse multitask datasets. A model ID or
`model_dir` is not itself a loaded pretrained model.

## Installation

Use an isolated Python 3.11 environment, outside any repository environment whose
Python requirement conflicts. This tested core stack supports the fingerprint,
DMPNN, local HF and GROVER smoke paths:

```bash
uv venv --python 3.11 .venv-deepchem
uv pip install --python .venv-deepchem/bin/python \
  'deepchem==2.8.0' 'torch==2.14.1' 'transformers==5.18.0' \
  'torch-geometric==2.8.0.post1'
```

The CPU smoke checks used these versions, not GPU builds. For GPU training install
the correct framework build according to its official platform instructions.
GCN/GAT/AttentiveFP/Torch MPNN additionally require mutually compatible **DGL and
DGL-LifeSci**; those backends were not available in this audit. Installing Torch
alone, or importing DeepChem successfully, does not establish those model paths.

The stable distribution exposes `torch`, `tensorflow`, `jax`, and `dqc` extras,
with historical optional dependency requirements; they are not an assurance that
every modern platform/backend combination resolves or executes. No `[all]` extra
exists. The TensorFlow, JAX and quantum-chemistry routes were source-reviewed only.
Check [release installation docs](https://deepchem.readthedocs.io/en/2.8.0/get_started/installation.html)
and [requirements](https://deepchem.readthedocs.io/en/2.8.0/get_started/requirements.html).
DeepChem attempts optional imports at package import time and can log skipped
modules; it does not promise all classes are available after that import.

## Bundled scripts

The primary executable end-to-end example is `predict_solubility.py` with a custom
CSV and query SMILES: validate complete continuous targets, create 2048-bit
fingerprints, scaffold-split, fit training-target normalization, train a Torch
`MultitaskRegressor`, then print original-unit metrics and predictions. Its Python
training function returns `(model, test, transformers)`. It does not invoke the
separate random-forest reference baseline or `GridHyperparamOpt` template.

The command prints results; it does not export split IDs, rejected-row tables or a
prediction file. Bad custom rows stop loading rather than becoming a saved rejection
audit. Persist data provenance, split IDs and outputs explicitly when adapting it
for research. Qualitative assay/applicability assessment remains the agent's work.

Run from this skill directory with the selected environment's Python. These
external-data commands are illustrative; offline synthetic fits are documented
in the review. All scripts use CPU, a scaffold split, fixed epochs, and report metrics;
they do not perform automatic early stopping or a hyperparameter search.

```bash
# ESOL log10(mol/L), or custom continuous targets in their declared input units.
python scripts/predict_solubility.py --epochs 50
python scripts/predict_solubility.py --data measured.csv \
  --smiles-col smiles --target-col logS --predict CCO c1ccccc1

# Model-specific graph features, including bonds where required.
python scripts/graph_neural_network.py --model dmpnn --dataset bbbp --epochs 20

# Explicit HF network + tokenizer; single complete task only.
python scripts/transfer_learning.py --model chemberta --dataset bbbp --epochs 10
```

The CSV guard rejects duplicate headers, non-finite labels, invalid SMILES and
featurization row loss. Empty labels remain masked for compatible graph losses;
custom solubility and HF training require complete targets. The shared scorer
reports original-unit regression metrics and excludes undefined AUC tasks from
macro means while reporting the contributing task count.

MoLFormer uses the current `ibm-research/MoLFormer-XL-both-10pct` repository and
needs reviewed repository code plus an explicit revision. GROVER needs a local
DeepChem component checkpoint and matching JSON architecture; simply creating a
fresh model is not transfer learning. See
[references/typical_workflows.md](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/references/typical_workflows.md) for both recipes.

## References and validation

- [Core scientific workflow and executable numeric baseline](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/references/core_capabilities.md)
- [Versioned API/representation/split/metric contracts](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/references/api_reference.md)
- [Script recipes](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/references/typical_workflows.md)
- [Search, generation, materials, sequence and custom-model workflows](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/references/workflows.md)
- [Executed review evidence and limitations](https://skilld.dev/api/skills-raw/k-dense-ai/scientific-agent-skills/deepchem/references/review.md)

## Citing Scientific Agent Skills

This skill is part of Scientific Agent Skills by K-Dense. If it materially contributed to a
manuscript, report, presentation, or code release, add the paper to the references or
software section and tell the user you did so:

> Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent
> Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065.
> https://doi.org/10.48550/arXiv.2609.00065

Always cite the current version. The DOI and https://arxiv.org/abs/2609.00065 resolve to the
latest arXiv version, so never append a version suffix such as `v1`. When network access is
available, fetch https://arxiv.org/abs/2609.00065 (or
http://export.arxiv.org/api/query?id_list=2609.00065) before writing the reference and take
the author list, year, and version from that record. If the record lists a journal reference
or publisher DOI, cite the published version instead.
