DHIS2 Climate & Health Academy 2026 Wiki/AI: Technical Reference and Implementation Guide

Implementation - Implémentation Climate
,
1

While there is a high-level overview of the Climate & Health topics in dac2026 here: 🌍 DAC2026 Summary & Wiki/AI: Climate & Health. This technical guide is based on the DHIS2 Climate & Health Academy YouTube Playlist and is hopefully helpful for the community members interested in experimenting and learning more.

:warning: Note: This summary was generated and reviewed by the dhis2 docs Ask AI tool and may contain errors. As this is a Wiki post, we encourage you to edit and improve this content with your own expertise, or reply with your questions for discussion!

This reference guide provides technical specifications, configuration parameters, and environmental setup steps for DHIS2 implementers, database administrators, and data scientists deploying climate-informed disease prediction models, based on the DHIS2 Climate & Health Academy 2026. Please use this as a secondary guide to the actual references: https://www.youtube.com/playlist?list=PLo6Seh-066Ry9CiQLMEUSmkIbXegnwln7

How to Use This Guide

This guide is designed as a practical, hands-on “cheat sheet” that distills the CLI commands, metadata rules, coding interfaces, and environment requirements discussed throughout the DHIS2 Climate & Health Academy YouTube Playlist.

You can use this document as a companion reference while watching the Academy sessions by following this thematic and chronological mapping:

1. Initial Setup & Environment (Watch Videos 1 & 4)

  • Sessions to watch: “What’s New in DHIS2: Climate & Health” and “Chap and Predictive Modeling Deep-dive.”
  • Using the Guide: Refer to Part 1: Monday - Day 1 during setup. This section provides the exact command-line instructions to install uv and global chap-core packages demonstrated on screen.
  • Key Detail: Pay close attention to the WSL2 (Windows Subsystem for Linux 2) operating system requirement in the guide if you are developing on a Windows host machine [Developer Setup].

2. Data Ingestion & Metadata Rules (Watch Video 3)

  • Session to watch: “Climate Data Integration Deep-dive: Strategies, Approaches & Tools.”
  • Using the Guide: Refer to Part 1: Tuesday - Day 2 and Part 2: Section A. Configure your DHIS2 Maintenance App elements with the precise metadata rules specified (such as zeroIsSignificant = true and aggregationLevel = all) to prevent spatial and temporal data loss [Climate App User Guide].
  • Critical Implementation Step: Remember the “manual trigger” constraint detailed in the guide: newly imported climate datasets are completely invisible to CHAP and the Modeling App until you manually run “Analytics Table Generation” inside the DHIS2 Data Administration App [Climate App User Guide].

3. Building & Deploying Models (Watch Video 4)

  • Session to watch: “Chap and Predictive Modeling Deep-dive” (focusing on the minimalist coding and configuration walkthroughs).
  • Using the Guide: Use Part 1: Wednesday - Day 3 and Part 2: Section C as code templates. The guide provides the standard MLproject YAML configuration schema and the Python scripts for both the train and predict interfaces shown during the live demonstration [MLproject Configuration; Predict and Train].
  • Technical “Gotcha”: If you plan to run local feature attribution evaluations, the guide details a strict naming constraint: the serialized model output file created during training must be named literally model (with no file extension) for the LIME engine to load the state [explain-lime Reference].

4. Advanced GIS & Preprocessing (Watch Videos 3, 8 & 9)

  • Sessions to watch: “Climate Data Integration Deep-dive” and the country-specific early warning sessions.
  • Using the Guide: Refer to Part 2: Section A when presenters from Rwanda, Nepal, or Togo discuss high-resolution satellite covariates. The guide outlines the technical preprocessing steps used in these countries, including regression-based neighborhood smoothing to remediate cloud-cover gaps and 30-meter spatial downscaling for narrow valley mosquito breeding vectors [French Deep-dive; Early Warning for Climate Sensitive Diseases].

5. Evaluation, Trust-Building & Automation (Watch Videos 4 & 3)

  • Sessions to watch: The final segments of both the “Modeling Deep-dive” and the “Integration Deep-dive.”
  • Using the Guide:
    • Validation Metrics: Refer to Part 1: Thursday - Day 4 and Part 2: Section D to understand the mathematical logic behind the CRPS and Winkler Score plots rendered inside the evaluation dashboard [Accurancy Video].
    • Automation: Utilize the CAPS (Climate Analytics Pipeline Scheduler) block in the guide to plan and script the automated, trigger-based modeling pipelines discussed by the South Sudan technical teams [Predictive Modeling Deep-dive].

Summary Table for Quick Reference

Academy Topic / Day Guide Section Key Resource / Code Snippet in Guide
Day 1: Setup & Local Tooling Part 1, Day 1 uv global installation commands and environment virtualizations [Installing Chap].
Day 2: Ingestion & Metadata Part 1, Day 2 DHIS2 Maintenance App flags and OCS pyproject.toml dependency files [Climate App User Guide; OCS Instance Guide].
Day 3: CHAP Modeling Platform Part 1, Day 3 & Part 2, Section C Standardized MLproject YAML schema and Python train/predict code blocks [MLproject Configuration; Predict and Train].
Day 4: Metrics, Plots & Automation Part 1, Day 4 & Part 2, Section D Custom probabilistic metric classes, Altair backtest plots, and the CAPS workflow [Custom Metrics Overview; Basic Plot Guide].

Part 1: Chronological & Thematic Implementation Guide

First: System Orientation, Setup & Environment Management

Initial setup requires establishing a standardized local environment for executing the Climate and Health Assessment Platform (chap-core) command-line interface (CLI) and testing models [Developer Setup].

1. Operating System Compatibility

  • Linux / macOS: Supported natively [Developer Setup].
  • Windows: Windows users must utilize WSL2 (Windows Subsystem for Linux 2) to run a Linux environment and execute the CLI tools under a supported shell [Developer Setup].

2. Installing the CLI via uv

The chap CLI is managed globally using uv. To install uv and the global chap-core package, execute:

# Install the uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install chap-core globally with Python 3.13
uv tool install chap-core --python 3.13

[Installing Chap]

Verify the global installation by outputting the help menu:

chap --help

[Installing Chap]

3. Environment Environments for Modeling

A model’s virtual execution space is declared inside its local MLproject configuration file. Models execute in one of three environments [Defining Environment]:

  • uv Environment (Python): Points to a local pyproject.toml file. Execution is handled via uv run to isolate Python dependencies [Defining Environment].
  • renv Environment (R): Points to an renv.lock file containing serialized version pins for R-based statistical packages [Defining Environment].
  • Docker Environment: Points to a pre-built Docker image hosted on a registry (e.g., ghcr.io/dhis2-chap/docker_r_inla) for environments requiring OS-level package compilation [Defining Environment].

Second: Climate Data Ingestion & Metadata Configuration

1. DHIS2 Metadata Rules

To ensure the DHIS2 Climate App and import interfaces correctly parse and preselect incoming climate parameters (e.g., rainfall, temperature), specific data element attributes must be configured in the DHIS2 Maintenance App [Climate App User Guide]:

  • zeroIsSignificant = true: This database flag forces DHIS2 to explicitly store and retain zero values (e.g., 0mm of precipitation) [Climate App User Guide]. Note: Leaving this as false causes DHIS2 to ignore zero entries to save space, producing incomplete time-series records in analytics [Analytics Zero Values; Zero Values Forums].
  • domainType = AGGREGATE: Restricts the data element to aggregate workflows [Climate App User Guide].
  • aggregationLevel = all: Configures DHIS2 to aggregate environmental covariates separately at each administrative level (e.g., facility, district, province) from raw coordinates rather than summarizing up the spatial hierarchy, which would distort environmental precision [Climate App User Guide].

2. Open Climate Service (OCS) & openEO

The Open Climate Service provides programmatic access to meteorological datasets via the openEO API [openEO Implementation].

  • Core Concepts:
    • Collections: Datasets managed as multidimensional data cubes (such as ERA5-Land or CHIRPS) [openEO Processes].
    • Processes: Standardized execution nodes (e.g., spatial aggregation, temporal filtering) [openEO Processes].
    • Process Graphs: Directed Acyclic Graphs (DAGs) representing sequence operations mapped to data cube dimensions [openEO Implementation].
    • Batch Jobs: Asynchronous processing operations executed on OCS clusters [openEO Implementation].
import openeo

# Connect to the local Open Climate Service instance
connection = openeo.connect("http://127.0.0.1:9000")

3. OCS Dependency Management

The server component requires strict dependency management configured via a non-packaged pyproject.toml file to resolve transitive dependencies securely [OCS Instance Guide]:

[project]
name = "my-climate-service"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "open-climate-service[server]==0.1.0",
]

[tool.uv]
package = false

override-dependencies = [
    "geojson-pydantic>=2.1.0",
    "zarr>=3.1.6",
    "pyarrow>=19.0",
    "xarray>=2025.12.0",
    "numpy>=2.2",
    "dask>=2024.1.0",
    "dask-geopandas>=0.4",
    "geopandas>=1.1",
    "xvec>=0.3",
    "rioxarray>=0.17",
    "pystac>=1.10",
]

[OCS Instance Guide]

:warning: Critical Implementation Step: Immediately following any climate data ingestion (whether via the Climate App, OCS, or API scripts), a system administrator must manually execute “Analytics Table Generation” in the DHIS2 Data Administration App [Climate App User Guide]. Imported climate variables will remain completely invisible to CHAP, the Modeling App, and GIS Maps until the analytics tables are fully rebuilt [Climate App User Guide].

Third: CHAP Modeling Platform

The Climate Health Analytics Platform (CHAP) enforces a standard interface separating training from prediction, permitting the integration of R or Python models [MLproject Configuration].

1. MLproject Schema Configuration

Models must declare execution entry points, file parameters, and user options inside an MLproject file [MLproject Configuration]:

name: naive_python

docker_env:
  image: python:3.13

entry_points:
  train:
    parameters:
      train_data: str
      model: str
    command: "python train.py {train_data} {model}"
  predict:
    parameters:
      historic_data: str
      future_data: str
      model: str
      out_file: str
    command: "python predict.py {model} {historic_data} {future_data} {out_file}"

user_options:
  some_option:
    title: some_option
    type: integer
    default: '10'
    description: "Some option for the model"

[MLproject Configuration]

2. The Train Interface

The train entry point consumes historical dataset files and outputs serialized model binaries [Predict and Train].

import json
import sys
import pandas as pd

def train(training_data_filename: str, model_path: str):
    # Read the standardized CSV
    df = pd.read_csv(training_data_filename)
    
    # Simple aggregation logic (acting as the train algorithm)
    stats = df.groupby("location")["disease_cases"].agg(["mean", "std"]).to_dict()
    
    # Serialize model state
    with open(model_path, "w") as f:
        json.dump(stats, f)

if __name__ == "__main__":
    train(sys.argv[1], sys.argv[2])

[Predict and Train]

3. The Predict Interface

The predict entry point reads the serialized binary and produces probabilistic outputs as individual samples [Predict and Train].

import json
import sys
import numpy as np
import pandas as pd

def predict(model_filename: str, historic_data_filename: str,
            future_data_filename: str, output_filename: str):
    # Load serialized model binary
    with open(model_filename) as f:
        stats = json.load(f)

    future_df = pd.read_csv(future_data_filename)
    n_samples = 100 # Standard prediction distribution size

    rows = []
    for _, row in future_df.iterrows():
        loc = row["location"]
        mean = stats["mean"].get(loc, 0)
        std = stats["std"].get(loc, 1) or 1
        
        # Draw samples representing predictive distribution
        samples = np.maximum(0, np.random.normal(mean, std, n_samples))
        row_data = {"time_period": row["time_period"], "location": loc}
        row_data.update({f"sample_{i}": s for i, s in enumerate(samples)})
        rows.append(row_data)

    # Output predictions in the required CHAP flat format
    pd.DataFrame(rows).to_csv(output_filename, index=False)

if __name__ == "__main__":
    predict(sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4])

[Predict and Train]

Note: Model analysis or feature explainability extensions (such as LIME) require the serialized model output file created during training to be named literally model within the active execution directory [Predict and Train].

  • Deployment Flexibility: Implementers can register new models into the Modeling App either by uploading a local ZIP file of the codebase or by pointing the backend to a remote GitHub URL [Predictive Modeling Deep-dive]. When deploying via a GitHub URL, chap-core automatically fetches the code, parses the metadata from the MLproject file, and configures the isolated execution environment on the host server [Model Templates].

Fourth: Model Evaluation, Trust-Building, and Production Automation

1. Metric Plugins & Calculations

CHAP evaluates models by comparing forecast distributions against actual observations [Custom Metrics Overview].

  • Continuous Ranked Probability Score (CRPS): Compares the cumulative distribution function (CDF) of the probabilistic forecast samples against the step-function CDF of the actual observed value [Accurancy Video]. High calibration and narrow probability bands (sharpness) produce low CRPS scores [Accurancy Video].
  • Winkler Score: Evaluates the width of prediction intervals and applies a mathematical penalty for observed values falling outside the target upper or lower percentiles [Accurancy Video].
Creating a Custom Probabilistic Metric Plugin
import numpy as np
from chap_core.assessment.metrics.base import (
    AggregationOp,
    ProbabilisticMetric,
    MetricSpec,
)
from chap_core.assessment.metrics import metric


@metric()
class MySpreadMetric(ProbabilisticMetric):
    """Computes the spread (std dev) of forecast samples."""

    spec = MetricSpec(
        metric_id="my_spread",
        metric_name="My Spread",
        aggregation_op=AggregationOp.MEAN,
        description="Standard deviation of forecast samples",
    )

    def compute_sample_metric(self, samples: np.ndarray, observed: float) -> float:
        return float(np.std(samples))

[Custom Metrics Overview]

2. Automated Pipeline Orchestration (CAPS)

The Climate Analytics Pipeline Scheduler (CAPS) automates forecast updates without manual operator intervention.

[Open Climate Service (OCS)]
       │ (Detects new meteorological data updates)
       â–Ľ
[CAPS Trigger Engine] ────► Automatically executes local bash scripts
       │
       â–Ľ
[CHAP CLI Execution] ─────► Runs local 'chap eval' and prediction binaries
       │
       â–Ľ
[DHIS2 Web API Commit] ───► Programmatically POSTs results back to data elements
       │
       â–Ľ
[System Scheduler] ───────► Triggers immediate "Analytics Table Generation"

Part 2: Technical Specifications & Data Preprocessing Reference

A. Earth Observation (EO) & Spatial Data Preprocessing

  • Cloud Cover Remediation: Optical satellite datasets (such as MODIS or Landsat) are frequently affected by cloud-cover gaps, particularly during rainy seasons. The OCS uses a regression-based neighborhood approach (using median filter smoothing) across surrounding spatial and temporal coordinates to impute missing pixels [French Deep-dive; Accurancy Video].
  • Spatial Downscaling: Standard meteorological datasets (like ERA5-Land) resolve at a coarse scale of ~9km. Local vector-breeding environments (e.g., narrow valley marshlands or irrigated rice fields) require downscaling spatial covariates to a 30-meter resolution using high-resolution digital elevation models (DEM) and land-cover maps [French Deep-dive].
  • Zonal Aggregation: Raw environmental data starts as continuous gridded raster data cubes. Before running forecasts, the OCS performs zonal aggregation (computing spatial averages and statistics within the specific administrative polygons of your DHIS2 organization units) [openEO Processes]. This produces the flat CSV layout required for CHAP training and evaluation [Custom Plots Data].

B. Post-Ingestion Database Operations

Immediately after the OCS or the Climate App imports climate covariates (precipitation, temperature) or model outputs into DHIS2 data elements, a database administrator or system scheduler must run Analytics Table Generation [Climate App User Guide].

                  [Import Climate Data]
                           │
                           â–Ľ
             [dhis2-core datavalue table]
                           │ (Data elements updated, but invisible to reporting)
                           â–Ľ
            MANUAL STEP: Run Analytics Tables ◄─── (Via Data Administration App)
                           │
                           â–Ľ
          [dhis2-core analytics tables built]
                           │
                           â–Ľ
            (Data visible to Maps and CHAP)

Without triggering this generation in the Data Administration App (or via API scheduler endpoints), newly ingested climate data remains invisible to the DHIS2 Analytics engine and the Modeling App [Climate App User Guide; Analytics Management].

C. Model Versioning & Remote Registries

  • Model Template: The foundational, unconfigured machine learning codebase (e.g., a hierarchical Bayesian model package in R, or a Random Forest model in Python) stored inside a repository containing an MLproject file [Vocabulary].
  • Configured Model (Variant): An instance of a Model Template configured directly within the DHIS2 Modeling App interface [Predictive Modeling Deep-dive]. Implementers define unique spatial lags, select specific weather covariate mappings, and configure hyperparameter values [Predictive Modeling Deep-dive].
  • Remote Git Deployment: chap-core supports remote deployment of Model Templates by querying a YAML-based approved repository list [Model Templates]. The platform reads the remote Git repository URL, parses the MLproject file, and installs all listed package dependencies dynamically inside the configured virtual container [Model Templates].
  • :warning: Explainability Tooling (LIME) Constraint: When deploying a trained model for local explainability evaluations, the serialized model file created during the training step must be named literally model (with no file extension) and placed inside the run directory. The chap explain-lime command expects this exact file name alongside the MLproject configuration file to reload the model state and execute perturbation loops [explain-lime Reference].

D. Custom Plot Plugins and Uncertainty Visualizations

Developers can write custom visualization plugins to render evaluation curves directly inside the DHIS2 Modeling App [Custom Backtest Plots].

1. Designing a Custom Backtest Plot Plugin

from typing import Optional
import pandas as pd
import altair as alt
from chap_core.assessment.backtest_plots import backtest_plot, BacktestPlotBase, ChartType

@backtest_plot(
    plot_id="my_custom_plot",              # Unique identifier (used in APIs)
    name="My Custom Plot",                 # Human-readable display name
    description="Displays observations vs predictions.",
)
class MyCustomPlot(BacktestPlotBase):
    def plot(
        self,
        observations: pd.DataFrame,
        forecasts: pd.DataFrame,
        historical_observations: Optional[pd.DataFrame] = None,
    ) -> ChartType:
        # Generate an Altair chart
        chart = alt.Chart(observations).mark_point().encode(
            x='time_period:O',
            y='disease_cases:Q'
        )
        return chart

[Basic Plot Guide]

2. Plot Execution & Output Rendering

Once registered, developers can generate plots using the CLI:

chap plot-backtest evaluation.nc my_plot.html --plot-type my_custom_plot

[Using Your Plot]

Registered plots are automatically integrated into the DHIS2 Modeling App and served to the user interface as JSON Vega specifications via the rest endpoints [Using Your Plot]:

  • GET /visualization/backtest-plots/ (Lists available plots) [Using Your Plot]
  • GET /visualization/backtest-plots/{plot_id}/{backtest_id} (Generates the visualization data) [Using Your Plot]

E. Asynchronous Job Monitoring

Model training, dataset evaluation, and remote synchronization run as asynchronous tasks managed by the chap-core worker engine [Predictive Modeling Deep-dive].

Administrators must utilize the Active Jobs monitoring page inside the DHIS2 Modeling App to:

  • Track task execution stages (e.g., training, predicting, pushing).
  • Review execution run-time performance statistics [French Deep-dive].
  • Access stdout/stderr logs directly to debug virtual environment crashes, missing parameters, or network errors when calling the Open Climate Service API.
  • View real-time progress indicators: Check the active status of asynchronous tasks (e.g., success state, running, or error state) while chap-core completes background execution cycles [Predictive Modeling Deep-dive].
  • Probabilistic Sample Output (sample_0 to sample_N): To render standard prediction intervals (such as the 10th to 90th percentile bands), the model output must generate individual sample draws (standardly 100 samples) [Expanding with Uncertainty; Running Prediction]. In a flat export, these map to rows containing unique sample numbers and their corresponding forecast estimates [Creating Evaluation].
  • NetCDF (.nc) Output Storage: CHAP compiles final backtest evaluations into standardized NetCDF (.nc) files [Output Format]. This format stores structured dimensions (time, location, quantile, split) along with the raw predictions, observations, and model configuration parameters [Output Format]. Researchers can load these files directly into Python or R to run offline statistical analyses, or use commands like plot-backtest and export-metrics to extract performance statistics [Output Format; Evaluation Workflow].

Part 3: Technical Troubleshooting, Repositories, and Resources

Implementers and developers can access the following official resources and repositories to configure, troubleshoot, and extend the climate-health integration pipeline:

0. Baseline Tooling Prerequisites

Before executing CLI commands or deploying models, verify that the host machine (or WSL2 environment) has the following baseline software installed:

1. Core Software Repositories & Toolkits

  • The DHIS2 Climate Tools Github Organization: Hosts the codebase for chap-core and the automated pipeline scheduler (CAPS) [Predictive Modeling Deep-dive].
  • The chap-models GitHub Organization: Contains over 34 community-contributed modeling templates, including R (using INLA) and Python (using Random Forest or SARIMAX) frameworks, to serve as base templates [Predictive Modeling Deep-dive; Reference Table].
  • The Open Climate Service (OCS) Repository: Contains the openEO-compliant server implementation and documentation for hosting on-premise weather data repositories [openEO Implementation; OCS Instance Guide].

2. Documentation and Guides

  • The CHAP Modeling Platform Portal: The central technical reference for developers writing custom models, metric plugins, and backtest plots: chap.dhis2.org [Custom Backtest Plots].
  • In-App Interactive Documentation: The DHIS2 Modeling App bundles interactive API docs, CLI references, and setup guides directly within the user interface [Predictive Modeling Deep-dive].
  • DHIS2 Climate App User Guide: Outlines complete database configuration steps for administrators: docs.dhis2.org [Climate App User Guide].
  • The DHIS2 Community of Practice (CoP): The primary support channel for troubleshooting, configuration issues, and sharing use cases. Post questions and review solutions in the dedicated subcategory: Climate Health Analytics Platform - DHIS2 Community [Forum Post].
  • Using Climate Data for Malaria Program Planning Guide: The foundational governance and planning reference for climate-sensitive disease control. It details key programmatic considerations (e.g., SMC targeting, IRS timing) and governance setups (e.g., establishing inter-sectoral MOUs with Met Offices): Using Climate Data Guide [Using Climate Data].

3. Common Troubleshooting Workflows

  • Python Environment Compilation Failures: If a model’s virtual environment fails to initialize during chap eval or prediction tasks, navigate to the Active Jobs page within the DHIS2 Modeling App [Predictive Modeling Deep-dive]. This interface serves as the primary log viewer to inspect the raw stdout and stderr logs, allowing you to isolate missing native C-libraries or mismatched package versions.
  • Cloud-Cover Gaps in Satellite Imagery: When utilizing high-resolution Earth Observation datasets (e.g., MODIS NDVI) for local suitability modeling, cloud cover will cause data gaps [French Deep-dive]. To remediate this, configure a regression-based neighborhood approach (using median filter smoothing) to fill missing gridded values before feeding the CSV into CHAP [French Deep-dive; Accurancy Video].
1 Like
🗓️DAC2026 Thematic Summaries & Wikis/AI