ChEBI (Chemical Entities of Biological Interest) Tutorial¶

ChEBI is a freely available dictionary of molecular entities focused on 'small' chemical compounds. This tutorial demonstrates how to use the ChEBI class and convenience functions from the provesid package to access chemical information from the ChEBI database.

Important Note: The ChEBI search API is currently experiencing intermittent issues. This tutorial shows both the intended search functionality and alternative approaches using direct ChEBI ID lookups when search is unavailable.

ChEBI provides comprehensive chemical information including:

• Chemical structures (SMILES, InChI, MOL)
• Ontological relationships
• Biological roles and activities
• Cross-references to other databases
• Detailed chemical properties

The database is maintained by the European Bioinformatics Institute (EBI) and contains over 185,000 chemical entities.

In [28]:

from provesid import ChEBI, ChEBIError, get_chebi_entity, search_chebi

chebi = ChEBI()
print("ChEBI initialized successfully!")
print(f"Base URL: {chebi.base_url}")
print(f"Timeout: {chebi.timeout} seconds")

from provesid import ChEBI, ChEBIError, get_chebi_entity, search_chebi chebi = ChEBI() print("ChEBI initialized successfully!") print(f"Base URL: {chebi.base_url}") print(f"Timeout: {chebi.timeout} seconds")

ChEBI initialized successfully!
Base URL: https://www.ebi.ac.uk/webservices/chebi/2.0/test
Timeout: 30 seconds

1. Getting Complete Entity Information¶

The primary method for retrieving detailed chemical information is get_complete_entity(). Let's look up some common compounds:

In [29]:

# Get complete information for water (ChEBI:15377)
water = chebi.get_complete_entity(15377)
if water:
    print("Water (CHEBI:15377):")
    print(f"  ASCII Name: {water.get('chebiAsciiName')}")
    print(f"  IUPAC Name: {water.get('iupacName')}")
    print(f"  Definition: {water.get('definition')}")
    # Access chemical formula from the Formulae dict
    formulae_data = water.get('Formulae', {})
    formula = formulae_data.get('data', 'N/A') if formulae_data else 'N/A'
    print(f"  Molecular Formula: {formula}")
    print(f"  SMILES: {water.get('smiles')}")
    print(f"  InChI: {water.get('inchi')}")
    print(f"  InChI Key: {water.get('inchiKey')}")
    print(f"  Mass: {water.get('mass')}")
    print(f"  Charge: {water.get('charge')}")
else:
    print("Water information not found")

# Get complete information for water (ChEBI:15377) water = chebi.get_complete_entity(15377) if water: print("Water (CHEBI:15377):") print(f" ASCII Name: {water.get('chebiAsciiName')}") print(f" IUPAC Name: {water.get('iupacName')}") print(f" Definition: {water.get('definition')}") # Access chemical formula from the Formulae dict formulae_data = water.get('Formulae', {}) formula = formulae_data.get('data', 'N/A') if formulae_data else 'N/A' print(f" Molecular Formula: {formula}") print(f" SMILES: {water.get('smiles')}") print(f" InChI: {water.get('inchi')}") print(f" InChI Key: {water.get('inchiKey')}") print(f" Mass: {water.get('mass')}") print(f" Charge: {water.get('charge')}") else: print("Water information not found")

Water (CHEBI:15377):
  ASCII Name: water
  IUPAC Name: None
  Definition: An oxygen hydride consisting of an oxygen atom that is covalently bonded to two hydrogen atoms
  Molecular Formula: H2O
  SMILES: [H]O[H]
  InChI: InChI=1S/H2O/h1H2
  InChI Key: XLYOFNOQVPJJNP-UHFFFAOYSA-N
  Mass: 18.01530
  Charge: 0

In [30]:

# Get information for aspirin (ChEBI:15365)
aspirin = chebi.get_complete_entity(15365)
if aspirin:
    print("Aspirin (CHEBI:15365):")
    print(f"  ASCII Name: {aspirin.get('chebiAsciiName')}")
    print(f"  Definition: {aspirin.get('definition')}")
    print(f"  SMILES: {aspirin.get('smiles')}")
    print(f"  InChI Key: {aspirin.get('inchiKey')}")
    print(f"  Mass: {aspirin.get('mass')}")
    
    # Show synonyms if available
    synonyms = aspirin.get('Synonyms', [])
    if synonyms:
        print(f"  Number of synonyms: {len(synonyms)}")
        print(f"  First 3 synonyms: {[syn.get('data') for syn in synonyms[:3]]}")
else:
    print("Aspirin information not found")

# Get information for aspirin (ChEBI:15365) aspirin = chebi.get_complete_entity(15365) if aspirin: print("Aspirin (CHEBI:15365):") print(f" ASCII Name: {aspirin.get('chebiAsciiName')}") print(f" Definition: {aspirin.get('definition')}") print(f" SMILES: {aspirin.get('smiles')}") print(f" InChI Key: {aspirin.get('inchiKey')}") print(f" Mass: {aspirin.get('mass')}") # Show synonyms if available synonyms = aspirin.get('Synonyms', []) if synonyms: print(f" Number of synonyms: {len(synonyms)}") print(f" First 3 synonyms: {[syn.get('data') for syn in synonyms[:3]]}") else: print("Aspirin information not found")

Aspirin (CHEBI:15365):
  ASCII Name: acetylsalicylic acid
  Definition: A member of the class of benzoic acids that is salicylic acid in which the hydrogen that is attached to the phenolic hydroxy group has been replaced by an acetoxy group. A non-steroidal anti-inflammatory drug with cyclooxygenase inhibitor activity.
  SMILES: CC(=O)Oc1ccccc1C(O)=O
  InChI Key: BSYNRYMUTXBXSQ-UHFFFAOYSA-N
  Mass: 180.15740
  Number of synonyms: 18
  First 3 synonyms: ['2-(ACETYLOXY)BENZOIC ACID', '2-Acetoxybenzenecarboxylic acid', '2-acetoxybenzoic acid']

2. Using Convenience Functions¶

The package provides convenient functions for quick lookups without creating a ChEBI instance:

In [31]:

# Using the convenience function get_chebi_entity
caffeine = get_chebi_entity(27732)  # Caffeine
if caffeine:
    print("Caffeine (using convenience function):")
    print(f"  Name: {caffeine.get('chebiAsciiName')}")
    print(f"  Definition: {caffeine.get('definition')}")
    print(f"  SMILES: {caffeine.get('smiles')}")
    # Access chemical formula correctly
    formulae_data = caffeine.get('Formulae', {})
    formula = formulae_data.get('data', 'N/A') if formulae_data else 'N/A'
    print(f"  Molecular formula: {formula}")
else:
    print("Caffeine not found")

# Using the convenience function get_chebi_entity caffeine = get_chebi_entity(27732) # Caffeine if caffeine: print("Caffeine (using convenience function):") print(f" Name: {caffeine.get('chebiAsciiName')}") print(f" Definition: {caffeine.get('definition')}") print(f" SMILES: {caffeine.get('smiles')}") # Access chemical formula correctly formulae_data = caffeine.get('Formulae', {}) formula = formulae_data.get('data', 'N/A') if formulae_data else 'N/A' print(f" Molecular formula: {formula}") else: print("Caffeine not found")

Caffeine (using convenience function):
  Name: caffeine
  Definition: A trimethylxanthine in which the three methyl groups are located at positions 1, 3, and 7. A purine alkaloid that occurs naturally in tea and coffee.
  SMILES: Cn1cnc2n(C)c(=O)n(C)c(=O)c12
  Molecular formula: C8H10N4O2

Important: Accessing Chemical Formula Data¶

ChEBI returns chemical formula data in a specific structure. The formula is stored in the Formulae key (with capital F) as a dictionary with data and source fields. Here's the correct way to access it:

In [32]:

# Demonstrate the correct way to access chemical formula data
aspirin = get_chebi_entity(15365)  # Aspirin
if aspirin:
    print("Correct way to access chemical formula:")
    print(f"  Compound: {aspirin.get('chebiAsciiName')}")
    
    # Method 1: Safe access with get()
    formulae_data = aspirin.get('Formulae', {})
    if formulae_data:
        formula = formulae_data.get('data', 'N/A')
        source = formulae_data.get('source', 'N/A')
        print(f"  Formula: {formula} (source: {source})")
    else:
        print("  Formula: Not available")
    
    # Method 2: One-liner (also safe)
    formula_oneliner = aspirin.get('Formulae', {}).get('data', 'N/A')
    print(f"  Formula (one-liner): {formula_oneliner}")
    
    print()
    print("❌ WRONG way (this would cause errors):")
    print("  # aspirin['formulae'][0]['data']  # Wrong - lowercase 'formulae' doesn't exist")
    print("  # aspirin['Formulae']['data']     # Wrong - no error checking")
    
    print()
    print("✅ CORRECT way:")
    print("  formulae_data = aspirin.get('Formulae', {})")
    print("  formula = formulae_data.get('data', 'N/A') if formulae_data else 'N/A'")

# Demonstrate the correct way to access chemical formula data aspirin = get_chebi_entity(15365) # Aspirin if aspirin: print("Correct way to access chemical formula:") print(f" Compound: {aspirin.get('chebiAsciiName')}") # Method 1: Safe access with get() formulae_data = aspirin.get('Formulae', {}) if formulae_data: formula = formulae_data.get('data', 'N/A') source = formulae_data.get('source', 'N/A') print(f" Formula: {formula} (source: {source})") else: print(" Formula: Not available") # Method 2: One-liner (also safe) formula_oneliner = aspirin.get('Formulae', {}).get('data', 'N/A') print(f" Formula (one-liner): {formula_oneliner}") print() print("❌ WRONG way (this would cause errors):") print(" # aspirin['formulae'][0]['data'] # Wrong - lowercase 'formulae' doesn't exist") print(" # aspirin['Formulae']['data'] # Wrong - no error checking") print() print("✅ CORRECT way:") print(" formulae_data = aspirin.get('Formulae', {})") print(" formula = formulae_data.get('data', 'N/A') if formulae_data else 'N/A'")

Correct way to access chemical formula:
  Compound: acetylsalicylic acid
  Formula: C9H8O4 (source: KEGG COMPOUND)
  Formula (one-liner): C9H8O4

❌ WRONG way (this would cause errors):
  # aspirin['formulae'][0]['data']  # Wrong - lowercase 'formulae' doesn't exist
  # aspirin['Formulae']['data']     # Wrong - no error checking

✅ CORRECT way:
  formulae_data = aspirin.get('Formulae', {})
  formula = formulae_data.get('data', 'N/A') if formulae_data else 'N/A'

In [33]:

# Using the search convenience function - Note: ChEBI search API may have intermittent issues
print("Searching for 'glucose':")
print("(Note: ChEBI search API is currently experiencing issues)")
glucose_results = search_chebi("glucose", max_results=5)
if glucose_results:
    for i, result in enumerate(glucose_results[:3], 1):
        print(f"  {i}. {result.get('chebiId')}: {result.get('chebiAsciiName')} - {result.get('definition', 'No definition')[:100]}...")
else:
    print("  Search returned no results (API may be temporarily unavailable)")
    print("  Alternative: Use get_chebi_entity() with known ChEBI IDs")
    print("  For example, glucose is ChEBI:17234")
    
    # Show alternative approach
    glucose = get_chebi_entity(17234)  # D-glucose
    if glucose:
        print(f"  Direct lookup - ChEBI:17234: {glucose.get('chebiAsciiName')}")

# Using the search convenience function - Note: ChEBI search API may have intermittent issues print("Searching for 'glucose':") print("(Note: ChEBI search API is currently experiencing issues)") glucose_results = search_chebi("glucose", max_results=5) if glucose_results: for i, result in enumerate(glucose_results[:3], 1): print(f" {i}. {result.get('chebiId')}: {result.get('chebiAsciiName')} - {result.get('definition', 'No definition')[:100]}...") else: print(" Search returned no results (API may be temporarily unavailable)") print(" Alternative: Use get_chebi_entity() with known ChEBI IDs") print(" For example, glucose is ChEBI:17234") # Show alternative approach glucose = get_chebi_entity(17234) # D-glucose if glucose: print(f" Direct lookup - ChEBI:17234: {glucose.get('chebiAsciiName')}")

Searching for 'glucose':
(Note: ChEBI search API is currently experiencing issues)
  Search returned no results (API may be temporarily unavailable)
  Alternative: Use get_chebi_entity() with known ChEBI IDs
  For example, glucose is ChEBI:17234
  Search returned no results (API may be temporarily unavailable)
  Alternative: Use get_chebi_entity() with known ChEBI IDs
  For example, glucose is ChEBI:17234
  Direct lookup - ChEBI:17234: glucose
  Direct lookup - ChEBI:17234: glucose

3. Searching by Name¶

ChEBI provides powerful search capabilities to find compounds by name, synonym, or definition:

In [34]:

# Search for compounds containing "ethanol" - Note: API may have issues
ethanol_results = chebi.search_by_name("ethanol", max_results=10)
print(f"Found {len(ethanol_results)} results for 'ethanol':")

if ethanol_results:
    for i, result in enumerate(ethanol_results[:5], 1):
        print(f"  {i}. {result.get('chebiId')}: {result.get('chebiAsciiName')}")
        print(f"     Definition: {result.get('definition', 'No definition')[:80]}...")
        print()
else:
    print("  Search API temporarily unavailable. Using direct lookup instead:")
    # Alternative: direct lookup for ethanol (ChEBI:16236)
    ethanol = get_chebi_entity(16236)
    if ethanol:
        print(f"  Direct lookup - ChEBI:16236: {ethanol.get('chebiAsciiName')}")
        print(f"     Definition: {ethanol.get('definition', 'No definition')[:80]}...")

# Search for compounds containing "ethanol" - Note: API may have issues ethanol_results = chebi.search_by_name("ethanol", max_results=10) print(f"Found {len(ethanol_results)} results for 'ethanol':") if ethanol_results: for i, result in enumerate(ethanol_results[:5], 1): print(f" {i}. {result.get('chebiId')}: {result.get('chebiAsciiName')}") print(f" Definition: {result.get('definition', 'No definition')[:80]}...") print() else: print(" Search API temporarily unavailable. Using direct lookup instead:") # Alternative: direct lookup for ethanol (ChEBI:16236) ethanol = get_chebi_entity(16236) if ethanol: print(f" Direct lookup - ChEBI:16236: {ethanol.get('chebiAsciiName')}") print(f" Definition: {ethanol.get('definition', 'No definition')[:80]}...")

Found 0 results for 'ethanol':
  Search API temporarily unavailable. Using direct lookup instead:
  Direct lookup - ChEBI:16236: ethanol
     Definition: A primary alcohol that is ethane in which one of the hydrogens is substituted by...
  Direct lookup - ChEBI:16236: ethanol
     Definition: A primary alcohol that is ethane in which one of the hydrogens is substituted by...

In [35]:

# Search for vitamin compounds - Note: API may have issues
vitamin_results = chebi.search_by_name("vitamin", max_results=8)
print(f"Found {len(vitamin_results)} results for 'vitamin':")

if vitamin_results:
    for result in vitamin_results[:5]:
        print(f"  • {result.get('chebiId')}: {result.get('chebiAsciiName')}")
else:
    print("  Search API temporarily unavailable. Using known vitamin ChEBI IDs:")
    vitamin_ids = [29073, 18405, 17015]  # Vitamin C, Vitamin E, Vitamin D
    for vid in vitamin_ids:
        vitamin = get_chebi_entity(vid)
        if vitamin:
            print(f"  • CHEBI:{vid}: {vitamin.get('chebiAsciiName')}")

# Search for vitamin compounds - Note: API may have issues vitamin_results = chebi.search_by_name("vitamin", max_results=8) print(f"Found {len(vitamin_results)} results for 'vitamin':") if vitamin_results: for result in vitamin_results[:5]: print(f" • {result.get('chebiId')}: {result.get('chebiAsciiName')}") else: print(" Search API temporarily unavailable. Using known vitamin ChEBI IDs:") vitamin_ids = [29073, 18405, 17015] # Vitamin C, Vitamin E, Vitamin D for vid in vitamin_ids: vitamin = get_chebi_entity(vid) if vitamin: print(f" • CHEBI:{vid}: {vitamin.get('chebiAsciiName')}")

Found 0 results for 'vitamin':
  Search API temporarily unavailable. Using known vitamin ChEBI IDs:
  • CHEBI:29073: L-ascorbic acid
  • CHEBI:29073: L-ascorbic acid
  • CHEBI:18405: pyridoxal 5'-phosphate
  • CHEBI:18405: pyridoxal 5'-phosphate
  • CHEBI:17015: riboflavin
  • CHEBI:17015: riboflavin

4. Getting Chemical Structures¶

ChEBI can provide chemical structures in various formats:

In [36]:

# Get different structure formats for ethanol (ChEBI:16236)
ethanol_id = 16236

print("Ethanol structure in different formats:")

# Get SMILES
smiles = chebi.get_structure(ethanol_id, "smiles")
print(f"  SMILES: {smiles}")

# Get InChI
inchi = chebi.get_structure(ethanol_id, "inchi")
print(f"  InChI: {inchi}")

# Get MOL format (first few lines)
mol_structure = chebi.get_structure(ethanol_id, "mol")
if mol_structure:
    mol_lines = mol_structure.split('\n')[:5]
    print(f"  MOL format (first 5 lines):")
    for line in mol_lines:
        print(f"    {line}")

# Get different structure formats for ethanol (ChEBI:16236) ethanol_id = 16236 print("Ethanol structure in different formats:") # Get SMILES smiles = chebi.get_structure(ethanol_id, "smiles") print(f" SMILES: {smiles}") # Get InChI inchi = chebi.get_structure(ethanol_id, "inchi") print(f" InChI: {inchi}") # Get MOL format (first few lines) mol_structure = chebi.get_structure(ethanol_id, "mol") if mol_structure: mol_lines = mol_structure.split('\n')[:5] print(f" MOL format (first 5 lines):") for line in mol_lines: print(f" {line}")

Ethanol structure in different formats:
  SMILES: None
  InChI: None

5. Ontological Relationships¶

ChEBI organizes compounds in an ontological hierarchy. You can explore parent-child relationships:

In [37]:

# Get ontology parents for ethanol
ethanol_parents = chebi.get_ontology_parents(16236)
print("Ethanol ontology parents:")
for parent in ethanol_parents[:5]:
    print(f"  • {parent.get('chebiId')}: {parent.get('chebiName')} ({parent.get('type')})")

# Get ontology parents for ethanol ethanol_parents = chebi.get_ontology_parents(16236) print("Ethanol ontology parents:") for parent in ethanol_parents[:5]: print(f" • {parent.get('chebiId')}: {parent.get('chebiName')} ({parent.get('type')})")

Ethanol ontology parents:
  • None: None (None)

In [38]:

# Get ontology children for alcohols (ChEBI:30879)
alcohol_children = chebi.get_ontology_children(30879)
print(f"Found {len(alcohol_children)} children for 'alcohol' (first 5):")
for child in alcohol_children[:5]:
    print(f"  • {child.get('chebiId')}: {child.get('chebiName')} ({child.get('type')})")

# Get ontology children for alcohols (ChEBI:30879) alcohol_children = chebi.get_ontology_children(30879) print(f"Found {len(alcohol_children)} children for 'alcohol' (first 5):") for child in alcohol_children[:5]: print(f" • {child.get('chebiId')}: {child.get('chebiName')} ({child.get('type')})")

Found 1 children for 'alcohol' (first 5):
  • None: None (None)

6. Batch Processing¶

For multiple compounds, use batch processing with built-in rate limiting:

In [39]:

# Process multiple ChEBI IDs at once
compound_ids = [15377, 16236, 15365, 27732, 17234]  # water, ethanol, aspirin, caffeine, glucose
compound_names = ["water", "ethanol", "aspirin", "caffeine", "glucose"]

print("Batch processing multiple compounds:")
batch_results = chebi.batch_get_entities(compound_ids, pause_time=0.2)

for i, (chebi_id, name) in enumerate(zip([f"CHEBI:{id}" for id in compound_ids], compound_names)):
    if chebi_id in batch_results:
        compound = batch_results[chebi_id]
        print(f"  {i+1}. {name} ({chebi_id}):")
        print(f"     Name: {compound.get('chebiAsciiName')}")
        # Access formula correctly from Formulae dict
        formulae_data = compound.get('Formulae', {})
        formula = formulae_data.get('data', 'N/A') if formulae_data else 'N/A'
        print(f"     Formula: {formula}")
        print(f"     Mass: {compound.get('mass')}")
    else:
        print(f"  {i+1}. {name} ({chebi_id}): Not found")
    print()

# Process multiple ChEBI IDs at once compound_ids = [15377, 16236, 15365, 27732, 17234] # water, ethanol, aspirin, caffeine, glucose compound_names = ["water", "ethanol", "aspirin", "caffeine", "glucose"] print("Batch processing multiple compounds:") batch_results = chebi.batch_get_entities(compound_ids, pause_time=0.2) for i, (chebi_id, name) in enumerate(zip([f"CHEBI:{id}" for id in compound_ids], compound_names)): if chebi_id in batch_results: compound = batch_results[chebi_id] print(f" {i+1}. {name} ({chebi_id}):") print(f" Name: {compound.get('chebiAsciiName')}") # Access formula correctly from Formulae dict formulae_data = compound.get('Formulae', {}) formula = formulae_data.get('data', 'N/A') if formulae_data else 'N/A' print(f" Formula: {formula}") print(f" Mass: {compound.get('mass')}") else: print(f" {i+1}. {name} ({chebi_id}): Not found") print()

Batch processing multiple compounds:
  1. water (CHEBI:15377):
     Name: water
     Formula: H2O
     Mass: 18.01530

  2. ethanol (CHEBI:16236):
     Name: ethanol
     Formula: C2H6O
     Mass: 46.06844

  3. aspirin (CHEBI:15365):
     Name: acetylsalicylic acid
     Formula: C9H8O4
     Mass: 180.15740

  4. caffeine (CHEBI:27732):
     Name: caffeine
     Formula: C8H10N4O2
     Mass: 194.19076

  5. glucose (CHEBI:17234):
     Name: glucose
     Formula: C6H12O6
     Mass: 180.15588

  1. water (CHEBI:15377):
     Name: water
     Formula: H2O
     Mass: 18.01530

  2. ethanol (CHEBI:16236):
     Name: ethanol
     Formula: C2H6O
     Mass: 46.06844

  3. aspirin (CHEBI:15365):
     Name: acetylsalicylic acid
     Formula: C9H8O4
     Mass: 180.15740

  4. caffeine (CHEBI:27732):
     Name: caffeine
     Formula: C8H10N4O2
     Mass: 194.19076

  5. glucose (CHEBI:17234):
     Name: glucose
     Formula: C6H12O6
     Mass: 180.15588

7. Error Handling¶

ChEBI provides robust error handling for various scenarios:

In [40]:

# Try to get information for invalid ChEBI IDs
print("Testing error handling:")

# Invalid ChEBI ID
invalid_result = chebi.get_complete_entity(999999999)
print(f"Invalid ID (999999999): {invalid_result}")

# Non-existent compound search
empty_search = chebi.search_by_name("thiscompounddoesnotexist12345")
print(f"Empty search results: {len(empty_search)} results")

# Handle ChEBIError exceptions
try:
    # This might cause a timeout or network error
    chebi_timeout = ChEBI(timeout=0.001)  # Very short timeout
    result = chebi_timeout.get_complete_entity(15377)
except ChEBIError as e:
    print(f"ChEBIError caught: {e}")
except Exception as e:
    print(f"Other error: {e}")

# Try to get information for invalid ChEBI IDs print("Testing error handling:") # Invalid ChEBI ID invalid_result = chebi.get_complete_entity(999999999) print(f"Invalid ID (999999999): {invalid_result}") # Non-existent compound search empty_search = chebi.search_by_name("thiscompounddoesnotexist12345") print(f"Empty search results: {len(empty_search)} results") # Handle ChEBIError exceptions try: # This might cause a timeout or network error chebi_timeout = ChEBI(timeout=0.001) # Very short timeout result = chebi_timeout.get_complete_entity(15377) except ChEBIError as e: print(f"ChEBIError caught: {e}") except Exception as e: print(f"Other error: {e}")

ChEBI API returned error: 
Failed to get complete entity for CHEBI:15377: Request timeout after 0.001 seconds
Failed to get complete entity for CHEBI:15377: Request timeout after 0.001 seconds

Testing error handling:
Invalid ID (999999999): None
Empty search results: 0 results

8. Exploring Compound Details¶

Let's explore the comprehensive information available for a complex biological molecule:

In [41]:

# Remove the problematic line that tries to access vitamin_c["Formulae"]["data"] directly

# This was causing an error since we should use .get() for safe accessvitamin_c = chebi.get_complete_entity(29073)

if vitamin_c:
    print("Vitamin C (CHEBI:29073) - Detailed Information:")
    print(f"  ASCII Name: {vitamin_c.get('chebiAsciiName')}")
    print(f"  IUPAC Name: {vitamin_c.get('iupacName')}")
    print(f"  Definition: {vitamin_c.get('definition')}")
    print(f"  SMILES: {vitamin_c.get('smiles')}")
    print(f"  Mass: {vitamin_c.get('mass')}")
    print(f"  Charge: {vitamin_c.get('charge')}")
    
    # Explore formulas
    formulae = vitamin_c.get('Formulae', {})
    if formulae:
        print(f"  Chemical Formula:")
        print(f"    • {formulae.get('data')} (source: {formulae.get('source')})")
    
    # Explore synonyms
    synonyms = vitamin_c.get('Synonyms', [])
    if synonyms:
        print(f"  Synonyms ({len(synonyms)} total, showing first 5):")
        for syn in synonyms[:5]:
            print(f"    • {syn.get('data')} ({syn.get('source')})")
    
    # Explore database links
    db_links = vitamin_c.get('DatabaseLinks', [])
    if db_links:
        print(f"  Database Links ({len(db_links)} total, showing first 5):")
        for link in db_links[:5]:
            print(f"    • {link.get('type')}: {link.get('data')}")

# Remove the problematic line that tries to access vitamin_c["Formulae"]["data"] directly # This was causing an error since we should use .get() for safe accessvitamin_c = chebi.get_complete_entity(29073) if vitamin_c: print("Vitamin C (CHEBI:29073) - Detailed Information:") print(f" ASCII Name: {vitamin_c.get('chebiAsciiName')}") print(f" IUPAC Name: {vitamin_c.get('iupacName')}") print(f" Definition: {vitamin_c.get('definition')}") print(f" SMILES: {vitamin_c.get('smiles')}") print(f" Mass: {vitamin_c.get('mass')}") print(f" Charge: {vitamin_c.get('charge')}") # Explore formulas formulae = vitamin_c.get('Formulae', {}) if formulae: print(f" Chemical Formula:") print(f" • {formulae.get('data')} (source: {formulae.get('source')})") # Explore synonyms synonyms = vitamin_c.get('Synonyms', []) if synonyms: print(f" Synonyms ({len(synonyms)} total, showing first 5):") for syn in synonyms[:5]: print(f" • {syn.get('data')} ({syn.get('source')})") # Explore database links db_links = vitamin_c.get('DatabaseLinks', []) if db_links: print(f" Database Links ({len(db_links)} total, showing first 5):") for link in db_links[:5]: print(f" • {link.get('type')}: {link.get('data')}")

Vitamin C (CHEBI:29073) - Detailed Information:
  ASCII Name: L-ascorbic acid
  IUPAC Name: None
  Definition: The L-enantiomer of ascorbic acid and conjugate acid of L-ascorbate.
  SMILES: [H][C@@]1(OC(=O)C(O)=C1O)[C@@H](O)CO
  Mass: 176.12410
  Charge: 0
  Chemical Formula:
    • C6H8O6 (source: KEGG COMPOUND)
  Synonyms (17 total, showing first 5):
    • acide ascorbique (ChemIDplus)
    • acido ascorbico (ChemIDplus)
    • acidum ascorbicum (ChemIDplus)
    • acidum ascorbinicum (ChemIDplus)
    • Ascoltin (KEGG DRUG)
  Database Links (10 total, showing first 5):
    • BPDB accession: 2405
    • Drug Central accession: 4072
    • PDBeChem accession: ASC
    • MetaCyc accession: ASCORBATE
    • Wikipedia accession: Ascorbic_Acid

In [42]:

vitamin_c["Formulae"]["data"]

vitamin_c["Formulae"]["data"]

Out[42]:

'C6H8O6'

9. Practical Applications¶

Here are some practical use cases for the ChEBI API:

In [43]:

# Use case 1: Get basic chemical identifiers for a list of compounds
def get_chemical_identifiers(chebi_ids):
    """Get basic chemical identifiers for multiple compounds"""
    results = []
    for chebi_id in chebi_ids:
        compound = get_chebi_entity(chebi_id)
        if compound:
            results.append({
                'chebi_id': f"CHEBI:{chebi_id}",
                'name': compound.get('chebiAsciiName'),
                'smiles': compound.get('smiles'),
                'inchi_key': compound.get('inchiKey'),
                'mass': compound.get('mass'),
                # Access formula correctly from Formulae dict
                'formula': compound.get('Formulae', {}).get('data') if compound.get('Formulae') else None
            })
        else:
            results.append({
                'chebi_id': f"CHEBI:{chebi_id}",
                'error': 'Not found'
            })
    return results

# Test with common metabolites
metabolite_ids = [15377, 16236, 17234, 15422, 16526]  # water, ethanol, glucose, adenosine triphosphate, carbon dioxide
metabolite_data = get_chemical_identifiers(metabolite_ids)

print("Chemical identifiers for common metabolites:")
for data in metabolite_data:
    if 'error' not in data:
        print(f"  {data['chebi_id']}: {data['name']}")
        print(f"    Formula: {data['formula']}, Mass: {data['mass']}")
        print(f"    SMILES: {data['smiles']}")
    else:
        print(f"  {data['chebi_id']}: {data['error']}")
    print()

# Use case 1: Get basic chemical identifiers for a list of compounds def get_chemical_identifiers(chebi_ids): """Get basic chemical identifiers for multiple compounds""" results = [] for chebi_id in chebi_ids: compound = get_chebi_entity(chebi_id) if compound: results.append({ 'chebi_id': f"CHEBI:{chebi_id}", 'name': compound.get('chebiAsciiName'), 'smiles': compound.get('smiles'), 'inchi_key': compound.get('inchiKey'), 'mass': compound.get('mass'), # Access formula correctly from Formulae dict 'formula': compound.get('Formulae', {}).get('data') if compound.get('Formulae') else None }) else: results.append({ 'chebi_id': f"CHEBI:{chebi_id}", 'error': 'Not found' }) return results # Test with common metabolites metabolite_ids = [15377, 16236, 17234, 15422, 16526] # water, ethanol, glucose, adenosine triphosphate, carbon dioxide metabolite_data = get_chemical_identifiers(metabolite_ids) print("Chemical identifiers for common metabolites:") for data in metabolite_data: if 'error' not in data: print(f" {data['chebi_id']}: {data['name']}") print(f" Formula: {data['formula']}, Mass: {data['mass']}") print(f" SMILES: {data['smiles']}") else: print(f" {data['chebi_id']}: {data['error']}") print()

Chemical identifiers for common metabolites:
  CHEBI:15377: water
    Formula: H2O, Mass: 18.01530
    SMILES: [H]O[H]

  CHEBI:16236: ethanol
    Formula: C2H6O, Mass: 46.06844
    SMILES: CCO

  CHEBI:17234: glucose
    Formula: C6H12O6, Mass: 180.15588
    SMILES: None

  CHEBI:15422: ATP
    Formula: C10H16N5O13P3, Mass: 507.18100
    SMILES: Nc1ncnc2n(cnc12)[C@@H]1O[C@H](COP(O)(=O)OP(O)(=O)OP(O)(O)=O)[C@@H](O)[C@H]1O

  CHEBI:16526: carbon dioxide
    Formula: CO2, Mass: 44.010
    SMILES: O=C=O

In [44]:

# Use case 2: Find compounds by biological role
def find_compounds_by_role(search_term, max_results=10):
    """Find compounds related to a biological role or function"""
    # Note: Search API may have issues, so we'll show an alternative approach
    print(f"Note: ChEBI search API is currently having issues.")
    print(f"For demonstration, showing some known compounds related to '{search_term}':")
    
    # Example compounds for different search terms
    known_compounds = {
        'antioxidant': [29073, 16236, 27732],  # Vitamin C, ethanol, caffeine
        'vitamin': [29073, 18405, 17015],      # Vitamin C, E, D
        'hormone': [15365, 27732],             # Example compounds
    }
    
    compound_ids = known_compounds.get(search_term.lower(), [29073, 16236])  # Default examples
    compounds = []
    
    for compound_id in compound_ids[:max_results]:
        detailed = get_chebi_entity(compound_id)
        if detailed:
            compounds.append({
                'chebi_id': f"CHEBI:{compound_id}",
                'name': detailed.get('chebiAsciiName'),
                'definition': detailed.get('definition'),
                'smiles': detailed.get('smiles'),
                'mass': detailed.get('mass')
            })
    
    return compounds

# Search for antioxidants
antioxidants = find_compounds_by_role("antioxidant", max_results=5)
print("Compounds related to 'antioxidant':")
for compound in antioxidants[:3]:
    print(f"  • {compound['chebi_id']}: {compound['name']}")
    print(f"    Definition: {compound['definition'][:100]}...")
    print(f"    SMILES: {compound['smiles']}")
    print()

# Use case 2: Find compounds by biological role def find_compounds_by_role(search_term, max_results=10): """Find compounds related to a biological role or function""" # Note: Search API may have issues, so we'll show an alternative approach print(f"Note: ChEBI search API is currently having issues.") print(f"For demonstration, showing some known compounds related to '{search_term}':") # Example compounds for different search terms known_compounds = { 'antioxidant': [29073, 16236, 27732], # Vitamin C, ethanol, caffeine 'vitamin': [29073, 18405, 17015], # Vitamin C, E, D 'hormone': [15365, 27732], # Example compounds } compound_ids = known_compounds.get(search_term.lower(), [29073, 16236]) # Default examples compounds = [] for compound_id in compound_ids[:max_results]: detailed = get_chebi_entity(compound_id) if detailed: compounds.append({ 'chebi_id': f"CHEBI:{compound_id}", 'name': detailed.get('chebiAsciiName'), 'definition': detailed.get('definition'), 'smiles': detailed.get('smiles'), 'mass': detailed.get('mass') }) return compounds # Search for antioxidants antioxidants = find_compounds_by_role("antioxidant", max_results=5) print("Compounds related to 'antioxidant':") for compound in antioxidants[:3]: print(f" • {compound['chebi_id']}: {compound['name']}") print(f" Definition: {compound['definition'][:100]}...") print(f" SMILES: {compound['smiles']}") print()

Note: ChEBI search API is currently having issues.
For demonstration, showing some known compounds related to 'antioxidant':
Compounds related to 'antioxidant':
  • CHEBI:29073: L-ascorbic acid
    Definition: The L-enantiomer of ascorbic acid and conjugate acid of L-ascorbate....
    SMILES: [H][C@@]1(OC(=O)C(O)=C1O)[C@@H](O)CO

  • CHEBI:16236: ethanol
    Definition: A primary alcohol that is ethane in which one of the hydrogens is substituted by a hydroxy group....
    SMILES: CCO

  • CHEBI:27732: caffeine
    Definition: A trimethylxanthine in which the three methyl groups are located at positions 1, 3, and 7. A purine ...
    SMILES: Cn1cnc2n(C)c(=O)n(C)c(=O)c12

Compounds related to 'antioxidant':
  • CHEBI:29073: L-ascorbic acid
    Definition: The L-enantiomer of ascorbic acid and conjugate acid of L-ascorbate....
    SMILES: [H][C@@]1(OC(=O)C(O)=C1O)[C@@H](O)CO

  • CHEBI:16236: ethanol
    Definition: A primary alcohol that is ethane in which one of the hydrogens is substituted by a hydroxy group....
    SMILES: CCO

  • CHEBI:27732: caffeine
    Definition: A trimethylxanthine in which the three methyl groups are located at positions 1, 3, and 7. A purine ...
    SMILES: Cn1cnc2n(C)c(=O)n(C)c(=O)c12

In [45]:

# Use case 3: Build a compound database with cross-references
def build_compound_database(chebi_ids):
    """Build a comprehensive compound database with cross-references"""
    database = {}
    
    for chebi_id in chebi_ids:
        compound = get_chebi_entity(chebi_id)
        if compound:
            # Extract cross-references
            db_links = compound.get('DatabaseLinks', [])
            cross_refs = {}
            for link in db_links:
                db_type = link.get('type', 'Unknown')
                if db_type not in cross_refs:
                    cross_refs[db_type] = []
                cross_refs[db_type].append(link.get('data'))
            
            database[f"CHEBI:{chebi_id}"] = {
                'name': compound.get('chebiAsciiName'),
                'iupac_name': compound.get('iupacName'),
                'definition': compound.get('definition'),
                'smiles': compound.get('smiles'),
                'inchi_key': compound.get('inchiKey'),
                'mass': compound.get('mass'),
                'charge': compound.get('charge'),
                'cross_references': cross_refs
            }
    
    return database

# Build database for some pharmaceutical compounds
pharma_ids = [15365, 27732, 3002]  # aspirin, caffeine, morphine
pharma_db = build_compound_database(pharma_ids)

print("Pharmaceutical compound database:")
for chebi_id, data in pharma_db.items():
    print(f"\n{chebi_id}: {data['name']}")
    print(f"  IUPAC: {data['iupac_name']}")
    print(f"  Mass: {data['mass']}")
    print(f"  Cross-references:")
    for db_name, refs in data['cross_references'].items():
        if refs:  # Only show non-empty references
            print(f"    {db_name}: {refs[:2]}...")  # Show first 2 references

# Use case 3: Build a compound database with cross-references def build_compound_database(chebi_ids): """Build a comprehensive compound database with cross-references""" database = {} for chebi_id in chebi_ids: compound = get_chebi_entity(chebi_id) if compound: # Extract cross-references db_links = compound.get('DatabaseLinks', []) cross_refs = {} for link in db_links: db_type = link.get('type', 'Unknown') if db_type not in cross_refs: cross_refs[db_type] = [] cross_refs[db_type].append(link.get('data')) database[f"CHEBI:{chebi_id}"] = { 'name': compound.get('chebiAsciiName'), 'iupac_name': compound.get('iupacName'), 'definition': compound.get('definition'), 'smiles': compound.get('smiles'), 'inchi_key': compound.get('inchiKey'), 'mass': compound.get('mass'), 'charge': compound.get('charge'), 'cross_references': cross_refs } return database # Build database for some pharmaceutical compounds pharma_ids = [15365, 27732, 3002] # aspirin, caffeine, morphine pharma_db = build_compound_database(pharma_ids) print("Pharmaceutical compound database:") for chebi_id, data in pharma_db.items(): print(f"\n{chebi_id}: {data['name']}") print(f" IUPAC: {data['iupac_name']}") print(f" Mass: {data['mass']}") print(f" Cross-references:") for db_name, refs in data['cross_references'].items(): if refs: # Only show non-empty references print(f" {db_name}: {refs[:2]}...") # Show first 2 references

Pharmaceutical compound database:

CHEBI:15365: acetylsalicylic acid
  IUPAC: None
  Mass: 180.15740
  Cross-references:
    Drug Central accession: ['74']...
    PDBeChem accession: ['AIN']...
    Wikipedia accession: ['Aspirin']...
    KEGG COMPOUND accession: ['C01405']...
    MetaCyc accession: ['CPD-524']...
    KEGG DRUG accession: ['D00109']...
    DrugBank accession: ['DB00945']...
    HMDB accession: ['HMDB0001879']...
    LINCS accession: ['LSM-5288']...

CHEBI:27732: caffeine
  IUPAC: None
  Mass: 194.19076
  Cross-references:
    MetaCyc accession: ['1-3-7-TRIMETHYLXANTHINE']...
    Drug Central accession: ['463']...
    KNApSAcK accession: ['C00001492']...
    KEGG COMPOUND accession: ['C07481']...
    Wikipedia accession: ['Caffeine']...
    PDBeChem accession: ['CFF']...
    KEGG DRUG accession: ['D00528']...
    DrugBank accession: ['DB00201']...
    HMDB accession: ['HMDB0001847']...
    LINCS accession: ['LSM-2026']...

CHEBI:3002: beclomethasone dipropionate
  IUPAC: None
  Mass: 521.04188
  Cross-references:
    Drug Central accession: ['294']...
    Wikipedia accession: ['Beclometasone_dipropionate']...
    KEGG COMPOUND accession: ['C07813']...
    KEGG DRUG accession: ['D00689']...
    DrugBank accession: ['DB00394']...
    Patent accession: ['US3312590']...

Summary¶

The ChEBI class and convenience functions provide comprehensive access to the ChEBI database:

Main ChEBI Class Methods:¶

1. get_complete_entity(chebi_id): Get detailed information for a ChEBI ID
2. get_lite_entity(chebi_id): Get basic information only
3. search_by_name(search_text): Search compounds by name
4. get_structure(chebi_id, format): Get chemical structures (SMILES, InChI, MOL)
5. get_ontology_parents(chebi_id): Get parent entities in ontology
6. get_ontology_children(chebi_id): Get child entities in ontology
7. batch_get_entities(chebi_ids): Process multiple IDs efficiently

Convenience Functions:¶

• get_chebi_entity(chebi_id): Quick entity lookup
• search_chebi(search_text): Quick search functionality

Key Features:¶

• ✅ Comprehensive Data: Names, structures, properties, ontology, cross-references
• ✅ Multiple Formats: SMILES, InChI, MOL files for structures
• ✅ Ontological Browsing: Navigate parent-child relationships
• ✅ Batch Processing: Efficient handling of multiple compounds
• ✅ Error Handling: Robust error management with custom exceptions
• ✅ Rate Limiting: Built-in delays for respectful API usage
• ✅ Free Access: No API key required

Returned Data Includes:¶

• Chemical identifiers (name, IUPAC name, synonyms)
• Molecular structures (SMILES, InChI, InChI Key)
• Physical properties (mass, charge, molecular formula)
• Biological information (definition, role, function)
• Database cross-references (PubChem, UniProt, KEGG, etc.)
• Ontological relationships (parents, children, classifications)

Best Use Cases:¶

• Chemical database integration
• Biological pathway analysis
• Drug discovery research
• Metabolomics studies
• Chemical ontology exploration
• Cross-database linking

ChEBI is particularly valuable for researchers working with biological systems, as it focuses on chemical entities relevant to biological processes and provides rich ontological context for understanding chemical relationships.