Tooluniverse Protein Structure Retrieval

Protein Structure Data Retrieval

Retrieve protein structures with disambiguation, quality assessment, and comprehensive metadata.

IMPORTANT: Always use English terms in tool calls. Respond in the user's language.

LOOK UP DON'T GUESS: Never assume PDB IDs, resolution, or availability. Always query RCSB/PDBe and AlphaFold to confirm.

Domain Reasoning

Not all structures are equal. X-ray <2 A is high-quality for drug design. Cryo-EM 3-4 A is good for fold but not side chains. AlphaFold is excellent for well-folded domains but unreliable for disordered regions. Always check pLDDT (AlphaFold) or resolution (experimental) before drawing conclusions.

Workflow

Phase 0: Clarify (if needed) → Phase 1: Disambiguate Protein → Phase 2: Retrieve Structures → Phase 3: Report

---

Phase 0: Clarification (When Needed)

Ask ONLY if: protein name ambiguous (e.g., "kinase"), organism not specified, unclear if experimental vs AlphaFold needed. Skip for: specific PDB IDs, UniProt accessions, unambiguous protein+organism.

---

Phase 1: Protein Disambiguation

# By PDB ID: direct retrieval
# By UniProt: get AlphaFold + search experimental structures
af_structure = tu.tools.alphafold_get_prediction(uniprot_id=uniprot_id)
# By protein name: search
result = tu.tools.PDBeSearch_search_structures(protein_name=protein_name)

Identity Checklist

• Protein name/gene identified, organism confirmed
• UniProt accession (if available), isoform/variant specified (if relevant)

---

Phase 2: Data Retrieval (Internal)

Retrieve silently. Do NOT narrate the process.

pdb_id = "4INS"

# Search, metadata, quality, ligands, similar structures
result = tu.tools.PDBeSearch_search_structures(protein_name=name)
metadata = tu.tools.get_protein_metadata_by_pdb_id(pdb_id=pdb_id)
exp = tu.tools.RCSBData_get_entry(pdb_id=pdb_id)
quality = tu.tools.PDBeValidation_get_quality_scores(pdb_id=pdb_id)
ligands = tu.tools.PDBe_KB_get_ligand_sites(pdb_id=pdb_id)
similar = tu.tools.PDBeSIFTS_get_all_structures(pdb_id=pdb_id, cutoff=2.0)

# PDBe additional data
summary = tu.tools.pdbe_get_entry_summary(pdb_id=pdb_id)
molecules = tu.tools.pdbe_get_entry_molecules(pdb_id=pdb_id)

# AlphaFold (when no experimental structure, or for comparison)
af = tu.tools.alphafold_get_prediction(uniprot_id=uniprot_id)

Fallback Chains

---

Phase 3: Report Structure Profile

Present as a Structure Profile Report. Hide search process. Include:

1. Search Summary: query, organism, experimental + AlphaFold structure counts 2. Best Structure: PDB ID, UniProt, organism, method, resolution, date, quality assessment 3. Experimental Details: method, resolution, R-factor, R-free, space group 4. Composition: chains, residues (coverage%), ligands, waters, metals 5. Bound Ligands: ligand ID, name, type, binding site 6. Binding Site Details (for drug discovery): location, key residues, druggability 7. Alternative Structures: ranked by quality with resolution, method, ligands 8. AlphaFold Prediction: UniProt, model version, pLDDT confidence distribution, use cases 9. Structure Comparison: resolution, completeness, ligands across structures 10. Download Links: PDB/mmCIF/AlphaFold formats, database URLs

---

Quality Assessment

Experimental Structures

Resolution Use Cases

<1.5A: atomic detail, H-bond analysis. 1.5-2.0A: drug design. 2.0-2.5A: structure-based design. 2.5-3.5A: overall architecture. >3.5A: domain arrangement only.

AlphaFold Confidence (pLDDT)

>90: very high, experimental-like. 70-90: good backbone. 50-70: uncertain/flexible. <50: likely disordered.

---

Error Handling

---

Tool Reference

RCSB PDB: PDBeSearch_search_structures (search), get_protein_metadata_by_pdb_id (basic info), RCSBData_get_entry (details), PDBeValidation_get_quality_scores (quality), PDBe_KB_get_ligand_sites (ligands), PDBeSIFTS_get_all_structures (homologs)

PDBe: pdbe_get_entry_summary (overview), pdbe_get_entry_molecules (entities), pdbe_get_entry_experiment (experimental), PDBe_KB_get_ligand_sites (pockets)

AlphaFold: alphafold_get_prediction (get prediction), alphafold_get_summary (search)

Protein Structure Retrieval Checklist

Use this checklist to ensure complete structure profiles.

Protein Disambiguation

• [ ] Protein name/gene identified
• [ ] Organism confirmed
• [ ] UniProt accession (if available)
• [ ] Naming collisions handled (kinase, receptor, etc.)

Per Structure (Required)

• [ ] PDB ID
• [ ] Title
• [ ] Organism
• [ ] Experimental method
• [ ] Resolution (or N/A for NMR)
• [ ] Release date
• [ ] Quality assessment

Quality Assessment

• [ ] Resolution evaluated against tiers
• [ ] R-factor/R-free noted (if X-ray)
• [ ] Completeness assessed
• [ ] Method appropriateness considered

Structure Composition

• [ ] Chain count and identities
• [ ] Residue count and coverage
• [ ] Ligands listed (or "None bound")
• [ ] Metals/cofactors noted
• [ ] Waters (if relevant)

Binding Site Information

• [ ] Binding sites identified (or "None")
• [ ] Key residues listed
• [ ] Druggability assessed (for drug targets)

AlphaFold Coverage

• [ ] AlphaFold checked if no experimental structure
• [ ] Confidence scores reported
• [ ] Appropriate use cases noted

Download Links

• [ ] PDB format link
• [ ] mmCIF format link
• [ ] AlphaFold link (if applicable)
• [ ] Database web links

Report Quality

• [ ] Search process NOT shown in output
• [ ] Quality tiers (●●●●/●●●○/●●○○/●○○○/○○○○) applied
• [ ] Comparison table for multiple structures
• [ ] Retrieval date included

Error Handling

• [ ] PDB not found → format verified, obsolete status checked
• [ ] No structures → AlphaFold offered
• [ ] Download failed → alternative link provided

Protein Structure Retrieval Examples

Example 1: Find Insulin Structure

from tooluniverse import ToolUniverse
tu = ToolUniverse()
tu.load_tools()

# Search for insulin structures
result = tu.tools.search_structures_by_protein_name(
    protein_name="insulin"
)

print(f"Found {len(result['data'])} insulin structures")

# Get first high-resolution structure
for entry in result["data"]:
    if entry.get("resolution") and entry["resolution"] < 2.0:
        pdb_id = entry["pdb_id"]
        print(f"High-res structure: {pdb_id} ({entry['resolution']} Å)")
        break

Example 2: Get Complete Structure Information

pdb_id = "4INS"  # Human insulin

# Get basic metadata
metadata = tu.tools.get_protein_metadata_by_pdb_id(pdb_id=pdb_id)

print(f"Title: {metadata['data']['title']}")
print(f"Method: {metadata['data']['experimental_method']}")
print(f"Resolution: {metadata['data']['resolution']} Å")

# Get experimental details
exp = tu.tools.get_protein_experimental_details_by_pdb_id(
    pdb_id=pdb_id
)

# Get bound ligands
ligands = tu.tools.get_protein_ligands_by_pdb_id(pdb_id=pdb_id)

print(f"Ligands: {len(ligands['data'])}")
for lig in ligands["data"]:
    print(f"  - {lig['name']}")

Example 3: Download Structure File

pdb_id = "6LU7"  # SARS-CoV-2 main protease

# Download in PDB format
pdb_file = tu.tools.download_pdb_structure_file(
    pdb_id=pdb_id,
    format="pdb"
)

print(f"PDB file size: {len(pdb_file['data'])} characters")

# Also get as mmCIF (modern format)
cif_file = tu.tools.download_pdb_structure_file(
    pdb_id=pdb_id,
    format="cif"
)

# Save to file
with open(f"{pdb_id}.pdb", "w") as f:
    f.write(pdb_file["data"])

Example 4: Find Similar Structures

pdb_id = "1ABC"

# Find structurally similar proteins
similar = tu.tools.get_similar_structures_by_pdb_id(
    pdb_id=pdb_id,
    cutoff=2.0  # RMSD cutoff in Angstroms
)

print(f"Found {len(similar['data'])} similar structures")

for sim in similar["data"][:5]:
    print(f"{sim['pdb_id']}: RMSD {sim['rmsd']} Å")
    
    # Get metadata for each similar structure
    metadata = tu.tools.get_protein_metadata_by_pdb_id(
        pdb_id=sim["pdb_id"]
    )
    print(f"  {metadata['data']['title']}")

Example 5: Filter by Quality

# Search for hemoglobin
result = tu.tools.search_structures_by_protein_name(
    protein_name="hemoglobin"
)

# Filter by method and resolution
high_quality = []
for entry in result["data"]:
    if entry.get("method") == "X-ray":
        if entry.get("resolution") and entry["resolution"] < 1.5:
            high_quality.append(entry)

print(f"High-quality X-ray structures: {len(high_quality)}")

for entry in high_quality[:5]:
    print(f"{entry['pdb_id']}: {entry['resolution']} Å")

Example 6: Compare Experimental vs AlphaFold

# Get experimental structure
pdb_id = "6LU7"
exp_metadata = tu.tools.get_protein_metadata_by_pdb_id(
    pdb_id=pdb_id
)

print(f"Experimental: {pdb_id}")
print(f"  Method: {exp_metadata['data']['experimental_method']}")
print(f"  Resolution: {exp_metadata['data']['resolution']}")

# Get AlphaFold prediction
uniprot_id = "P0DTD1"  # Same protein
af_structure = tu.tools.alphafold_get_structure_by_uniprot(
    uniprot_id=uniprot_id
)

print(f"\nAlphaFold: {uniprot_id}")
print(f"  Confidence: {af_structure['data']['confidence_score']}")

Example 7: Analyze Binding Sites

pdb_id = "1ABC"

# Get ligands
ligands = tu.tools.get_protein_ligands_by_pdb_id(pdb_id=pdb_id)

# Get binding site information from PDBe
sites = tu.tools.pdbe_get_binding_sites(pdb_id=pdb_id)

print(f"Binding sites: {len(sites['data'])}")

for site in sites["data"]:
    print(f"Site {site['site_id']}:")
    print(f"  Residues: {site['residues']}")
    print(f"  Ligand: {site['ligand']}")

Example 8: Drug Discovery Target Analysis

# Search for kinase structures
result = tu.tools.search_structures_by_protein_name(
    protein_name="kinase"
)

# Filter for structures with inhibitors
kinases_with_drugs = []

for entry in result["data"][:20]:
    pdb_id = entry["pdb_id"]
    
    # Check for ligands
    ligands = tu.tools.get_protein_ligands_by_pdb_id(
        pdb_id=pdb_id
    )
    
    if ligands["data"]:
        # Get high-resolution structures
        if entry.get("resolution") and entry["resolution"] < 2.5:
            kinases_with_drugs.append({
                "pdb_id": pdb_id,
                "resolution": entry["resolution"],
                "ligands": len(ligands["data"])
            })

print(f"Found {len(kinases_with_drugs)} kinases with inhibitors")

for entry in kinases_with_drugs[:5]:
    print(f"{entry['pdb_id']}: {entry['resolution']} Å, "
          f"{entry['ligands']} ligands")

Example 9: Get Multiple Formats

pdb_id = "4INS"

# Get all available formats
pdb = tu.tools.download_pdb_structure_file(
    pdb_id=pdb_id,
    format="pdb"
)

cif = tu.tools.download_pdb_structure_file(
    pdb_id=pdb_id,
    format="cif"
)

xml = tu.tools.download_pdb_structure_file(
    pdb_id=pdb_id,
    format="xml"
)

print(f"PDB: {len(pdb['data'])} chars")
print(f"mmCIF: {len(cif['data'])} chars")
print(f"XML: {len(xml['data'])} chars")

Example 10: Structure-Based Drug Design Workflow

# 1. Find target protein structures
result = tu.tools.search_structures_by_protein_name(
    protein_name="EGFR kinase"
)

# 2. Filter for drug-bound, high-resolution
candidates = []
for entry in result["data"]:
    if entry.get("resolution") and entry["resolution"] < 2.0:
        ligands = tu.tools.get_protein_ligands_by_pdb_id(
            pdb_id=entry["pdb_id"]
        )
        if ligands["data"]:
            candidates.append(entry["pdb_id"])

# 3. Get structures for docking
for pdb_id in candidates[:3]:
    structure = tu.tools.download_pdb_structure_file(
        pdb_id=pdb_id,
        format="pdb"
    )
    
    # Get binding site details
    sites = tu.tools.pdbe_get_binding_sites(pdb_id=pdb_id)
    
    print(f"{pdb_id}: Ready for docking")
    print(f"  Binding sites: {len(sites['data'])}")