Prints explanations in the R console. Describes the five STEPS components
and the review labels behind spi_field_guide(), lists common errors in
interpreting SPI, and explains four districts selected from a field guide:
SPI at or above 1, an uncertain shortfall, a large shortfall supported by
extent and persistence, and a shortfall without nearby supporting evidence.
Usage
spi_field_guide_help(
topic = c("all", "signals", "verdict", "misreadings", "example"),
guide = NULL,
year = NULL
)Arguments
- topic
One or more of
"all","signals","verdict","misreadings","example". Default:"all".- guide
A
spi_field_guide()result to use for the worked example. Default: NULL (usesynth_field_guide).- year
Focal year for the worked example. Default: NULL (
guide$read_year).
Details
By default, the worked example uses synth_field_guide, the precomputed
result for the synthetic data, so no model fit is needed. Pass guide
to explain the results from your own spi_field_guide() call.
Examples
spi_field_guide_help("signals")
#>
#> ── Reviewing districts with a low SPI ──────────────────────────────────────────
#>
#> ── The five STEPS components ──
#>
#> For districts with an SPI below 1, five components help assess the wider
#> surveillance picture: strength, timeliness, extent, persistence, and stool
#> adequacy. They are interpreted together, not combined into a score, and they do
#> not carry the same weight. No single component establishes a surveillance
#> failure.
#>
#> ── S: Strength
#> • Asks: How large is the shortfall, and does the 90% credible interval lie
#> entirely below the reference value of 1?
#> • Interpretation: A larger shortfall with an interval below 1 is stronger
#> evidence. The difference between observed and expected counts is not a count of
#> missed cases.
#> • Adds evidence about the shortfall: No
#>
#> ── T: Timeliness
#> • Asks: Are specimens reaching the laboratory within 3 days?
#> • Interpretation: Measures how quickly specimens reach the laboratory after
#> collection. It is reported separately and does not change the review label.
#> • Adds evidence about the shortfall: No (independent)
#>
#> ── E: Extent
#> • Asks: Is an SPI below the chosen cutoff more common among other districts
#> in the same admin-1 area than nationally?
#> • Interpretation: Checks whether a low SPI is more common in the same region
#> than nationally.
#> • Adds evidence about the shortfall: Yes
#>
#> ── P: Persistence
#> • Asks: Was SPI also below the chosen cutoff in the previous year?
#> • Interpretation: Checks whether the district also had a low SPI in the
#> previous year.
#> • Adds evidence about the shortfall: Yes (supporting)
#>
#> ── S: Stool adequacy
#> • Asks: Are stool specimens adequate?
#> • Interpretation: Reports the share of AFP cases with adequate stool
#> specimens. It does not change the review label.
#> • Adds evidence about the shortfall: No (independent)
spi_field_guide_help("verdict")
#>
#> ── Reviewing districts with a low SPI ──────────────────────────────────────────
#>
#> ── Review labels ──
#>
#> The review label uses the SPI value, its interval, and findings for extent and
#> persistence. The labels help decide which districts to review first.
#> • Priority for review -- SPI below 1, the 90% credible interval entirely below
#> 1, and extent or persistence also raises concern. If enabled, the
#> sampling-noise check must also pass. These findings identify districts for
#> closer review.
#> • Monitor -- SPI below 1, but uncertainty or limited supporting information
#> favours reassessment as new data become available.
#> • No SPI indication -- no SPI indication for additional review. Routine
#> surveillance and review based on other indicators continue.
#> Timeliness and stool adequacy are reported beside the review label but never
#> change it. Trend, neighbouring-district context, seasonal patterns and any AFP
#> or ES detection are context outside STEPS.
spi_field_guide_help("example")
#>
#> ── Reviewing districts with a low SPI ──────────────────────────────────────────
#>
#> ── Worked example (2024) ──
#>
#> Four districts selected to illustrate different SPI results and findings for
#> the wider area and previous year:
#>
#> ── Belwen -- SPI at or above cutoff
#> SPI 1.11 (90% credible interval 1.01 to 1.21), so STEPS is not applied. Its SPI
#> was 0.93 in 2023, which shows why a single year at or above 1 should still be
#> read alongside earlier values. The SPI provides no current indication for
#> additional review.
#> ℹ Review label: no SPI indication for additional review. Routine surveillance and review based on other indicators continue.
#>
#> ── Yolan -- Uncertain shortfall
#> SPI 0.74, and its 90% credible interval extends to 1.23, so an SPI of 1 remains
#> compatible with the data and model. Its SPI was also below 1 in 2023 (0.00),
#> and 2 of 3 other districts in Harmar were below 1 (67%, against 56%
#> nationally). The interval includes 1. Review the result again when more data
#> are available.
#> ℹ Review label: monitor. Uncertainty or limited supporting information favours reassessment as new data become available.
#>
#> ── Gareth -- Large shortfall with supporting evidence
#> NPAFP rate 5.5, yet 3 cases reported against 7.5 expected, giving an SPI of
#> 0.42 (90% credible interval 0.32 to 0.55). Its SPI was also below 1 in 2023
#> (0.45), and 5 of 9 other districts in Sarndor were below 1 (55.6%, against
#> 55.5% nationally). The interval is below 1, and the area or previous year also
#> raises concern. These findings support closer review.
#> ℹ Review label: priority for review. The relative reporting shortfall is strong enough, with extent or persistence also raising concern, to warrant further investigation.
#>
#> ── Suzil -- Shortfall without wider area concern
#> SPI 0.13 (90% credible interval 0.10 to 0.17); its SPI was also below 1 in 2023
#> (0.53). However, 6 of 12 other districts in Nenad were below 1 (50%, against
#> 56% nationally). The shortfall warrants review, and local explanations,
#> including population estimates and boundary changes, should be checked.
#> ℹ Review label: priority for review. The relative reporting shortfall is strong enough, with extent or persistence also raising concern, to warrant further investigation.