ICICLE-AI/FoodFlow_GNN_Model

FoodFlow GNN Model v1.5

A Graph Neural Network (GNN) model for predicting food trade flows between U.S. counties and FAF zones. Applications include economic planning, infrastructure design, and food security policy. This repository predicts food trade flows between U.S. counties and FAF zones using Graph Neural Networks (GNNs). It includes:

• FAF_level(Old): Original GNN models for FAF zones (used only for training process in the early development stage)
• County_level(New): Enhanced GNNs for county-level inference
• FoodFlowPortal: Streamlit web portal for visualization and interaction

Applications include economic planning, infrastructure design, and food security policy.

Tags

• GNN
• trade_flow
• food_security
• pytorch
• regression

License

MIT

References

• [Multi-Scale Food Flow Prediction using Graph Neural Networks(https://github.com/GeoDS/GNNFoodFlow)

Acknowledgements

National Science Foundation (NSF) funded AI Institute for Intelligent Cyberinfrastructure with Computational Learning in the Environment (ICICLE) (OAC 2112606)

Tutorials

• See code/training.ipynb for model training
• See code/inference.ipynb for inference
• See code/data-postprocess.ipynb for post-processing

Folder Structure

FoodFlow_GNN_Model/
├── README.md                # This file
├── requirements.txt         # Unified dependencies for all components
│
├── FAF_level(Old)/          # FAF zone-level GNN implementation (early-stage training only)
│   ├── data/                # FAF datasets and shapefiles
│   ├── training.ipynb       # Training notebook
│   ├── utils.py             # Utilities
│   ├── gcn_model.pt         # Trained GCN weights
│   ├── model.py             # GNN model architecture
│   ├── test_model.py        # Inference script
│   ├── gat_model.pt         # Trained GAT weights
│
├── code/                    # County-level GNN source code (model, utils, notebooks)
│   ├── data-postprocess.ipynb
│   ├── training.ipynb
│   ├── inference.ipynb
│   ├── model.py
│   └── utils.py
│
├── models/                  # Trained model weights (county-level)
│   ├── best_model1_gcn.pth
│   ├── best_model2_gcn.pth
│   └── ...
│
├── data/                    # County-level datasets
│   ├── county_aligned_filtered.csv.zip
│   ├── FAF5_SCTG1.csv
│   └── ...
│
└── FoodFlowPortal/          # Streamlit web portal
    ├── app.py               # Main app
    ├── requirements.txt     # (legacy, now use root requirements.txt)
    ├── data/                # Portal data
    ├── files/               # Additional files
    ├── image/               # Images for portal
    └── cleaned_data/        # Cleaned data for portal

---

How-To (Setup Instructions)

1. Clone the repository:

   git clone <repo-url>
   cd FoodFlow_GNN_Model
   

2. Install dependencies: It is recommended to use a virtual environment (e.g., venv or conda).

   pip install -r requirements.txt
   

3. Download Training/Inferenced data:

• FoodFlow Inference Data Google Drive
• FoodFlow Visualization Results Google Drive

---

Tutorial (Usage)

1. County-Level GNN (County_level(New))

• Train or test the model:
  • Training: Use code/training.ipynb.
  • Inference: Use code/inference.ipynb or adapt the notebook for script-based inference.
• Post-processing:
  • After running inference, you can use code/data-postprocess.ipynb in the project root to further process and analyze the results as needed.
• Required data files:
  • All files required for inferencing (such as county_aligned_filtered.csv, county_flows_with_ports_distance_gravity.csv, etc.) can be downloaded from the following Google Drive folder: FoodFlow Inference Data

2. FoodFlowPortal (Streamlit Web App)

• Optional: For visualization, you may also use the precomputed results available at FoodFlow Visualization Results.
• Run the portal:

  cd FoodFlowPortal
  streamlit run app.py
  

  • The portal provides interactive visualization and exploration of food flow predictions.

---

Data & Models

• Data files are provided in the respective data/ folders.
• Trained model weights are in models/ (county) and as .pth files.
• Some data files are large and may be compressed or require download from external sources.
• All files required for inferencing are available at: FoodFlow Inference Data Google Drive
• Precomputed results for visualization are available at: FoodFlow Visualization Results Google Drive

---

Notes

• FAF_level(Old) is only used for the training process in the early development stage and is not intended for current usage or inference.
• All dependencies are now managed via the root requirements.txt.
• For custom data or retraining, update the relevant CSVs and rerun the notebooks/scripts.
• The portal is designed for demonstration and exploration; for production, further security and deployment steps are recommended.

---

License & Credits

• License: MIT
• Developed by: Qianheng Zhang & ICICLE Team
• Funding: NSF AI Institute for Intelligent Cyberinfrastructure with Computational Learning in the Environment (ICICLE) (OAC 2112606)

---

Troubleshooting

• If you encounter missing package errors, ensure you are using the correct Python environment and have installed all dependencies from the root requirements.txt.

---

For further details, see the code and notebooks in each subfolder.