Summarise TB Burden - By Region, Globally and for Custom Groups

Summarise TB burden metrics by region, globally, and for custom groupings. For variables with uncertainty represented by confidence intervals bootstrapping can be used (assuming a normal distribution) to include this in any estimated summary measures. Currently two statistics are supported; the mean (with 95\

summarise_tb_burden(
  df = NULL,
  dict = NULL,
  metric = "e_inc_num",
  metric_label = NULL,
  conf = c("_lo", "_hi"),
  years = NULL,
  samples = 1000,
  countries = NULL,
  compare_to_region = FALSE,
  compare_to_world = TRUE,
  custom_compare = NULL,
  compare_all_regions = TRUE,
  stat = "rate",
  denom = "e_pop_num",
  rate_scale = 1e+05,
  truncate_at_zero = TRUE,
  annual_change = FALSE,
  download_data = TRUE,
  save = TRUE,
  verbose = FALSE,
  ...
)

Arguments

df	Dataframe of TB burden data, as sourced by `get_tb_burden`. If not specified then will source the WHO TB burden data, either locally if available or directly from the WHO (if `download_data = TRUE`).
dict	A tibble of the data dictionary. See `get_data_dict` for details. If not supplied the function will attempt to load a saved version of the dictionary. If this fails and `download_data = TRUE` then the dictionary will be downloaded.
metric	Character string specifying the metric to plot
metric_label	Character string specifying the metric label to use.
conf	Character vector specifying the name variations to use to specify the upper and lower confidence intervals. Defaults to `NULL` for which no confidence intervals are used. Used by `annual_change`.
years	Numeric vector of years. Defaults to `NULL` which includes all years in the data.
samples	Numeric, the number of samples to use to generate confidence intervals (only used when `conf` are present)
countries	A character string specifying the countries to target.
compare_to_region	Logical, defaults to `FALSE`. If `TRUE` all countries that share a region with those listed in `countries` will be plotted. Note that this will override settings for `facet`, unless it is set to "country".
compare_to_world	Logical, defaults to `TRUE`. Should a comparison be made to the metric of interests global value.
custom_compare	Logical, defaults to `NULL`. A named list of custom countries.
compare_all_regions	Logical, defaults to `TRUE`. Should all regions be compared.
stat	Character string, defaults to `"rate"`. The statistic to use to summarise the metric, currently `"mean"`, `"median"`, `"rate"` and `"prop"` are supported. Note "mean" and "median" do not recompute the supplied country levels values but can be used to summarise the distribution of region or global metrics. `"prop"` and`"rate"` compute the overall incidence rate for a given grouping (i.e the sum of the metric divided by the sum of the denominator).
denom	Character string defaulting to `e_pop_num` (country level population). If `stat` is set to `rate` or `prop` then this is the parameter to use as the denominator.
rate_scale	Numeric defaults to 100,000. The scaling to use for rates. If `stat` is to set to `prop` then this defaults to 1.
truncate_at_zero	Logical, defaults to `TRUE`. Should lower bounds be truncated at zero?
annual_change	Logical, defaults to `FALSE`. If `TRUE` then the percentage annual change is computed for the specified metric.
download_data	Logical, defaults to `TRUE`. If not found locally should the data be downloaded from the specified URL?
save	Logical, should the data be saved for reuse during the current R session. Defaults to `TRUE`. If `TRUE` then the data is saved to the temporary directory specified by `tempdir`.
verbose	Logical, defaults to `FALSE`. Should additional status and progress messages be displayed.
...	Additional arguments to pass to `get_tb_burden`.

Value

A tibble containing summarised values (with 95% confidence intervals) for the metric of choice stratified by area and year.

Examples


## Get the most recent year of data
tb_burden <- get_tb_burden()
most_recent_year <- max(tb_burden$year)

## Get summary of the e_mdr_pct_rr_new cases
summarise_tb_burden(
  metric = "e_mdr_pct_rr_new",
  years = most_recent_year,
  stat = "mean",
  samples = 100,
  compare_all_regions = TRUE,
  compare_to_world = TRUE,
  verbose = TRUE
)
#> Loading data from: /var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T//RtmpxMXZ0P/tb_burden.rds
#> Loading data from: /var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T//RtmpxMXZ0P/mdr_tb.rds
#> Joining TB burden data and MDR TB data.
#> Loading data from: /var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T//RtmpxMXZ0P/dictionary.rds
#> 1 results found for your variable search for e_mdr_pct_rr_new
#> Loading data from: /var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T//RtmpxMXZ0P/tb_burden.rds
#> Loading data from: /var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T//RtmpxMXZ0P/mdr_tb.rds
#> Joining TB burden data and MDR TB data.
#> Loading data from: /var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T//RtmpxMXZ0P/dictionary.rds
#> 1 results found for your variable search for e_mdr_pct_rr_new
#> Filtering to use only data from: 2018
#> Confidence intervals were not found using your specified conf, so defaulting to estimating
#>                 only based on the point estimate.
#> # A tibble: 7 x 5
#>   area               year e_mdr_pct_rr_new e_mdr_pct_rr_new_… e_mdr_pct_rr_new_…
#>   <fct>             <int>            <dbl>              <dbl>              <dbl>
#> 1 Africa             2018             79.8               51.9               108.
#> 2 Americas           2018             71.4               41.0               102.
#> 3 Eastern Mediterr…  2018             79.6               39.2               120.
#> 4 Europe             2018             83.3               45.8               121.
#> 5 Global             2018             78.6               41.1               116.
#> 6 South-East Asia    2018             96.4               79.7               113.
#> 7 Western Pacific    2018             72.8               24.6               121.
if (FALSE) {
## Get median (with 95% IQR) of the case fatality rate for regions and the world
## Boostrapping uncertainty in country measures
summarise_tb_burden(
  metric = "cfr",
  years = most_recent_year,
  samples = 100,
  stat = "median",
  compare_all_regions = TRUE,
  compare_to_world = TRUE,
  verbose = FALSE
)


## Get summary data for the UK, Europe and the world
## Bootstrapping CI's
summarise_tb_burden(
  metric = "e_inc_num",
  samples = 100,
  stat = "median",
  countries = "United Kingdom",
  compare_to_world = TRUE,
  compare_to_region = TRUE,
  verbose = FALSE
)

## Get an overview of incidence rates regionally and globally compared to the UK
summarise_tb_burden(
  metric = "e_inc_num",
  stat = "rate",
  countries = "United Kingdom",
  compare_to_world = TRUE,
  compare_to_region = TRUE,
  verbose = FALSE
)
}