MS Thesis Advisor Allocation

An interactive web app for assigning MS thesis advisors to students following a structured, CPI-based protocol.

---

What it does

1. Phase 0 — Classifies students into tiers (A / B / C) based on CPI percentiles and sets each faculty's maximum student load.
2. Round 1 — Each faculty picks one student from those who listed them as their first choice (skipped under the cpi_fill policy).
3. Main allocation — Remaining students are assigned interactively following the active allocation policy (see below). The app recommends an advisor for each student; manual overrides require confirmation.

Allocation policies

Five policies are available, selected by setting ALLOCATION_POLICY in app.py or via the --policy CLI flag:

Policy	Pipeline	Core rule	Best for
least_loaded (default)	Phase 0 → Round 1 → Class A→B→C	Assign to the least-loaded eligible advisor within the student's N_tier window	Balanced advisor loads; robust default
adaptive_ll	Phase 0a+0b → Round 1 → Class A→B→C	Adaptive caps guarantee no empty labs when S ≥ F	Balanced loads with structural empty-lab guarantee
cpi_fill	Phase 0 → CPI-Fill Phase 1 → Phase 2	Process students in strict descending CPI order; Phase 2 guarantees no empty labs	Merit-first access; guaranteed no empty labs
tiered_rounds	Phase 0 → Preference Rounds	Each advisor picks one student per round; highest CPI wins; ties require manual pick	Transparent preference-driven process
tiered_ll	Phase 0a+0b → Tiered Rounds 1..k → Backfill (GUI: LL-HP; CLI: CPI-Fill)	Hybrid: interactive rounds up to critical round k, then automatic backfill	Transparent early rounds + guaranteed no empty labs

Full descriptions: docs/policy_least_loaded.md · docs/policy_adaptive_ll.md · docs/policy_cpi_fill.md · docs/policy_tiered_rounds.md · docs/policy_tiered_ll.md

---

Demo

A short walkthrough of a full allocation run is available in AllocationRun.mp4.

---

Installation

Prerequisites

Tool	Mac	Linux	Windows
Git	git-scm.com or brew install git	sudo apt install git / sudo dnf install git	git-scm.com — install with default options
Conda	Miniconda (recommended) or Anaconda	Same	Same — use the Anaconda Prompt for all commands below

---

Step 1 — Clone the repository

Mac / Linux — open Terminal:

git clone https://github.com/aitgcodes/Allocator.git
cd Allocator

Windows — open Anaconda Prompt (search for it in the Start menu):

git clone https://github.com/aitgcodes/Allocator.git
cd Allocator

---

Step 2 — Create the Conda environment

This installs Python 3.11 and all required packages into an isolated environment called allocator.

Mac / Linux:

conda env create -f environment.yml

Windows:

conda env create -f environment.yml

This only needs to be done once. It may take a few minutes the first time.

---

Step 3 — Activate the environment

Mac / Linux:

conda activate allocator

Windows:

conda activate allocator

Your prompt will change to show (allocator) on the left, confirming the environment is active.

---

Step 4 — Launch the app

Mac / Linux:

PYTHONPATH=src python -m allocator.app

Windows:

set PYTHONPATH=src && python -m allocator.app

You should see output like:

Dash is running on http://127.0.0.1:8050/

---

Step 5 — Open in your browser

Open http://localhost:8050 in Chrome, Firefox, or Edge.

Keep the terminal window open while you use the app. Close it (or press Ctrl+C) to stop the server.

---

Stopping and restarting

To stop the app, press Ctrl+C in the terminal.

To restart it later, you only need steps 3 and 4 — the environment is already installed:

Mac / Linux:

cd Allocator
conda activate allocator
PYTHONPATH=src python -m allocator.app

Windows:

cd Allocator
conda activate allocator
set PYTHONPATH=src && python -m allocator.app

---

Preparing input files from a form export

If students submitted their preferences via Google Forms (or similar), use the bundled conversion script to produce the required CSVs automatically:

python scripts/make_preference_sheet.py form_responses.csv

This generates two ready-to-use files:

Output file	Contents
preference_sheet.csv	One row per student — student_id, name, cpi, pref_1 … pref_N where N = total unique faculty
faculty_list.csv	One row per faculty — faculty_id, name, max_load (blank; fill in manually before running the app)

What the script handles automatically:

• Detects Name, Roll No., CPI/CGPA, and Preference N columns (case-insensitive, flexible naming)
• Deduplicates each student's list — if a faculty appears more than once, the repeated entry is dropped and the remaining preferences shift up
• Fills trailing slots with any faculty the student did not mention, listed in alphabetical order — so every student's list covers all faculty
• Auto-assigns faculty_id values (F01, F02, …) in first-seen order

Options:

Flag	Default	Description
-o / --output	preference_sheet.csv	Student output path
-f / --faculty-output	faculty_list.csv	Faculty output path
--cpi-col COLUMN	auto-detect	Override CPI column name if auto-detection fails

---

Input files

Students (students.csv)

Column	Description
student_id	Unique ID
name	Full name
cpi	Cumulative Performance Index (numeric)
pref_1, pref_2, …	Faculty IDs in preference order

Faculty (faculty.csv)

Column	Description
faculty_id	Unique ID (must match student preference values)
name	Full name
max_load	(optional) Max students; leave blank to use the formula value

Sample files are in data/.

---

Output

• Interactive summary — assignment table + advisor popularity breakdown in the browser
• CSV report — download via the "Save report" button after allocation completes
• Replay slider — step through every allocation decision in the visualisation panel

---

Troubleshooting

Symptom	Fix
conda: command not found	Miniconda/Anaconda is not installed or not on PATH — reinstall and restart your terminal
ModuleNotFoundError: No module named 'allocator'	PYTHONPATH=src was not set — re-run the launch command exactly as shown
Browser shows "This site can't be reached"	The app is not running — check the terminal for errors and make sure Step 4 completed successfully
Port 8050 already in use	Another instance is running. Stop it with Ctrl+C, or run lsof -i :8050 (Mac/Linux) to find and kill it
CondaEnvException: prefix already exists	Environment already created — skip Step 2 and go straight to Step 3

---

Project structure

src/allocator/
  app.py          – Dash application and callbacks
  allocation.py   – Phase 0 / Round 1 / main allocation / all five policy engines
  analyze.py      – CLI analysis tool: metrics, compare, study subcommands
  data_loader.py  – CSV/Excel ingestion and Phase-0 report I/O
  state.py        – Data classes (Student, Faculty, AllocationSnapshot)
  visualizer.py   – Plotly figure builders
  metrics.py      – NPSS, PSI, MSES, LUR, ERR, and CPI-skewness metrics
scripts/
  make_preference_sheet.py      – Convert a form-export CSV into preference_sheet.csv and faculty_list.csv
  generate_comparison_report.py – Run all 5 policies on real cohort data; write reports/comparison/
data/             – Sample student and faculty CSV files
docs/             – User manual (PDF) and policy reference docs
  policy_least_loaded.md  – least_loaded policy specification
  policy_adaptive_ll.md   – adaptive_ll policy specification
  policy_cpi_fill.md      – cpi_fill policy specification
  policy_tiered_rounds.md – tiered_rounds policy specification
  policy_tiered_ll.md     – tiered_ll policy specification
stats/            – Policy comparison study
  run_study.py        – Generates synthetic datasets and runs all 5 policies
  policy_report.md    – Comparison report (tables, deltas, recommendations)
  students_*.csv      – Synthetic preference sheets used in the study
reports/          – Phase-0 reports and allocation outputs written here
  comparison/     – Real-cohort 5-policy comparison (real_data_report.md/pdf)
test/             – Real preference data (anonymized_preferences.csv, faculty.csv)
tests/            – Pytest test suite