getTBinR

getTBinR: an R package for accessing and summarising the World Health Organisation Tuberculosis data - Published in JOSS (2019)

https://github.com/seabbs/gettbinr

Keywords

Keywords from Contributors

Scientific Fields

Repository

An R package for accessing and summarising the World Health Organisation Tuberculosis data.

README.Rmd

---
output: github_document
---

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/"
)
```

# getTBinR: Access and Summarise World Health Organization Tuberculosis Data  

[![badge](https://img.shields.io/badge/Launch-getTBinR-blue.svg)](https://mybinder.org/v2/gh/seabbs/getTBinR/master?urlpath=rstudio) 
[![CRAN_Release_Badge](http://www.r-pkg.org/badges/version-ago/getTBinR)](https://CRAN.R-project.org/package=getTBinR)
[![develVersion](https://img.shields.io/badge/devel%20version-0.7.1-blue.svg?style=flat)](https://github.com/seabbs/getTBinR)
[![DOI](https://zenodo.org/badge/112591837.svg)](https://zenodo.org/badge/latestdoi/112591837)
[![DOI](http://joss.theoj.org/papers/10.21105/joss.01260/status.svg)](https://doi.org/10.21105/joss.01260)
[![metacran monthly downloads](http://cranlogs.r-pkg.org/badges/getTBinR)](https://cran.r-project.org/package=getTBinR)
[![metacran downloads](http://cranlogs.r-pkg.org/badges/grand-total/getTBinR?color=ff69b4)](https://cran.r-project.org/package=getTBinR)

Quickly and easily import analysis ready Tuberculosis (TB) burden data, from the World Health Organization (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. See [here](http://www.who.int/about/copyright/en/) for the WHO data permissions. For help getting started see the [Getting Started](https://www.samabbott.co.uk/getTBinR/articles/intro.html) vignette and for a case study using the package see the [Exploring Global Trends in Tuberculosis Incidence Rates](https://www.samabbott.co.uk/getTBinR/articles/case_study_global_trends.html) vignette.

## Installation

Install the CRAN version:

```{r cran-installation, eval = FALSE}
install.packages("getTBinR")
```

Alternatively install the development version from GitHub:

```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("seabbs/getTBinR")
```

## Documentation

[![Documentation](https://img.shields.io/badge/Documentation-release-lightgrey.svg?style=flat)](https://www.samabbott.co.uk/getTBinR/)
[![Development documentation](https://img.shields.io/badge/Documentation-development-lightblue.svg?style=flat)](https://www.samabbott.co.uk/getTBinR/dev)
[![Getting started](https://img.shields.io/badge/Documentation-getting started-yellow.svg?style=flat)](https://www.samabbott.co.uk/getTBinR/articles/intro.html)
[![Functions](https://img.shields.io/badge/Documentation-functions-orange.svg?style=flat)](https://www.samabbott.co.uk/getTBinR/reference/index.html)


## Testing

[![Travis-CI Build Status](https://travis-ci.org/seabbs/getTBinR.svg?branch=master)](https://travis-ci.org/seabbs/getTBinR)
[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/seabbs/getTBinR?branch=master&svg=true)](https://ci.appveyor.com/project/seabbs/getTBinR)
[![Coverage Status](https://img.shields.io/codecov/c/github/seabbs/getTBinR/master.svg)](https://codecov.io/github/seabbs/getTBinR?branch=master)

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

```{r map-tb-incidence-eur, fig.height = 4, fig.width = 8}
getTBinR::map_tb_burden(metric = "e_inc_100k")
```

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

```{r plot-tb-incidence-eur, fig.height = 8}
getTBinR::plot_tb_burden_overview(metric = "e_inc_100k",
                                  countries = "United Kingdom",
                                  compare_to_region = TRUE)
```

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

```{r plot-tb-incidence-eur-per, fig.height = 8}
getTBinR::plot_tb_burden_overview(metric = "e_inc_100k",
                                  countries = "United Kingdom",
                                  compare_to_region = TRUE,
                                  annual_change = TRUE)
```

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

```{r plot-tb-incidence-uk-compare}
getTBinR::plot_tb_burden_summary(metric = "e_inc_num",
                                 metric_label = "e_inc_100k",
                                 countries = "United Kingdom",
                                 compare_all_regions = FALSE,
                                 compare_to_region = TRUE,
                                 compare_to_world = TRUE)
```

We can 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.

```{r plot-tb-incidence-uk}
getTBinR::plot_tb_burden(metric = "e_inc_100k",
                         countries = "United Kingdom")
```

We might be interested in having some of this information in tablular form. We can either generate a short summary for the most recent year of available data with the following, 

```{r summarise-metric}
getTBinR::summarise_metric(metric = "e_inc_100k",
                           countries = "United Kingdom")
```


Or a more detailed dataset as follows, 

```{r summarise_tb_burden}
getTBinR::summarise_tb_burden(metric = "e_inc_num",
                              stat = "rate",
                              countries = "United Kingdom", 
                              compare_to_world = FALSE, 
                              compare_to_region = FALSE) 

```

Here `e_inc_num` is used rather than `e_inc_100k` as incidence rates are being estimated based on notified cases. This allows country level rates to be compared to regional (using `compare_to_region = TRUE`) and global (using `compare_to_world = TRUE`) rates.

See [Functions](https://www.samabbott.co.uk/getTBinR/reference/index.html) for more details of the functions used (note the fuzzy country matching, all functions 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 the plots above interactive by specifying `interactive = TRUE`


## Additional datasets

On top of the core datasets provided by default, `getTBinR` also supports importing multiple other datasets. These include data on latent TB, HIV surveillance, intervention budgets, and outcomes. The currently supported datasets are listed below,

```{r additional_datasets}
knitr::kable(getTBinR::available_datasets[, 1:4])
```

These datasets can be imported into `R` by supplying the name of the required dataset to the `additional_datasets` argument of `get_tb_burden` (or any of the various plotting/summary functions). Alternatively, they can all be imported in one go using `additional_datasets = "all"`, as below, 

```{r import-additional_datasets}
getTBinR::get_tb_burden(additional_datasets = "all")
```

Once imported, these datasets can be used in the plotting and summary functions provided by `getTBinR` (by passing them to their `df` argument or using the `additional_datasets` argument in each function). See the contributing section if their are any other datasets that you think `getTBinR` should support or if you have suggestions for better descriptions for each dataset.

## WHO-inspired themes and palettes. 

The WHO makes use of several standardised plot themes and colour palettes. `getTBinR` implements these so that the package can be easily used internally at the WHO or by those collaborating with the WHO. 

```{r who-theme-example, message = FALSE, warning = FALSE}
getTBinR::plot_tb_burden_summary(countries = "United Kingdom", 
                                 compare_all_regions = FALSE, 
                                 compare_to_region = TRUE) +
  getTBinR::theme_who() +
  getTBinR::scale_colour_who(reverse = TRUE) +
  getTBinR::scale_fill_who(reverse = 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, 

```{r run-dash, eval = FALSE}
getTBinR::run_tb_dashboard()
```

Or accessed [online](http://www.seabbs.co.uk/shiny/ExploreGlobalTB). 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.](man/figures/ExploreGlobalTB.png)


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

```{r, eval = FALSE}
## Code saves report into your current working directory
render_country_report(country = "United Kingdom", save_dir = ".")
```

![Example report for the United Kingdom.](man/figures/ExampleCountryReport.png)


## Contributing

File an issue [here](https://github.com/seabbs/getTBinR/issues) if there is a feature, or a dataset, that you think is missing from the package, or better yet submit a pull request!

Please note that the `getTBinR` project is released with a [Contributor Code of Conduct](https://github.com/seabbs/getTBinR/blob/master/.github/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.

## Citing 

If using `getTBinR` please consider citing the package in the relevant work. Citation information can be generated in R using the following (after installing the package),

```{r}
citation("getTBinR")
```

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

```{bash, eval = FALSE}
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. Alternatively, access the development environment via [binder](https://mybinder.org/v2/gh/seabbs/getTBinR/master?urlpath=rstudio).

Owner

JOSS Publication

getTBinR: an R package for accessing and summarising the World Health Organisation Tuberculosis data

Published

February 26, 2019

DOI

10.21105/joss.01260

Volume 4, Issue 34, Page 1260

Authors

Sam Abbott
Bristol Medical School: Population Health Sciences, University of Bristol, Bristol, UK

Editor

Tania Allard

Tags

rstats World Health Organisation Open Data Visualisation Infectious Disease Tuberculosis

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 5 months ago

Issues and Pull Requests

Last synced: 4 months ago