43 lines
2.0 KiB
Markdown
43 lines
2.0 KiB
Markdown
|
# 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.
|
||
|
|
|
||
|
|
## Build, Test, and Development Commands
|
||
|
|
|
||
|
|
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`.
|
||
|
|
|
||
|
|
## Coding Style & Naming Conventions
|
||
|
|
|
||
|
|
- 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`).
|
||
|
|
|
||
|
|
## Testing Guidelines
|
||
|
|
|
||
|
|
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 & Pull Request Guidelines
|
||
|
|
|
||
|
|
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/`).
|