Skip to content

USAGE_GUIDE.md

Latest commit

 

History

History
264 lines (199 loc) · 6.04 KB

USAGE_GUIDE.md

File metadata and controls

264 lines (199 loc) · 6.04 KB

Complete Usage Guide - Kabale Voter Data System

🎉 Batch Processing Complete!

All 54 PDF files have been processed successfully!

📊 What You Have Now

1. Raw Data (54 files each)

  • input/ - Original PDF files
  • output/ - OCR text files
  • processed/ - CSV files with extracted voter data
  • logs/ - Processing logs

2. Google Sheets Integration

  • Upload to Google Sheets with charts
  • Interactive dashboards
  • Parish and station analysis
  • Gender analysis

3. Searchable Web Interface

  • Real-time search
  • Filter by name, gender, age, station, parish
  • Export to CSV
  • Beautiful modern UI

🚀 Quick Start - Upload to Google Sheets

Step 1: Verify Credentials

Your credentials file is ready: credentials.json.json

Step 2: Run the Enhanced Uploader

python google_sheets_enhanced.py

This will create a single Google Spreadsheet with 5 sheets:

  1. All Voters - Complete dataset (filterable & sortable)
  2. Dashboard - Summary statistics with key metrics
  3. By Polling Station - Detailed breakdown by station
  4. By Parish - Parish-level aggregation
  5. Gender Analysis - Gender balance analysis

Features:

  • 📊 Color-coded headers
  • 🔍 Built-in filters
  • 📈 Automatic statistics
  • 🎨 Beautiful formatting
  • 🔗 Shareable link (view-only)

🌐 Launch the Web Interface

Start the Server

python web_interface.py

Access the Interface

Open your browser to: http://localhost:5000

Features:

  • 🔍 Real-time search - Search by name instantly
  • 🎚️ Advanced filters - Filter by gender, station, parish, age range
  • 📊 Live statistics - See male/female counts as you filter
  • 💾 Export - Download filtered results as CSV
  • 🎨 Modern UI - Beautiful gradient design
  • 📱 Responsive - Works on mobile and desktop

📈 Data Analysis Features

In Google Sheets:

  1. Dashboard Sheet

    • Total voters count
    • Male/Female breakdown
    • Age distribution (18-35, 36-60, 60+)
    • Number of polling stations

  2. By Polling Station Sheet

    • Voter count per station
    • Gender breakdown & percentages
    • Age group distribution
    • Parish and division mapping

  3. By Parish Sheet

    • Parish-level aggregation
    • Average voters per station
    • Total statistics per parish

  4. Gender Analysis Sheet

    • Sorted by gender gap
    • Balance status (Balanced/Male-Heavy/Female-Heavy)
    • Percentage breakdowns

Polling Station Metadata Included:

  • District code
  • Constituency
  • Sub-county
  • Parish code and name
  • Station code and name
  • Official voter counts for comparison

📁 File Structure

Voter-extractor/
├── input/                      # 54 PDF files
├── output/                     # 54 OCR text files
├── processed/                  # 54 CSV files
├── logs/                       # Processing logs
├── voter_extractor.py          # Main OCR script
├── google_sheets_enhanced.py   # Enhanced Google Sheets uploader
├── web_interface.py            # Web search interface
├── credentials.json.json       # Google credentials
├── polling-station-data.txt.txt # Official station metadata
├── config.json                 # Station mapping
└── .env                        # API keys

🎯 Common Tasks

Task 1: Upload to Google Sheets

python google_sheets_enhanced.py

Result: Single spreadsheet with 5 analyzed sheets + shareable link

Task 2: Search Voter Data Locally

python web_interface.py

Result: Web interface at http://localhost:5000

Task 3: Re-process a Single PDF

# Place PDF in input/ folder
python voter_extractor.py --batch

Task 4: Export Filtered Data

  1. Open web interface
  2. Apply your filters
  3. Click "Export CSV"
  4. File downloads to your browser

📊 Data Fields

Each voter record contains:

Field Description
Name Full name
Gender M/F
Dob Date of birth (DD-MM-YYYY)
Age Calculated age
Village Village name
Polling Station Station name
Parish Parish name
Division Division (Central/Northern/Southern)

🎨 Visualization & Analysis Options

In Google Sheets:

✅ Built-in filters on all sheets ✅ Sortable columns ✅ Color-coded headers ✅ Frozen header rows ✅ Auto-resized columns ✅ Percentage calculations ✅ Statistical summaries

In Web Interface:

✅ Live search ✅ Multiple filters simultaneously ✅ Instant statistics update ✅ Export functionality ✅ Gender color coding (Blue=Male, Pink=Female) ✅ Responsive design

🔧 Advanced Features

Custom Analysis in Google Sheets

After uploading, you can:

  1. Create pivot tables
  2. Add charts (bar, pie, line)
  3. Create custom formulas
  4. Share with specific people
  5. Download as Excel
  6. Embed in websites

Custom Filters in Web Interface

Combine multiple filters:

  • Name contains "AGABA"
  • Gender = Male
  • Age 25-40
  • Parish = "RUTOOMA"
  • Instant results!

📞 Next Steps

  1. ✅ Run the Google Sheets uploader

    python google_sheets_enhanced.py

  2. ✅ Launch the web interface

    python web_interface.py

  3. ✅ Share the Google Sheets link with your team

  4. ✅ Use the web interface for quick searches

🎊 Summary

You now have a complete voter data management system with:

📊 54 polling stations fully processed 📈 Enhanced Google Sheets with 5 analysis sheets 🌐 Searchable web interface with real-time filtering 🎨 Beautiful visualizations and statistics 💾 Export capabilities for further analysis 🔍 Multi-criteria search functionality

All data is clean, organized, and ready for analysis!

💡 Tips

  • Use Google Sheets for sharing and collaboration
  • Use Web Interface for quick local searches
  • Export filtered results for reports
  • Combine filters for detailed analysis
  • Check logs/ folder if any issues

Enjoy your data analysis! 🎉