| name | map-media-ingredients |
| description | Use this skill to map MediaIngredientMech growth-media ingredient names to ontology terms (CHEBI for chemicals, FOODON for biologicals, ENVO for environmental) via exact → normalized → fuzzy → manual matching, with chemical normalization (hydrates, formulas, catalog codes) and synonym preservation. Use when curating unmapped ingredients, adding new ones, or validating existing mappings. |
| category | workflow |
| requires_database | false |
| requires_internet | true |
| version | 1.1.0 |
Media Ingredient Ontology Mapping
Overview
Map microbial growth-media ingredient names to authoritative ontology terms for semantic
integration and knowledge-graph construction. This ensures consistency across datasets,
enables semantic queries, and links to KG-Microbe / CHEBI / FOODON / ENVO. Scope: chemical
compounds (salts, organics), biological materials (extracts, peptones), and environmental
samples (soil, seawater).
When to Use This Skill
- Adding new ingredients to MediaIngredientMech, or curating unmapped ones from formulations
- Validating existing ontology mappings
- Integrating media data with the KG-Microbe knowledge graph
- Normalizing chemical names with hydrates, catalog codes, or incomplete formulas
- Deciding which ontology (CHEBI vs FOODON vs ENVO) to use
Ontology Selection Guide
| Ingredient Type | Primary Ontology | Examples | When to Use |
|---|
| Simple chemicals | CHEBI | NaCl, glucose, MgSO4•7H2O, K2HPO4 | Pure chemical compounds, salts, ions |
| Biological materials | FOODON | yeast extract, peptone, tryptone, beef extract | Biological/food-derived preparations |
| Environmental samples | ENVO | soil extract, seawater, sediment | Natural environmental materials |
| Complex mixtures | often unmappable | "Vitamin solution A", "Trace metals" | Too generic for a specific mapping |
Priority order: CHEBI → FOODON → ENVO. Try the most specific ontology first; fall back to
broader ones.
Chemical Normalization Rules
Many names need normalization before matching — chemical_normalizer.py handles these
patterns, and preserves the original form as a typed synonym:
- Hydrate stripping (synonym
HYDRATE_FORM): MgSO4•7H2O → MgSO4 → "magnesium sulfate"; CaCl2·2H2O → "calcium chloride".
- Incomplete-formula correction (synonym
INCOMPLETE_FORMULA): K2HPO → K2HPO4 → "dipotassium phosphate".
- Catalog-number removal (synonym
CATALOG_VARIANT): NaCl (Fisher S271-500) → NaCl.
- Abbreviation expansion:
dH2O → "distilled water"; NaOAc → "sodium acetate".
- Formula → common name: built-in
FORMULA_TO_NAME map (40+ entries, e.g. NaCl → "sodium chloride", MgSO4 → "magnesium sulfate").
Matching Strategies
Escalate from cheapest to most expensive; use the simplest that works. Full code (OAK,
OntologyClient, chemical_normalizer, OLS) is in
reference/matching-strategies.md.
- Level 1 — Exact match. Case-insensitive string match against ontology labels, via OAK
basic_search or OntologyClient.search(..., sources=["CHEBI"]).
- Level 2 — Normalized match. Apply
normalize_chemical_name / generate_search_variants,
then client.search_with_variants(...) (deduplicates, keeps best scores).
- Level 3 — Fuzzy match. OAK lexical search (
l~ prefix) or the EBI OLS web API for
synonyms/spelling variants. OAK is primary (fast, offline); OLS is secondary (cross-validation).
- Level 4 — Manual curation. For complex mixtures, generic/incomplete terms, ambiguous
names, or novel formulations — mark
NEEDS_EXPERT.
Workflows
A. Interactive single ingredient
python scripts/curate_unmapped.py
Normalizes the name, generates variants, searches CHEBI → FOODON → ENVO, presents scored
candidates with media-usage context; user accepts or marks NEEDS_EXPERT.
B. Batch curation (auto-curable simple chemicals)
python scripts/analyze_unmapped.py
python scripts/batch_curate_unmapped.py --category SIMPLE_CHEMICAL \
--auto-normalize --min-confidence 0.9 --dry-run
python scripts/batch_curate_unmapped.py --category SIMPLE_CHEMICAL \
--auto-normalize --min-confidence 0.9
Best for SIMPLE_CHEMICAL with clear normalization patterns and score ≥ 0.9. Auto-normalizes
with synonym preservation, multi-variant dedup, dry-run, and provenance tracking.
C. Claude Code-assisted curation (complex cases, zero API cost)
python scripts/prepare_for_claude_curation.py --category UNKNOWN --limit 20 --output notes/batch_001.md
python scripts/apply_claude_suggestions.py --suggestions notes/batch_001_suggestions.yaml --validate
Full reasoning/audit trail for ambiguous cases. See docs/CLAUDE_CODE_CURATION.md.
Quality Guidelines
| Quality Level | Meaning |
|---|
EXACT_MATCH | String matches the ontology label exactly |
SYNONYM_MATCH | Matches a known ontology synonym |
CLOSE_MATCH | Semantically equivalent, different phrasing |
MANUAL_CURATION | Expert judgment required |
LLM_ASSISTED | Claude Code / LLM suggested |
NEEDS_EXPERT | Requires domain-expert review |
All mappings record curator (automated/manual/LLM), timestamp, and reasoning.
Categorization System
scripts/analyze_unmapped.py assigns categories + mappability scores to prioritize effort:
| Category | Description | Mappability | Strategy |
|---|
SIMPLE_CHEMICAL | Salts, common organics | High (80–100) | Batch curation |
COMPLEX_MIXTURE | Vitamin/metal solutions | Low (10–30) | Often unmappable |
ENVIRONMENTAL | Soil, seawater | Medium (50–70) | Try ENVO |
INCOMPLETE | Generic terms | Low (20–40) | Manual review |
PLACEHOLDER | "See source" | Very low (0–10) | Leave unmapped |
UNKNOWN | Uncategorized | Medium (40–60) | Claude Code-assisted |
Best Practices
DO
- Normalize before searching; try multiple ontologies (CHEBI → FOODON → ENVO).
- Use the most specific term ("D-glucose" > "glucose" > "sugar").
- Record provenance and preserve original forms (hydrates, catalogs) as synonyms.
- Validate that the term exists and the definition matches; check KG-Microbe first to reuse existing entities.
DON'T
- Don't force mappings for complex mixtures, or use generic terms when a specific one exists.
- Don't skip normalization for chemicals, or ignore synonym preservation.
- Don't guess at low confidence — mark
NEEDS_EXPERT; and don't create duplicates.
Reference Files
| File | Contents |
|---|
reference/matching-strategies.md | Full code for all 4 matching levels — OAK basic_search, OntologyClient.search/search_with_variants, chemical_normalizer, OAK l~ fuzzy search, and the EBI OLS API wrapper |
reference/kg-microbe-integration.md | CultureMech import/export scripts, checking existing KG-Microbe ingredients, and how ingredients link to media/organisms |
reference/examples-and-troubleshooting.md | Five worked examples (hydrate, incomplete formula, biological extract, environmental, unmappable mixture) and troubleshooting (no/too-many/ambiguous matches, complex mixtures) |
reference/tools-and-api.md | Curation scripts, core utilities, docs, related skills, and the chemical_normalizer/OntologyClient/UnmappedCurator implementation API |
