Pdb Database

{
  "description": "\"Access RCSB PDB for 3D protein/nucleic acid structures. Search by text/sequence/structure, download coordinates (PDB/mmCIF), retrieve metadata, for structural biology and drug discovery.\"",
  "references": {
    "files": [
      "references/api_reference.md"
    ]
  },
  "content": "### 1. Searching for Structures\r\n\r\nFind PDB entries using various search criteria:\r\n\r\n**Text Search:** Search by protein name, keywords, or descriptions\r\n```python\r\nfrom rcsbapi.search import TextQuery\r\nquery = TextQuery(\"hemoglobin\")\r\nresults = list(query())\r\nprint(f\"Found {len(results)} structures\")\r\n```\r\n\r\n**Attribute Search:** Query specific properties (organism, resolution, method, etc.)\r\n```python\r\nfrom rcsbapi.search import AttributeQuery\r\nfrom rcsbapi.search.attrs import rcsb_entity_source_organism\r\n\r\nquery = AttributeQuery(\r\n    attribute=rcsb_entity_source_organism.scientific_name,\r\n    operator=\"exact_match\",\r\n    value=\"Homo sapiens\"\r\n)\r\nresults = list(query())\r\n```\r\n\r\n**Sequence Similarity:** Find structures similar to a given sequence\r\n```python\r\nfrom rcsbapi.search import SequenceQuery\r\n\r\nquery = SequenceQuery(\r\n    value=\"MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQVVIDGETCLLDILDTAGQEEYSAMRDQYMRTGEGFLCVFAINNTKSFEDIHHYREQIKRVKDSEDVPMVLVGNKCDLPSRTVDTKQAQDLARSYGIPFIETSAKTRQGVDDAFYTLVREIRKHKEKMSKDGKKKKKKSKTKCVIM\",\r\n    evalue_cutoff=0.1,\r\n    identity_cutoff=0.9\r\n)\r\nresults = list(query())\r\n```\r\n\r\n**Structure Similarity:** Find structures with similar 3D geometry\r\n```python\r\nfrom rcsbapi.search import StructSimilarityQuery\r\n\r\nquery = StructSimilarityQuery(\r\n    structure_search_type=\"entry\",\r\n    entry_id=\"4HHB\"  # Hemoglobin\r\n)\r\nresults = list(query())\r\n```\r\n\r\n**Combining Queries:** Use logical operators to build complex searches\r\n```python\r\nfrom rcsbapi.search import TextQuery, AttributeQuery\r\nfrom rcsbapi.search.attrs import rcsb_entry_info\r\n\r\nquery1 = AttributeQuery(\r\n    attribute=rcsb_entity_source_organism.scientific_name,\r\n    operator=\"exact_match\",\r\n    value=\"Homo sapiens\"\r\n)\r\nquery2 = AttributeQuery(\r\n    attribute=rcsb_entry_info.resolution_combined,\r\n    operator=\"less\",\r\n    value=2.0\r\n)\r\ncombined_query = query1 & query2  # AND operation\r\nresults = list(combined_query())\r\n```\r\n\r\n### 2. Retrieving Structure Data\r\n\r\nAccess detailed information about specific PDB entries:\r\n\r\n**Basic Entry Information:**\r\n```python\r\nfrom rcsbapi.data import Schema, fetch\r\n\r\nentry_data = fetch(\"4HHB\", schema=Schema.ENTRY)\r\nprint(entry_data[\"struct\"][\"title\"])\r\nprint(entry_data[\"exptl\"][0][\"method\"])\r\n```\r\n\r\n**Polymer Entity Information:**\r\n```python\r\nentity_data = fetch(\"4HHB_1\", schema=Schema.POLYMER_ENTITY)\r\nprint(entity_data[\"entity_poly\"][\"pdbx_seq_one_letter_code\"])\r\n```\r\n\r\n**Using GraphQL for Flexible Queries:**\r\n```python\r\nfrom rcsbapi.data import fetch\r\n\r\nquery = \"\"\"\r\n{\r\n  entry(entry_id: \"4HHB\") {\r\n    struct {\r\n      title\r\n    }\r\n    exptl {\r\n      method\r\n    }\r\n    rcsb_entry_info {\r\n      resolution_combined\r\n      deposited_atom_count\r\n    }\r\n  }\r\n}\r\n\"\"\"\r\ndata = fetch(query_type=\"graphql\", query=query)\r\n```\r\n\r\n### 3. Downloading Structure Files\r\n\r\nRetrieve coordinate files in various formats:\r\n\r\n**Download Methods:**\r\n- **PDB format** (legacy text format): `https://files.rcsb.org/download/{PDB_ID}.pdb`\r\n- **mmCIF format** (modern standard): `https://files.rcsb.org/download/{PDB_ID}.cif`\r\n- **BinaryCIF** (compressed binary): Use ModelServer API for efficient access\r\n- **Biological assembly**: `https://files.rcsb.org/download/{PDB_ID}.pdb1` (for assembly 1)\r\n\r\n**Example Download:**\r\n```python\r\nimport requests\r\n\r\npdb_id = \"4HHB\"\r\n\r\npdb_url = f\"https://files.rcsb.org/download/{pdb_id}.pdb\"\r\nresponse = requests.get(pdb_url)\r\nwith open(f\"{pdb_id}.pdb\", \"w\") as f:\r\n    f.write(response.text)\r\n\r\ncif_url = f\"https://files.rcsb.org/download/{pdb_id}.cif\"\r\nresponse = requests.get(cif_url)\r\nwith open(f\"{pdb_id}.cif\", \"w\") as f:\r\n    f.write(response.text)\r\n```\r\n\r\n### 4. Working with Structure Data\r\n\r\nCommon operations with retrieved structures:\r\n\r\n**Parse and Analyze Coordinates:**\r\nUse BioPython or other structural biology libraries to work with downloaded files:\r\n```python\r\nfrom Bio.PDB import PDBParser\r\n\r\nparser = PDBParser()\r\nstructure = parser.get_structure(\"protein\", \"4HHB.pdb\")\r\n\r\nfor model in structure:\r\n    for chain in model:\r\n        for residue in chain:\r\n            for atom in residue:\r\n                print(atom.get_coord())\r\n```\r\n\r\n**Extract Metadata:**\r\n```python\r\nfrom rcsbapi.data import fetch, Schema\r\n\r\ndata = fetch(\"4HHB\", schema=Schema.ENTRY)\r\n\r\nresolution = data.get(\"rcsb_entry_info\", {}).get(\"resolution_combined\")\r\nmethod = data.get(\"exptl\", [{}])[0].get(\"method\")\r\ndeposition_date = data.get(\"rcsb_accession_info\", {}).get(\"deposit_date\")\r\n\r\nprint(f\"Resolution: {resolution} Å\")\r\nprint(f\"Method: {method}\")\r\nprint(f\"Deposited: {deposition_date}\")\r\n```\r\n\r\n### 5. Batch Operations\r\n\r\nProcess multiple structures efficiently:\r\n\r\n```python\r\nfrom rcsbapi.data import fetch, Schema\r\n\r\npdb_ids = [\"4HHB\", \"1MBN\", \"1GZX\"]  # Hemoglobin, myoglobin, etc.\r\n\r\nresults = {}\r\nfor pdb_id in pdb_ids:\r\n    try:\r\n        data = fetch(pdb_id, schema=Schema.ENTRY)\r\n        results[pdb_id] = {\r\n            \"title\": data[\"struct\"][\"title\"],\r\n            \"resolution\": data.get(\"rcsb_entry_info\", {}).get(\"resolution_combined\"),\r\n            \"organism\": data.get(\"rcsb_entity_source_organism\", [{}])[0].get(\"scientific_name\")\r\n        }\r\n    except Exception as e:\r\n        print(f\"Error fetching {pdb_id}: {e}\")\r\n\r\n\r\nInstall the official RCSB PDB Python API client:\r\n\r\n```bash\r\npip install rcsb-api",
  "name": "pdb-database",
  "id": "scientific-db-pdb-database",
  "sections": {
    "Additional Resources": "- **RCSB PDB Website:** https://www.rcsb.org\r\n- **PDB-101 Educational Portal:** https://pdb101.rcsb.org\r\n- **API Documentation:** https://www.rcsb.org/docs/programmatic-access/web-apis-overview\r\n- **Python Package Docs:** https://rcsbapi.readthedocs.io/\r\n- **Data API Documentation:** https://data.rcsb.org/\r\n- **GitHub Repository:** https://github.com/rcsb/py-rcsb-api",
    "Python Package Installation": "pip install rcsbsearchapi\r\n```\r\n\r\nThe `rcsb-api` package provides unified access to both Search and Data APIs through the `rcsbapi.search` and `rcsbapi.data` modules.",
    "Overview": "RCSB PDB is the worldwide repository for 3D structural data of biological macromolecules. Search for structures, retrieve coordinates and metadata, perform sequence and structure similarity searches across 200,000+ experimentally determined structures and computed models.",
    "When to Use This Skill": "This skill should be used when:\r\n- Searching for protein or nucleic acid 3D structures by text, sequence, or structural similarity\r\n- Downloading coordinate files in PDB, mmCIF, or BinaryCIF formats\r\n- Retrieving structural metadata, experimental methods, or quality metrics\r\n- Performing batch operations across multiple structures\r\n- Integrating PDB data into computational workflows for drug discovery, protein engineering, or structural biology research",
    "Common Use Cases": "### Drug Discovery\r\n- Search for structures of drug targets\r\n- Analyze ligand binding sites\r\n- Compare protein-ligand complexes\r\n- Identify similar binding pockets\r\n\r\n### Protein Engineering\r\n- Find homologous structures for modeling\r\n- Analyze sequence-structure relationships\r\n- Compare mutant structures\r\n- Study protein stability and dynamics\r\n\r\n### Structural Biology Research\r\n- Download structures for computational analysis\r\n- Build structure-based alignments\r\n- Analyze structural features (secondary structure, domains)\r\n- Compare experimental methods and quality metrics\r\n\r\n### Education and Visualization\r\n- Retrieve structures for teaching\r\n- Generate molecular visualizations\r\n- Explore structure-function relationships\r\n- Study evolutionary conservation",
    "Core Capabilities": "for pdb_id, info in results.items():\r\n    print(f\"\\n{pdb_id}: {info['title']}\")\r\n    print(f\"  Resolution: {info['resolution']} Å\")\r\n    print(f\"  Organism: {info['organism']}\")\r\n```",
    "Resources": "This skill includes reference documentation in the `references/` directory:\r\n\r\n### references/api_reference.md\r\nComprehensive API documentation covering:\r\n- Detailed API endpoint specifications\r\n- Advanced query patterns and examples\r\n- Data schema reference\r\n- Rate limiting and best practices\r\n- Troubleshooting common issues\r\n\r\nUse this reference when you need in-depth information about API capabilities, complex query construction, or detailed data schema information.",
    "Key Concepts": "**PDB ID:** Unique 4-character identifier (e.g., \"4HHB\") for each structure entry. AlphaFold and ModelArchive entries start with \"AF_\" or \"MA_\" prefixes.\r\n\r\n**mmCIF/PDBx:** Modern file format that uses key-value structure, replacing legacy PDB format for large structures.\r\n\r\n**Biological Assembly:** The functional form of a macromolecule, which may contain multiple copies of chains from the asymmetric unit.\r\n\r\n**Resolution:** Measure of detail in crystallographic structures (lower values = higher detail). Typical range: 1.5-3.5 Å for high-quality structures.\r\n\r\n**Entity:** A unique molecular component in a structure (protein chain, DNA, ligand, etc.)."
  }
}

---
name: pdb-database
description: "Access RCSB PDB for 3D protein/nucleic acid structures. Search by text/sequence/structure, download coordinates (PDB/mmCIF), retrieve metadata, for structural biology and drug discovery."
---

# PDB Database

## Overview

RCSB PDB is the worldwide repository for 3D structural data of biological macromolecules. Search for structures, retrieve coordinates and metadata, perform sequence and structure similarity searches across 200,000+ experimentally determined structures and computed models.

## When to Use This Skill

This skill should be used when:
- Searching for protein or nucleic acid 3D structures by text, sequence, or structural similarity
- Downloading coordinate files in PDB, mmCIF, or BinaryCIF formats
- Retrieving structural metadata, experimental methods, or quality metrics
- Performing batch operations across multiple structures
- Integrating PDB data into computational workflows for drug discovery, protein engineering, or structural biology research

## Core Capabilities

### 1. Searching for Structures

Find PDB entries using various search criteria:

**Text Search:** Search by protein name, keywords, or descriptions
```python
from rcsbapi.search import TextQuery
query = TextQuery("hemoglobin")
results = list(query())
print(f"Found {len(results)} structures")
```

**Attribute Search:** Query specific properties (organism, resolution, method, etc.)
```python
from rcsbapi.search import AttributeQuery
from rcsbapi.search.attrs import rcsb_entity_source_organism

# Find human protein structures
query = AttributeQuery(
    attribute=rcsb_entity_source_organism.scientific_name,
    operator="exact_match",
    value="Homo sapiens"
)
results = list(query())
```

**Sequence Similarity:** Find structures similar to a given sequence
```python
from rcsbapi.search import SequenceQuery

query = SequenceQuery(
    value="MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQVVIDGETCLLDILDTAGQEEYSAMRDQYMRTGEGFLCVFAINNTKSFEDIHHYREQIKRVKDSEDVPMVLVGNKCDLPSRTVDTKQAQDLARSYGIPFIETSAKTRQGVDDAFYTLVREIRKHKEKMSKDGKKKKKKSKTKCVIM",
    evalue_cutoff=0.1,
    identity_cutoff=0.9
)
results = list(query())
```

**Structure Similarity:** Find structures with similar 3D geometry
```python
from rcsbapi.search import StructSimilarityQuery

query = StructSimilarityQuery(
    structure_search_type="entry",
    entry_id="4HHB"  # Hemoglobin
)
results = list(query())
```

**Combining Queries:** Use logical operators to build complex searches
```python
from rcsbapi.search import TextQuery, AttributeQuery
from rcsbapi.search.attrs import rcsb_entry_info

# High-resolution human proteins
query1 = AttributeQuery(
    attribute=rcsb_entity_source_organism.scientific_name,
    operator="exact_match",
    value="Homo sapiens"
)
query2 = AttributeQuery(
    attribute=rcsb_entry_info.resolution_combined,
    operator="less",
    value=2.0
)
combined_query = query1 & query2  # AND operation
results = list(combined_query())
```

### 2. Retrieving Structure Data

Access detailed information about specific PDB entries:

**Basic Entry Information:**
```python
from rcsbapi.data import Schema, fetch

# Get entry-level data
entry_data = fetch("4HHB", schema=Schema.ENTRY)
print(entry_data["struct"]["title"])
print(entry_data["exptl"][0]["method"])
```

**Polymer Entity Information:**
```python
# Get protein/nucleic acid information
entity_data = fetch("4HHB_1", schema=Schema.POLYMER_ENTITY)
print(entity_data["entity_poly"]["pdbx_seq_one_letter_code"])
```

**Using GraphQL for Flexible Queries:**
```python
from rcsbapi.data import fetch

# Custom GraphQL query
query = """
{
  entry(entry_id: "4HHB") {
    struct {
      title
    }
    exptl {
      method
    }
    rcsb_entry_info {
      resolution_combined
      deposited_atom_count
    }
  }
}
"""
data = fetch(query_type="graphql", query=query)
```

### 3. Downloading Structure Files

Retrieve coordinate files in various formats:

**Download Methods:**
- **PDB format** (legacy text format): `https://files.rcsb.org/download/{PDB_ID}.pdb`
- **mmCIF format** (modern standard): `https://files.rcsb.org/download/{PDB_ID}.cif`
- **BinaryCIF** (compressed binary): Use ModelServer API for efficient access
- **Biological assembly**: `https://files.rcsb.org/download/{PDB_ID}.pdb1` (for assembly 1)

**Example Download:**
```python
import requests

pdb_id = "4HHB"

# Download PDB format
pdb_url = f"https://files.rcsb.org/download/{pdb_id}.pdb"
response = requests.get(pdb_url)
with open(f"{pdb_id}.pdb", "w") as f:
    f.write(response.text)

# Download mmCIF format
cif_url = f"https://files.rcsb.org/download/{pdb_id}.cif"
response = requests.get(cif_url)
with open(f"{pdb_id}.cif", "w") as f:
    f.write(response.text)
```

### 4. Working with Structure Data

Common operations with retrieved structures:

**Parse and Analyze Coordinates:**
Use BioPython or other structural biology libraries to work with downloaded files:
```python
from Bio.PDB import PDBParser

parser = PDBParser()
structure = parser.get_structure("protein", "4HHB.pdb")

# Iterate through atoms
for model in structure:
    for chain in model:
        for residue in chain:
            for atom in residue:
                print(atom.get_coord())
```

**Extract Metadata:**
```python
from rcsbapi.data import fetch, Schema

# Get experimental details
data = fetch("4HHB", schema=Schema.ENTRY)

resolution = data.get("rcsb_entry_info", {}).get("resolution_combined")
method = data.get("exptl", [{}])[0].get("method")
deposition_date = data.get("rcsb_accession_info", {}).get("deposit_date")

print(f"Resolution: {resolution} Å")
print(f"Method: {method}")
print(f"Deposited: {deposition_date}")
```

### 5. Batch Operations

Process multiple structures efficiently:

```python
from rcsbapi.data import fetch, Schema

pdb_ids = ["4HHB", "1MBN", "1GZX"]  # Hemoglobin, myoglobin, etc.

results = {}
for pdb_id in pdb_ids:
    try:
        data = fetch(pdb_id, schema=Schema.ENTRY)
        results[pdb_id] = {
            "title": data["struct"]["title"],
            "resolution": data.get("rcsb_entry_info", {}).get("resolution_combined"),
            "organism": data.get("rcsb_entity_source_organism", [{}])[0].get("scientific_name")
        }
    except Exception as e:
        print(f"Error fetching {pdb_id}: {e}")

# Display results
for pdb_id, info in results.items():
    print(f"\n{pdb_id}: {info['title']}")
    print(f"  Resolution: {info['resolution']} Å")
    print(f"  Organism: {info['organism']}")
```

## Python Package Installation

Install the official RCSB PDB Python API client:

```bash
# Current recommended package
pip install rcsb-api

# For legacy code (deprecated, use rcsb-api instead)
pip install rcsbsearchapi
```

The `rcsb-api` package provides unified access to both Search and Data APIs through the `rcsbapi.search` and `rcsbapi.data` modules.

## Common Use Cases

### Drug Discovery
- Search for structures of drug targets
- Analyze ligand binding sites
- Compare protein-ligand complexes
- Identify similar binding pockets

### Protein Engineering
- Find homologous structures for modeling
- Analyze sequence-structure relationships
- Compare mutant structures
- Study protein stability and dynamics

### Structural Biology Research
- Download structures for computational analysis
- Build structure-based alignments
- Analyze structural features (secondary structure, domains)
- Compare experimental methods and quality metrics

### Education and Visualization
- Retrieve structures for teaching
- Generate molecular visualizations
- Explore structure-function relationships
- Study evolutionary conservation

## Key Concepts

**PDB ID:** Unique 4-character identifier (e.g., "4HHB") for each structure entry. AlphaFold and ModelArchive entries start with "AF_" or "MA_" prefixes.

**mmCIF/PDBx:** Modern file format that uses key-value structure, replacing legacy PDB format for large structures.

**Biological Assembly:** The functional form of a macromolecule, which may contain multiple copies of chains from the asymmetric unit.

**Resolution:** Measure of detail in crystallographic structures (lower values = higher detail). Typical range: 1.5-3.5 Å for high-quality structures.

**Entity:** A unique molecular component in a structure (protein chain, DNA, ligand, etc.).

## Resources

This skill includes reference documentation in the `references/` directory:

### references/api_reference.md
Comprehensive API documentation covering:
- Detailed API endpoint specifications
- Advanced query patterns and examples
- Data schema reference
- Rate limiting and best practices
- Troubleshooting common issues

Use this reference when you need in-depth information about API capabilities, complex query construction, or detailed data schema information.

## Additional Resources

- **RCSB PDB Website:** https://www.rcsb.org
- **PDB-101 Educational Portal:** https://pdb101.rcsb.org
- **API Documentation:** https://www.rcsb.org/docs/programmatic-access/web-apis-overview
- **Python Package Docs:** https://rcsbapi.readthedocs.io/
- **Data API Documentation:** https://data.rcsb.org/
- **GitHub Repository:** https://github.com/rcsb/py-rcsb-api