GFM Module Catalog
This catalog documents all Gap Filling Modules available in the EOS Engine. Each module fills specific data gaps in environmental impact calculations.
Version numbers correspond to the EOS release tag in which each module was last updated. For example, v0.5.328 means the module was last modified in EOS release v0.5.328.
Module Overview
EOS includes 27 modules organized into functional categories:
Graph Building
These modules construct and manage the calculation graph structure.
add_client_nodes_gfm
Loads child nodes of recipes, sub-recipes, and ingredients into the calculation graph.
ModeledActivityNode, ElementaryResourceEmissionNodemerge_linked_nodes_gfm
Merges linked Flow Nodes that reference the same product into a single node.
FlowNodes with LinkingActivityNode parentadd_client_nodes_gfmingredient_splitter_gfm
Splits a product's ingredient list into separate nodes for individual assessment. Particularly useful for processed foods or dishes where exact composition is not provided.
FlowNode per ingredientinventory_connector_gfm
Connects food products to Life Cycle Inventory data from databases like Agribalyse and ecoinvent. Uses an aggregated cache for system nodes to optimize performance.
ModeledActivityNode, FlowNodeProduct Matching
These modules match product names to standardized database terms.
match_product_name_gfm
Matches product names to FoodEx2 terms from the glossary database containing over 565,000 convenient products.
FoodProductFlowNodeOutput: Terms ("A1791", "J0116") = "CARROT" + "DEHYDRATED OR DRIED"
attach_food_tags_gfm
Attaches food classification tags to products based on matched FoodEx2 terms.
FoodProductFlowNodematch_product_name_gfmlink_food_categories_gfm
Links matched food terms to food category classifications.
FoodProductFlowNode (not subdivision)match_product_name_gfmlink_term_to_activity_node_gfm
Links product terms to LCA activity processes in the database. Searches glossary_link for connections between matched Terms and LCA processes.
FoodProductFlowNode, PracticeFlowNodematch_product_name_gfmIngredient Analysis
These modules analyze and estimate ingredient quantities.
ingredient_amount_estimator_gfm
Estimates ingredient amounts when only a list of ingredients is available without quantities. Uses convex optimization (CVXPY) to match declared product nutrition with ingredient compositions.
nutrient_subdivision_gfm
Subdivides ingredients into nutrient-based variants for more accurate matching.
FoodProductFlowNode without sub-nodesOutput: "low-fat cocoa powder" + "high-fat cocoa powder"
unit_weight_conversion_gfm
Converts product quantities to standardized weight-based units. Handles weight units, volume to weight, food-specific units, and count-based items.
FoodProductFlowNode, FlowNodeLocation & Origin
These modules determine geographic origin and location data.
origin_gfm
Determines the geographic origin of food products using FAO trade data. When origin is not provided, uses FAO import statistics to estimate the most likely source country.
FoodProductFlowNodeOutput: { origin: "CH", originConfidence: 0.9, originBasis: "name_analysis" }
location_gfm
Handles detailed geographic location data including coordinates and regions. Integrates with geographical databases for standardized location information.
FoodProductFlowNodeorigin_gfmTransportation
These modules calculate transportation impacts.
transportation_decision_gfm
Determines the optimal transport mode (road, rail, sea, air) based on cost, distance, and product requirements. Considers product perishability and available infrastructure.
location_gfm, perishability_gfmtransportation_mode_distance_gfm
Calculates transport distances and route-specific emissions using the EcoTransit API. Models complete transport routes including road-to-port, port-to-port, and cooling requirements.
FlowNode from FoodProcessingActivityNodetransportation_decision_gfmProcessing & Conservation
These modules model food processing, production methods, and storage impacts.
greenhouse_gfm
Estimates emissions from heated greenhouse cultivation. Greenhouse production can increase climate impact by up to 10x compared to field-grown equivalents due to heating energy requirements.
ModeledActivityNode with vegetable parentField-grown Spanish tomato (August): 0.2 kg CO₂eq/kg
processing_gfm
Models food processing steps and their environmental impact. Handles both complex processing models (creating new Life Cycle Inventories) and simple processing models (weight-based).
FoodProductFlowNodematch_product_name_gfmconservation_gfm
Models storage requirements, cold chain, and preservation impacts. Analyzes preservation methods including canning, freezing, drying, and fermentation.
FoodProductFlowNode (not subdivision)location_gfmperishability_gfm
Calculates food loss and waste factors based on product perishability. Estimates shelf life, refrigeration energy during transport, and food waste due to spoilage.
add_client_nodes_gfmImpact Calculation
These modules compute environmental impact metrics.
water_scarcity_gfm
Calculates water scarcity footprint based on origin and regional water stress factors. Uses Water Stress Index (WSI) factors to weight blue water consumption by regional water scarcity.
ModeledActivityNode with FoodProductFlowNode parentorigin_gfmTomatoes from Netherlands: 12.8 L scarce water/kg
rainforest_gfm
Evaluates deforestation risk and rainforest impact for relevant commodities.
ModeledActivityNode with FoodProductFlowNode parentimpact_assessment_gfm
Computes Life Cycle Impact Assessment using IPCC methodology. Calculates CO₂ equivalents for each production node using IPCC 2013 climate change impact assessment.
ActivityNode (processing, modeled, supply sheet)matrix_calculation_gfm
Performs matrix-based LCA calculations for complex product systems. A critical performance component for matrix aggregation in complex graphs.
Nutrition & Scoring
These modules calculate health and nutrition metrics.
vitascore_gfm
Calculates nutritional health score based on Global Burden of Disease risk factors.
FoodProductFlowNodeaggregation_gfm, daily_food_unit_gfmdaily_food_unit_gfm
Computes the daily food unit contribution from aggregated nutrient values.
FoodProductFlowNode (not subdivision)aggregation_gfmAggregation
These modules combine results across ingredients.
aggregation_gfm
Aggregates data from all ingredients to the product level. Aggregates nutrient values, amounts per category, rainforest critical products, and animal products.
matrix_calculation_gfmpost_nutrients_aggregation_gfm
Performs post-calculation aggregation after impact assessment.
impact_assessment_gfm, daily_food_unit_gfmModule Dependencies
The typical execution flow follows this dependency pattern:
Why GFMs Matter
- Efficiency - Automate repetitive data entry tasks, making EOS scalable to thousands of products
- Accuracy - Leverage statistical models, standard recipes, and trade data to increase reliability
- Standardization - Harmonize data from varied sources into consistent formats
- Adaptability - Update modules independently as new data or methodologies emerge
Next Steps
- How GFMs Work - Internal mechanics
- GFM SDK (coming soon) - Build custom modules