Repository Guidelines

Project Structure & Module Organization

*.py: Standalone analysis/optimization scripts (run directly with Python).
- kmin_effectiveness.py: k-min vs effectiveness/fairness analysis; writes artifacts to data/.
- fairness_optimization.py, analyze_visits.py, plot_sites.py: additional analyses/plots.
prob/: Problem statement and source dataset (e.g., prob/MFP Regular Sites 2019.xlsx).
latex-template/: Report template and compilation assets.
data/ (generated): Output CSV/PNG artifacts produced by scripts.

This repo is script-driven (no package build step).

Run k-min analysis: python3 kmin_effectiveness.py
- Outputs: data/kmin_effectiveness.png, data/kmin_effectiveness_data.csv, data/kmin_effectiveness_sites.csv
Run visit analysis: python3 analyze_visits.py (generates plots in the workspace)
Run site map: python3 plot_sites.py
Quick syntax check: python3 -m py_compile kmin_effectiveness.py

Dependencies commonly used: numpy, pandas, matplotlib, plus Excel readers like openpyxl.

Python: 4-space indentation; keep scripts runnable as python3 <script>.py.
Prefer descriptive names (k_min, total_demand) and Chinese comments/docstrings where already used.
Output files should be written under data/ and named predictably (e.g., kmin_effectiveness_*.csv/png).

There is no formal test suite currently. When changing math/metrics:

Add a small deterministic check (e.g., py_compile, or seed-controlled simulation runs).
Prefer reproducible randomness via explicit seeds (see RANDOM_SEED in kmin_effectiveness.py).

Commit history uses short subjects, sometimes with prefixes (e.g., P1: / add:). Follow this pattern:

Keep messages concise and action-oriented (e.g., P1: add gini plot).
PRs should include: what changed, which script(s) to run, and expected outputs (file names under data/).