Map Media Ingredients

Ontology Selection Guide

Ontology priority order: CHEBI → FOODON → ENVO

Try the most specific ontology first. If no match, try broader ontologies.

Chemical Normalization Rules

Many ingredient names require normalization before ontology matching. The chemical_normalizer.py utility handles common patterns:

1. Hydrate Notation Stripping

Pattern: Remove hydration notation (•, ·, .) and water count

• MgSO4•7H2O → MgSO4 → search as "magnesium sulfate"
• CaCl2·2H2O → CaCl2 → search as "calcium chloride"
• FeSO4.7H2O → FeSO4 → search as "ferrous sulfate"
• Na2HPO4 dihydrate → Na2HPO4 → search as "disodium phosphate"

Synonym preservation: Original hydrate form is saved as synonym with type HYDRATE_FORM

2. Incomplete Formula Correction

Pattern: Add missing atoms to common incomplete formulas

• K2HPO → K2HPO4 → "dipotassium phosphate"
• Na2HPO → Na2HPO4 → "disodium phosphate"
• NaHPO → NaH2PO4 → "sodium dihydrogen phosphate"

Synonym preservation: Incomplete form saved as INCOMPLETE_FORMULA synonym

3. Catalog Number Removal

Pattern: Strip supplier/catalog information

• NaCl (Fisher S271-500) → NaCl → "sodium chloride"
• Glucose (Sigma G7021) → Glucose → "glucose"
• Agar (BD 214010) → Agar → "agar"

Synonym preservation: Catalog variant saved as CATALOG_VARIANT synonym

4. Abbreviation Expansion

Pattern: Expand common abbreviations to full names

• dH2O → distilled water → "water"
• NaOAc → sodium acetate
• KOAc → potassium acetate

5. Formula to Common Name

Built-in mappings for common chemical formulas:

FORMULA_TO_NAME = {
    'NaCl': 'sodium chloride',
    'MgSO4': 'magnesium sulfate',
    'CaCl2': 'calcium chloride',
    'KCl': 'potassium chloride',
    'K2HPO4': 'dipotassium phosphate',
    # ... 40+ common chemicals
}

Matching Strategies

Level 1: Exact Match

Direct string match with ontology labels (case-insensitive).

Using OAK (Ontology Access Kit):

from oaklib import get_adapter

# Search CHEBI
adapter = get_adapter("sqlite:obo:chebi")
results = adapter.basic_search("sodium chloride")

for entity_id in results:
    label = adapter.label(entity_id)
    print(f"{entity_id}: {label}")
# Output: CHEBI:26710: sodium chloride

Using OntologyClient:

from mediaingredientmech.utils.ontology_client import OntologyClient

client = OntologyClient()
results = client.search("glucose", sources=["CHEBI"])

for candidate in results:
    print(f"{candidate.ontology_id}: {candidate.label} (score: {candidate.score})")

Level 2: Normalized Match

Apply chemical normalization, then search with all variants.

Using chemical_normalizer:

from mediaingredientmech.utils.chemical_normalizer import (
    normalize_chemical_name,
    generate_search_variants
)

# Normalize
result = normalize_chemical_name("MgSO4•7H2O")
print(f"Original: {result.original}")
print(f"Normalized: {result.normalized}")
print(f"Variants: {result.variants}")
# Variants: ['magnesium sulfate', 'MgSO4', 'magnesium sulphate']

# Search with all variants
client = OntologyClient()
matches = client.search_with_variants(result.variants, sources=["CHEBI"])

Multi-variant search (deduplicates results, keeps best scores):

# Generate comprehensive search variants
variants = generate_search_variants("MgSO4•7H2O")
# Returns: ['MgSO4•7H2O', 'MgSO4', 'magnesium sulfate', 'magnesium sulphate']

# Search with all variants, deduplicate results
results = client.search_with_variants(variants, sources=["CHEBI"], max_results=10)

Level 3: Fuzzy Match

Use fuzzy/lexical search for synonym matching and spelling variations.

Using OAK fuzzy search:

# Lexical search (prefix: l~)
uv run runoak -i sqlite:obo:chebi info "l~magnesium sulphate"

# Search with synonyms
uv run runoak -i sqlite:obo:chebi search "magnesium sulfate"

Using EBI OLS API (web-based, requires internet):

# Basic search
curl "https://www.ebi.ac.uk/ols4/api/search?q=magnesium%20sulfate&ontology=chebi"

# Python wrapper
import requests

def ols_search(query, ontology="chebi"):
    url = "https://www.ebi.ac.uk/ols4/api/search"
    params = {"q": query, "ontology": ontology}
    response = requests.get(url, params=params)
    return response.json()

results = ols_search("magnesium sulfate", "chebi")
for doc in results['response']['docs']:
    print(f"{doc['obo_id']}: {doc['label']}")

When to use OLS vs OAK:

• OAK (primary): Faster, works offline, integrated with curation scripts
• OLS (secondary): Cross-validation, broader coverage, web-based exploration

Level 4: Manual Curation

When automated matching fails, manual expert curation is required.

Use manual curation when:

• Complex mixtures ("Vitamin solution A", "Trace metal mix")
• Generic/incomplete terms ("See source", "Mineral salts")
• Ambiguous names requiring context
• Novel/proprietary formulations

KG-Microbe Integration

MediaIngredientMech integrates with CultureMech (primary integration point) for KG-Microbe knowledge graph construction.

Data Flow

CultureMech → MediaIngredientMech (curate) → Export back to CultureMech

Import from CultureMech

# Import ingredients from CultureMech
python scripts/import_from_culturemech.py \
  --culturemech-dir /path/to/CultureMech/data \
  --output data/ingredients

Export to CultureMech

# Export curated mappings back
python scripts/export_to_culturemech.py \
  --input data/ingredients/mapped \
  --output /path/to/CultureMech/data/ingredients

Check Existing Ingredients

Before creating new mappings, check if ingredient already exists in KG-Microbe:

# Search for existing ingredient entities
# Pattern: mediadive.ingredient:*
# Check media_dive_ingredients in CultureMech data

# If found, use existing ID instead of creating duplicate

Link to Media and Organisms

Ingredients in KG-Microbe are linked via:

• has_part: Medium → Ingredient relationships
• Growth requirements: Organism → Medium → Ingredients
• Frequency analysis: How often ingredient appears across media

Workflows

Workflow A: Interactive Single Ingredient

For one-off ingredient mapping with manual review:

# Interactive curation with GUI
python scripts/curate_unmapped.py

# Shows:
# - Original name and normalized variants
# - Top candidates from each ontology
# - Context (how many media use this ingredient)
# - Accept, skip, or mark for expert review

Process:

1. Tool normalizes the name
2. Generates search variants
3. Searches CHEBI, then FOODON, then ENVO
4. Presents top candidates with scores
5. User accepts mapping or marks NEEDS_EXPERT

Workflow B: Batch Curation

For auto-curable simple chemicals with high confidence:

# Analyze unmapped ingredients first
python scripts/analyze_unmapped.py

# Batch curate simple chemicals
python scripts/batch_curate_unmapped.py \
  --category SIMPLE_CHEMICAL \
  --auto-normalize \
  --min-confidence 0.9 \
  --dry-run

# Review dry-run results, then apply
python scripts/batch_curate_unmapped.py \
  --category SIMPLE_CHEMICAL \
  --auto-normalize \
  --min-confidence 0.9

Best for:

• SIMPLE_CHEMICAL category (salts, common organics)
• Ingredients with clear normalization patterns
• High-confidence matches (score ≥ 0.9)

Features:

• Auto-normalization with synonym preservation
• Multi-variant search with deduplication
• Dry-run mode for safety
• Automatic provenance tracking

Workflow C: Claude Code-Assisted Curation

For complex ingredients requiring LLM reasoning (zero-cost, no API):

Step 1: Prepare batch

# Prepare ingredients for Claude Code review
python scripts/prepare_for_claude_curation.py \
  --category UNKNOWN \
  --limit 20 \
  --output notes/batch_001.md

This creates a markdown file with:

• Ingredient names with context
• Category and normalization info
• Search variants
• Instructions for Claude Code

Step 2: Ask Claude Code

Open notes/batch_001.md and ask Claude Code:
"Please analyze these ingredients and suggest ontology mappings"

Claude Code will:

• Analyze each ingredient
• Apply normalization patterns
• Search relevant ontologies
• Provide structured suggestions with reasoning
• Output YAML with mappings

Step 3: Apply suggestions

# Apply Claude Code suggestions
python scripts/apply_claude_suggestions.py \
  --suggestions notes/batch_001_suggestions.yaml \
  --validate

# Validation checks:
# - Term exists in specified ontology
# - Confidence score is reasonable
# - Quality level is appropriate

Benefits:

• Zero-cost (uses Claude Code, no API tokens)
• Full reasoning and audit trail
• Handles ambiguous cases
• Batch processing efficiency

See: docs/CLAUDE_CODE_CURATION.md for detailed guide

Examples

Example 1: Simple Chemical with Hydrate

Input: MgSO4•7H2O

Process:

1. Normalize: Strip hydrate → MgSO4
2. Map formula to name: MgSO4 → magnesium sulfate
3. Generate variants: ['MgSO4', 'magnesium sulfate', 'magnesium sulphate']
4. Search CHEBI: Find CHEBI:32599 (magnesium sulfate)
5. Accept with quality EXACT_MATCH
6. Save original MgSO4•7H2O as synonym type HYDRATE_FORM

Result:

ontology_id: CHEBI:32599
ontology_label: magnesium sulfate
ontology_source: CHEBI