DHIS2 TB AI Prediction System in Practice: From Risk Stratification to Clinical Decision Support

Project Background: Where Public Health Meets Machine Learning

A Reddit post caught attention recently: an intern was about to join a research project tasked with integrating AI/ML capabilities into a national tuberculosis (TB) control program built on the DHIS2 platform. The project timeline was just three months, and the intern was a machine learning novice whose only hands-on experience was building a movie recommendation system.

This scenario is remarkably representative — it captures a challenge facing countless digital health transformation efforts across developing countries. The DHIS2 platform has already accumulated years of TB screening and treatment records, but converting that data into actionable clinical decision support remains a formidable gap between technology and medicine.

DHIS2 (District Health Information System 2) is the world's most widely used open-source health information management platform, deployed in over 70 countries. Developed and maintained by the HISP project group at the University of Oslo, it has become the de facto standard for global health information systems since its 2006 release. Its Tracker module — unlike traditional aggregate data reporting — tracks individual patients longitudinally across the full disease management cycle, from initial screening and lab testing to treatment initiation and follow-up completion. This patient-centric data structure is naturally well-suited for machine learning, as it preserves a complete sequence of events over time: screening symptoms, exposure history, visit adherence, and more. That's precisely the kind of data ideal for building TB prediction models. That said, the quality of DHIS2 deployments varies enormously across countries. Data completeness, field standardization, and timeliness of entry all directly affect the feasibility of downstream modeling — a reality that must be confronted head-on at project inception.

Project Breakdown: Four Core Modules

Based on the original post, the project involves four progressively layered objective modules. Let's examine the technical feasibility and implementation path for each.

TB Risk Stratification: A Supervised Classification Problem

The first objective is to predict an individual's probability of having tuberculosis based on screening symptoms and exposure history in DHIS2 Tracker, then classify that risk into high, medium, or low tiers.

Technically, this is a classic supervised classification task. For medical tabular data, there's no need to jump straight to deep learning. Experience consistently shows that gradient boosting tree models — XGBoost, LightGBM, CatBoost — tend to perform best on this type of structured data, with fast training times and strong interpretability.

Gradient boosting trees iteratively train decision trees to correct the residuals of prior predictions, achieving powerful nonlinear fitting. XGBoost, LightGBM, and CatBoost are the three mainstream implementations, each with distinct strengths in regularization strategy, histogram-based acceleration, and categorical feature handling respectively. A large-scale benchmark study published at NeurIPS 2022 found that gradient boosting trees outperformed deep learning models (including TabNet, SAINT, and other architectures specifically designed for tabular data) on the majority of 45 tabular datasets at small-to-medium scale. For clinical applications, tree models offer another critical advantage: they naturally handle mixed feature types (continuous values like age and weight alongside categorical values like symptom presence or absence) and have built-in mechanisms for missing values — especially important in real-world health information systems where data quality is uneven. For a three-month project, this is the most pragmatic starting point.

The key challenge lies in label quality: where do the three-tier risk labels actually come from? If confirmed diagnoses are recorded in DHIS2, confirmed positives can serve as the positive class; risk tiers can then be derived from probability thresholds (e.g., >0.7 = high risk) rather than building a direct three-class classifier.

For TB risk prediction feature engineering, common usable fields in DHIS2 Tracker include: duration of persistent cough (over two weeks is a key indicator), night sweats, weight loss, and fever — the four WHO-recommended screening symptoms — along with exposure and host factors such as HIV status, diabetes comorbidity, close contact with active TB cases, prior TB treatment history, smoking and alcohol use, and nutritional status (BMI). Worth noting: across different countries' DHIS2 deployments, these fields may be named and coded in completely different ways, with some recorded as free text and others as coded values. This means substantial data cleaning and feature standardization work is required before modeling can begin. Additionally, the gold standard for TB diagnosis is sputum smear or culture positivity, or GeneXpert molecular testing — but in resource-limited settings, a significant proportion of patients are "clinically diagnosed" based on symptoms rather than laboratory confirmation. This introduces substantial noise and uncertainty into label definitions for supervised learning.

Treatment Loss to Follow-Up Prediction: Temporal Adherence Modeling

The second module aims to identify patients likely to interrupt treatment or drop out. TB treatment spans six months or more, and poor patient adherence is one of the central challenges in global TB control — treatment interruption drives the spread of drug-resistant TB.

The severity of this problem cannot be overstated. The WHO-recommended standard TB treatment regimen (the DOTS strategy) requires patients to take medication continuously for at least six months: an intensive phase of two months followed by a consolidation phase of four months. Globally, roughly 13–25% of patients fail to complete the full course. Dropout doesn't just mean treatment failure and increased relapse risk for the individual — more critically, it's the primary driver of multidrug-resistant tuberculosis (MDR-TB). MDR-TB requires 18–24 months of treatment, costs hundreds of times more than standard TB treatment, and has significantly lower cure rates. Therefore, identifying high-risk patients early and intervening — through intensified follow-up, transportation subsidies, or community health worker-accompanied medication — is one of the highest-value strategies in TB control.

The data here is fundamentally about adherence patterns and visit compliance history, with an inherently temporal character. Two approaches are viable:

• Feature engineering + tree models: Compress time-series information into statistical features (e.g., number of missed appointments, average delay in days, consecutive absence flags), then continue with XGBoost.
• Sequence models: If sufficient data is available, LSTM or Transformer architectures can handle raw visit sequences. For beginners working on a short timeline, the former is far more reliable.

In practice, loss to follow-up is typically a class imbalance problem — the majority of patients do complete treatment. This requires careful attention to appropriate evaluation metrics (such as AUPRC and recall) rather than raw accuracy, and consideration of oversampling techniques or class weighting. Concretely: if the ratio of treatment completers to dropouts is 9:1, a model that simply predicts "no dropout" for everyone achieves 90% accuracy but has zero clinical value. AUPRC (area under the precision-recall curve) is more appropriate than AUC-ROC for evaluating model performance under class imbalance, because it is more sensitive to prediction quality on the minority class. Technically, SMOTE (Synthetic Minority Over-sampling Technique) generates new samples by interpolating between minority class instances, but in high-dimensional medical data it may produce implausible synthetic records; assigning higher class weights to the minority class (via the class_weight parameter) or using adaptive loss functions like Focal Loss is generally more robust. In clinical settings, decision thresholds should also be calibrated against the actual cost of interventions — the cost of missing a high-risk dropout patient far exceeds the cost of an extra follow-up visit with a low-risk patient.

In practice, the operational definition of "loss to follow-up" itself requires careful consideration. WHO defines treatment loss to follow-up (LTFU) as interrupting treatment for two consecutive months or more, but different national TB programs may use different thresholds. In DHIS2 Tracker, dropout signals typically manifest as the gap between scheduled and actual visit dates, consecutive missing visit records, and interruptions in medication pickup records. A critical temporal window issue must be addressed: the model must issue a warning early enough before actual dropout to enable intervention. If the model only identifies risk after a patient has already missed multiple appointments, its clinical utility is greatly diminished. Feature construction should therefore focus on signals observable early in treatment (e.g., within the first one to two months): first visit delay, medication regularity during the initial treatment phase, geographic distance to the health facility, and patient socioeconomic characteristics.

Spatial and Environmental Factors: Triangulating Data

The third module is the most ambitious and the most risky — fusing township-level population density data with meteorological variables (rainfall, air quality, temperature) to capture spatial clustering and environmental risk factors.

This idea has epidemiological grounding: TB transmission does correlate with population density, ventilation conditions, and air pollution. Spatial epidemiology has accumulated substantial evidence on the environmental determinants of tuberculosis. A systematic review published in The Lancet Planetary Health in 2019 found that each 10 μg/m³ increase in PM2.5 was associated with approximately a 12–19% increase in TB incidence, likely related to air pollution impairing pulmonary immune defenses. High-density areas carry higher TB transmission risk because Mycobacterium tuberculosis spreads most efficiently via droplet nuclei in enclosed, crowded, poorly ventilated environments.

From an engineering standpoint, however, this is the part of the project most likely to spiral out of control. Translating these macro-level associations into effective features for individual risk prediction faces the serious challenge of the "ecological fallacy" — statistical associations at the population level don't necessarily hold at the individual level. Furthermore, publicly available meteorological data (such as NASA POWER or ERA5 reanalysis data) typically has spatial resolution on the order of tens of kilometers, which offers limited precision when matching to township-level administrative units.

Pragmatic Implementation Recommendations

For a three-month project, geospatial and climate data should be treated as optional enhancement features, not a core module. Three reasons:

1. High data alignment costs: Linking township-level meteorological data to individual patient records involves extensive geocoding and temporal alignment work.
2. Ambiguous causal relationships: The marginal contribution of environmental variables to individual risk may be small, and they can easily introduce noise.
3. Prioritization: Build the two core prediction models solidly first, then consider enhancements.

If time allows, townships can serve as the aggregation unit for a standalone spatial heatmap analysis — a useful complement to individual-level predictions rather than something forced into the same model.

The Critical Piece: Explainability and DHIS2 Workflow Integration

The fourth module represents the project's true value — embedding interpretable outputs (SHAP risk scores and alerts) directly into frontline health workers' application interfaces to support clinical decision-making.

Why Medical AI Must Be Explainable

In clinical settings, "black box models" are unacceptable. Frontline health workers need to understand why a patient has been flagged as high risk — is it symptoms, exposure history, or adherence patterns? SHAP values (SHapley Additive exPlanations) provide exactly this kind of individual-level feature contribution explanation, which is yet another reason to choose tree models (SHAP integrates most maturely and efficiently with tree-based models).

SHAP values derive from the Shapley value concept in cooperative game theory, introduced by Lloyd Shapley in 1953 to fairly distribute contributions among participants. In machine learning interpretability, each feature is treated as a "player" and the model prediction as the "total payoff"; SHAP values compute the expected marginal contribution of each feature across all possible feature subsets. This guarantees several important mathematical properties: the sum of all SHAP values equals the difference between the model prediction and the baseline prediction (additivity), and features with equal contributions receive equal SHAP values (symmetry). In clinical practice, this means a clinician can see something like: "This patient is predicted as high risk; persistent cough contributed +0.15, close contact history contributed +0.12, and age contributed -0.03." That kind of transparency is crucial for building frontline health workers' trust in AI-assisted tools. The TreeSHAP algorithm is specifically optimized for tree models, computing SHAP values in polynomial time rather than the exponential brute-force approach — making it practical to generate real-time explanations for every prediction in a deployed system.

Technical Pathways for DHIS2 Integration

Writing model outputs back to the DHIS2 frontend can be achieved through several approaches:

• Use the DHIS2 Web API to read Tracker data and write back predictions as Data Elements
• Develop a DHIS2 App (built on the App Platform) to display risk scores within the Tracker Capture interface
• Use Program Rules to trigger alert notifications

This work is fundamentally more about software engineering and systems integration than machine learning itself, and it typically consumes more time than anticipated.

DHIS2's technical ecosystem has evolved significantly in recent years, and understanding its architecture is essential for model integration. The DHIS2 App Platform is React-based and provides a standardized development toolchain (d2 CLI) and UI component library (@dhis2/ui), enabling developers to build custom web applications embedded in the DHIS2 main interface. For data interaction, DHIS2 offers a comprehensive RESTful Web API supporting CRUD operations on Tracked Entity Instances, Events, and Enrollments within Tracker. A common integration architecture involves deploying a standalone Python backend service (Flask/FastAPI) that periodically pulls new data from the DHIS2 API, runs model inference, and writes prediction results back to DHIS2 as Data Elements or Tracked Entity Attributes. The frontend then reads these predictions through a custom DHIS2 App and presents them visually. Note that DHIS2 instances are typically deployed on government servers where network bandwidth and compute resources may be limited — the deployment of model inference services must account for these infrastructure constraints.

Three-Month Action Roadmap

Given the real-world three-month constraint, the following prioritization is recommended:

Month 1: Data Exploration and Preparation. Understand the DHIS2 Tracker data structure thoroughly; assess data quality, missingness, and label availability. This step determines whether the project succeeds or fails — don't rush past it.

Month 2: Build Core Prediction Models. Develop the TB risk classification and dropout prediction models, using XGBoost/LightGBM as the baseline, paired with SHAP explanations. Evaluate rigorously using cross-validation and appropriate metrics for imbalanced data.

Month 3: Integration and Prototype Validation. Connect model outputs to DHIS2 via API and build a prototype demonstration. The geospatial/climate module is a "stretch goal" if time permits.

Ethics and Privacy Considerations

Medical AI involves ethical and privacy dimensions that cannot be overlooked. The WHO's 2021 Ethics and Governance of Artificial Intelligence for Health guidance identifies six core principles: protecting human autonomy, promoting human well-being and safety, ensuring transparency and explainability, fostering responsibility and accountability, ensuring inclusiveness and equity, and promoting sustainable AI.

For TB prediction models specifically, fairness deserves particular attention — if training data primarily comes from urban health facilities, the model may perform significantly worse for rural patients; if certain demographic groups have been systematically under-reported or misdiagnosed in historical data, the model will inherit and potentially amplify that bias. Additionally, in many developing countries, legal frameworks for health data protection remain incomplete, requiring particular care when using TB data that includes sensitive information such as HIV co-infection status. Working with real patient data requires ethical approval and appropriate de-identification.

Once deployed, a continuous monitoring mechanism is needed to detect model performance degradation due to data drift (e.g., emergence of new TB strains, changes in screening criteria). Equally important: the model is always a support tool, never a replacement — final clinical decisions must be made by healthcare professionals. Any alert should be clearly labeled as a probabilistic recommendation.

For an ML newcomer, the ambitions of this project are significant — but with sensible modular decomposition and prioritization, delivering a valuable prototype system within three months is entirely achievable. The key is: start with simple, reliable models; put explainability and workflow integration at the center; and resist the urge to chase algorithmic complexity.

Data drift is a long-term challenge that emerges after model deployment. In TB control settings, drift can arise from multiple sources: changes in screening strategy that shift the input feature distribution (e.g., new GeneXpert testing sites increasing the proportion of laboratory-confirmed diagnoses), seasonal epidemic pattern changes, emergence of new drug-resistant strains altering treatment outcome distributions, or even DHIS2 system upgrades changing data formats. A simple monitoring dashboard should be established post-deployment to regularly compare input feature distributions against the training set for significant shift (using PSI or KS tests), and to track whether key metrics on new data (recall, positive predictive value) are degrading. Significant drift should trigger a model retraining workflow.

Key Takeaways