---
title: "Using EpiGraphDB R package"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using EpiGraphDB R package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---




```r
library("epigraphdb")
```

## Methods to query EpiGraphDB

We provide a
[list of functions](https://mrcieu.github.io/epigraphdb-r/index.html#functionalities)
that are equivalent to the
[upstream API endpoints](https://api.epigraphdb.org)
for users to use.
For endpoints that don't have equivalent functions, users can use the
[`query_epigraphdb`](https://mrcieu.github.io/epigraphdb-r/reference/query_epigraphdb.html)
function.

Here we show the two approaches to query MR data from EpiGraphDB, using the
[`mr`](https://mrcieu.github.io/epigraphdb-r/reference/mr.html) function and
using
[`query_epigraphdb`](https://mrcieu.github.io/epigraphdb-r/reference/query_epigraphdb.html)
to query the
[`GET /mr`](https://docs.epigraphdb.org/api/api-endpoints/#get-mr)
endpoint.

### `mr`


```r
df <- mr(
  exposure_trait = "Body mass index",
  outcome_trait = "Coronary heart disease",
  mode = "table"
)
df
#> # A tibble: 18 × 10
#>    exposure.id  exposure.trait  outcome.id  outcome.trait   mr.b  mr.se  mr.pval
#>    <chr>        <chr>           <chr>       <chr>          <dbl>  <dbl>    <dbl>
#>  1 ieu-a-2      Body mass index ieu-a-7     Coronary hear… 0.464 0.0415 5.46e-29
#>  2 ebi-a-GCST0… Body mass index ieu-a-7     Coronary hear… 0.457 0.0410 3.33e-20
#>  3 ieu-a-974    Body mass index ieu-a-7     Coronary hear… 0.389 0.0493 3.42e-15
#>  4 ieu-a-835    Body mass index ieu-a-7     Coronary hear… 0.417 0.0492 1.00e-11
#>  5 ieu-a-974    Body mass index ieu-a-9     Coronary hear… 0.320 0.0536 2.32e- 9
#>  6 ieu-a-2      Body mass index ieu-a-9     Coronary hear… 0.358 0.0535 5.91e- 9
#>  7 ieu-a-835    Body mass index ieu-a-9     Coronary hear… 0.397 0.0604 1.79e- 8
#>  8 ebi-a-GCST0… Body mass index ieu-a-9     Coronary hear… 0.341 0.0590 1.24e- 7
#>  9 ieu-a-95     Body mass index ieu-a-9     Coronary hear… 0.371 0.0708 1.62e- 7
#> 10 ebi-a-GCST0… Body mass index ieu-a-6     Coronary hear… 0.493 0.0986 5.88e- 7
#> 11 ieu-a-785    Body mass index ieu-a-9     Coronary hear… 0.395 0.0609 1.07e- 6
#> 12 ebi-a-GCST0… Body mass index ebi-a-GCST… Coronary hear… 0.309 0.0648 1.81e- 6
#> 13 ebi-a-GCST0… Body mass index ieu-a-8     Coronary hear… 0.309 0.0648 1.81e- 6
#> 14 ebi-a-GCST0… Body mass index ieu-a-7     Coronary hear… 0.275 0.0514 2.76e- 6
#> 15 ieu-a-95     Body mass index ieu-a-7     Coronary hear… 0.455 0.0971 2.82e- 6
#> 16 ieu-a-2      Body mass index ieu-a-8     Coronary hear… 0.317 0.0686 3.93e- 6
#> 17 ieu-a-2      Body mass index ebi-a-GCST… Coronary hear… 0.312 0.0688 5.86e- 6
#> 18 ieu-a-974    Body mass index ieu-a-8     Coronary hear… 0.328 0.0731 6.97e- 6
#> # … with 3 more variables: mr.method <chr>, mr.selection <chr>,
#> #   mr.moescore <dbl>
```

### `GET /mr`


```r
df <- query_epigraphdb(
  route = "/mr",
  params = list(
    exposure_trait = "Body mass index",
    outcome_trait = "Coronary heart disease"
  ),
  mode = "table"
)

df
#> # A tibble: 18 × 10
#>    exposure.id  exposure.trait  outcome.id  outcome.trait   mr.b  mr.se  mr.pval
#>    <chr>        <chr>           <chr>       <chr>          <dbl>  <dbl>    <dbl>
#>  1 ieu-a-2      Body mass index ieu-a-7     Coronary hear… 0.464 0.0415 5.46e-29
#>  2 ebi-a-GCST0… Body mass index ieu-a-7     Coronary hear… 0.457 0.0410 3.33e-20
#>  3 ieu-a-974    Body mass index ieu-a-7     Coronary hear… 0.389 0.0493 3.42e-15
#>  4 ieu-a-835    Body mass index ieu-a-7     Coronary hear… 0.417 0.0492 1.00e-11
#>  5 ieu-a-974    Body mass index ieu-a-9     Coronary hear… 0.320 0.0536 2.32e- 9
#>  6 ieu-a-2      Body mass index ieu-a-9     Coronary hear… 0.358 0.0535 5.91e- 9
#>  7 ieu-a-835    Body mass index ieu-a-9     Coronary hear… 0.397 0.0604 1.79e- 8
#>  8 ebi-a-GCST0… Body mass index ieu-a-9     Coronary hear… 0.341 0.0590 1.24e- 7
#>  9 ieu-a-95     Body mass index ieu-a-9     Coronary hear… 0.371 0.0708 1.62e- 7
#> 10 ebi-a-GCST0… Body mass index ieu-a-6     Coronary hear… 0.493 0.0986 5.88e- 7
#> 11 ieu-a-785    Body mass index ieu-a-9     Coronary hear… 0.395 0.0609 1.07e- 6
#> 12 ebi-a-GCST0… Body mass index ebi-a-GCST… Coronary hear… 0.309 0.0648 1.81e- 6
#> 13 ebi-a-GCST0… Body mass index ieu-a-8     Coronary hear… 0.309 0.0648 1.81e- 6
#> 14 ebi-a-GCST0… Body mass index ieu-a-7     Coronary hear… 0.275 0.0514 2.76e- 6
#> 15 ieu-a-95     Body mass index ieu-a-7     Coronary hear… 0.455 0.0971 2.82e- 6
#> 16 ieu-a-2      Body mass index ieu-a-8     Coronary hear… 0.317 0.0686 3.93e- 6
#> 17 ieu-a-2      Body mass index ebi-a-GCST… Coronary hear… 0.312 0.0688 5.86e- 6
#> 18 ieu-a-974    Body mass index ieu-a-8     Coronary hear… 0.328 0.0731 6.97e- 6
#> # … with 3 more variables: mr.method <chr>, mr.selection <chr>,
#> #   mr.moescore <dbl>
```

For more information on the API endpoints, please visit:

- The API Swagger interface https://api.epigraphdb.org
- The documentation on API endpoints https://docs.epigraphdb.org/api/api-endpoints/

## Returned data format

As a general principle, we offer two modes of the returned data:
a `table` mode (default) that returns a data frame,
and a `raw` mode that preserves the hierarchical structure of the upstream
json data and contains other information that might benefit users.

### `mode = "table"`

By default, for ease of use, the query returns a data frame which is a
tidyverse [`tibble`](https://tibble.tidyverse.org/):


```r
df <- mr(
  exposure_trait = "Body mass index",
  outcome_trait = "Coronary heart disease"
)
df
#> # A tibble: 18 × 10
#>    exposure.id  exposure.trait  outcome.id  outcome.trait   mr.b  mr.se  mr.pval
#>    <chr>        <chr>           <chr>       <chr>          <dbl>  <dbl>    <dbl>
#>  1 ieu-a-2      Body mass index ieu-a-7     Coronary hear… 0.464 0.0415 5.46e-29
#>  2 ebi-a-GCST0… Body mass index ieu-a-7     Coronary hear… 0.457 0.0410 3.33e-20
#>  3 ieu-a-974    Body mass index ieu-a-7     Coronary hear… 0.389 0.0493 3.42e-15
#>  4 ieu-a-835    Body mass index ieu-a-7     Coronary hear… 0.417 0.0492 1.00e-11
#>  5 ieu-a-974    Body mass index ieu-a-9     Coronary hear… 0.320 0.0536 2.32e- 9
#>  6 ieu-a-2      Body mass index ieu-a-9     Coronary hear… 0.358 0.0535 5.91e- 9
#>  7 ieu-a-835    Body mass index ieu-a-9     Coronary hear… 0.397 0.0604 1.79e- 8
#>  8 ebi-a-GCST0… Body mass index ieu-a-9     Coronary hear… 0.341 0.0590 1.24e- 7
#>  9 ieu-a-95     Body mass index ieu-a-9     Coronary hear… 0.371 0.0708 1.62e- 7
#> 10 ebi-a-GCST0… Body mass index ieu-a-6     Coronary hear… 0.493 0.0986 5.88e- 7
#> 11 ieu-a-785    Body mass index ieu-a-9     Coronary hear… 0.395 0.0609 1.07e- 6
#> 12 ebi-a-GCST0… Body mass index ebi-a-GCST… Coronary hear… 0.309 0.0648 1.81e- 6
#> 13 ebi-a-GCST0… Body mass index ieu-a-8     Coronary hear… 0.309 0.0648 1.81e- 6
#> 14 ebi-a-GCST0… Body mass index ieu-a-7     Coronary hear… 0.275 0.0514 2.76e- 6
#> 15 ieu-a-95     Body mass index ieu-a-7     Coronary hear… 0.455 0.0971 2.82e- 6
#> 16 ieu-a-2      Body mass index ieu-a-8     Coronary hear… 0.317 0.0686 3.93e- 6
#> 17 ieu-a-2      Body mass index ebi-a-GCST… Coronary hear… 0.312 0.0688 5.86e- 6
#> 18 ieu-a-974    Body mass index ieu-a-8     Coronary hear… 0.328 0.0731 6.97e- 6
#> # … with 3 more variables: mr.method <chr>, mr.selection <chr>,
#> #   mr.moescore <dbl>
```

### `mode = "raw"`

Alternatively, you can use `results_type = "raw"` to get the unformatted
response from EpiGraphDB API.


```r
response <- mr(
  exposure_trait = "Body mass index",
  outcome_trait = "Coronary heart disease",
  mode = "raw"
)
response %>% str(2)
#> List of 2
#>  $ metadata:List of 3
#>   ..$ query        : chr "MATCH (exposure:Gwas)-[mr:MR_EVE_MR]->(outcome:Gwas) WHERE exposure.trait = \"Body mass index\" AND outcome.tra"| __truncated__
#>   ..$ total_seconds: num 0.0207
#>   ..$ empty_results: logi FALSE
#>  $ results :List of 18
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
#>   ..$ :List of 3
```

There are several reasons that a `raw` mode might benefit you:

1. The `results` component preserves the upstream hierarchical json structure
   that might be useful for users aiming for specific tasks
   such as rendering network plots or batch post-processing the returned data
   in a large scale.

2. The `query` component returns
   the [cypher](https://neo4j.com/developer/cypher/)
   query that fetches data from the EpiGraphDB neo4j databases.
   EpiGraphDB will offer functionality (forthcoming) for users to
   send cypher queries to the web API that can return more complex query
   structure (visit our [web app](https://epigraphdb.org) for examples).
   Once you are sufficiently well-versed in cypher you can construct
   your own refined queries to better suit your needs.
