Skip to content

TOOLS_GUIDE.md

Latest commit

 

History

History
316 lines (227 loc) · 7.07 KB

TOOLS_GUIDE.md

File metadata and controls

316 lines (227 loc) · 7.07 KB

DNM Campaign Tools - Quick Reference Guide

Dan Musinguzi Nabaasa 2026

Extraction Progress Update

Status: V4 extraction running (30/54 files complete - 56%) Location: processed_v4/ folder Expected completion: Shortly

1. Manual Voter Manager

Purpose: Add missing voters or edit existing voter records

Usage

python manual_voter_manager.py

Features

  1. Add New Voter (Interactive)

    • Enter voter details step-by-step
    • Automatic age calculation from DOB
    • Prevents duplicates
    • Auto-saves to correct polling station CSV

  2. Search for Voter

    • Find voters by name (fuzzy search)
    • View complete voter information
    • Check if someone is in the register

  3. View Statistics

    • Total voters count
    • Gender breakdown
    • Voters per polling station

Example: Add Yourself to Register

$ python manual_voter_manager.py

1. Add new voter (interactive)

Full Name: DAN MUSINGUZI NABAASA
Gender: M
Date of Birth: 15-03-1990
Village: BUTARE
Polling Station: AMIIZI MARUNGI CENTRE
Parish: RUTOOMA
Division: KABALE NORTHERN

✓ Voter added successfully!

Example: Search for Someone

2. Search for voter

Enter name: NABAASA

Found 1 match:
1. DAN MUSINGUZI NABAASA
   DOB: 15-03-1990 | Age: 35 | Gender: M
   Village: BUTARE | Station: AMIIZI MARUNGI CENTRE

2. Contact Matcher V2

Purpose: Match contact lists (phone numbers, emails) with verified voters

Directory Structure (Auto-Created)

Contacts/
├── Matched/      ← Successfully matched contacts
├── Unmatched/    ← Contacts not found in voter register
└── Logs/         ← Matching history and statistics

Usage

# Basic usage
python contact_matcher_v2.py <file> <name_column> [phone_column] [email_column]

# Examples
python contact_matcher_v2.py contacts.csv Name Phone Email
python contact_matcher_v2.py "DNM Master Contact Database.xlsx" full_name mobile

# Scan for contact files in directory
python contact_matcher_v2.py --scan

What It Does

  1. Loads your contact file (CSV or Excel)
  2. Matches each contact against verified voters using:
    • Exact name match
    • Fuzzy name matching (handles typos, variations)
    • 75%+ similarity threshold
  3. Creates two files:
    • Matched/ - Contacts found in voter register (with full voter details)
    • Unmatched/ - Contacts not found (for manual review)
  4. Saves detailed log of matching process

Example Output

MATCHING CONTACTS FROM: my_contacts.csv
=============================================

Loaded 150 contacts from my_contacts.csv

[1/150] MATCHED: Dan Nabaasa → DAN MUSINGUZI NABAASA (92.5%)
[2/150] MATCHED: John Ahimbisibwe → AHIMBISIBWE JOHN (100.0%)
[3/150] UNMATCHED: Mary Unknown

✓ Saved 120 matched contacts to: my_contacts_matched_20251109.csv
✓ Saved 30 unmatched contacts to: my_contacts_unmatched_20251109.csv

MATCHING SUMMARY
=============================================
Total Contacts: 150
Matched: 120 (80.0%)
Unmatched: 30 (20.0%)

3. File Organization

Current Structure

D:\Voter-extractor/
├── input/              ← Original 54 PDF files
├── processed_v4/       ← CLEAN voter data (V4 extractor)
├── Contacts/           ← Contact matching (auto-created)
│   ├── Matched/
│   ├── Unmatched/
│   └── Logs/
├── logs/               ← Extraction logs
├── dnm_data.db         ← Main database
│
├── manual_voter_manager.py    ← Add/edit voters
├── contact_matcher_v2.py      ← Match contacts
├── voter_extractor_v4.py      ← Final extractor
│
└── app.py              ← Web interface (run with: python app.py)

Files to Move to Contacts Folder

If you have contact files scattered around, move them to the Contacts/ folder:

# Example: Move contact files
move "my_contacts.csv" Contacts/
move "phone_list.xlsx" Contacts/

Then scan for them:

python contact_matcher_v2.py --scan

4. Common Tasks

Task 1: Find Yourself in the Register

python manual_voter_manager.py
# Choose option 2 (Search)
# Enter your name

If not found → Use option 1 (Add new voter)

Task 2: Add Missing Voters from a List

Option A: Use contact matcher to identify who's missing

python contact_matcher_v2.py your_list.csv Name
# Check Unmatched/ folder for who's not in register

Option B: Add them manually

python manual_voter_manager.py
# Use option 1 repeatedly

Task 3: Match Phone Numbers with Voters

# If you have a CSV with Name and Phone columns
python contact_matcher_v2.py contacts.csv Name Phone

# Check Contacts/Matched/ for results

Task 4: Check Extraction Progress

# Count files processed
dir /b processed_v4\*.csv | find /c /v ""

# View extraction log (latest file in logs/ folder)

5. Next Steps (After Extraction Completes)

  1. Verify Data Quality

    python analyze_extraction_quality.py

  2. Update Main Database

    • The web interface (app.py) will need to load V4 data
    • Script will be provided

  3. Match All Contacts

    # Match DNM Master Database
python contact_matcher_v2.py "DNM Master Contact Database.xlsx" Name Phone Email

# Match any other contact lists
python contact_matcher_v2.py --scan  # Find all contact files

  4. Manual Review

    • Add yourself if not found
    • Add any critical team members missing
    • Review Contacts/Unmatched/ for important people to add

6. Troubleshooting

"No voters found" when searching

  • Extraction may still be running
  • Try searching in original processed/ folder
  • Name might be spelled differently (use fuzzy search)

Excel file not working

pip install openpyxl

Want to see all voters from a station

# Open the CSV file directly
type "processed_v4\AMIIZI MARUNGI CENTER_voters_v4.csv"

Need to edit a voter's information

  • Use manual_voter_manager.py
  • Search for voter → Edit option (coming soon)
  • Or edit CSV file directly

7. Extraction Progress Monitoring

Current: 30/54 files processed (56%)

To check progress:

# Count processed files
dir /b processed_v4\*.csv | find /c /v ""

# Check if still running
tasklist | findstr python

When extraction completes, you'll see:

EXTRACTION COMPLETE - V4 FINAL
======================================================================
Files processed: 54
Successful: 54
Total voters extracted: ~15,000-18,000
Expected (official): 29,348
Extraction rate: 50-60%
======================================================================

Support Files

Tools Ready: ✓ Manual Voter Manager | ✓ Contact Matcher V2 Extraction: Running (30/54 complete) Next: Complete extraction → Match contacts → Update database