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

xmart4

R build status test-coverage

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 with:

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:

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:

Azure Client Setup


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.

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:

library(xmart4)

head(xmart4_mart("GPW13"))

Let's access the CONVERT table.

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.

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 for more details.

Contributions

Additional feature requests should be made through the GitHub issues page. Any contributions appreciated and encouraged, but please create an open issue first for discussion before proceeding with a pull request.



gpw13/xmart4 documentation built on May 12, 2022, 8:35 p.m.