In como-ph/oxcgrt: An Interface to the Oxford COVID-19 Government Response Tracker API

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

oxcgrt: An Interface to the Oxford COVID-19 Government Response Tracker API

The Oxford COVID-19 Government Response Tracker (OxCGRT) tracks and compares worldwide government responses to the COVID-19 pandemic rigorously and consistently. OxCGRT makes available systematic information in a consistent way, aiding those who require information have access to it efficiently. This package facilitates access to the OxCGRT data for R users via version 2 of its API. This package also includes functions to calculate the various OxCGRT indices in R. This package is aimed at R users who use or plan to use the OxCGRT data for their research or for other academic purposes or who develop or want to develop other metrics or indices that build on the OxCGRT approach.

What does oxcgrt do?

The oxcgrt package has two main sets of functions that:

1. Retrieve OxCGRT data (get_* functions) via version 2 of its API; and,

2. Calculate various OxCGRT indicators, sub-indices and indices (calculate_* functions).

There are other R packages that provide access to data from the OxCGRT. The COVID19 package and the oxcovid19 package are just two examples of these. However, all these packages provide access to the OxCGRT data as data dumps and only for the time-series of the stringency index per country. To our knowledge, the oxcgrt package is the only R package currently that provides an interface to the available API for querying and retrieving data. Also, the oxcgrt package provides functions to calculate the OxCGRT sub-indices and indices based on their methodology. None of the other R packages that we have seen and reviewed have this functionality.

Installation

You can install the released version of oxcgrt from CRAN with:

install.packages("oxcgrt")

And the development version from GitHub with:

if(!require(remotes)) install.packages("remotes")
remotes::install_github("como-ph/oxcgrt")

Usage

The oxcgrt data retrieval workflow via API

The retrieve data functions are based on the OxCGRT's JSON API described here. Two API endpoints are provided: 1) endpoint for JSON providing data for stringency index by country over time; and, 2) endpoint for JSON providing data on policy actions and stringency index for a specific country on a specific day.

For each of these endpoints, the data retrieval workflow is composed of two steps: first is the creation of the appropriate API URL query; and, second is the retrieval of the appropriate data as per query into a data.frame structure usable in R. This workflow is show in code below:

## Load oxcgrt package
library(oxcgrt)

## Step 1: Create the appropriate API URL query for time series data from 
## 1 June 2020 up to current day
query <- get_json_time(from = "2020-06-01")

## Step 2: Retrieve the data
get_data_time(query)

This results in the following:

## Load oxcgrt package
library(oxcgrt)

## Step 1: Create the appropriate API URL query for time series data from 
## 1 June 2020 up to current day
query <- get_json_time(from = "2020-06-01")

## Step 2: Retrieve the data
get_data_time(query)

The oxcgrt functions are designed to work with pipe operators via the magrittr package. The steps shown above can be replicated using pipe operators as follows:

## Load magrittr package
library(magrittr)

get_json_time(from = "2020-06-01") %>%    ## Step 1: Creat API URL query
  get_data_time()                         ## Step 2: Retrieve data

This results in the same output as the earlier workflow albeit sorted alphabetically by country code:

## Load magrittr  package
library(magrittr)

get_json_time(from = "2020-06-01") %>%    ## Step 1: Creat API URL query
  get_data_time()                         ## Step 2: Retrieve data

For more detailed examples of how to retrieve data via the OxCGRT API version 2, read Retrieve data via OxCGRT API.

The oxcgrt calculate workflow

The calculate_* functions are based on the OxCGRT's methodology described here. There are two sets of calculate functions included in oxcgrt. The first calculates the OxCGRT sub-indices and the second calculates the four OxCGRT indices which are composed of various combinations of the indicators used by OxCGRT sub-indices and indices.

For more detailed examples of how to calculate the various OxCGRT sub-indices and indices, read Calculate OxCGRT sub-indices and indices.

Datasets

The oxcgrt package comes with helpful datasets which serve as guides to facilitate in usage and interpretation of the OxCGRT data.

Codebook

The OxCGRT provides an authoritative codebook found here. The oxcgrt package has extracted the tables from this documentation into a single codebook that can serve as a handy and convenient reference for an R user when working with OxCGRT data in R. The OxCGRT codebook can be accessed as follows:

codebook

which outputs the codebook as a singular table in tbl format as shown below:

codebook

The current oxcgrt package version includes the OxCGRT codebook version 2.5 released on 4 November 2020.

Example OxCGRT indicators dataset

In the OxCGRT methodology document, an example indicator dataset is used to demonstrate the calculation of per indicator sub-indices and the four main indices that OxCGRT provides. This example dataset has been made available in table format in the oxcgrt package and can be accessed as follows:

indicatorData

which outputs the example data as a singular table in tbl format as shown below:

indicatorData

This dataset is used by the oxcgrt package to test the calculate_* functions and for demonstrating how these functions work. This dataset can be useful for those trying to learn the OxCGRT's calculation methods and R users who are learning how to use the oxcgrt package calculate_* functions.

Limitations

The current version of oxcgrt package is experimental in that its stability and future development would depend on the OxCGRT's current and future development. The OxCGRT is in continuous evolution given that the COVID-19 pandemic is still on-going and various governments' responses to it are continuously changed and/or updated. The OxCGRT has also been developing other indices that capture other aspects of governments' responses not yet covered by current indices.

The oxcgrt package author and maintainer commit to ensuring that current functions are maintained and/or updated in a manner that ensures backwards compatibility should changes to the data structure and/or to the indices calculation are implemented by the OxCGRT team. This would include maintaining the arguments used by the current functions, maintaining the functionality of the current functions, and maintaining the type of outputs of the current functions. Should changes implemented by the OxCGRT team to the data structure and/or to the indices calculation require the breaking of the syntax, functionality and/or outputs of the current functions, a formal and proper deprecation process will be implemented that include proper and detailed documentation of the changes and the potential impact on current users.

Disclaimer

The oxcgrt package is an independent development and is separate from and not recognised and approved by the OxCGRT team. The author and maintainer of the package is not affiliated with OxCGRT but is committed to ensure fidelity to the methods and usage specified by OxCGRT and accuracy of outputs described and required by OxCGRT.

Any mistakes, problems and issues with the functionality and outputs of the oxcgrt including mistakes in interpretation of the calculation of the sub-indices and indices noted (if any) are that of the author and maintainer and not of the OxCGRT. Hence any problems and issues to the usage, functionality and outputs of the oxcgrt package should be addressed directly to the author and maintainer here.

Citation

When using the oxcgrt package, please cite both the source of the OxCGRT data and oxcgrt package itself.

For the source of the OxCGRT data, the following citation is recommended:

Hale, Thomas, Noam Angrist, Emily Cameron-Blake, Laura Hallas, Beatriz Kira, Saptarshi Majumdar, Anna Petherick, Toby Phillips, Helen Tatlow, Samuel Webster (2020). Oxford COVID-19 Government Response Tracker, Blavatnik School of Government.

For the oxcgrt package, the suggested citation can be obtained using a call to the citation function as follows:

citation("oxcgrt")

Community guidelines

Feedback, bug reports and feature requests are welcome; file issues or seek support here. If you would like to contribute to the package, please see our contributing guidelines.

This project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

como-ph/oxcgrt documentation built on April 7, 2022, 9:27 a.m.