# Scripts Reference — Which Script to Run When

## Quick Decision Tree

```
Need to download student data from UDISE+?
  ↓
Run → python3 ~/udise_student_manager.py

Need to clean/organize already-downloaded data?
  ↓
Run → python3 ~/udise_data_processor.py

Need Excel helper functions (add student, find duplicates)?
  ↓
Import → from excel_helper_functions import *

Need time table for school schedule?
  ↓
Run → python3 ~/school_time_table.py  (or use fixed version in references/)

Need Instagram-ready image of schedule?
  ↓
See → references/instagram-time-table-post.md
```

---

## Script 1: `udise_student_manager.py`

**Purpose:** Main tool — downloads student data automatically from UDISE+ portal

**When to run:**
- First time getting student data
- Monthly update required
- New academic year start
- After portal data changes

**What it does:**
1. Launches Chrome browser
2. Logs into UDISE+ with your credentials
3. Navigates to student section
4. Downloads data as Excel/CSV (or scrapes HTML table)
5. Creates `UDISE_Student_Master.xlsx` with 4 sheets:
   - Basic_Info
   - Academic
   - Attendance
   - Fees

**Output location:** `~/UDISE_Data/`

**Time required:** 2-5 minutes (depends on internet speed, portal load)

**Common flags:**
- `--headless` — run without browser window (for cron/automation)
- `--test-mode` — simulate without actual download
- `--debug` — show browser actions, wait longer

**Example:**
```bash
source ~/UDISE_Data/venv/bin/activate
python3 ~/udise_student_manager.py
```

---

## Script 2: `udise_data_processor.py`

**Purpose:** Clean and analyze downloaded student data

**When to run:**
- After running `udise_student_manager.py`
- Before making manual edits in Excel
- To generate summary statistics
- To find data quality issues

**What it does:**
- Standardizes column names (lowercase, no spaces)
- Cleans phone numbers (removes non-digits)
- Normalizes gender values (Male/Female)
- Removes completely empty rows
- Finds duplicates (admission numbers)
- Detects missing names/admission numbers
- Saves cleaned version with timestamp

**Output:**
- `Student_Data_Cleaned_[timestamp].xlsx` in `~/UDISE_Data/`
- Multiple analysis sheets: All_Students, Class_Summary, Gender_Summary, Issues_Found

**Example:**
```bash
python3 ~/udise_data_processor.py
```

---

## Script 3: `excel_helper_functions.py`

**Purpose:** Reusable Python functions for Excel operations

**When to import:** When writing custom scripts

**Functions included:**

| Function | Purpose | Example |
|----------|---------|---------|
| `add_student(df, new_student_data)` | Add new row to DataFrame | `df = add_student(df, {'Admission_No': '2024001', 'Name': 'Rahul'})` |
| `update_student(df, admission_no, update_dict)` | Update existing record | `df, found = update_student(df, '2024001', {'Class': '10A'})` |
| `find_student(df, column, value)` | Search students | `results = find_student(df, 'Name', 'Rahul')` |
| `merge_duplicates(df)` | Find duplicate records | `dupes = merge_duplicates(df)` |
| `validate_data(df)` | Check data quality | `report = validate_data(df)` |
| `export_to_csv(df)` | Save as CSV with timestamp | `csv_path = export_to_csv(df)` |
| `export_to_excel_multi(df)` | Save multi-sheet Excel | `excel_path = export_to_excel_multi(df)` |
| `backup_excel(filepath)` | Create timestamped backup | `backup = backup_excel('master.xlsx')` |
| `generate_student_id(df)` | Auto-generate IDs for blank rows | `new_ids = generate_student_id(df)` |
| `split_by_class(df)` | Save each class as separate file | `files = split_by_class(df)` |

**How to use in your script:**
```python
import sys
sys.path.insert(0, '/home/piyush')
from excel_helper_functions import *

# Now use functions
df = pd.read_excel('~/UDISE_Data/UDISE_Student_Master.xlsx')
df = add_student(df, {'Admission_No': '2024050', 'Name': 'Rahul', 'Class': '10'})
df.to_excel('~/UDISE_Data/UDISE_Student_Master.xlsx', index=False)
```

---

## Script 4: `school_time_table.py` (Original — Broken)

**Status:** ❌ Has syntax error (unterminated triple-quoted string on line 123)

**Issue:** Original version too complex, mixed too many features, docstring mismatch.

**See:** `references/time-table-session-notes.md` for **corrected minimal version** that works.

**Quick fixed version (copy-paste):**
```python
import pandas as pd

schedule = [
    ("10:00 AM - 11:00 AM", "Period 1", "Regular Class"),
    ("11:00 AM - 11:30 AM", "Tea Break", "Break"),
    # ... add other slots
]

df = pd.DataFrame(schedule, columns=["Time", "Activity", "Details"])
df.to_excel("/home/piyush/Simple_Time_Table.xlsx", index=False)
print("✓ Created Simple_Time_Table.xlsx")
```

---

## Script 5: Instagram Image Generator (Generated on-demand)

**No persistent script** — code generated and executed in-session to produce `instagram_time_table.jpg`.

**To regenerate with modifications:**
```python
from PIL import Image, ImageDraw, ImageFont

# ... reuse code from references/instagram-time-table-post.md
```

**Customizable variables:**
- `time_slots` list — modify periods/times
- Colors — `#0d6efd` (blue), `#198754` (green)
- Footer text — change school name
- Header gradient — adjust RGB values

---

## When to Run Each Script — Flowchart

```
START
  ↓
 monsoon / new academic year?
  ├─ Yes → Run udise_student_manager.py (download fresh data)
  └─ No → Have existing UDISE_Student_Master.xlsx?
           ├─ Yes → Make manual edits directly in Excel
           └─ No → Run udise_student_manager.py first

After download:
  ↓
 Run udise_data_processor.py (clean & analyze)

Need custom operation?
  ↓
 Write new script importing excel_helper_functions.py

Need to share schedule on social media?
  ↓
 Run Instagram generator code (see references) OR use simple image

Need automated monthly download?
  ↓
 Set up cron job calling udise_student_manager.py with --headless
```

---

## Expected Outputs

| Script | Primary Output | Secondary Outputs |
|--------|---------------|-------------------|
| `udise_student_manager.py` | `UDISE_Student_Master.xlsx` | Chrome browser session, downloaded raw files |
| `udise_data_processor.py` | `Student_Data_Cleaned_[ts].xlsx` | Console summary report |
| `school_time_table.py` | `School_Time_Table.xlsx` | (If fixed) 5-sheet workbook |
| Instagram generator | `instagram_time_table.jpg` | None |

---

## Automation Mode Tips

### For Cron/Scheduled Runs:
```bash
# Add to crontab -e
0 2 1 * * cd /home/piyush/UDISE_Data && source venv/bin/activate && python3 udise_student_manager.py --headless --no-browser
```

**Flags to implement** (add to scripts if needed):
- `--headless` — don't show browser window
- `--no-prompt` — use environment variables only
- `--skip-existing` — don't re-download if file exists
- `--backup` — create backup before updating master

---

## Debug Mode

If a script fails:

1. **Add logging:**
```python
import logging
logging.basicConfig(filename='debug.log', level=logging.DEBUG)
```

2. **Run with Python verbose:**
```bash
python3 -v script.py 2>&1 | tee debug_output.txt
```

3. **Take screenshot on error (Selenium):**
```python
driver.save_screenshot('error_screenshot.png')
```

---

## File Locations Summary

```
~/ (home directory)
├── udise_student_manager.py              ← Main (run this)
├── udise_data_processor.py               ← After download
├── excel_helper_functions.py             ← Import in custom scripts
├── school_time_table.py                  ← (broken; see fixed version)
├── UDISE_User_Guide.md                   ← Hindi/Gujarati instructions
│
├── UDISE_Data/                           ← All data goes here
│   ├── venv/                             ← Virtual environment
│   ├── UDISE_Student_Master.xlsx         ← MAIN DATABASE
│   ├── Student_Data_Cleaned_*.xlsx       ← Cleaned versions
│   ├── ReportCards/                      ← Individual HTML reports
│   └── cron.log                          ← Scheduler logs
│
└── .hermes/skills/productivity/
    └── school-records-automation/
        ├── SKILL.md                       ← This skill guide
        ├── references/
        │   ├── instagram-time-table-post.md
        │   ├── time-table-session-notes.md
        │   ├── scripts-reference.md       ← This file
        │   └── udise-portal-specifics.md
        └── templates/
            └── excel-structure.md
```

---

*Last updated: 2026-05-08 | For Piyush Sahib*