Ontology API

fs.ontology is a FoodOnAPI — the lookup surface over the loaded FoodOn ontology, used by the linker, the Layer A projection, and Layer C prompts. See the ontology concept page for loading and caching behaviour.

.. py:class:: FoodOnAPI(terms, *, prefix_filter=(‘FOODON:’,))

module:

foodscholar.ontology.api

Bases: :py:class:object

O(1) lookup surface over OntologyTerm.

Indexes:

  • id → term

  • normalized label → id

  • normalized exact synonym → id (synonyms can resolve to multiple ids)

  • id → set(child ids) for descendants

obsolete terms are loaded but excluded from name lookups so the linker never resolves to a deprecated id.

prefix_filter (default ("FOODON:",)) drops every term whose id doesn’t start with one of the allowed prefixes. Real FoodOn .owl files ship with NCBITaxon, CHEBI, BFO, ENVO and other ontology terms inline; without the filter the linker happily matches “EVOO” → NCBITaxon:Brevoortia (a fish genus) and “iron” → CHEBI:iron(2+). Pass prefix_filter=None to disable filtering entirely (useful for unit fixtures with synthetic prefixes like TEST:); prefix_filter=() keeps no terms.

.. py:method:: FoodOnAPI.terms()

module:

foodscholar.ontology.api

.. py:method:: FoodOnAPI.get(term_id)

module:

foodscholar.ontology.api

.. py:method:: FoodOnAPI.name_to_id(name)

module:

foodscholar.ontology.api

Exact match against label or exact synonym.

Case-insensitive and punctuation/whitespace-insensitive — omega 3, omega-3, and omega_3 all resolve identically. Returns None if no match. If a name maps to multiple ids (rare but possible with synonyms), returns the first deterministically. Use name_to_ids if you need all matches.

.. py:method:: FoodOnAPI.name_to_ids(name)

module:

foodscholar.ontology.api

.. py:method:: FoodOnAPI.id_to_label(term_id)

module:

foodscholar.ontology.api

.. py:method:: FoodOnAPI.id_to_synonyms(term_id, *, include_related=False)

module:

foodscholar.ontology.api

.. py:method:: FoodOnAPI.id_to_ancestors(term_id)

module:

foodscholar.ontology.api

Closed transitive set of ancestors. Empty if the term doesn’t exist.

.. py:method:: FoodOnAPI.id_to_parents(term_id)

module:

foodscholar.ontology.api

Direct-parent ids only. Empty if the term doesn’t exist or is a root.

.. py:method:: FoodOnAPI.id_to_descendants(term_id)

module:

foodscholar.ontology.api

Closed transitive set of descendants. Empty if the term doesn’t exist.

.. py:method:: FoodOnAPI.id_to_children(term_id)

module:

foodscholar.ontology.api

Direct children only. Empty if the term doesn’t exist or has no children.

.. py:method:: FoodOnAPI.is_subclass_of(child_id, ancestor_id)

module:

foodscholar.ontology.api

.. py:method:: FoodOnAPI.search(query, *, limit=25)

module:

foodscholar.ontology.api

Substring search over labels + exact synonyms (case-insensitive).

Cheap and deterministic — it’s the prefilter for the dense SapBERT fallback. Sorted: shortest match first, then alphabetical id.