Access and Summarise World Health Organisation Tuberculosis data

Quickly and easily import analysis ready Tuberculosis (TB) burden data, from the World Health Organisation (WHO), into R. The aim of getTBinR is to allow researchers, and other interested individuals, to quickly and easily gain access to a detailed TB data set and to start using it to derive key insights. It provides a consistent set of tools that can be used to rapidly evaluate hypotheses on a widely used data set before they are explored further using more complex methods or more detailed data. These tools include: generic plotting and mapping functions; a data dictionary search tool; an interactive shiny dashboard; and an automated, country level, TB report. For newer R users, this package reduces the barrier to entry by handling data import, munging, and visualisation. All plotting and mapping functions are built with ggplot2 so can be readily extended.


CRAN_Release_Badge develVersion Travis-CI Build Status AppVeyor Build Status Coverage Status metacran monthly downloads metacran downloads

Quickly and easily import analysis ready TB burden data, from the World Health Organisation (WHO), into R. The aim of the package is to speed up access to high quality TB burden data, using a simple R interface. Generic plotting functions are provided to allow for rapid graphical exploration of the WHO TB data. A shiny dashboard is built in to showcase package functionality. See here for the WHO data permissions. For help getting started see the Getting Started vignette and for a case study using the package see the Exploring Global Trends in Tuberculosis Incidence Rates vignette. See here for the development documentation.

Installation

Install the CRAN version:

install.packages("getTBinR")

Alternatively install the development version from GitHub:

devtools::install_github("seabbs/getTBinR")

Quick start

Lets get started quickly by mapping and then plotting TB incidence rates in the United Kingdom. First map the most recently available global TB incidence rates (this will also download and save both the TB burden data and its data dictionary, if they are not found locally, to R's temporary directory),

getTBinR::map_tb_burden(metric = "e_inc_100k")
#> Downloading data from: https://extranet.who.int/tme/generateCSV.asp?ds=estimates
#> Saving data to: /tmp/RtmpdWPpNq/TB_burden.rds
#> Downloading data from: https://extranet.who.int/tme/generateCSV.asp?ds=mdr_rr_estimates
#> Saving data to: /tmp/RtmpdWPpNq/MDR_TB.rds
#> Joining TB burden data and MDR TB data.
#> Downloading data from: https://extranet.who.int/tme/generateCSV.asp?ds=dictionary
#> Saving data to: /tmp/RtmpdWPpNq/TB_data_dict.rds
#> 1 results found for your variable search for e_inc_100k

Then compare TB incidence rates in the UK to TB incidence rates in other countries in the region,

getTBinR::plot_tb_burden_overview(metric = "e_inc_100k",
                                  countries = "United Kingdom",
                                  compare_to_region = TRUE,
                                  interactive = FALSE)
#> Loading data from: /tmp/RtmpdWPpNq/TB_burden.rds
#> Loading data from: /tmp/RtmpdWPpNq/MDR_TB.rds
#> Joining TB burden data and MDR TB data.
#> Loading data from: /tmp/RtmpdWPpNq/TB_data_dict.rds
#> 1 results found for your variable search for e_inc_100k

In order to compare the changes in incidence rates over time, in the region, plot the annual percentage change,

getTBinR::plot_tb_burden_overview(metric = "e_inc_100k",
                                  countries = "United Kingdom",
                                  compare_to_region = TRUE,
                                  annual_change = TRUE,
                                  interactive = FALSE)
#> Loading data from: /tmp/RtmpdWPpNq/TB_burden.rds
#> Loading data from: /tmp/RtmpdWPpNq/MDR_TB.rds
#> Joining TB burden data and MDR TB data.
#> Loading data from: /tmp/RtmpdWPpNq/TB_data_dict.rds
#> 1 results found for your variable search for e_inc_100k

Now plot TB incidence rates over time in the United Kingdom, compared to TB incidence rates in Europe and globally.

getTBinR::plot_tb_burden_summary(metric = "e_inc_num",
                                 metric_label = "e_inc_100k",
                                 countries = "United Kingdom",
                                 legend = "top",
                                 compare_all_regions = FALSE,
                                 compare_to_region = TRUE,
                                 compare_to_world = TRUE,
                                 interactive = FALSE)
#> Loading data from: /tmp/RtmpdWPpNq/TB_data_dict.rds
#> 1 results found for your variable search for e_inc_100k
#> Extracting data for specified countries
#> Loading data from: /tmp/RtmpdWPpNq/TB_burden.rds
#> Loading data from: /tmp/RtmpdWPpNq/MDR_TB.rds
#> Joining TB burden data and MDR TB data.
#> Loading data from: /tmp/RtmpdWPpNq/TB_data_dict.rds
#> 1 results found for your variable search for e_inc_num
#> Loading data from: /tmp/RtmpdWPpNq/TB_burden.rds
#> Loading data from: /tmp/RtmpdWPpNq/MDR_TB.rds
#> Joining TB burden data and MDR TB data.
#> Loading data from: /tmp/RtmpdWPpNq/TB_data_dict.rds
#> 1 results found for your variable search for e_inc_num
#> Loading data from: /tmp/RtmpdWPpNq/TB_burden.rds
#> Loading data from: /tmp/RtmpdWPpNq/MDR_TB.rds
#> Joining TB burden data and MDR TB data.
#> Loading data from: /tmp/RtmpdWPpNq/TB_data_dict.rds
#> 1 results found for your variable search for e_inc_num

Finally we repeat the above plot but this time only for the UK - this allows us to get a clear picture of trends in TB incidence rates in the UK.

getTBinR::plot_tb_burden(metric = "e_inc_100k",
                         countries = "United Kingdom",
                         interactive = FALSE)
#> Loading data from: /tmp/RtmpdWPpNq/TB_burden.rds
#> Loading data from: /tmp/RtmpdWPpNq/MDR_TB.rds
#> Joining TB burden data and MDR TB data.
#> Loading data from: /tmp/RtmpdWPpNq/TB_data_dict.rds
#> 1 results found for your variable search for e_inc_100k

See Functions for more details of the functions used (note the fuzzy country matching, map_tb_burden, plot_tb_burden_overview, plot_tb_burden_summary and plot_tb_burden will try to exactly match your country request and if that fails will search for partial matches) and for more package functionality. We could make these plots interactive by specifying interactive = TRUE

Shiny Dashboard

To explore the package functionality in an interactive session, or to investigate TB without having to code extensively in R, a shiny dashboard has been built into the package. This can either be used locally using,

getTBinR::run_tb_dashboard()

Or accessed online. Any metric in the WHO data can be explored, with country selection using the built in map, and animation possible by year.

Snapshot of the integrated dashboard.

Country Report

To get a detailed overview of TB in a country of your choice run the following, alternatively available from the built in dashboard above.

## Code saves report into your current working directory
render_country_report(country = "United Kingdom", save_dir = ".")

Example report for the United Kingdom.

Additional Functionality

File an issue here if there is a feature, or a dataset, that you think is missing from the package, or better yet submit a pull request!

Docker

This package has been developed in docker based on the rocker/tidyverse image, to access the development environment enter the following at the command line (with an active docker daemon running),

docker pull seabbs/gettbinr
docker run -d -p 8787:8787 -e USER=getTBinR -e PASSWORD=getTBinR --name getTBinR seabbs/gettbinr

The rstudio client can be accessed on port 8787 at localhost (or your machines ip). The default username is getTBinR and the default password is getTBinR.

News

getTBinR 0.5.7

Feature updates

  • Added support for annual_change to summarise_tb_burden and added validating tests.
  • Added support for rates and proportions to summarise_tb_burden and added validating tests.
  • Added a new function - plot_tb_burden_summary. Function wraps summarise_tb_burden and allows all in one summary plotting. Inspired by this case study.
  • Added a rmarkdown parameterised country level report on TB.
  • Added a report generating button to the dashboard generated by run_tb_dashboard.
  • Added render_country_report to generate a TB report for a given country.
  • Tweaked map_tb_burden to not use geom_path for country outlines.
  • Added a smooth argument to plot_tb_burden to allow smooth trend lines to be plotted (derived using ggplot2::geom_smooth).
  • Tweaked line thickness in plot_tb_burden to improve plot appearance.
  • Added legend argument to all plotting functions to allow control of the legend appearance.

Package updates

  • Added script to generate hexsticker
  • Added hexsticker to README
  • Added DOI link to Zenodo. (to do on CRAN release).
  • Updated tests to account for dplyr 8.0 release and vdiffr updates.
  • Added itdepends to package report functionality.

getTBinR 0.5.6

Feature updates

  • No new features in this release

Package updates

  • Updated custom legend setting in map_tb_burden to work with new version of rlang.
  • Updated map_tb_burden tests to work with new version of R lang.
  • Added dev to pkgdown site yml for docs prior to release.

getTBinR 0.5.5

Feature updates

  • Added a years filter to plot_tb_burden and plot_tb_burden_overview. This allows a range of years to be plotted. The default is all years which was the previous de facto default.

Package updates

  • Updated docs to reflect new year of data.
  • Updated examples to use the new year of data as standard.
  • Updated README to always use the current year of data.
  • Updated all vignettes to reflect new data or be fixed to historic data as appropriate.
  • Update site with links out to blog posts using the newest version of pkgdown.

getTBinR 0.5.4

Feature updates

  • Added MDR-TB data for 2016, see here for the dataset. The MDR-TB data is automatically joined to the WHO TB burden data.
  • Aesthetic updates to map_tb_burden.
  • Added new summarise_tb_burden function for summarising metrics across regions, across custom groups and globally.

Package updates

  • Improved data cleaning, converting Inf and NaN values to NA when the data is read in.
  • Added pgknet report.
  • Improved test robustness and scope
  • Added vdiffr to test plots when not on CRAN.
  • Fixed bug for map_tb_burden which was adding duplicate variables which caused map build to fail.

getTBinR 0.5.3

Feature updates

  • Added viridis_palette option to all plotting functions to allow the colour scheme to be set by the user.
  • Added ability to handle categories in the legend for map_tb_burden
  • Added new case study exploring case fatality rates.

Package updates

  • Added improved tests in response to WHO data updates. See here
  • Added an additional method for downloading data in response to test failures on CRAN. See here
  • Added skip on CRAN for data backend related tests.
  • Added Makefile at top level and for data-raw to build the package.

getTBinR 0.5.2

Feature updates

  • Improved plotly tool tips in all interactive plots.
  • Added option to pass multiple years for interactive maps using the built in plotly frame functionality.

Package updates

  • Added retry download option to deal with possible API rate limits in response to this issue.
  • Added downloads badge to readme.

getTBinR 0.5.1

Feature updates

  • Added annual_change argument to all plotting/mapping functions. Passed to prepare_df_plot. Returns the percentage annual change for the supplied metric.
  • Added trans argument to all plotting functions to allow scaling using any ggplot2::continous_scale trans argument.
  • Added adaptive axis and legend labels to properly show annual percentage change.
  • Added run_tb_dashboard to launch a shiny dashboard for exploring global tuberculosis
  • Changed function defaults so that data is automatically downloaded and saved into the temporary directory when get_data functions are called.

Package updates

  • Added new examples to display new functionality
  • Updated readme with new functionality
  • Updated intro vignette with new functionality
  • Added a new case studies vignette section
  • Added a case study exploring global trends in Tuberculosis incidence rates
  • Added a work around using utils::read.csv for downloading the data when fread::data.table fails. Related to this issue.

getTBinR 0.5.0

Feature updates

  • Added download_data argument to all functions to make downloading data explicit.
  • Added save argument to all functions to make saving the data explicit.
  • Added save_name and path arguments to all functions to make location of saving explicit.

Package updates

  • Updated documentation to reflect above changes.
  • Updated tests to reflect changes.
  • Doc improvements ready for CRAN.
  • Switched Imported packages from github versions to CRAN versions.
  • Switched to saving data only to temporary directory (tempdir())

getTBinR 0.1.0

Feature updates

  • Added map_tb_burden function to map TB metrics.

Package updates

  • Added a NEWS.md file to track changes to the package.

getTBinR 0.0.5

Feature updates

  • Added plot_tb_burden_overview function to plot an overview of the TB burden.

Package updates

  • Updated the package site.
  • Refactored plotting code.

getTBinR 0.0.1

Feature updates

  • Added plot_tb_burden function to plot TB burden

Package updates

  • Set up package infractstructure

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.