Skip to content

README.md

Latest commit

 

History

History
114 lines (84 loc) · 4.51 KB

README.md

File metadata and controls

114 lines (84 loc) · 4.51 KB

Coverage Analysis Tools

This project contains tools for analyzing delivery coverage data and generating visualizations and statistics.

Project Structure

The project is organized into the following directories:

Root Level Entry Points

  • run_coverage.py - Main entry point for generating Coverage HTML reports and visualizations
  • run_report_generator.py - Launches a GUI interface for generating additional specialized reports

Source Code Organization

  • src/ - Contains all the source code organized into modules:

    • coverage_master.py - The main command that coordinates the coverage analysis workflow

    • create_delivery_map.py - Creates an interactive map of delivery units

    • create_statistics.py - Generates statistical analysis and visualizations

    • create_flw_views.py - Generates Field-Level Worker performance analysis

    • opportunity_comparison_statistics.py - Generates comparison statistics between opportunities

    • report_generator_gui.py - GUI interface for report generation

    • models/ - Data models for coverage analysis:

      • coverage_data.py - Main coverage data model
      • delivery_unit.py - Delivery unit data model
      • flw.py - Field-Level Worker data model
      • service_delivery_point.py - Service delivery point data model
      • service_area.py - Service area data model

    • utils/ - Utility functions and data handling:

      • data_loader.py - Data loading utility functions
      • superset_export.py - Superset data export utilities

    • reports/ - Specialized report generation modules:

      • base_report.py - Base class for report generation
      • microplan_review.py - Microplan review report generator
      • flw_visit_count.py - FLW visit count analysis report

Documentation

  • Coverage Data Guide - Comprehensive guide explaining the data flow into the CoverageData object and data dictionary for all models

Supporting Directories

  • tests/ - Contains unit tests for the application
  • data/ - Directory for input data files

Requirements

This requires numerous Python packages, You can install them with:

pip install -r requirements.txt

Usage

Setup a .env file

You will need to create a .env file that includes:
COMMCARE_API_KEY COMMCARE_USERNAME USE_API=TRUE or False OPPORTUNITY_DOMAIN_MAPPING={"ZEGCAWIS | CHC Givewell Scale Up": "ccc-chc-zegcawis-2024-25", "COWACDI | CHC Givewell Scale Up": "ccc-chc-cowacdi-2024-25", "Name of Opp in Connect": "Name of project space in HQ"} SUPERSET_URL SUPERSET_USERNAME SUPERSET_PASSWORD SUPERSET_QUERY_ID

Using the Entry Point Script

The simplest way to use these tools is through the main entry point script:

python run_coverage.py

This will:

  1. Load environment variables from .env file (including API credentials and opportunity-domain mappings)
  2. Check if USE_API is set to True in environment variables:
    • API Mode: Load service delivery data from Superset, then fetch delivery unit data from CommCare API for each opportunity found in the CSV
    • Local File Mode: Prompt you to select input Excel and CSV files (if there is only one excel and/or one csv, it will use those without asking)
  3. Create coverage data objects for each project/opportunity (Local File Mode will only let you select on xls and csv, API mode must be used for multiple oppurtunities)
  4. Create a timestamped output directory (unless custom directory specified)
  5. For each project, generate outputs in separate subdirectories:
    • Generate the delivery map
    • Generate the statistics report
    • Generate the FLW analysis report
  6. Create a main index HTML dashboard page linking to all project reports
  7. Automatically open the dashboard in your default web browser

Input Files

The tools expect input files:

  1. Excel File (Delivery Unit Data Exported from CommCareHQ if using local mode) - Contains delivery unit data with the following columns like:

    • du_id
    • service_area or service_area_number
    • buildings
    • delivery_count
    • delivery_target
    • du_status
    • owner_name (used as FLW identifier)
    • WKT (geographic boundaries)
    • surface_area

  2. CSV File (Service Delivery Data exported from Connect Superset) - Contains service delivery points with columns like:

    • lattitude, longitude (coordinates)
    • flw_id, flw_name (field worker identifiers)
    • service_date or date (when available)

When in API mode, if the Superset query contains multiple oppurtunities, Delivery Unit data for each oppurtunityw will be retrieved.