degninou/viral_ai

Reproducible pipeline for predicting HIV viral suppression in five West African (IeDEA) countries, with geographic and temporal external validation. # IeDEA West Africa — ViralAI Code for **AI-based prediction models for viral suppression in HIV care across five West African countries (2019–2025)**: development and internal–external validation on IeDEA West Africa cohort data from Benin, Burkina Faso, Côte d'Ivoire, Nigeria and Togo. Two notebooks, run in order. They share no code — the handoff is a set of files. | Notebook | Status | Does | |---|---|---| | `viralai_data_cleaning_v02.ipynb` | runnable | raw SAS extracts → analytic cohort | | `viralai_pipeline_pseudocode_v02.ipynb` | pseudocode blueprint | analytic cohort → validated models | --- ## 1. Data cleaning Reads `rawdata/rawdatafiles.zip` (seven `.sas7bdat` tables) and builds the analytic cohort: inclusion criteria (adults ≥ 18 on ART with a viral load, cohort entry 2019–2025), cross-country recoding, and the derived variables. Handles cohort construction et guarantees structure only: column set and order, dtypes, categorical levels, one row per patient, non-nullable completeness. Value-range plausibility is deliberately left to the pipeline. Writes to `cleandata/`: - `viralai_analytic_cohort.parquet` — the machine handoff (preserves dtypes and NA) - `…parquet.manifest.json` — counts by country and year, prevalence, file hash, run parameters, git SHA, authorship - `viralai_contract_v1.json` — the schema the table satisfies - `summary_statistics_analytic_cohort.csv` — pooled and per-country - `*.csv` / `*.xlsx` and codebook HTML — for humans, never read by the pipeline Parameters worth checking before a run, all in the **Run parameters** cell: `DATA_CLOSE_DATE`, `LTFU_GAP_YEARS`, `COHORT_TIME_DEFINITION` (`enrolment_to_last_followup`, per protocol Table 2, or `art_start_to_close`), `MIN_AGE_ART`, `VL_THRESHOLD` (suppressed iff ` /`. --- ## Running ```bash pip install pandas numpy pyarrow scipy scikit-learn imbalanced-learn \ xgboost lightgbm tensorflow torch matplotlib seaborn missingno codebooks ``` Colab: mount Drive and place the notebook …