alterlab-pubchem

$npx mdskill add AlterLab-IEU/AlterLab-Academic-Skills/alterlab-pubchem

Query PubChem for chemical compounds, properties, and structure searches.

  • Search 110M+ compounds by name, CID, or SMILES.
  • Uses PUG-REST API and PubChemPy with no authentication.
  • Selects search type based on input format and user intent.
  • Returns molecular properties, bioactivity, or structure matches as JSON.

SKILL.md

.github/skills/alterlab-pubchemView on GitHub ↗
---
name: alterlab-pubchem
description: Query PubChem via the PUG-REST API and PubChemPy across 110M+ compounds, searching by name, CID, or SMILES and retrieving molecular properties, bioactivity, and similarity/substructure matches. Use when looking up a chemical compound, converting names/SMILES to CIDs, fetching physicochemical properties, or running cheminformatics structure searches. Part of the AlterLab Academic Skills suite.
license: MIT
allowed-tools: Read WebFetch Bash(curl:*) Bash(python:*)
compatibility: Keyless PubChem PUG-REST API; PubChemPy optional for Python (no authentication required)
metadata:
    skill-author: AlterLab
    version: "1.0.0"
---

# PubChem Database

## Overview

PubChem is the world's largest freely available chemical database with 110M+ compounds and
270M+ bioactivities. 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

## 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:

```python
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. See `references/best_practices.md` for rate limits and error handling.

## Installation Requirements

```bash
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.

More from AlterLab-IEU/AlterLab-Academic-Skills

SkillDescription
alterlab-abm-mesaBuilds agent-based models of social systems with Mesa 3 — the current AgentSet API (model.agents.shuffle_do('step'), auto-assigned unique_id, mandatory super().__init__(seed=...)), cell spaces (mesa.discrete_space OrthogonalMooreGrid / classic mesa.space grids), the DataCollector, batch_run parameter sweeps, and SolaraViz — for emergence, segregation, diffusion, opinion dynamics, and cooperation models. It uses the Mesa 3.x API (the old mesa.time schedulers like RandomActivation are removed) and treats the model as a generative theory to be validated, not just run. Use when the request mentions an agent-based model, Mesa, simulating interacting agents, or emergent macro behavior from micro rules. For discrete-event (queueing/process) simulation prefer alterlab-simpy; for reinforcement learning prefer alterlab-stable-baselines3. Part of the AlterLab Academic Skills suite.
alterlab-academic-careerPrepares academic career documents and professional-development materials for faculty and researchers. Use when drafting academic CVs, research statements, teaching philosophies, diversity statements, faculty-position cover letters, tenure dossiers, promotion narratives, academic portfolios, or mentorship statements, and when planning conference-networking strategy, building academic web presence, setting up ORCID profiles, or understanding impact metrics. Part of the AlterLab Academic Skills suite.
alterlab-accreditation-aolScaffolds program-level Assurance-of-Learning (AoL) documentation for AACSB (2020 Standard 5) and ABET (Criterion 3 Student Outcomes, Criterion 4 Continuous Improvement) accreditation — program learning outcomes / competency goals, curriculum-to-outcome mapping matrices, direct- and indirect-assessment plans, rubric design, and closing-the-loop continuous-improvement narratives — and validates the structure of an outcome-mapping matrix with scripts/aol_matrix.py. Use when the user needs AACSB or ABET assurance-of-learning material, a program-learning-outcomes set, a curriculum/outcome map or coverage matrix, a direct/indirect assessment plan, a closing-the-loop report, or accreditation self-study text. For single-course design or course rubrics prefer alterlab-teaching-design; for post-award grant reports prefer alterlab-grant-reporting. Part of the AlterLab Academic Skills suite.
alterlab-adaptyvSubmits and tracks protein-testing experiments on the Adaptyv Bio Foundry cloud lab (wet-lab validation), and optimizes protein sequences before submission with computational tools (NetSolP, SoluProt, SolubleMPNN, ESM). Use when designing proteins that need wet-lab validation - binding/affinity screening, expression testing, thermostability, or fluorescence assays - or when submitting experiments to the Foundry API, browsing the target catalog, tracking experiment status, retrieving results, or pre-screening sequences for solubility/expression. Triggers on "Adaptyv", "Foundry API", "cloud lab", "biolayer interferometry / BLI", "wet-lab validation". Part of the AlterLab Academic Skills suite.
alterlab-aeonRuns time series machine learning with the aeon library — classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search via scikit-learn compatible APIs. Use when working with temporal data, sequential patterns, or time-indexed observations (univariate or multivariate) that need specialized algorithms beyond standard ML approaches. Part of the AlterLab Academic Skills suite.
alterlab-akademik-tesvikComputes the annual Turkish academic-incentive (akademik teşvik) score for Devlet (state) university öğretim elemanı (academic staff) from a classified activity list, applying the verified Akademik Teşvik Ödeneği Yönetmeliği (2018/11834) Faaliyet Hesaplama Tablosu headline puanları (Proje 20, Araştırma 15, Yayın 30, Patent 30, Atıf 30, Tebliğ 20, Ödül 20) with the k (author-count), p (Q1 1/Q2 0.8/Q3 0.5/Q4 0.25), and r (project-role) coefficients via türü puanı = Σ(faaliyet oranları) × headline (MADDE 8/2), then enforcing the per-type headline ceilings, the 100 cap (MADDE 8/3), and the net-30 payment gate (MADDE 10/3) in a deterministic scripts/tesvik_score.py. Use when the user wants to calculate akademik teşvik puanı, check the en az 30 (net-30) threshold, apply TABLO 4 ceilings, or estimate teşvik eligibility; keeps its coefficients separate from doçentlik scoring. For doçentlik point eligibility prefer alterlab-docentlik-eligibility. Part of the AlterLab Academic Skills suite.
alterlab-alpha-vantageAccesses real-time and historical stock market data, forex rates, cryptocurrency prices, commodities, economic indicators, and 50+ technical indicators via the Alpha Vantage API (requires a free API key from alphavantage.co). Use when fetching stock prices (OHLCV), company fundamentals (income statement, balance sheet, cash flow), earnings, options data, market news/sentiment, insider transactions, GDP, CPI, treasury yields, gold/silver/oil prices, Bitcoin/crypto prices, forex exchange rates, or calculating technical indicators (SMA, EMA, MACD, RSI, Bollinger Bands). Part of the AlterLab Academic Skills suite.
alterlab-alphafoldPredict protein 3D structures with AlphaFold2 via ColabFold — MMseqs2-accelerated MSAs, monomer and AlphaFold2-Multimer complex folding, and confidence-based validation (pLDDT, pTM/ipTM, PAE). Use when folding a protein sequence or complex from FASTA, generating a predicted structure with confidence metrics, ranking models, or checking self-consistency of a design. For co-folding a protein WITH a small-molecule ligand or predicting binding affinity prefer alterlab-boltz; for antibody–antigen or one-FASTA multi-entity complexes prefer alterlab-chai; to LOOK UP an already-computed structure prefer alterlab-alphafold-db; for ESM embeddings or inverse folding prefer alterlab-esm. Part of the AlterLab Academic Skills suite.
alterlab-alphafold-dbAccess the AlphaFold DB of 200M+ AI-PREDICTED protein structures — retrieve models by UniProt accession, download PDB/mmCIF files, and analyze prediction confidence metrics (pLDDT, PAE). Use when a UniProt ID needs a computationally predicted 3D structure or when no experimental structure exists, for homology modeling, protein engineering, or structure-based drug discovery; for EXPERIMENTALLY determined structures (X-ray, cryo-EM, NMR) prefer alterlab-pdb, and for protein sequences, annotations, or accession ID mapping prefer alterlab-uniprot instead. Part of the AlterLab Academic Skills suite.
alterlab-anndataBuild, slice, concatenate, read, and write AnnData annotated data matrices (obs, var, X, layers, obsm, uns) — the scverse data STRUCTURE, not an analysis pipeline. Use when creating or wrangling .h5ad/zarr files, managing cell and gene annotations, concatenating batches, or handling layers/obsm/backed-mode; for the QC, normalization, clustering, UMAP, and differential-expression analysis pipeline prefer alterlab-scanpy instead, and for RNA velocity from spliced/unspliced layers prefer alterlab-scvelo instead. Part of the AlterLab Academic Skills suite.