---
title: "An R API to the Oxford COVID-19 Database"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{An R API to the Oxford COVID-19 Database}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The primary use case for the `oxcovid19` package is for facilitating a simplified, R-based workflow for 1) connecting to the [OxCOVID19](https://covid19.eng.ox.ac.uk) [PostgreSQL](https://www.postgresql.org) server; 2) accessing table/s available from the [PostgreSQL](https://www.postgresql.org) server; and, 3) querying the [PostgreSQL](https://www.postgresql.org) server with specific parameters to customise table/s output for intended use. This workflow is illustrated in the workflow diagram below:

<br>

```{r workflow, echo = FALSE, eval = TRUE, fig.width = 8, fig.height = 10, fig.pos = "center"}
DiagrammeR::grViz("
  digraph oxcovid19 {

    # a 'graph' statement
    graph [overlap = false, fontsize = 12, fontname = Helvetica]

    # Terminal nodes
    node [shape = oval, width = 1.5, penwidth = 2, fontsize = 14]
        
    a [label = '@@1'; color = darkgreen; fontcolor = darkgreen];
    h [label = '@@8'; color = crimson; fontcolor = crimson];

    # Input/output nodes
    node [shape = parallelogram, fixedsize = true, height = 1, width = 1.5, penwidth = 2, color = royalblue1, fontcolor = royalblue1]
    
    b [label = '@@2'];

    # Process nodes
    node [shape = rect]
  
    d [label = '@@4'];
    f [label = '@@6'];

    # Package nodes
    node [shape = oval, fixedsize = TRUE, width = 2, penwidth = 2, fontsize = 10, fontname = Courier, color = darkviolet, fontcolor = darkviolet]
    
    c [label = '@@3';];
    e [label = '@@5'];
    g [label = '@@7'];

    edge [minlen = 2, arrowsize = 0.75, penwidth = 2, color = dimgray]
    
    a -> b
    b -> d
    d -> f
    f -> h

    edge [minlen = 3]

    b -> c
    c -> b
    d -> e
    e -> d
    f -> g
    g -> f

    subgraph {
      rank = same; b; c;
    }

    subgraph {
      rank = same; d; e;
    }

    subgraph {
      rank = same; f; g;
    }

  }

    [1]: 'START'
    [2]: 'Step 1:\\nConnect\\nto server'
    [3]: 'oxcovid19\\nconnect_oxcovid19()'
    [4]: 'Step 2:\\nRetrieve\\ntable'
    [5]: 'oxcovid19\\nget_table; get_layer'
    [6]: 'Step 3:\\nQuery\\ntable'
    [7]: 'dplyr - filter; select\\nsf - st_read'
    [8]: 'END'
")
```
<br>

The following code demonstrates how this workflow can be implemented in R:

```{r workflow1, echo = TRUE, eval = TRUE}
library(oxcovid19)

## Step 1: Create a connection to OxCOVID19 PostgreSQL server
con <- connect_oxcovid19()

## Step 2: Access epidemiology table from OxCOVID19 PostgreSQL server
epi_tab <- get_table(con = con, tbl_name = "epidemiology")

## Step 3: Query the epidemiology table to show data for Great Britain
gbr_epi_tab <- dplyr::filter(.data = epi_tab, countrycode == "GBR")
```

**Step 1** and **Step 2** above are facilitated by the `connect_oxcovid19` and the `get_table` functions provided by the `oxcovid19` package. These functions are basically low-level wrappers to functions in the [`DBI`](https://db.rstudio.com/dbi/) and [`RPostgres`](https://rpostgres.r-dbi.org) packages applied specifically to work with the [OxCOVID19](https://covid19.eng.ox.ac.uk) [PostgreSQL](https://www.postgresql.org). These functions facilitate convenient access to the server for general R users without having to learn to use the `DBI` and `RPostgres` packages.

**Step 3**, on the other hand, is facilitated by the `dplyr` package functions which were designed to work with different types of tables including those from various database server connections such as [PostgreSQL](https://www.postgresql.org).

The output of the workflow shown above is:

```{r workflow2, echo = FALSE, eval = TRUE}
gbr_epi_tab
```

The `oxcovid19` package functions are also designed to allow *pipe operations* using the `magrittr` package. The workflow above can be done using piped operations as follows:

```{r workflow3, echo = TRUE, eval = TRUE}
## Load magrittr to use pipe operator %>%
library(magrittr)

connect_oxcovid19() %>%
  get_table(tbl_name = "epidemiology") %>%
  dplyr::filter(countrycode == "GBR")
```

The workflow using the piped workflow outputs the same result as the earlier workflow but with a much streamlined use of code.

