HIV Program Indicators Tool

A comprehensive Streamlit-based web application for processing SmartCare Pro exports to generate HIV program indicators and clinical dashboards for HIV treatment programs.

This tool processes SmartCare Pro Excel exports to calculate key HIV program indicators following PEPFAR/WHO standards. It provides real-time analysis of treatment outcomes, viral load cascades, and patient management metrics to support clinical decision-making and program monitoring.

• TX_CURR - Current treatment status with age disaggregation (<15 and 15+ years)
• TX_PVLS - Viral load cascade (eligible, documented, suppressed) by age groups
• Retention Analysis - 6-month and 12-month retention rates
• Appointment Management - Missed, due, and upcoming appointment tracking

• SmartCare Pro Integration - Direct processing of ART Register and QAQI Report exports
• Data Validation - Automatic validation of column structures and data types
• Error Handling - Robust error handling for file operations and data processing
• Memory Optimization - Efficient processing of large datasets

• CSV Downloads - Export patient lists and summary reports
• Print-Friendly Reports - Formatted summary reports for clinical use
• Custom Styling - Consistent branding and professional appearance

• Python 3.8 or higher
• SmartCare Pro system access for data exports

1. Clone the repository:

git clone <repository-url>
cd hiv-indicators-tool

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Run the application:

streamlit run app.py

5. Open your browser to http://localhost:8501

1. Export from SmartCare Pro:

   • Generate ART Register Report (Excel format)
   • Generate QAQI Report (Excel format)

2. Upload to Tool:

   • Use the file upload interface
   • Files are automatically validated upon upload

3. Review Results:

   • View calculated indicators in real-time
   • Download patient lists and reports as needed

• Required Columns: Patient ID, TX_CURR status, demographics, ART start dates
• Format: Excel (.xlsx/.xls) with headers starting at row 7
• Content: Active patient treatment data

• Required Columns: TX_PVLS indicators (eligible, documented, suppressed)
• Format: Excel (.xlsx/.xls) with headers starting at row 5
• Content: Viral load testing and suppression data

hiv-indicators-tool/
├── app.py                      # Main Streamlit application
├── config/
│   ├── settings.py            # Application settings
│   └── facility_config.py     # Facility-specific configurations
├── processors/
│   ├── art_processor.py       # ART Register data processing
│   └── qaqi_processor.py      # QAQI Report data processing
├── utils/
│   ├── file_utils.py          # File handling utilities
│   └── report_generator.py    # Report generation functions
├── components/
│   └── ui_components.py       # Reusable UI components
├── tests/
│   ├── test_processors.py     # Unit tests for processors
│   └── test_utils.py          # Unit tests for utilities
├── requirements.txt           # Python dependencies
└── README.md                  # This file

• Line Length: Maximum 79 characters (PEP 8)
• Formatting: Use black for code formatting
• Linting: Use flake8 for code linting
• Documentation: Google-style docstrings for all functions

• Framework: pytest for unit testing
• Coverage: Write tests for success and error scenarios
• Location: All tests in /tests/ directory
• Execution: Run pytest from project root

• Separation of Concerns: Business logic separate from UI code
• Modularity: Related functionality grouped in appropriate modules
• Error Handling: Comprehensive exception handling throughout
• Performance: Caching with @st.cache_data for data processing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow the development guidelines above
4. Add tests for new functionality
5. Ensure all tests pass (pytest)
6. Format code with black and check with flake8
7. Commit changes (git commit -m 'Add amazing feature')
8. Push to branch (git push origin feature/amazing-feature)
9. Open a Pull Request

• Data Protection: Patient data files are excluded from version control
• Local Processing: All data processing occurs locally
• No Data Storage: No patient data is stored by the application
• Secure Handling: Temporary files are automatically cleaned up

• File Upload Errors: Ensure Excel files match expected SmartCare Pro format
• Missing Columns: Verify export includes all required data columns
• Performance Issues: Use chunking for very large datasets (>10,000 patients)

For technical issues or feature requests, please open an issue in the repository.

This project is licensed under the MIT License - see the LICENSE file for details.

This tool is designed for healthcare program monitoring and reporting purposes. It should not be used for individual patient care decisions. Always verify calculations and consult with clinical staff for patient management decisions. Ensure compliance with local data protection and privacy regulations.