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

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.
You can install xmart4 from GitHub with:
remotes::install_github("gpw13/xmart4", build_vignettes = TRUE)
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")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:
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")
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.
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.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.