Create a one-page SPI district report

Creates a one-page district report from a spi_field_guide() result. It includes the review label, an SPI chart with a 90% credible interval and detection markers, the five STEPS components, and a summary of the findings that support the label. For a guide built from spi_simple() results, the chart has no interval band. The strength component compares the SPI value with the selected cutoff.

Usage

spi_field_guide_pager(
  x,
  district,
  adjacency = NULL,
  boundaries = NULL,
  region = NULL,
  year_label = NULL,
  prob_under = NULL,
  indicators_df = NULL,
  npafp_target = NULL,
  es = NULL,
  es_col = NULL,
  detection_label = NULL,
  year = NULL,
  path = NULL,
  file = NULL,
  format = c("html", "png"),
  name_col = NULL,
  id_col = NULL,
  admin_label = "admin-2 district",
  unit_noun = "district",
  note = NULL,
  verbose = TRUE
)

Arguments

x: A spi_field_guide() result (class spi_field_guide).
district: District to report on: either an id (e.g. the admin-2 GUID) in the id column, or a district name matched (case-insensitively) against name_col. Ids are tried first, so an id is unambiguous.
adjacency: Deprecated and ignored. The location map shows the district within its country and does not use a neighbour graph. Default: NULL.
boundaries: Optional sf polygon layer keyed by id_col, covering the whole country. Uses these boundaries to draw the location map. An adm1_name column, if present, supplies the regional outlines; an adm0_name column restricts a multi-country layer to the focal district's own country. Default: NULL (no inset).
region: Optional regional context for the header, as a named list or one-row data frame. Recognised fields: name (or region/adm1), rank (or region_rank), n (or n_regions) and spi (or region_spi). It renders as a header line reading region SUD-OUEST, SPI 0.70 and rank 1 of 22 (lowest SPI first), joined by middle dots. The rank provides context and does not change the label. Default: NULL (no regional line).
year_label: Optional label for the reporting period, shown in the header instead of the year alone. Use it when the window is not a calendar year, e.g. "rolling year to Apr 2025". Default: NULL (the year).
prob_under: Optional posterior probability of a relative reporting shortfall under the chosen centring setting, P(SPI < 1), as a single number on the 0 to 1 scale. It is appended to the strength line as a percentage, with the tails printed as "over 99%" and "under 1%" so reported precision matches the posterior draws. This probability describes relative reporting, not the presence of poliovirus. Default: NULL (not shown).
indicators_df: Optional district-year panel of conventional AFP and ES indicators, keyed by guid (or id_col) and year. When supplied, a strip below the chart shows the non-polio AFP rate over the same years against its target, plus tiles for whichever of stool_adequacy_cond_pct, inv_timeliness_pct, onset_notify_pct and ev_rate are present. Pass the assessable counts (inv_timeliness_n, onset_notify_n) and they are shown under each figure; a percentage on fewer than five cases prints as a fraction instead because the percentage is based on few cases. These indicators are context: they never change the label. Default NULL (no strip).
npafp_target: Numeric non-polio AFP rate target for the strip's rate panel, per 100,000 under 15. Default: NULL (x$thresholds$npafp).
es: Optional ad-hoc environmental-surveillance detections keyed by id_col and year, overriding the field guide's own ES data. Normally ES is supplied once to spi_field_guide() (via its es argument) and read from there, so this is only needed for a field guide built without ES. Each row (or each es_col-positive row) is an ES positive. Default: NULL (use the field guide's es_years).
es_col: Optional name of a count / logical column in es; only rows with a positive count (or TRUE) count as detections. Default: NULL (every row counts).
detection_label: What the detections in x and es actually are, e.g. "cVDPV2" or "WPV1". Use this to name the serotype selected in detections / es when building the guide. Leave it NULL for mixed serotypes; the report then uses "poliovirus". Default: NULL.
year: Integer year for the report. Default: NULL (x$read_year).
path: Optional output directory. When set, the pager is written into it under an auto-generated name, spi_<adm0>_<adm1>_<adm2>_field_pager.<ext>, one file per format. The directory is created if it does not exist. Default: NULL.
file: Optional explicit output path; the extension (.html or .png) sets the format. Takes precedence over path / format. Default: NULL (return the pager object without writing).
format: Output format(s) written under path: any of "html" and "png". PNG rendering needs webshot2 and a headless Chrome. Default: both.
name_col: Column to resolve district against and label the pager by. Default: NULL (first of adm2_name, adm1_name, else the id column).
id_col: District id column, shared by adjacency / boundaries / es. Default: NULL (x$id_col).
admin_label: Short description of the administrative level, shown under the district name. Default: "admin-2 district".
unit_noun: Singular common noun for the operational unit, used in the extent reading ("other unit_nouns in ..."). Set it to match admin_label, e.g. "province" for admin-1 inputs. Default: "district".
note: Optional note about the data or report, printed in the footer, e.g. "illustrative" for a worked example. Default: NULL (untagged).
verbose: Logical. Print a summary when the report is created. Default: TRUE.

Value

An object of class spi_pager: a list with the rendered html string, the resolved district, year, verdict (the review label), and paths (the files written, empty when neither path nor file is set). Printing it reports the label and any written files. Get the HTML with as.character().

Details

The report is static HTML with an SVG chart. It works offline, using system fonts when Google Fonts is unavailable.

The chart shows the district's SPI and any poliovirus detections. The header reports the neighbour median. Pass boundaries to add a location map with the district highlighted within its country and admin-1 divisions.

Pass indicators_df to show the NPAFP rate, stool adequacy, timeliness, and the enterovirus (EV) isolation rate in environmental samples. Percentages based on fewer than five assessable cases are shown as fractions and are not assessed against a target.

AFP detections appear as filled diamonds and ES detections as hollow circles. Seasonality and trend are also shown as context. These findings and the optional indicators do not change the STEPS label.

The report uses rose for priority for review, amber for monitor, and green for no SPI indication.

Examples

fg <- synth_field_guide
pager <- spi_field_guide_pager(fg, district = "Tirwen")
#> ✔ Pager for "Tirwen" (2024): "Priority for review".
pager
#> 
#> ── SPI pager ───────────────────────────────────────────────────────────────────
#> Tirwen | 2024 | "Priority for review"
#> ℹ Not written to disk; pass `path` or `file`, or use `writeLines(as.character(x), "pager.html")`.
if (FALSE) { # \dontrun{
# Add a location map and the AFP / ES detections from the field guide.
spi_field_guide_pager(
  fg,
  district = "Tirwen",
  boundaries = synth_surveillance$boundaries,
  id_col = "adm2_guid",
  path = "."
)
} # }

Usage

Arguments

Value

Details

See also

Examples