DOCSEARCHbyAlgolia
Submit Docs

FoodOn Ontology

repository·master·Indexed 42 days ago

https://github.com/foodontology/foodon

An ontology for food, organized according to the Basic Formal Ontology (BFO). It provides stable release versions via the OBO Library PURL and an editors' version for contributors. The project includes tools for maintaining NCBITaxon identifiers, performing SPARQL queries and constraint violation checks via ROBOT, and managing ontology builds using the Ontology Development Kit (ODK).

Tokens
24.4K
Snippets
72
Records
108
Agent score
53%

What's inside FoodOn

  1. How the ingredients.py recogniser pipeline works

    master

    The ingredients.py recogniser maps free-text food ingredient strings to FoodOn ontology terms. It uses a three-stage pipeline where the first match wins:

    1. Assumption rules: If the normalized text is an exact key in the assumptions dictionary (e.g., egg becomes chicken egg), the value is substituted and the process moves to stage 2.
    2. Global exact match: The (possibly substituted) text is looked up in a single alias + food-form index built from all types. This returns the matched entry's type and subtype directly.
    3. Component search: Only attempted if stages 1 and 2 fail. It uses a sequence of stripping techniques including:
      • Plant prefix stripping (wild, whole)
      • Parenthetical qualifier stripping (base (qualifier))
      • Global adjective stripping
      • Characteristic stripping loop
      • Trailing-form stripping (e.g., L. acidophilus bacterial culture)
      • Anatomy standalone match.

  2. Customise an import module type

    master

    By default, imports are treated as SLME modules. You can change this in src/ontology/foodon-odk.yaml using the module_type key.

    Filter Module

    Use module_type: filter to import all external terms declared by your ontology. You can specify additional base_iris to include terms from other namespaces.

    Custom Module

    Use module_type: custom to specify your own ROBOT command. You must then define a corresponding goal in your custom Makefile (src/ontology/foodon.Makefile).

    import_group:
  products:
    - id: ro
    - id: go
      module_type: filter
      base_iris:
        - http://purl.obolibrary.org/obo/GO_
        - http://purl.obolibrary.org/obo/CL_

  3. How the Base Module approach works

    master

    The Base Module approach (supported since ODK 1.2.31) generates modules by only importing axioms that actually belong to the target ontology. It uses a 'base file' which is a subset of the ontology containing only axioms about its own terms, excluding axioms belonging to other ontologies.

    Workflow:

    1. Merge all mirrors into one large file.
    2. Extract a single mega module (e.g., imports/merged_import.owl).

    How to identify if your ontology uses this: Check src/ontology/foodon-odk.yaml. If use_base_merging: TRUE is declared under import_group, you are using this approach.

    How to update terms in a Base Module ontology:

    1. Add the term to its associated term file (see "Using term files" in the declaration guide).
    2. Navigate to the ontology directory:
      cd src/ontology
    3. Refresh the merged import:
      sh run.sh make imports/merged_import.owl
      Note: If mirrors are updated, you can use sh run.sh make no-mirror-refresh-merged.

    Warning: This process requires significant local memory. If you encounter memory errors, request assistance from a local developer.

    After refreshing, restart Protégé to see the changes.

    cd src/ontology
sh run.sh make imports/merged_import.owl

  4. Use Constraint Violation checks to validate ontology integrity

    master
    Constraint Violation checks are used to ensure the ontology adheres to specific logical or structural rules. These files are named with the suffix *violation.sparql. In automated environments (like Travis CI), these checks are configured to fail the build if they return any results, indicating a violation has occurred. You should consult the specific .sparql file to understand the exact logic of the check being performed.

  5. How robot_deprecate.py processes deprecations

    master

    The script follows a multi-step process to ensure a clean transition from a deprecated term to its replacement:

    1. Merge: It uses robot merge to create a cache-foodon-merged.owl snapshot, which serves as the source for all queries.
    2. Discovery: It finds terms matching the --prefix that have obo:IAO_0100001 but are not yet owl:deprecated.
    3. Collection: It gathers annotations and identifies blank-node references (axioms on other terms that use the deprecated term as a filler).
    4. Locating: It identifies the specific source file where the term and its replacement are declared (searching components/ but excluding imports/).
    5. Execution (with --update):
      • Declaration: Adds Declaration(Class(?x)) to components/deprecation_import.ofn if missing.
      • Deprecation Record: Inserts the obsolete label, the replacement IRI, and owl:deprecated true into deprecation_import.ofn.
      • Axiom Removal: Deletes all non-blank-node axioms where the deprecated term is the subject in its source file.
      • Annotation Transfer: Copies synonyms, definitions, and Xrefs from the deprecated term to the replacement term.
      • Repointing: Updates blank-node restriction fillers to point to the replacement instead of the deprecated term.

    Important Limitations

    • Blank-node objects: Axioms where the deprecated term is the object (e.g., SubClassOf(?x some Replacement)) cannot be automatically deleted and must be removed manually in Protégé.
    • Curation Status: The obo:IAO_0000114 (curation status) annotation is not transferred; it must be set manually on the replacement term.

  6. Allowed Files for Manual Editing

    master

    To maintain ontology integrity, only specific files and directories should be manually edited. Edits to imports will be overwritten during the next update.

    Allowed locations for manual edits:

    • src/ontology/foodon-edit.owl (The primary edit file)
    • ROBOT templates (TSV files only)
    • DOSDP data tables (TSV files and associated patterns)
    • Components located in src/ontology/components

  7. Generate informative reports using SPARQL

    master
    Informative SPARQL queries are used to generate reports about the state or characteristics of the ontology. Unlike violation checks, these are intended for information gathering rather than validation. A subset of these reports is typically generated during each ontology release.

  8. How matching tiers and annotations work within types

    master

    Within a specific ingredient type, the recogniser attempts matching in the following order:

    1. Direct match: Exact alias or food-form lookup based on the configured tier order (alias_first or food_form_first).
    2. Adjective stripping: Strips adjectives from the front, reconstructs the parenthetical form (e.g., "dried mango" $\rightarrow$ "mango (dried)"), and retries.
    3. Fallback suffix: Appends a configured fallback word (e.g., leaf for herbs) and retries.
    4. Trailing annotation strip: Removes a trailing (...) clause and retries. The clause becomes residual text, resulting in a partial match. Example: "bacterial culture (bifidobacterium lactis bb-12)" $\rightarrow$ bacterial food culture + residual "bifidobacterium lactis bb-12".

    Note on Food-forms: Food-form matches automatically support "ingredient (qualifier)" variants via parenthetical permutation (e.g., "cinnamon (ground)" also indexes "ground cinnamon").

  9. Understand the difference between Imports and Components in FOODON

    master

    FOODON distinguishes between external dependencies (Imports) and native ontology parts (Components). Understanding this distinction is crucial for knowing which axioms are part of the core 'base' product and which are external.

    Imports

    Imports are external ontologies (like software dependencies) that contain terms and axioms reused in FOODON. They are not included in the official release artefact; the release only contains axioms that are personally maintained within FOODON.

    Components

    Components are considered full, native members of the ontology. Any axiom in a component is included in the ontology base. Components are typically used when:

    1. A part of the ontology is automatically generated/re-generated.
    2. A part of the ontology is managed via ROBOT templates.
    3. The logic requires higher expressivity (e.g., OWL features) than the primary edit format (e.g., OBO) can provide.

  10. How NCBITaxon Manager updates different file formats

    master

    The NCBITaxon Manager updates files while preserving their specific conventions:

    • OWL / OFN: Replaces every occurrence of NCBITaxon_<old> with NCBITaxon_<new> throughout the file.
    • OntoFox .txt: For each replaced URL line, it inserts a comment # REPLACED NCBITaxon_<old> # <old label> on the line immediately above. The URL is updated to the new ID, and the trailing name comment is updated to the current scientific name from the NCBI API.
    • ROBOT template .tsv: Replaces NCBITaxon:<old> in column 0 with NCBITaxon:<new>. Header and directive rows are left unchanged.
    ### OntoFox .txt Example

**Before:**

    http://purl.obolibrary.org/obo/NCBITaxon_6657 # Pancrustacea

    
**After:**

    REPLACED NCBITaxon_6657 # Pancrustacea

    http://purl.obolibrary.org/obo/NCBITaxon_197562 # Pancrustacea

  11. Understand ingredient match statuses

    master

    When using the recogniser, each match is assigned a status indicating the level of coverage for the input string:

    StatusMeaning
    exactThe full ingredient string matched a specific ontology term
    compositeThe full string is accounted for by a material term + one or more characteristics
    partialOne or more component terms matched; remainder is unresolved
    parentA broader group term matched; the specific form is likely a narrower child not yet in the ontology
    no_matchNothing matched

  12. Configure and manage ingredients.yaml

    master

    The ingredients.yaml file is the central registry for ingredient mappings. It consists of two main sections:

    1. configuration: Defines the behavior for each ingredient type (e.g., grain, nutrient). It specifies OWL roots for BFS traversal, valid subtypes, tier_order (how to prioritize matches), fallbacks, and adjectives to strip (like "whole" or "rolled").
    2. ingredient: Contains the actual mappings. Each entry is keyed by its ontology CURIE (e.g., CHEBI:12777) and includes metadata like type, subtype, label, synonyms, and ai_synonyms.

    Synonym Matching Logic

    • synonyms: Always included; sourced from OWL (hasExactSynonym, hasSynonym).
    • ai_synonyms[status=ok]: Always included; manually curated or AI-generated.
    • ai_synonyms[status=proposed]: Included only if the --synonyms proposed flag is used.
    • ai_synonyms[status=reject]: Never included.
    • E-numbers (e.g., e322): Kept in the synonyms field.