Download and Clean WHO POLIS Data • polished

polished retrieves and cleans poliovirus surveillance data from the WHO Polio Information System (POLIS). The downloader writes each table to a local cache as raw_*; the cleaning pipeline reads those files and writes polished_* tables, with optional surveillance indicators and data-quality checks.

Installation

Install the development version from GitHub with pak::pak("truenomad/polished"). Downloading requires a POLIS API key, read from the POLIS_API_KEY environment variable.

The workflow

library(polished)

# 1. Download — writes raw_afp, raw_es, ... to a local cache (resumable, parallel)
get_polis_data(tables = c("case", "environmental_sample"), polis_folder = "data/polis")

# 2. Clean the downloaded tables and write outputs and quality reports
run_pipeline_dir("data/polis", "data/processed")
#   -> polished_afp.*, polished_es.*, polished_virus.*  + checks_*.xlsx workbooks

To create the project directories, a .Rprofile that defines cfg, and starter scripts for downloading and processing data:

# scaffolds the whole pipeline project, then run 2a (download) and 2b (process)
init_polis_pipeline("my_project", regions = "EMRO")

# add renv = TRUE to pin package versions (renv::snapshot / restore) for collaborators
init_polis_pipeline("my_project", regions = "EMRO", renv = TRUE)

Key functions

Function	Purpose
`get_polis_data()`	Download POLIS tables to a local cache, with resumable batches, parallel year downloads and checks for missing records.
`run_pipeline()` / `run_pipeline_dir()`	Clean tables in memory or from `raw_*` files, with optional geography reconciliation and surveillance indicators.
`clean_afp()` · `clean_es()` · `clean_human_spec()` · `clean_sia()`	Standardise columns, parse dates, derive variables, reconcile geography and remove duplicate records for each stream.
`clean_virus()`	Combine poliovirus-positive records from cleaned AFP and environmental samples.
`clean_pop()`	Prepare country, province and district population denominators, with optional WorldPop reconciliation.
`impute_geo_from_epid()`	Fill missing administrative names and GUIDs using EPID matches, and record the source of each fill.
`calc_polio_indicators()`	Calculate surveillance indicators from cleaned tables, including NPAFP rate, stool adequacy and timeliness.
`checks_afp()` … `write_checks_excel()`	Check cleaned tables and export a summary and flagged records to Excel.
`init_polis_pipeline()`	Create data directories, a project configuration and starter download and processing scripts.
`init_polis_project()`	Create directories for raw data, processed outputs, validation reports, caches and logs.

See the vignettes and each function’s help page (e.g. ?get_polis_data) for usage and data-formatting requirements.

Indicator modules and synthetic data

Five indicator modules read the cleaned polished_* tables alongside calc_polio_indicators(). Each module documents its numerator and denominator, and takes a cols argument, keyed by table name (cases, specimens, samples, campaigns, detections), when a column is named differently. The reporting date is always as_of, grouping by administrative area is always level, and area tables always carry level, guid and name.

AFP case quality: calc_afp_timeliness(), calc_afp_specimen_pathway(), calc_afp_specimen_reasons(), calc_afp_specimen_receipt_monthly(), calc_afp_specimen_receipt_by_area() and calc_afp_followup(), with afp_stool_adequacy() as the single stool adequacy classifier.
Pending classification: calc_pending_stage().
Environmental surveillance performance: calc_es_resolution(), calc_es_district_performance() and calc_es_site_performance().
Detections in comparison windows: calc_detection_windows() and calc_detection_comparison().
The environmental site scorecard: calc_es_scorecard(), calc_es_score_network() and calc_es_score_profile().

simulate_polio_data() builds a matching set of synthetic tables on one invented geography: population, AFP cases, environmental samples, virus detections, stool specimens and campaign rounds. Every place name and identifier is invented, every rate and delay is an argument, and the same seed gives the same tables.

polio <- simulate_polio_data(seed = 1)
calc_afp_timeliness(polio$afp_cases, level = "adm1")
calc_pending_stage(polio$afp_cases, polio$human_specimens, as_of = as.Date("2024-12-31"))

Citation

To cite polished in publications, run citation("polished") in R, or use:

Yusuf, Mohamed A. (2026). polished: Retrieve and Prepare GPEI POLIS Surveillance Data. R package version 0.3.0. https://doi.org/10.5281/zenodo.22998766

@Manual{polished,
  title  = {polished: Retrieve and Prepare GPEI POLIS Surveillance Data},
  author = {Mohamed A. Yusuf},
  year   = {2026},
  note   = {R package version 0.3.0},
  url    = {https://github.com/truenomad/polished},
  doi    = {10.5281/zenodo.22998766},
}

License

MIT © Mohamed A. Yusuf. See license for details. Issues and pull requests welcome at https://github.com/truenomad/polished.