Perishability GFM

The Perishability Gap Filling Module determines the perishability classification of food products and identifies combined products (convenience products versus mono products). This classification is essential for downstream modules that calculate storage requirements, transport conditions, and food loss factors.

Quick Reference

Property	Description
Runs on	Root node of calculation (recipe level)
Dependencies	`AddClientNodesGFM`, `MatchProductNameGFM`, `IngredientSplitterGFM`, `NutrientSubdivisionGFM`, `LinkTermToActivityNodeGFM`, `AttachFoodTagsGFM`, `OriginGFM`
Key Input	Food product glossary tags, ingredient hierarchy
Output	Perishability classification tag, combined/mono product tag
Trigger	Runs on every calculation at the root node level

When It Runs

The module triggers when:

Processing reaches the root node of a calculation
All dependency modules have completed their processing
Food products in the graph need perishability classification

Key Output

The module adds two types of glossary tags to food product nodes:

Perishability Tag: One of three levels (shelf-stable, perishable, highly perishable)
Product Type Tag: Either combined product or mono product classification

Scientific Methodology

Perishability Classification

Food products are classified into three perishability levels based on their shelf life and storage requirements:

Level	Term External ID	Description	Typical Products
Shelf-Stable	`EOS_STABLE`	Products that can be stored at room temperature for extended periods	Dried goods, canned products, grains, oils
Perishable	`EOS_PERISHABLE`	Products requiring controlled storage with moderate shelf life	Dairy, eggs, processed meats
Highly Perishable	`EOS_HIGH-PERISHABLE`	Products requiring immediate refrigeration with short shelf life	Fresh meat, seafood, cut produce

Propagation Rules

The perishability classification follows a bottom-up propagation model through the ingredient hierarchy:

Product Perishability = max(Ingredient Perishabilities)

Propagation Logic:

Leaf ingredients receive perishability from their glossary term definitions
Combined products inherit the highest perishability from their sub-ingredients
Products without explicit perishability default to shelf-stable

Example: A salad bowl containing:

Lettuce (highly perishable)
Cheese (perishable)
Croutons (shelf-stable)

Result: The salad bowl is classified as highly perishable.

Combined Product Classification

The module also determines whether a product is a combined product (convenience product) or a mono product (single ingredient):

Classification	Term External ID	Criteria
Combined Product	`EOS_COMBINED_PRODUCT`	Product combines multiple different food product ingredients
Mono Product	`EOS_MONO_PRODUCT`	Product is a single ingredient or does not combine multiple products

Combined Product Logic:

A product is marked as combined if it directly combines multiple food product ingredients
The combined product tag propagates upward through the hierarchy
Once any sub-ingredient is marked as a combined product, parent products also receive the combined product tag

Implementation Details

Algorithm Overview

The module uses a depth-first traversal with post-order processing to propagate perishability from leaf nodes to the root:

# Pseudocode for perishability propagation
def propagate_perishability(node):
    if node has explicit perishability tag:
        return node.perishability

    sub_perishabilities = []
    for sub_node in node.sub_nodes:
        sub_perishabilities.append(propagate_perishability(sub_node))

    if sub_perishabilities:
        return max(sub_perishabilities, key=perishability_order)
    else:
        return SHELF_STABLE  # Default

Perishability Order

Perishability levels are ordered from lowest to highest:

perishability_order = {
    "EOS_STABLE": 0,        # Lowest perishability
    "EOS_PERISHABLE": 1,    # Medium perishability
    "EOS_HIGH-PERISHABLE": 2  # Highest perishability
}

Source Attribution

When the module assigns a perishability tag, it uses the source eos_assumed to indicate the value was inferred rather than explicitly provided:

GlossaryTermProp(
    term_uid=perishability_term.uid,
    source=SourceEnum.eos_assumed
)

Dependency Chain

The module waits for these modules to complete before running:

Module	Reason
`AddClientNodesGFM`	Client-specified nodes must be added first
`MatchProductNameGFM`	Products must be matched to glossary terms
`IngredientSplitterGFM`	Composite ingredients must be split
`NutrientSubdivisionGFM`	Nutrient-based subdivisions must be processed
`LinkTermToActivityNodeGFM`	Terms must be linked to activities
`AttachFoodTagsGFM`	Food-specific tags must be attached
`OriginGFM`	Origin information must be determined

Data Sources

Perishability Glossary Terms

The perishability classification uses terms from the EOS Glossary under the root term EOS_Perishability:

Term External ID	Display Name	Description
`EOS_STABLE`	Shelf-Stable	Products with extended room-temperature shelf life
`EOS_PERISHABLE`	Perishable	Products requiring controlled storage
`EOS_HIGH-PERISHABLE`	Highly Perishable	Products requiring immediate refrigeration

Product Type Glossary Terms

The combined/mono product classification uses terms under EOS_Combined_Product_Mono_Product:

Term External ID	Display Name	Description
`EOS_COMBINED_PRODUCT`	Combined Product	Multi-ingredient convenience product
`EOS_MONO_PRODUCT`	Mono Product	Single ingredient product

Calculation Example

Scenario: A convenience salad bowl recipe with the following structure:

Salad Bowl (no explicit perishability)
├── Fresh Salad (highly perishable)
├── Ready-Made Sauce (no explicit perishability)
│   ├── Milk Powder (shelf-stable)
│   ├── Vinegar (shelf-stable)
│   ├── Oil (shelf-stable)
│   └── Fresh Parsley (highly perishable)
└── Tofu (perishable)

Step 1: Traverse to Leaf Nodes

The algorithm visits all leaf nodes first:

Fresh Salad: EOS_HIGH-PERISHABLE (from glossary)
Milk Powder: EOS_STABLE (from glossary)
Vinegar: EOS_STABLE (from glossary)
Oil: EOS_STABLE (from glossary)
Fresh Parsley: EOS_HIGH-PERISHABLE (from glossary)
Tofu: EOS_PERISHABLE (from glossary)

Step 2: Propagate to Parent Nodes

Ready-Made Sauce:

Sub-perishabilities: [stable, stable, stable, highly-perishable]
Maximum: EOS_HIGH-PERISHABLE
Combined product: Yes (multiple food product ingredients)

Step 3: Propagate to Root

Salad Bowl:

Sub-perishabilities: [highly-perishable, highly-perishable, perishable]
Maximum: EOS_HIGH-PERISHABLE
Combined product: Yes (combines multiple products, and has combined product sub-ingredient)

Final Output

Product	Perishability Tag	Product Type Tag
Fresh Salad	`EOS_HIGH-PERISHABLE`	`EOS_MONO_PRODUCT`
Milk Powder	`EOS_STABLE`	`EOS_MONO_PRODUCT`
Vinegar	`EOS_STABLE`	`EOS_MONO_PRODUCT`
Oil	`EOS_STABLE`	`EOS_MONO_PRODUCT`
Fresh Parsley	`EOS_HIGH-PERISHABLE`	`EOS_MONO_PRODUCT`
Tofu	`EOS_PERISHABLE`	`EOS_MONO_PRODUCT`
Ready-Made Sauce	`EOS_HIGH-PERISHABLE` (assumed)	`EOS_COMBINED_PRODUCT`
Salad Bowl	`EOS_HIGH-PERISHABLE` (assumed)	`EOS_COMBINED_PRODUCT`

Integration with Other Modules

Downstream Consumers

The perishability classification is used by several downstream modules:

Module	Usage
Conservation GFM	Determines storage requirements (cooled, frozen, dried)
Transport GFM	Calculates cold chain requirements and transport mode feasibility
Food Loss GFM	Estimates waste factors based on shelf life

Conservation Rules

The Conservation GFM uses perishability to assign default conservation methods:

Highly Perishable + No Conservation Tag: Assigned "cooled" conservation
Perishable + No Conservation Tag: Assigned "cooled" conservation
Shelf-Stable: No conservation required (room temperature)

Transport Implications

Transport mode selection considers perishability:

Highly Perishable: May require air transport for long distances
Perishable: Can use refrigerated truck/ship transport
Shelf-Stable: No cold chain requirements

Known Limitations

Classification Coverage

Not all food products in the glossary have explicit perishability classifications
Products without classification default to shelf-stable, which may underestimate cold chain requirements
Some processed products may have variable perishability depending on processing method

Conservation Interaction

The current model does not account for conservation methods that change perishability (for example, drying highly perishable herbs)
Frozen products are handled separately by the Conservation GFM
The interaction between perishability and conservation could be more sophisticated

Combined Product Detection

The combined product detection is based solely on ingredient structure
It does not consider production location differences (convenience products produced at different facilities)
EAN/GTIN codes are not yet used to identify industrially produced convenience products

Future Enhancements

Planned improvements include:

Tree crawling for glossary tags to improve perishability detection
Better integration with conservation methods that alter perishability
Location-based convenience product detection
Support for product-specific conservation method restrictions

References

EOS Glossary Documentation. Internal Eaternity documentation for glossary term definitions.
Food Storage Guidelines. FDA and EFSA food safety guidelines for storage temperature requirements.
Cold Chain Logistics. Industry standards for perishable food transport and storage.

Quick Reference​

When It Runs​

Key Output​

Scientific Methodology​

Perishability Classification​

Propagation Rules​

Combined Product Classification​

Implementation Details​

Algorithm Overview​

Perishability Order​

Source Attribution​

Dependency Chain​

Data Sources​

Perishability Glossary Terms​

Product Type Glossary Terms​

Calculation Example​

Step 1: Traverse to Leaf Nodes​

Step 2: Propagate to Parent Nodes​

Step 3: Propagate to Root​

Final Output​

Integration with Other Modules​

Downstream Consumers​

Conservation Rules​

Transport Implications​

Known Limitations​

Classification Coverage​

Conservation Interaction​

Combined Product Detection​

Future Enhancements​

References​