-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.Rmd
116 lines (89 loc) · 4.51 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# xmart4 <a href='https://github.com/gpw13/xmart4'><img src='man/figures/logo.png' align="right" height="139" /></a>
<!-- badges: start -->
[](https://github.com/gpw13/xmart4/actions)
[](https://github.com/gpw13/xmart4/actions/workflows/test-coverage.yaml)
<!-- badges: end -->
The goal of xmart4 is to provide easy access to the World Health Organization's
xMart4 API by managing client access to the xMart. Once a machine is connected to the
database, xmart4 provides a simple interface to interact with the OData API by
pulling in tables and marts directly into R.
## Installation
You can install xmart4 from [GitHub](https://github.com/gpw13/xmart4) with:
``` r
remotes::install_github("gpw13/xmart4", build_vignettes = TRUE)
```
## Connection types
To get setup with the xmart4 package, there are two ways to authenticate your machine
with the Azure database. Following xMart's team recommendations, the package has
switched to use the client authentification as a default (it was WIMS access before).
The guide for this setup can be found below or in the relevant vignette:
* `vignette("azure-client-setup", package = "xmart4")`
However, for some use cases, particularly dashboards, Shiny applications, or other
non-interactive R pipelines, we instead want to setup a separate Azure client to
connect to the xMart4 database. The instructions for these are in the
following vignette:
* `vignette("azure-token-setup", package = "xmart4")`
## Azure Client Setup
```{r child = "vignettes/azure-client-setup.Rmd"}
```
## Getting data
Once you have sorted out access to the xMart4 database using one of the two methods
above, you can start using the simple functions available in the package to access
xMart4 marts and tables.
* `xmart4_mart()` provides a character vector of all available tables and views in a specified mart.
* `xmart4_table()` retrieves data from a specified mart or table.
Using both should just require you to specify mart name, server (UAT or PROD),
and table name (if applicable). It's as easy as opening an R session and going:
```{r example_mart}
library(xmart4)
head(xmart4_mart("GPW13"))
```
Let's access the CONVERT table.
```{r example_convert}
xmart4_table(mart = "GPW13", table = "CONVERT", xmart_server = "UAT")
```
And I can request the top $n$ rows of a table and even supply OData filters
with my request. This is especially useful in instances where tables or views
have many rows and requests may take a long time, so you can explore the table
on a small subset and find useful OData queries to reduce the size of the data
requested.
```{r example_top}
xmart4_table(mart = "GPW13",
table = "CONVERT",
top = 2,
query = "$filter=Input eq 'A'",
xmart_server = "UAT")
```
## Memoisation
`xmart4_api()`, the function underlying requests to the xMart4 API, has cached
functionality based on `memoise::memeoise()` so that calls to the
`xmart4_api()` function are cached in your local memory in a single session.
This means that once you've made a call to access an xMart mart or table/view,
running an identical request will use the cached data rather than re-request the
data from the xMart4 API. This provides large advantages when working with big
tables and views, as the API requests grow quite time consuming as the number of
rows grows. Load the xmart4 package explicitly through `library(xmart4)`, rather
than simply callin functions via `xmart4::fun()`.
This could be problematic if using the xmart4 package to test or consume
data from marts that are being updated throughout an R session. If you need to
ensure that the xmart4 package is making new requests to the API each time, then
you will need to run `memoise::forget(xmart4:::xmart4_api)` to clear the cache
prior to repeating a call. See the documentation of the
[memoise package](https://github.com/r-lib/memoise) for more details.
## Contributions
Additional feature requests should be made through the
[GitHub issues page](https://github.com/xmart4/xmart4/issues). Any contributions
appreciated and encouraged, but please create an open issue first for discussion
before proceeding with a pull request.