Plot an overview of TB Burden for Multiple Countries

Source: R/plot_tb_burden_overview.R

This functions returns a dot plot for a given metric over a specified list of countries. If compare_to_region is specified then a given country will be compared to others in its region. This enables the user to rapidly understand trends in Tuberculosis over time and the progress towards global elimination.

plot_tb_burden_overview(df = NULL, dict = NULL,
  metric = "e_inc_100k", metric_label = NULL, countries = NULL,
  years = NULL, compare_to_region = FALSE, facet = NULL,
  annual_change = FALSE, trans = "identity", legend = "right",
  scales = "free_y", interactive = FALSE, download_data = TRUE,
  save = TRUE, viridis_palette = "viridis", viridis_direction = -1,
  viridis_end = 0.9, 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.
countries

A character string specifying the countries to target.
years

Numeric vector of years. Defaults to NULL which includes all years in the data.
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".
facet

Character string, the name of the variable to facet by.
annual_change

Logical, defaults to FALSE. If TRUE then the percentage annual change is computed for the specified metric.
trans

A character string specifying the transform to use on the specified metric. Defaults to no transform ("identity"). Other options include log scaling ("log") and log base 10 scaling ("log10"). For a complete list of options see ggplot2::continous_scale.
legend

Character string, defaults to "right". Position of the legend see ?ggplot2::theme for defaults but known options are: "none", "top", "right" and "bottom".
scales

Character string, see ?ggplot2::facet_wrap for details. Defaults to "fixed", alternatives are "free_y", "free_x", or "free".
interactive

Logical, defaults to FALSE. If TRUE then an interactive plot is returned.
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.
viridis_palette

Character string indicating the viridis colour palette to use. Defaults to "viridis". Options include "cividis", "magma", "inferno", "plasma", and "viridis". For additional details see viridis_pal for additional details.
viridis_direction

Numeric, indicating the direction for the colour palette (1 or -1), defaults to -1. See scale_color_viridis for additional details.
viridis_end

Numeric between 0 and 1, defaults to 0.9. The end point of the viridis scale to use. #' See scale_color_viridis for additional details.
verbose

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

Additional arguments to pass to get_tb_burden.

Value

A dot plot of any numeric metric by country.

See also

get_tb_burden search_data_dict

Examples


## Plot incidence rates over time for both the United Kingdom and Botswana
plot_tb_burden_overview(countries = c("United Kingdom", "Botswana"),
                        compare_to_region = FALSE)
#> Loading data from: /tmp/RtmpA3cD0E/tb_burden.rds
#> Loading data from: /tmp/RtmpA3cD0E/mdr_tb.rds
#> Joining TB burden data and MDR TB data.
#> Loading data from: /tmp/RtmpA3cD0E/dictionary.rds
#> 1 results found for your variable search for e_inc_100k

## Plot percentage annual change in incidence rates.
plot_tb_burden_overview(countries = c("United Kingdom", "Botswana"),
                        compare_to_region = FALSE, annual_change = TRUE)
#> Loading data from: /tmp/RtmpA3cD0E/tb_burden.rds
#> Loading data from: /tmp/RtmpA3cD0E/mdr_tb.rds
#> Joining TB burden data and MDR TB data.
#> Loading data from: /tmp/RtmpA3cD0E/dictionary.rds
#> 1 results found for your variable search for e_inc_100k

## Compare incidence rates in the UK and Botswana to incidence rates in their regions
plot_tb_burden_overview(countries = c("United Kingdom", "Botswana"),
                        compare_to_region = TRUE)
#> Loading data from: /tmp/RtmpA3cD0E/tb_burden.rds
#> Loading data from: /tmp/RtmpA3cD0E/mdr_tb.rds
#> Joining TB burden data and MDR TB data.
#> Loading data from: /tmp/RtmpA3cD0E/dictionary.rds
#> 1 results found for your variable search for e_inc_100k

## Find variables relating to mortality in the WHO dataset
search_data_dict(def = "mortality")
#> Loading data from: /tmp/RtmpA3cD0E/dictionary.rds
#> 9 results found for your definition search for mortality
#> # A tibble: 9 x 4
#>   variable_name      dataset  code_list definition                              
#>   <chr>              <chr>    <chr>     <chr>                                   
#> 1 e_mort_100k        Estimat… ""        Estimated mortality of TB cases (all fo…
#> 2 e_mort_100k_hi     Estimat… ""        Estimated mortality of TB cases (all fo…
#> 3 e_mort_100k_lo     Estimat… ""        Estimated mortality of TB cases (all fo…
#> 4 e_mort_exc_tbhiv_… Estimat… ""        Estimated mortality of TB cases (all fo…
#> 5 e_mort_exc_tbhiv_… Estimat… ""        Estimated mortality of TB cases (all fo…
#> 6 e_mort_exc_tbhiv_… Estimat… ""        Estimated mortality of TB cases (all fo…
#> 7 e_mort_tbhiv_100k  Estimat… ""        Estimated mortality of TB cases who are…
#> 8 e_mort_tbhiv_100k… Estimat… ""        Estimated mortality of TB cases who are…
#> 9 e_mort_tbhiv_100k… Estimat… ""        Estimated mortality of TB cases who are…

## Compare mortality rates (exc HIV) in the UK and Botswana to mortality rates in their regions
## Do not show progress messages
plot_tb_burden_overview(metric = "e_mort_exc_tbhiv_100k",
                        countries = c("United Kingdom", "Botswana"),
                        compare_to_region = TRUE, verbose = FALSE)