114 lines
3.8 KiB
Markdown
114 lines
3.8 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
|
||
|
|
This is a mathematical modeling competition (MCM/ICM) project for the 2021 "Where and When" problem about optimizing mobile food distribution for the Food Bank of the Southern Tier (FBST). The project involves analyzing 2019 visit data from 70 regular MFP sites to design an optimized 2021 visit schedule.
|
||
|
|
|
||
|
|
## Problem Context
|
||
|
|
|
||
|
|
- **Organization**: FBST serves six counties in New York State
|
||
|
|
- **Service**: Mobile Food Pantry (MFP) program delivering nutritious food to underserved communities
|
||
|
|
- **Capacity**: 3 trucks available, typically 2 operational per day
|
||
|
|
- **Visit specs**: Each visit lasts ~2 hours, serves 200-250 families
|
||
|
|
- **2019 data**: 70 regular sites with 722 total visits
|
||
|
|
- **Goal**: Optimize 2021 schedule based on 2019 statistics
|
||
|
|
|
||
|
|
## Tasks (Complete 3/4)
|
||
|
|
|
||
|
|
- **Task 1**: Propose effective & fair schedule for all 70 sites (frequency based on demand)
|
||
|
|
- **Task 2 OR 3**: Either (a) reduce optimized site locations, or (b) schedule for longer client travel feasibility; OR implement two-site truck routing
|
||
|
|
- **Task 4**: 1-page executive summary
|
||
|
|
|
||
|
|
## Data Sources
|
||
|
|
|
||
|
|
- `prob/MFP Regular Sites 2019.xlsx` - Main dataset with:
|
||
|
|
- Site Name, latitude, longitude
|
||
|
|
- Number of Visits in 2019
|
||
|
|
- Average Demand per Visit
|
||
|
|
- StDev(Demand per Visit)
|
||
|
|
- `prob/full_bilingual.md` - Bilingual problem statement (English/Chinese)
|
||
|
|
|
||
|
|
## Code Structure
|
||
|
|
|
||
|
|
### Analysis Scripts
|
||
|
|
|
||
|
|
- `analyze_visits.py` - Correlation and regression analysis
|
||
|
|
- Reads Excel data using pandas
|
||
|
|
- Pearson correlation between average demand and visit frequency
|
||
|
|
- Linear regression analysis
|
||
|
|
- Standard deviation analysis (coefficient of variation)
|
||
|
|
- Multi-variate regression (demand + std_dev)
|
||
|
|
- Outputs: `analysis_result.png`
|
||
|
|
|
||
|
|
- `plot_sites.py` - Geographic visualization
|
||
|
|
- Reads Excel data and plots site locations
|
||
|
|
- Color-codes by visit frequency using viridis colormap
|
||
|
|
- Latitude correction for proper aspect ratio
|
||
|
|
- Outputs: `sites_map.png`
|
||
|
|
|
||
|
|
### Dependencies
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Core libraries
|
||
|
|
pandas numpy scipy matplotlib scikit-learn
|
||
|
|
|
||
|
|
# Excel support
|
||
|
|
openpyxl xlrd
|
||
|
|
```
|
||
|
|
|
||
|
|
### Running Analysis
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Run visit frequency analysis
|
||
|
|
python analyze_visits.py
|
||
|
|
|
||
|
|
# Generate geographic map
|
||
|
|
python plot_sites.py
|
||
|
|
```
|
||
|
|
|
||
|
|
## Latex Template
|
||
|
|
|
||
|
|
Location: `latex-template/`
|
||
|
|
|
||
|
|
```bash
|
||
|
|
cd latex-template
|
||
|
|
xelatex mcmthesis-demo.tex # Compile once
|
||
|
|
biber mcmthesis-demo # Run references
|
||
|
|
xelatex mcmthesis-demo.tex # Compile twice more
|
||
|
|
```
|
||
|
|
|
||
|
|
Key template elements:
|
||
|
|
- Document class: `mcmthesis` with MCM/ICM formatting
|
||
|
|
- Uses APA bibliography style with biblatex/biber
|
||
|
|
- Includes abstract, table of contents, sections, appendices
|
||
|
|
- "Report on Use of AI" section required per competition rules
|
||
|
|
- Problem selection: Set `problem=\textcolor{red}{A}/{B}/{C}/{D}/{E}/{F}` in mcmsetup
|
||
|
|
|
||
|
|
## Key Modeling Considerations
|
||
|
|
|
||
|
|
From `analyze_visits.py` findings:
|
||
|
|
- Low correlation between average demand per visit and total visit frequency
|
||
|
|
- Scheduling decisions should consider both mean demand AND demand variability (standard deviation)
|
||
|
|
- The coefficient of variation (CV = std_dev/mean) helps identify sites with irregular attendance
|
||
|
|
|
||
|
|
### Fairness vs Effectiveness Metrics
|
||
|
|
|
||
|
|
- **Effectiveness**: Overall service quality across all clients
|
||
|
|
- **Fairness**: Equity in service distribution across different communities
|
||
|
|
- Avoid concentration of visits in few high-demand areas
|
||
|
|
|
||
|
|
### Scheduling Constraints
|
||
|
|
|
||
|
|
- Max 2 trucks per day
|
||
|
|
- Each visit ~2 hours
|
||
|
|
- Schedule published months in advance
|
||
|
|
- No pre-registration required (post-pandemic model)
|
||
|
|
|
||
|
|
## Development Notes
|
||
|
|
|
||
|
|
- Python scripts use Chinese comments for analysis context
|
||
|
|
- Data file paths relative to project root
|
||
|
|
- Visualizations saved to root directory
|
||
|
|
- Latex compilation requires XeLaTeX (for Chinese support in CTeX)
|