Malaria remains one of the leading causes of mortality in tropical regions, exacerbated by climate change, which alters the breeding patterns of the Anopheles mosquito. The main challenge lies in the reactive nature of current health systems: interventions (spraying, supply distribution) are typically launched only after clinical cases are detected, when the outbreak is already in its expansion phase.
A critical gap exists between the availability of satellite environmental data (climate, humidity, vegetation) and its practical application in local health decision-making. The lack of accessible predictive tools prevents authorities from prioritizing limited resources in the micro-zones that will actually become infection hotspots in the weeks ahead.
MalariaSentinel/
pyproject.toml Workspace root (uv workspace)
README.md This file
AGENTS.md Agent guide: where to put new work
opencode.json Agent harness configuration
.gitignore
# ─── Python packages (UV workspace members) ────────────────────
mal-commonlib/ Shared config, paths, AOI registry, raster helpers
mal-core/ Stable pipeline logic (malariasim CLI, C++ ABM engine,
scoring, training, prediction)
mal-execution/ Batch scripts, HPC/cloud automation (Hetzner, CESGA)
mal-data-explorer/ Dataset visualization, mapping, bias analysis scripts
social-networks/ Outreach content (videos, posts) for the project
agents/janus/ Multi-agent orchestrator (deepagents + gawt)
# ─── Agent infrastructure ──────────────────────────────────────
agents/ Loops + installable memory module (Neo4j knowledge graph)
.opencode/ Per-project OpenCode agents and tools
# ─── Research & data content ───────────────────────────────────
data/ Datasets (ghana AOI, ghana_idit, colombia_vl, react, guf…)
(raw .txt/.zip gitignored — re-download via `malariasim download`)
papers/ Research PDFs + markdown
core-hypothesis/ Environmental drivers of malaria
spatial-analysis/ Spatial & spatio-temporal methods
… (see papers/README.md for the full list)
terrain/ SRTM DEM tiles and download scripts
(raw .tif gitignored — PNGs tracked)
runs/ Experiment outputs (gitignored, regenerated by pipeline)
docs/ Specs, plans, diagrams, project website
tools/ Dev scripts (lint, format, verify, test runners)
| Package | Depends on | Purpose |
|---|---|---|
mal-commonlib |
(none) | Shared config, paths, AOI registry, data utilities |
mal-core |
mal-commonlib |
Stable, production-ready pipeline code (malariasim CLI lives here) |
mal-execution |
mal-core, mal-commonlib |
Batch scripts, schedulers, cloud/HPC automation |
mal-data-explorer |
(none, scripts only) | Dataset visualization and bias analysis |
agents/janus |
mal-core (via malariasim shell) |
Multi-agent orchestration |
Nothing depends on the research packages. When research code stabilizes, promote it to mal-core or mal-commonlib.
The malariasim CLI (defined in mal-core, entry point mal_core:cli_main) drives every stage:
# Build C++ simulation engine (can be run from anywhere)
uv run malariasim abm --compile
uv run malariasim download --aoi ghana --datasets era5 --outputs wind_6hourly --years 2024,2025
uv run malariasim ingest --aoi ghana --year 2024 --month 6
uv run malariasim abm --aoi ghana --days 30
uv run malariasim score --run-dir runs/abm
uv run malariasim train --run-dir runs/abm --epochs 50
uv run malariasim predict --aoi ghana --year 2026Additional subcommands: validate-detections (seeds occurrence spots and measures detection coverage, feeds the D16 scorer), validate-cases, feedback, status, serve (API server). Run malariasim --help for the full list.
Full design: docs/plans/completed/perf-cpp-abm-plan.md.
cd mal-data-explorer
uv run python 03_map_ghana.py # Ghana larval sites map
uv run python 04_map_colombia.py # Colombia VectorLink sites
uv run python 05_map_react.py # REACT Burkina Faso + Côte d'Ivoire
uv run python 06_compare_three_maps.py # 3-dataset comparison
uv run python 12_bias_plot.py # Bias analysis visualizations
uv run python 14_breeding_pools.py # ABM breeding-pool model replica (Python)| What you're doing | Where it goes |
|---|---|
| Shared config, utils, data helpers | mal-commonlib/src/mal_commonlib/ |
| Stable pipeline code | mal-core/src/mal_core/ |
| Batch jobs, cloud/HPC automation | mal-execution/scripts/ |
| New experiment / simulation | mal-<name>-sim/ (new package, add to workspace) |
| New dataset visualization / analysis | mal-data-explorer/ (scripts) |
| Research papers (PDFs) | papers/<topic>/ |
| Datasets | data/<region>/ |
| Terrain / SRTM | terrain/ |
| Docs, specs, plans | docs/ |
| Dev tooling | tools/ |
- Experiment works in a
mal-*-sim/research package - Refactor stable parts into
mal-core/ormal-commonlib/ - Delete the experimental version
- Update
mal-execution/scripts to use the promoted modules
The Ghana pipeline runs end-to-end: env ingestion → C++ ABM simulation → calibration scoring → U-Net surrogate → risk prediction. This is a proof-of-pipeline, not a validated predictor. Honest limitations:
Data layers. Env tensors are built from ERA5 (wind/temperature) and CHIRPS rainfall, reprojected to a common EPSG:32630 @1 km grid. MODIS NDVI was not fetched — needs a (free) NASA Earthdata login.
ABM engine (C++20). The mal-abm-fast engine in mal-core/src/mal_core/abm/ is bit-compatible with the former M1.5 Python ABM (~1000× faster per rollout, scaling to 100 rollouts under 5 minutes). The former Python ABM experiment (mal-ghana-sim) has been removed.
Calibration scorers. Post-run scoring (malariasim score) writes a scorecard.json into the run directory: 11 scored dimensions + 6 hard gates combined via weighted composite. The companion pytest calibration framework (22 weighted dimensions, D1–D24 + LLM verdict) lives in mal-core/src/mal_core/abm/tests/calibration/ — see its README.
U-Net surrogate — learns, but weak: best val Dice 0.24 (criterion was > 0.6). Data- and compute-limited on this workstation. Scaling to ≥100 rollouts + a real GPU + the larger (32,64,128,256) U-Net is the path to the 0.6 bar.
Artifacts (gitignored, regenerated): runs/abm/ (state COGs, cohort logs), runs/training/ (U-Net checkpoints), runs/prediction/ (risk maps).
The repo is kept lean: raw DwC occurrence files (.txt), DwC-A archives (.zip),
and SRTM DEM rasters (.tif) are gitignored (regenerable). Tracked instead:
all source code, documentation, output PNG maps (small), and the open-access
papers in papers/.
From a fresh clone, download the AOI data (env rasters, occurrence records)
with the pipeline itself — every dataset is registered in the AOI manifest
(data/<aoi>/manifest.json), the single source of truth:
# Download datasets for an AOI (idempotent: skips what already exists)
uv run malariasim download --aoi ghana --datasets era5
uv run malariasim ingest --aoi ghana --year 2024 --month 6
uv run malariasim abm --aoi ghana --days 30For the legacy DwC occurrence archives and SRTM tiles, see
data/README.md (dataset catalogue, sources, licenses) and
terrain/README.md (SRTM download scripts).
- ANFAIA — Artificial Intelligence Non-Profit Research Organization driving open-source AI solutions for global health.
- CESGA — Galicia Supercomputing Center (Centro de Supercomputación de Galicia), providing HPC infrastructure and computational support.
This project is licensed under the Apache License 2.0 — see the LICENSE file for details.