domains / science / pubchem-compound-queries / pubchem-database

pubchem-database

Skill card

combined

The copies overlap heavily on PubChem search, property retrieval, similarity, and substructure workflows, but they disagree on the intended interface and include material steps the others lack. The benchflow and OpenClaw copies are nearly identical inline PubChemPy tutorials, while the aipoch copy wraps the same operations in a scripts/pubchem_ops.py module, adds explicit rate-limit handling, and documents bioactivity retrieval as a first-class operation. Crowning one copy would hide the alternative module-based workflow and the rate-limit constraint.

Repositories

Other copies

Combined skill

# PubChem Database

## Overview

Use PubChem to search chemical compounds, retrieve physicochemical properties, perform similarity or substructure searches, and access bioactivity data. PubChem contains 110M+ compounds and 270M+ bioactivities.

## When to Use

- Search compounds by name, CID, SMILES, InChI, or molecular formula.
- Retrieve properties such as molecular weight, LogP, TPSA, and hydrogen-bond descriptors.
- Find structurally similar compounds or compounds containing a substructure.
- Access bioactivity or assay data for a compound.
- Convert between chemical identifier formats.
- Batch-process compounds for property analysis.

## Dependencies

Install the required Python packages:

```bash
uv pip install pubchempy requests
```

## Rate Limiting

Respect PubChem's rate limit of no more than 5 requests per second. Add delays or retries when making multiple requests.

## Interface Options

### Option A: Inline PubChemPy

Use PubChemPy directly in Python scripts.

### Option B: Module Wrapper

Use a `scripts/pubchem_ops.py` module exposing `get_properties`, `structure_search`, and `get_bioactivity` functions.

## Core Operations

### 1. Chemical Structure Search

Search by name, CID, SMILES, InChI, or molecular formula.

Inline PubChemPy examples:

```python
import pubchempy as pcp

# By name
compounds = pcp.get_compounds('aspirin', 'name')

# By CID
compound = pcp.Compound.from_cid(2244)

# By SMILES
compound = pcp.get_compounds('CC(=O)OC1=CC=CC=C1C(=O)O', 'smiles')[0]

# By InChI
compound = pcp.get_compounds('InChI=1S/C9H8O4/...', 'inchi')[0]

# By formula
compounds = pcp.get_compounds('C9H8O4', 'formula')
```

Module wrapper example:

```python
from scripts.pubchem_ops import get_properties

result = get_properties(query_value='Aspirin', query_type='name')
```

### 2. Property Retrieval

Retrieve molecular properties using PubChemPy or the module wrapper.

Inline PubChemPy:

```python
import pubchempy as pcp

compound = pcp.get_compounds('caffeine', 'name')[0]

molecular_formula = compound.molecular_formula
molecular_weight = compound.molecular_weight
iupac_name = compound.iupac_name
smiles = compound.canonical_smiles
inchi = compound.inchi
xlogp = compound.xlogp
tpsa = compound.tpsa
```

Request specific properties:

```python
properties = pcp.get_properties(
    ['MolecularFormula', 'MolecularWeight', 'CanonicalSMILES', 'XLogP'],
    'aspirin',
    'name'
)
```

Batch retrieval:

```python
import pandas as pd

compound_names = ['aspirin', 'ibuprofen', 'paracetamol']
all_properties = []

for name in compound_names:
    props = pcp.get_properties(
        ['MolecularFormula', 'MolecularWeight', 'XLogP'],
        name,
        'name'
    )
    all_properties.extend(props)

df = pd.DataFrame(all_properties)
```

Module wrapper:

```python
from scripts.pubchem_ops import get_properties

result = get_properties(query_value='Aspirin', query_type='name')
```

Available properties include MolecularFormula, MolecularWeight, CanonicalSMILES, IsomericSMILES, InChI, InChIKey, IUPACName, XLogP, TPSA, HBondDonorCount, HBondAcceptorCount, RotatableBondCount, Complexity, and Charge.

### 3. Similarity Search

Find structurally similar compounds using Tanimoto similarity.

Inline PubChemPy:

```python
import pubchempy as pcp

query_compound = pcp.get_compounds('gefitinib', 'name')[0]
query_smiles = query_compound.canonical_smiles

similar_compounds = pcp.get_compounds(
    query_smiles,
    'smiles',
    searchtype='similarity',
    Threshold=85,
    MaxRecords=50
)
```

Similarity searches may be asynchronous for large queries and can take 15-30 seconds.

Module wrapper:

```python
from scripts.pubchem_ops import structure_search

smiles = 'CC(=O)OC1=CC=CC=C1C(=O)O'
result = structure_search(query_value=smiles, search_type='similarity')
```

### 4. Substructure Search

Find compounds containing a specific structural motif.

Inline PubChemPy:

```python
import pubchempy as pcp

pyridine_smiles = 'c1ccncc1'

matches = pcp.get_compounds(
    pyridine_smiles,
    'smiles',
    searchtype='substructure',
    MaxRecords=100
)
```

Common substructures:
- Benzene ring: `c1ccccc1`
- Pyridine: `c1ccncc1`
- Phenol: `c1ccc(O)cc1`
- Carboxylic acid: `C(=O)O`

Module wrapper:

```python
from scripts.pubchem_ops import structure_search

result = structure_search(query_value='c1ccncc1', search_type='substructure')
```

### 5. Format Conversion

Convert between chemical structure formats.

```python
import pubchempy as pcp

compound = pcp.get_compounds('aspirin', 'name')[0]

smiles = compound.canonical_smiles
inchi = compound.inchi
inchikey = compound.inchikey
cid = compound.cid

pcp.download('SDF', 'aspirin', 'name', 'aspirin.sdf', overwrite=True)
pcp.download('JSON', '2244', 'cid', 'aspirin.json', overwrite=True)
```

### 6. Structure Visualization

Generate 2D structure images.

```python
import pubchempy as pcp

pcp.download('PNG', 'caffeine', 'name', 'caffeine.png', overwrite=True)
```

Or use the PUG-REST URL directly:

```python
import requests

cid = 2244
url = f"https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/cid/{cid}/PNG?image_size=large"
response = requests.get(url)

with open('structure.png', 'wb') as f:
    f.write(response.content)
```

### 7. Synonym Retrieval

Get all known names and synonyms for a compound.

```python
import pubchempy as pcp

synonyms_data = pcp.get_synonyms('aspirin', 'name')

if synonyms_data:
    cid = synonyms_data[0]['CID']
    synonyms = synonyms_data[0]['Synonym']

    print(f"CID {cid} has {len(synonyms)} synonyms:")
    for syn in synonyms[:10]:
        print(f"  - {syn}")
```

### 8. Bioactivity Data Access

Retrieve biological activity data for a compound.

Module wrapper:

```python
from scripts.pubchem_ops import get_bioactivity

result = get_bioactivity(cid=2244)
```

## Error Handling

- Return a structured error or `None` if a compound is not found.
- Handle PubChem rate limits by throttling requests to 5 or fewer per second.
- Verify query format (valid SMILES or InChI) if results are empty.
- Ensure network access to `pubchem.ncbi.nlm.nih.gov`.

## References

- API documentation: `references/api_reference.md`
- Primary script: `scripts/pubchem_ops.py`