getTBinR (version 0.5.5)

summarise_tb_burden: Summarise TB Burden

Description

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% confidence intervals) and the median (with 95% interquartile range). An incidence rate and weighted proportion statistic are in development.

Usage

summarise_tb_burden(df = NULL, dict = NULL, metric = "e_inc_100k",
  metric_label = NULL, conf = c("_lo", "_hi"), years = NULL,
  samples = 1000, countries = NULL, compare_to_region = FALSE,
  compare_to_world = FALSE, custom_compare = NULL,
  compare_all_regions = FALSE, stat = "mean", denominator = NULL,
  truncate_at_zero = TRUE, annual_change = FALSE,
  download_data = TRUE, save = TRUE, burden_save_name = "TB_burden",
  dict_save_name = "TB_data_dict", verbose = TRUE)

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 plot.

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 FALSE. Should a comparision 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 FALSE. Should all regions be compared.

stat

Character string, defaults to "mean". The statistic to use to summarise the metric, currently "mean" and "median" are supported. Note "mean" and "median" do not recompute the supplied country levels values. Future options will include the weighted proportion and the summarised incidence rate.

denominator

Character string identifying the variable to use as a denominator in any proportion or rate calculation.

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.

burden_save_name

Character string, name to save the data under. Defaults to "TB_burden".

dict_save_name

Character string, name to save dictionary under. Defaults to TB_data_dict.

verbose

Logical, defaults to TRUE. Should additional status and progress messages be displayed.

Value

A tibble containing summarised values (with 95 stratified by area and year.

Examples

# NOT RUN {
## 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,
                    samples = 100,
                    compare_all_regions = TRUE,
                    compare_to_world = TRUE,
                    verbose = TRUE)

## 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)
                    
# }