From d68dc8cde0b0040b84e994a6fc21b73e9d010258 Mon Sep 17 00:00:00 2001
From: ntnt <tongnian0613@hotmail.com>
Date: Sat, 17 Jan 2026 18:46:16 +0800
Subject: [PATCH] P1: add data and agents.md

---
 AGENTS.md                                     |  42 ++++++++++++++++++
 .../kmin_effectiveness.png                    | Bin
 .../kmin_effectiveness_data.csv               |   0
 .../kmin_effectiveness_sites.csv              |   0
 kmin_effectiveness.py                         |  12 +++--
 5 files changed, 50 insertions(+), 4 deletions(-)
 create mode 100644 AGENTS.md
 rename kmin_effectiveness.png => data/kmin_effectiveness.png (100%)
 rename kmin_effectiveness_data.csv => data/kmin_effectiveness_data.csv (100%)
 rename kmin_effectiveness_sites.csv => data/kmin_effectiveness_sites.csv (100%)

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..0282743
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,42 @@
+# 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/`).
diff --git a/kmin_effectiveness.png b/data/kmin_effectiveness.png
similarity index 100%
rename from kmin_effectiveness.png
rename to data/kmin_effectiveness.png
diff --git a/kmin_effectiveness_data.csv b/data/kmin_effectiveness_data.csv
similarity index 100%
rename from kmin_effectiveness_data.csv
rename to data/kmin_effectiveness_data.csv
diff --git a/kmin_effectiveness_sites.csv b/data/kmin_effectiveness_sites.csv
similarity index 100%
rename from kmin_effectiveness_sites.csv
rename to data/kmin_effectiveness_sites.csv
diff --git a/kmin_effectiveness.py b/kmin_effectiveness.py
index 038d42c..94428dc 100644
--- a/kmin_effectiveness.py
+++ b/kmin_effectiveness.py
@@ -8,6 +8,7 @@ k_min为实数：如2.7表示70%站点最低2次，30%站点最低3次
 import numpy as np
 import pandas as pd
 import math
+import os
 
 try:
     import matplotlib
@@ -28,6 +29,7 @@ ALPHA = 0.5
 BETA = 0.2
 N_SIMS = 2000
 RANDOM_SEED = 42
+OUTPUT_DIR = "data"
 
 
 def gini_coefficient(values):
@@ -393,7 +395,8 @@ def plot_results(results):
     axes[3, 1].axis('off')
 
     plt.tight_layout()
-    plt.savefig('kmin_effectiveness.png', dpi=150)
+    os.makedirs(OUTPUT_DIR, exist_ok=True)
+    plt.savefig(os.path.join(OUTPUT_DIR, 'kmin_effectiveness.png'), dpi=150)
     plt.close(fig)
 
     return selected_k, selected_eff
@@ -443,9 +446,10 @@ def main():
     print(f"  访问次数: [{df_opt['AllocatedVisits'].min()}, {df_opt['AllocatedVisits'].max()}]")
 
     # 6. 保存
-    results.to_csv('kmin_effectiveness_data.csv', index=False)
-    sites_out.to_csv("kmin_effectiveness_sites.csv", index=False)
-    print("\n已保存: kmin_effectiveness.png, kmin_effectiveness_data.csv, kmin_effectiveness_sites.csv")
+    os.makedirs(OUTPUT_DIR, exist_ok=True)
+    results.to_csv(os.path.join(OUTPUT_DIR, 'kmin_effectiveness_data.csv'), index=False)
+    sites_out.to_csv(os.path.join(OUTPUT_DIR, "kmin_effectiveness_sites.csv"), index=False)
+    print("\n已保存到 data/: kmin_effectiveness.png, kmin_effectiveness_data.csv, kmin_effectiveness_sites.csv")
 
 
 if __name__ == '__main__':