alterlab-pubchem

PubChem Database

Overview

PubChem is the world's largest freely available chemical database — 119M+ compounds, 322M+ substances, and 295M+ bioactivities per the PubChem 2025 update (Kim et al., NAR 2025). Query chemical structures by name, CID, or SMILES, retrieve molecular properties, perform similarity and substructure searches, and access bioactivity data using the PUG-REST API and PubChemPy.

When to Use This Skill

This skill should be used when:

• Searching for chemical compounds by name, structure (SMILES/InChI), or molecular formula
• Retrieving molecular properties (MW, LogP, TPSA, hydrogen bonding descriptors)
• Performing similarity searches to find structurally related compounds
• Conducting substructure searches for specific chemical motifs
• Accessing bioactivity data from screening assays
• Converting between chemical identifier formats (CID, SMILES, InChI)
• Batch processing multiple compounds for drug-likeness screening or property analysis

Does NOT Trigger

Scenario	Use Instead
Curated potency data (IC50/Ki) for targets and medicinal-chemistry series	alterlab-chembl
Computing descriptors or fingerprints on your own molecules locally	alterlab-rdkit
Human metabolite concentrations, biofluids, biomarker evidence	alterlab-hmdb
Drug pharmacology, interactions, and approval details	alterlab-drugbank
Purchasable compound libraries for virtual screening	alterlab-zinc-db

Core Capabilities

PubChem access is organized into nine capability areas. Copy-ready snippets for each live in references/capabilities.md.

1. Chemical structure search — by name, CID, SMILES, InChI, or molecular formula.
2. Property retrieval — single, specific-list, or batch molecular properties.
3. Similarity search — Tanimoto similarity with threshold/MaxRecords.
4. Substructure search — find compounds containing a structural motif.
5. Format conversion — CID/SMILES/InChI/InChIKey and structure-file download.
6. Structure visualization — 2D PNG images via PubChemPy or direct URL.
7. Synonym retrieval — all known names for a compound.
8. Bioactivity data access — assay summaries via PUG-REST and helper script.
9. Comprehensive annotations — full PUG-View records (properties, drug info, safety, toxicity).

Core Workflow

The canonical entry point resolves an identifier to a compound, then reads properties:

import pubchempy as pcp

compound = pcp.get_compounds('aspirin', 'name')[0]
print(compound.cid, compound.molecular_formula, compound.molecular_weight)
print(compound.smiles, compound.xlogp, compound.tpsa)

Prefer CIDs for repeated queries (more efficient than names/structures). Similarity and substructure searches run asynchronously and may take 15-30 seconds; PubChemPy polls automatically. PUG-REST answers HTTP 503 (PUGREST.ServerBusy) both when you exceed the limits and when PubChem itself is overloaded — read the X-Throttling-Control response header and back off rather than retrying immediately. See references/best_practices.md for rate limits and error handling.

Installation Requirements

uv pip install 'pubchempy>=1.0.5'  # Python-based access (1.0.5 = current SMILES property names)
uv pip install requests            # direct API / bioactivity queries
uv pip install pandas              # optional, for data analysis

SMILES property naming (PubChem changed this in 2025): the PUG-REST CanonicalSMILES and IsomericSMILES properties are deprecated. Use SMILES (full SMILES with stereo/isotope info, replaces IsomericSMILES) and ConnectivitySMILES (connectivity-only, replaces CanonicalSMILES). In PubChemPy 1.0.5 the matching Compound attributes are compound.smiles and compound.connectivity_smiles (the old canonical_smiles / isomeric_smiles attributes still resolve but are deprecated).

Helper Scripts

This skill ships two Python helper scripts under scripts/:

• scripts/compound_search.py — search, property retrieval, similarity/substructure search, synonyms, batch search, and structure download.
• scripts/bioactivity_query.py — bioassay summaries, target identification, target-based compound search, and PUG-View annotations.

Full function inventories and usage are in references/helper_scripts.md.

Reference Index

• references/api_reference.md — Complete PUG-REST endpoint docs, full molecular property list, asynchronous request handling, PubChemPy API, PUG-View API, and official doc links.
• references/capabilities.md — Copy-ready code for all nine capability areas.
• references/workflows.md — Five end-to-end workflows (identifier conversion, drug-likeness screening, similar-candidate search, batch property comparison, substructure virtual screening).
• references/helper_scripts.md — Function inventory and usage for the two helper scripts.
• references/best_practices.md — Rate limits, best practices, error handling, troubleshooting, and additional resources.