README.md

---
license: mit
version: 1.5
language:
- en
metrics:
- accuracy
pipeline_tag: graph-ml
tags:
- GNN
- trade_flow
- food_security
- pytorch
- regression
---

# 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:**
   ```bash
   git clone <repo-url>
   cd FoodFlow_GNN_Model
   ```

2. **Install dependencies:**
   It is recommended to use a virtual environment (e.g., `venv` or `conda`).
   ```bash
   pip install -r requirements.txt
   ```
3. **Download Training/Inferenced data:**
- [FoodFlow Inference Data Google Drive](https://drive.google.com/drive/u/0/folders/1mnlbiRvBHw4Hy2iU-i1IvElLw3Uuf0aV)
- [FoodFlow Visualization Results Google Drive](https://drive.google.com/drive/folders/1r6hdnym5wU3DOawecwknBP13VDMOcB7c?usp=drive_link)

---

## 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](https://drive.google.com/drive/u/0/folders/1mnlbiRvBHw4Hy2iU-i1IvElLw3Uuf0aV)


### 2. FoodFlowPortal (Streamlit Web App)
- **Optional:** For visualization, you may also use the precomputed results available at [FoodFlow Visualization Results](https://drive.google.com/drive/folders/1r6hdnym5wU3DOawecwknBP13VDMOcB7c?usp=drive_link).
- **Run the portal:**
  ```bash
  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](https://drive.google.com/drive/u/0/folders/1mnlbiRvBHw4Hy2iU-i1IvElLw3Uuf0aV)
- **Precomputed results for visualization are available at:** [FoodFlow Visualization Results Google Drive](https://drive.google.com/drive/folders/1r6hdnym5wU3DOawecwknBP13VDMOcB7c?usp=drive_link)

---

## 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.