git:20260428.81ea2d2 to git:20260522.6a6fd41

---

name: "unichem-database"

license: "Apache-2.0"

---

# UniChem Database

## Overview

## When to Use

- Translating a ChEMBL compound ID to a PubChem CID, DrugBank accession, or ChEBI ID for cross-database analysis

- Resolving an InChIKey to all database sources where a compound appears

- Finding all structurally related compounds (same connectivity, different stereochemistry/salts) across databases using connectivity search

- Validating compound identity across sources before merging datasets from multiple databases

- Building a compound cross-reference table for a drug discovery project (linking bioactivity data in ChEMBL to structural data in PDB)

- Checking if a synthesized compound or a vendor compound exists in any public database by InChIKey

## Prerequisites

- **Environment**: internet connection; no API key required

```bash

pip install requests pandas matplotlib

```

## Quick Start

```python

import requests

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

r.raise_for_status()

return r.json()

# Find all database sources for aspirin by InChIKey

inchikey = "BSYNRYMUTXBXSQ-UHFFFAOYSA-N" # aspirin

compounds = result.get("compounds", [])

print(f"Found {len(compounds)} compound record(s) for {inchikey}")

if compounds:

sources = compounds[0].get("sources", [])

# Found 1 compound record(s) for BSYNRYMUTXBXSQ-UHFFFAOYSA-N

```

## Core API

```python

import requests, pandas as pd

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

SOURCE_NAMES = {

}

def lookup_by_inchikey(inchikey: str) -> pd.DataFrame:

"""Return all database cross-references for an InChIKey."""

r.raise_for_status()

compounds = r.json().get("compounds", [])

if not compounds:

return pd.DataFrame()

rows = []

for src in compounds[0].get("sources", []):

rows.append({

"compound_id": src["compoundId"],

"url": src.get("url", ""),

})

```

```python

# Extract specific source IDs from cross-reference table

def get_id_for_source(inchikey: str, source_id: int) -> str | None:

"""Return the compound ID in a specific database, or None if not found."""

r.raise_for_status()

compounds = r.json().get("compounds", [])

if not compounds:

return None

for src in compounds[0].get("sources", []):

return src["compoundId"]

return None

```

```python

import requests

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

def get_sources_for_compound(compound_id: str, source_id: int) -> list:

"""Get all database cross-references for a compound identified in a specific source.

Args:

source_id: UniChem source ID (1=ChEMBL, 2=DrugBank, 22=PubChem, 7=ChEBI)

"""

r.raise_for_status()

sources = get_sources_for_compound("CHEMBL192", source_id=1)

for s in sources:

```

```python

import requests, pandas as pd

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

"""

r.raise_for_status()

# Warfarin: find all stereoforms, racemates, and salt forms

```

```python

# Compare source coverage across connectivity relatives

def compare_coverage(inchikey: str) -> pd.DataFrame:

rows = []

rows.append({

})

```

### Query 4: List All Data Sources

```python

import requests, pandas as pd

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

def list_sources() -> pd.DataFrame:

"""Return all UniChem data sources as a DataFrame."""

r = requests.get(f"{UNICHEM_API}/sources", timeout=15)

r.raise_for_status()

sources = r.json().get("sources", [])

rows = []

for s in sources:

rows.append({

})

return pd.DataFrame(rows).sort_values("source_id")

sources_df = list_sources()

print(f"Total UniChem sources: {len(sources_df)}")

```

```python

import requests, time, pandas as pd

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

def batch_translate(inchikeys: list[str],

"""Translate a list of InChIKeys to IDs in multiple target databases.

"""

rows = []

for ik in inchikeys:

row = {"inchikey": ik}

for sid in target_source_ids:

row[SOURCE_NAMES.get(sid, f"src_{sid}")] = None

try:

r.raise_for_status()

compounds = r.json().get("compounds", [])

if compounds:

for src in compounds[0].get("sources", []):

except requests.RequestException as e:

row["error"] = str(e)

rows.append(row)

time.sleep(0.1) # respect ~10 req/s rate limit

return pd.DataFrame(rows)

# Translate a set of NSAIDs by InChIKey

nsaid_inchikeys = [

"BSYNRYMUTXBXSQ-UHFFFAOYSA-N", # aspirin

"HEFNNWSXXWATRW-UHFFFAOYSA-N", # ibuprofen

"CMWTZPSULFXXJA-VIFPVBQESA-N", # naproxen

]

df = batch_translate(nsaid_inchikeys, target_source_ids=[1, 2, 7, 22])

print(df.to_string(index=False))

df.to_csv("nsaid_xrefs.csv", index=False)

```

```python

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

"""

```

## Key Concepts

### InChI vs InChIKey

UniChem uses the **InChI** (IUPAC International Chemical Identifier) and its hashed form the **InChIKey** as the canonical compound identity. The InChIKey is a 27-character string split into three blocks: the first 14 characters encode the connectivity layer (heavy atoms and bonds), the next 8 encode stereochemistry and charge, and the last character is a version flag. UniChem cross-references compounds by requiring identical standard InChIKeys, ensuring the same chemical entity across databases.

| Source ID | Database | Scope |

|-----------|----------|-------|

## Common Workflows

### Workflow 1: Drug Compound Cross-Reference Report

**Goal**: Given a list of drug names (or ChEMBL IDs), resolve each to all major database IDs and export to CSV.

```python

import requests, time, pandas as pd

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

CHEMBL_API = "https://www.ebi.ac.uk/chembl/api/data"

def chembl_to_inchikey(chembl_id: str) -> str | None:

"""Look up the standard InChIKey for a ChEMBL compound ID."""

r = requests.get(f"{CHEMBL_API}/molecule/{chembl_id}.json", timeout=15)

if r.status_code == 404:

return None

r.raise_for_status()

return r.json().get("molecule_structures", {}).get("standard_inchi_key")

def inchikey_to_sources(inchikey: str) -> dict:

r.raise_for_status()

compounds = r.json().get("compounds", [])

if not compounds:

return {}

# Example: top cardiovascular drugs

drug_chembl_ids = {

"atorvastatin": "CHEMBL1487",

"lisinopril": "CHEMBL1237",

}

rows = []

for name, chembl_id in drug_chembl_ids.items():

ik = chembl_to_inchikey(chembl_id)

row = {"drug": name, "chembl_id": chembl_id, "inchikey": ik}

if ik:

srcs = inchikey_to_sources(ik)

for sid, col in SOURCE_NAMES.items():

row[col] = srcs.get(sid)

rows.append(row)

time.sleep(0.2)

df = pd.DataFrame(rows)

df.to_csv("drug_xrefs.csv", index=False)

print(df[["drug", "chembl", "drugbank", "pubchem", "chebi"]].to_string(index=False))

```

### Workflow 2: Structural Relatives Discovery and Visualization

**Goal**: Find all structural relatives of a compound, summarize their database coverage, and plot a bar chart showing source distribution.

```python

import requests, pandas as pd

import matplotlib.pyplot as plt

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

r.raise_for_status()

source_counter = Counter()

labels = [k for k, _ in source_counter.most_common()]

counts = [v for _, v in source_counter.most_common()]

fig, ax = plt.subplots(figsize=(9, 4))

bars = ax.bar(labels, counts, color="#2E86AB", edgecolor="white")

ax.bar_label(bars, padding=2)

ax.set_xlabel("Database")

plt.tight_layout()

plt.savefig("unichem_connectivity_coverage.png", dpi=150, bbox_inches="tight")

```

### Workflow 3: Merge ChEMBL Bioactivity with PubChem CIDs

**Goal**: Augment a ChEMBL bioactivity table with PubChem CIDs for downstream analysis in tools that use PubChem identifiers.

```python

import requests, time, pandas as pd

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

def add_pubchem_cids(df: pd.DataFrame,

inchikey_col: str = "standard_inchi_key") -> pd.DataFrame:

"""Add pubchem_cid column to a DataFrame that has an InChIKey column."""

unique_keys = df[inchikey_col].dropna().unique()

mapping = {}

for ik in unique_keys:

try:

r.raise_for_status()

compounds = r.json().get("compounds", [])

if compounds:

for src in compounds[0].get("sources", []):

mapping[ik] = src["compoundId"]

break

except requests.RequestException:

pass

time.sleep(0.1)

df = df.copy()

df["pubchem_cid"] = df[inchikey_col].map(mapping)

return df

# Simulate a small ChEMBL activity table

chembl_data = pd.DataFrame({

"compound_name": ["aspirin", "ibuprofen", "naproxen"],

"standard_inchi_key": [

"BSYNRYMUTXBXSQ-UHFFFAOYSA-N",

"HEFNNWSXXWATRW-UHFFFAOYSA-N",

"CMWTZPSULFXXJA-VIFPVBQESA-N",

],

"ic50_nm": [2500.0, 13000.0, 1600.0],

})

enriched = add_pubchem_cids(chembl_data)

print(enriched[["compound_name", "ic50_nm", "pubchem_cid"]].to_string(index=False))

enriched.to_csv("chembl_with_pubchem.csv", index=False)

```

## Key Parameters

## Best Practices

## Common Recipes

### Recipe: Resolve Any Compound ID to InChIKey

When to use: You have a PubChem CID or ChEBI ID and need the InChIKey to query UniChem or other services.

```python

import requests

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

PUBCHEM_API = "https://pubchem.ncbi.nlm.nih.gov/rest/pug"

"""Resolve a PubChem CID to a standard InChIKey via PubChem."""

r = requests.get(f"{PUBCHEM_API}/compound/cid/{cid}/property/InChIKey/JSON", timeout=10)

if r.status_code == 404:

return None

r.raise_for_status()

props = r.json()["PropertyTable"]["Properties"]

return props[0]["InChIKey"] if props else None

ik = pubchem_cid_to_inchikey(cid)

if not ik:

return []

r.raise_for_status()

compounds = r.json().get("compounds", [])

return compounds[0].get("sources", []) if compounds else []

sources = cid_to_all_sources(2244) # PubChem CID for aspirin

```

### Recipe: Check If a Compound Is an Approved Drug

```python

import requests

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

def is_approved_drug(inchikey: str) -> tuple[bool, str | None]:

r.raise_for_status()

compounds = r.json().get("compounds", [])

if not compounds:

return False, None

for src in compounds[0].get("sources", []):

return True, src["compoundId"]

return False, None

# Test a few compounds

test_compounds = {

}

for name, ik in test_compounds.items():

is_drug, db_id = is_approved_drug(ik)

status = f"DrugBank:{db_id}" if is_drug else "not in DrugBank"

```

### Recipe: Source Coverage Summary for a Compound Set

```python

import requests, time, pandas as pd

UNICHEM_API = "https://www.ebi.ac.uk/unichem/api/v1"

def source_coverage_matrix(inchikeys: list[str]) -> pd.DataFrame:

"""Return a boolean matrix: rows=compounds, columns=databases."""

rows = []

for ik in inchikeys:

row = {"inchikey": ik}

for sid, name in SOURCE_NAMES.items():

row[name] = False

if r.ok:

compounds = r.json().get("compounds", [])

if compounds:

rows.append(row)

time.sleep(0.1)

return pd.DataFrame(rows)

sample_keys = [

"BSYNRYMUTXBXSQ-UHFFFAOYSA-N", # aspirin

"HEFNNWSXXWATRW-UHFFFAOYSA-N", # ibuprofen

]

coverage = source_coverage_matrix(sample_keys)

print(coverage.to_string(index=False))

for col in list(SOURCE_NAMES.values()):

print(f" {col}: {coverage[col].sum()}/{len(coverage)}")

```

## Troubleshooting

| Problem | Cause | Solution |

|---------|-------|----------|

## Related Skills

## References