In databrew/whobcnapp: WHO BCN app

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  echo = TRUE, 
  warning = FALSE, 
  message = FALSE, 
  fig.path = "man/figures/README-",
  error = TRUE,
  out.width = "100%"
)

whobcnapp

whobcnapp is an R package containing utilities for both (a) transforming data per the specifications of the "Data Assessment Report" and and (b) visualizing that data in the form of a production-ready shiny web application.

Installation

You can install the most recent version of whobcnapp from GitHub with the following:

# install.packages("devtools")
devtools::install_github('databrew/whobcnapp')

Alternatively, one can build the package locally by first cloning the https://github.com/databrew/whobcnapp repository, then running the build_package.R script.

Usage

Data transformation utilities

Overview

The functions for "cleaning" data are customized for the formats currently used by the office. In general terms, the work flow is as follows:

• Define an "input" document (a country-specific MS Excel file)
• Run a series of operations on that document, thereby generating...
• An "output" of a series of machine-readable, structured tables ready for (a) upload to a SQL database, (b) manipulation or analysis as flat files using a statistical software, or (c) consumption by a web app.

For further details on the rationale and formats of these transformations, see the "UHC Policy Watch Platform Design: DATA ASSESSMENT REPORT".

Walk-through

One starts by preparing the workspace with the necessary packages:

library(tidyr)
library(dplyr)
library(lubridate)
library(readxl)
library(whobcnapp)

Next, one must define the input file to be transformed. For the purpose of this example, we'll use BUL_Appendix_tables.xlsx which is available at https://github.com/databrew/whobcnapp/blob/master/data-raw/BUL_Appendix_tables.xlsx.

input_file <- 'data-raw/BUL_Appendix_tables.xlsx'

Having defined the path to the data, one uses the function conformity_check to ensure that the data to be read conforms to the requirements of the ETL process:

ok <- conformity_check(input_file)

If the file's format is correct, the function will return a boolean TRUE, and print a message saying:

The file conforms. OK to go on.

Otherwise, the function will return the nature of the non-conformity. For example:

conformity_check('xyz_tables.xlsx')

Error in conformity_check("xyz_tables.xlsx") : 
  The file should be named "ISO_Appendix_tables.xlsx", where "ISO" is the 3 letter ISO code of the country in question.

Having confirmed that the file to be read is of the correct format, one can use the read_data function to load each sheet of the Excel workbook into memory:

data <- read_data(input_file)

The result of the read_data function is a list of dataframes, in which the name of each element in the list reflects the figure for which the data corresponds.

cat(paste0(names(data), collapse = '\n'))

Data is structured uniformly into a "long" format, following the principles of "tidy data". All dataframe share the following columns:

• year
• value
• indicator
• iso

Whereas some dataframes have additional columns such as:

• quintile
• grp

Below are the column names and first 3 rows of each dataset as an example:

for(i in 1:length(data)){
  print(names(data)[i])
  print(head(data[[i]], 3))
}

Data visualization utilities

Having transformed data to a tidy, machine-readable format, standardized visualizations can be constructed. In the whobcnapp library, this functionality is indicated by functions with the plot_ prefix. These functions take a data object (as generated by read_data) and return a ggplot2() object.

Walk-through

First, we'll transform data so as to prepare it for plotting (covered in previous section).

# Define the path to the input file
input_file <- 'data-raw/BUL_Appendix_tables.xlsx'
# Confirm that the data is correctly formatted
ok <- conformity_check(input_file)
# Transform the data to a tidy/long format
data <- read_data(input_file)

Now, we can pass the data object to the plot_... function as such:

Figure 1

plot_fig1(data = data)

Figure 2

plot_fig2(data = data)

Figure 3

plot_fig3(data = data)

Figure 4

plot_fig4(data = data)

Figure 5

plot_fig5(data = data)

T2 data

plot_t2(data = data)

Web application

Development

In a development environment, an engineer will likely carry out the following work flow:

1. Clone this repository: https://github.com/databrew/whobcnapp
2. cd into it cd whobcnapp
3. Open and modify the code in R/app.R (for the shiny application itself) or in R/... (for upstream function code)
4. cd into dev and run Rscript run_dev.R to quickly re-build and serve the application locally.

Production

To run the web application (under construction), reproduce the following code in an R session:

library(whobcnapp)
whobcnapp::run_app()

databrew/whobcnapp documentation built on Dec. 19, 2021, 8:12 p.m.