pydhis2 0.2.0

Reproducible DHIS2 Python SDK for LMIC scenarios

Quite possibly the most complete python toolkit for DHIS2
— a modern SDK designed for reproducible workflows in LMIC scenarios.

---

🎉 pydhis2 is officially released!

🚀 Getting Started

1. Installation

pip install pydhis2

2. Run the Quick Demo

Use the CLI to run a quick demo that connects to a live DHIS2 server and fetches some data. This is the best way to verify your installation.

# Check installation
py -m pydhis2 version

# Run quick demo
py -m pydhis2 demo quick

You should see output confirming a successful connection and data retrieval:

============================================================
pydhis2 Quick Demo
============================================================
=== Testing: https://demos.dhis2.org/dq ===
   Found working API endpoint!
   System: Data Quality
   Version: 2.38.4.3
Found working server: https://demos.dhis2.org/dq

2. Querying Analytics data...
Retrieved 1 data records
...
Demo completed successfully!

📖 Basic Usage

Here's how to use pydhis2 in your own script. Create a file named examples/my_analysis.py:

import asyncio
import sys
from pydhis2 import get_client, DHIS2Config
from pydhis2.core.types import AnalyticsQuery

# Get client classes
AsyncDHIS2Client, SyncDHIS2Client = get_client()

async def main():
    # 1. Configure connection (using a working demo server)
    config = DHIS2Config(
        base_url="https://demos.dhis2.org/dq",
        auth=("demo", "District1#")
    )
  
    async with AsyncDHIS2Client(config) as client:
        # 2. Define query parameters
        query = AnalyticsQuery(
            dx=["b6mCG9sphIT"],   # Data element: ANC 1 Outlier Threshold
            ou="qzGX4XdWufs",    # Org unit: A-1 District Hospital
            pe="2023"            # Period: Year 2023
        )

        # 3. Fetch data and convert to a Pandas DataFrame
        df = await client.analytics.to_pandas(query)

        # 4. Analyze and display
        print("Data fetched successfully!")
        print(f"Retrieved {len(df)} records.")
        print("\n--- Data Preview ---")
        print(df.head())

if __name__ == "__main__":
    # Fix for asyncio on Windows
    if sys.platform == 'win32':
        asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
    asyncio.run(main())

Run your script from the terminal:

py examples/my_analysis.py

🔧 DHIS2 Server Configuration

The examples use public DHIS2 demo servers by default. To connect to your own server, you can configure it in one of the following ways:

1. Environment Variables (Recommended)

set DHIS2_URL=https://your-dhis2-server.com
set DHIS2_USERNAME=your_username
set DHIS2_PASSWORD=your_password

# Then run any script
py examples/my_analysis.py

2. In Your Script

config = DHIS2Config(
    base_url="https://your-dhis2-server.com",  
    auth=("your_username", "your_password")
)

3. Using the CLI

py -m pydhis2 config --url "https://your-dhis2-server.com" --username "your_username"

📚 More Examples

The repository includes several scripts demonstrating different use cases:

Script	Description
quick_demo.py	Basic functionality and connection testing
demo_test.py	Comprehensive API testing with HTML reports
real_health_data_demo.py	Health data analysis with quality metrics
my_analysis.py	A template for your own custom analysis

You can run any of them using the CLI or as standalone scripts:

# Run a specific demo via CLI
py -m pydhis2 demo health

# Or run the Python script directly
py examples/real_health_data_demo.py

🖥️ Command Line Interface

pydhis2 provides a powerful CLI for common data operations.

Data Operations (Implementation in Progress):

# Pull analytics data
py -m pydhis2 analytics pull --dx "b6mCG9sphIT" --ou "qzGX4XdWufs" --pe "2023" --out analytics.parquet

# Pull tracker events
py -m pydhis2 tracker events --program "program_id" --out events.parquet

# Run data quality review
py -m pydhis2 dqr analyze --input analytics.parquet --html dqr_report.html --json dqr_summary.json

For detailed CLI usage, run py -m pydhis2 --help.

🚀 Reproducible Workflow: Using Project Templates

Beyond being a library, pydhis2 promotes a standardized and reproducible workflow crucial for scientific research. To jumpstart your analysis, we provide a project template powered by Cookiecutter.

Why use the template?

• Standardization: Every project starts with the same clean, logical structure. No more guessing where configs or scripts are.
• Rapid Start: Generate a fully functional project skeleton with a single command.
• Best Practices: The template includes pre-configured settings for DHIS2 connection, data quality pipelines, and environment management.
• Focus on Analysis: Spend less time on boilerplate setup and more time on your research.

Usage

1. Install Cookiecutter:

   pip install cookiecutter
   

2. Generate your project: Run Cookiecutter and point it to the pydhis2 template. It will ask you a few questions to personalize your new project.

   # Run from the root of the pydhis2 repository
   cookiecutter pydhis2/templates
   

   You'll be prompted for details like your project name and author info:

   project_name [My DHIS-2 Analysis Project]: Malaria Analysis Malawi
   project_slug [malaria_analysis_malawi]:
   author_name [Your Name]: Dr. Evans
   author_email [[e-mail]]: [e-mail]
   

3. Get a complete, ready-to-use project structure:

   malaria-analysis-malawi/
   ├── configs/          # DHIS-2 & DQR configurations
   ├── data/             # For raw and processed data
   ├── pipelines/        # Your analysis pipeline definitions
   ├── scripts/          # Runner scripts
   ├── .env.example      # Environment variable template
   └── README.md         # A dedicated README for your new project
   

Now you can cd into your new project directory and start your analysis immediately!

---

📊 Supported Endpoints

Endpoint	Read	Write	DataFrame	Pagination	Streaming
Analytics	✅	-	✅	✅	✅
DataValueSets	✅	✅	✅	✅	✅
Tracker Events	✅	✅	✅	✅	✅
Metadata	✅	✅	✅	-	-

---

📋 Compatibility

• Python: ≥ 3.9
• DHIS2: ≥ 2.36
• Platforms: Windows, Linux, macOS

---

📄 License

Apache License 2.0 - see the LICENSE file for details.

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details. Also, have a look at our Code of Conduct.

---

📞 Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions