Environmental site scorecard — calc_es

Judges whether each environmental surveillance site detects virus when virus is there, on two measures, and combines them with the site's own trend and its enterovirus isolation into one verdict.

Usage

calc_es_scorecard(
  samples,
  campaigns,
  isolation = NULL,
  country_iso = NULL,
  benchmark_iso = country_iso,
  from = as.Date("2016-01-01"),
  as_of = Sys.Date(),
  settings = es_score_settings(),
  cols = list()
)

Arguments

samples: Cleaned environmental sample table, one row per sample, such as polished_es. Duplicate sample identifiers are kept once.
campaigns: Cleaned campaign table, such as polished_sia.
isolation: Optional site table carrying each site's enterovirus isolation percentage (ev_pct, on a scale of 0 to 100), the number of samples with a final result (resolved) and the months sampled (months_sampled), one row per site, such as the result of calc_es_site_performance(). Without it, the low isolation rule is not applied and those columns are NA.
country_iso: ISO3 codes of the countries whose sites are reported. NULL (default) reports every country in samples.
benchmark_iso: ISO3 codes of the countries whose samples, campaigns and sites make up the network: the pool for neighbours, the latest sample and the network rates. Defaults to country_iso.
from: First collection date read. Default 1 January 2016.
as_of: The reporting date, as a Date or a string that as.Date() reads. Defaults to Sys.Date(). It is the last collection date read.
settings: Windows, distances, thresholds and labels, built with es_score_settings().
cols: Named list of column overrides keyed by table (samples, campaigns, isolation), in the style of calc_polio_indicators(). See es_score_cols() for the keys and defaults.

Value

A tibble with one row per active site in country_iso, sorted by verdict and judged percentage. For each measure (campaign_response, neighbour_recovery) it carries n_, k_, rate_, lo_ and hi_ columns, followed by the isolation, retention, background and trend columns, the percentages, judged_pct, judged_basis and the verdict factor. The rate_, lo_ and hi_ columns are proportions on a scale of 0 to 1. Every _pct column is on a scale of 0 to 100, and drop_pts is in percentage points. retention_pct is a percentage of campaign response, so it can exceed 100.

Measures

Every sample is placed against the latest campaign that started on or before its collection date in the site's own district (matched on the district GUID). Only campaigns with a vaccine type in opv_types and a status in campaign_statuses count. A site in a district with no such campaign has no samples on this measure.

Campaign response. The denominator is the number of the site's samples collected between 0 and peak_weeks weeks (default 4) after the start of the latest campaign in its district. The numerator is the number of those samples in which Sabin virus was detected.
Neighbour recovery. An occasion is a month in which the site was sampled and another site within neighbour_km kilometres (default 20) recovered target virus (by default WPV1 or VDPV2) in a month no more than window_days days away (default 62, which is about two months either side). The denominator is the number of such occasions. The numerator is the number of those months in which the site itself recovered target virus. Distances are straight-line distances in the projection crs. Two sites at the same coordinates are not counted as neighbours.

Each rate carries an exact (Clopper-Pearson) 95% interval. Two further measures are reported beside the verdict but do not decide it: retention, the share of samples between mid_weeks weeks after a campaign with Sabin detected, as a percentage of campaign response; and background, the share of samples more than floor_weeks weeks after a campaign with Sabin detected. Retention is NA when the site's campaign response rate is zero or missing, since it cannot be expressed as a percentage of nothing.

Trend

A site's campaign response samples are split at trend_years years before the latest sample in the network (default 3). For a site whose first sample falls after that date, the split is instead new_site_months months (default 12) before the latest sample. Both parts need at least trend_min_n samples (default 5). A site has declined when its recent percentage is at least trend_drop_pts points (default 15) below its earlier percentage and a two-sided Fisher's exact test gives a p-value below trend_alpha (default 0.05).

Verdict

Only active sites are judged: those whose last sample falls within active_months months (default 12) of the latest sample in the network. The judged percentage is the recent campaign response percentage where the trend could be tested, and the whole-record campaign response percentage otherwise. Rules are applied in this order and the first that holds wins:

Fewer than min_n campaign response samples (default 5), including none: unjudged ("Too few samples").
Judged percentage below floor_pct (default 30): below_floor.
A decline as defined above: falling.
At least isolation_min_samples samples with a final result (default 5) and enterovirus isolation below isolation_min_pct percent (default 50): low_isolation. This rule needs isolation.
Otherwise: working.

Examples

# \donttest{
es_score_cols()
#> $samples
#> $samples$country
#> [1] "country_iso3code"
#> 
#> $samples$sample_id
#> [1] "sample_id"
#> 
#> $samples$site_guid
#> [1] "site_guid"
#> 
#> $samples$site_code
#> [1] "site_code"
#> 
#> $samples$site_name
#> [1] "site_name"
#> 
#> $samples$adm1
#> [1] "adm1"
#> 
#> $samples$adm2
#> [1] "adm2"
#> 
#> $samples$adm2_guid
#> [1] "adm2_guid"
#> 
#> $samples$longitude
#> [1] "site_x_coordinate"
#> 
#> $samples$latitude
#> [1] "site_y_coordinate"
#> 
#> $samples$collection_date
#> [1] "collection_date"
#> 
#> $samples$sabin
#> [1] "vaccine1" "vaccine2" "vaccine3"
#> 
#> $samples$target
#> [1] "wild1" "vdpv2"
#> 
#> 
#> $campaigns
#> $campaigns$country
#> [1] "country_iso3code"
#> 
#> $campaigns$adm2_guid
#> [1] "adm2_guid"
#> 
#> $campaigns$status
#> [1] "activity_status"
#> 
#> $campaigns$vaccine_type
#> [1] "activity_vaccine_type"
#> 
#> $campaigns$start_date
#> [1] "activity_date_from"
#> 
#> 
#> $isolation
#> $isolation$site_guid
#> [1] "site_guid"
#> 
#> $isolation$ev_pct
#> [1] "ev_pct"
#> 
#> $isolation$resolved
#> [1] "resolved"
#> 
#> $isolation$months_sampled
#> [1] "months_sampled"
#> 
#> 
# }