In dark-peak-analytics/who_decide_AP: R Package to facilitate easy access to geospatial model data

knitr::opts_chunk$set(
  eval = FALSE,
  collapse = TRUE,
  comment = "#>"
)

library(bolsteR)

The aim of this simple Vignette is to get the user familiar with the bolsteR. This package uses R6 classes to allow for a clean and seamless experience.

Interacting directly with the R6 classes - without the shiny app:

The first step is to create an object of class Country_R6. To create such an object we need two things; the name of the country we want to query the APIs about and an API key or token. The key we need is for the Healthsities.io API. The Healthsities.io API key is optional, especially if health-sites data is not of interest to you. Please follow the following steps to get your own Healthsities.io API key.

1. Establish an OpenStreetMap account:
   • https://www.openstreetmap.org/user/new
2. Sign into Healthsites with your OSM account:
   • https://Healthsities.io.io/map
3. Get an API token off your profile page:
   • Click on your user profile to open your profile page.
   • There you will find an option to generate/view the API key/token.

Once you have your API key, you will need to keep it somewhere safe and readily accessible to the relevant functions. The package provides two helper-functions, set_hs_API_key and get_hs_API_key, to assist with this task. The former saves the Healthsities.io API key as an environment variable (a locally accessible variable), while the second one retrieves it. Below is a demonstration of this functionality. Please note that by default the get_hs_API_key function expects the name of the environment variable housing the Healthsities.io API key to be "Healthsites_API_key"; to this effect, make sure you retrieve the correct variable should you decide to save your API key via other methods but the set_hs_API_key.

# Set Healthsities.io API key as an environment variable:
# Using 123abcdefg as an API key:
set_hs_API_key(API_key = "123abcdefg")

# Get the locally stored Healthsities.io API key:
key <- get_hs_API_key(env_var_name = "Healthsites_API_key")

Now that we have set the API key, we can create our first Country_R6 object. Lets consider Kenya as a country of interest for this example. The first step is to instantiate a copy of class Country_R6, think of this as creating or getting your own copy of the API querying machine. To do this, we invoke the new function (better known as the new method but we will keep it simple for now). The new function requires two arguments, the name of the country (Kenya) and the Healthsities.io API key. To keep your API key safe, you can use the get_hs_API_key function to feed it directly to the new function. Please note that you (the user) may not want to query the Healthsites.io API, and therefore do not have or do not want to use the API key. In such occasions, you simply have the choice not to invoke the hs_API_key argument when instantiating your copy of the Country_R6 class.

# Instantiate a copy of class Country_R6:
Kenya <- Country_R6$
  new(country_name = "Kenya",
      hs_API_key = get_hs_API_key())

The first feedback we get is a vector of information indicating if the country of interest's (Kenya's) data was available in the respective API. In the current example, all four APIs seem to have Kenya-specific data.

Querying the APIs:

The package provides a few ways to initiate the process of fetching data from the relevant APIs, when such data is available. Actually, the first time this happens is when the APIs are queried about the availability of data (as we discussed in the previous section). For the next set of actions we will look at a group of functions (the initiate_ family) that either grab the country data, or some auxiliary data, off the APIs. As the name suggests, we mainly need to trigger any of these functions the first time we interact with the respective API(s); in fact, calling any of these functions more than once results in nothing (as if they were not executed).

The initiate_APIs is a wrapper function that happens to call the initiation function(s) of the API(s) that contain data for the country of interest. Below we demonstrate the use of the other initiate_xxx functions. Kindly remember that the time required by any of the initiate_xxx functions depends on the speed of your internet connection, the status of the API server, your local machine and the amount of data available for the country of interest.

On a different note, the package provides several functions that allows the user to interact with the information returned from the APIs, we call these functions getters, and they all start with get_. On the other hand, functions that start with set_ are called setters and they mostly interact with or request data from the API(s).

The getter functions are unlike the new and initiate_xxx in that they return something (a data table or a map); while the latter ones return nothing (at least to the user). This distinction is important if you (the user) were chaining the functions. Chaining is better illustrated by the following example.

The Global Health Observatory (GHO) API:

To initiate the GHO API we use the initiate_GHO_API function which fetches all available GHO indicators. The user can then access the GHO indicators by using the get_gho_ind_list function to identify the GHO indicator of interest. For example, if the user wants the value of the Ambient air pollution attributable DALYs per 100'000 children under 5 years, then they should pass the indicator's code/label AIR_10 to the get_gho_ind_data function. The code for this example is shown below.

# Initiate the API:
Kenya$
  initiate_GHO_API()
# Check the indicators:
Kenya$
  get_gho_ind_list() %>% 
  head(10)
# Query the GHO for the indicator with the label "AIR_10":
Kenya$
  get_gho_ind_data(indicator_code_ = "AIR_10")

The following lines of code shows how the initiating the API and checking the indicators could be done in one step by chaining the get_gho_ind_list function to the initiate_GHO_API.

# Chaining: initiate the API and check the indicators:
Kenya$
  initiate_GHO_API()$
  get_gho_ind_list() %>% 
  head(10)

Chaining is a feature of R6 class objects' methods (again just think of methods as functions in this context), but requires the chained-to function (the initiate_GHO_API in this example) to return invisible (i.e. to return nothing to the user). This constraint means that chaining two getter functions (or any functions that return something, but invisible, when called) together throws an error.

The Demographic and Health Surveys (DHS) API:

In line with the previous API, the DHS API is initiated via the initiate_DHS_API function. Unlike the GHO API initiation function, this function retrieves the entire data for the country of interest. Once it finished fetching the data, this function populates two objects, the dhs_survey_years and dhs_indicators. These two objects informs the user of the available surveys and the indicators observed in all of them. This user can go through the data available in these objects and use a survey year or indicator label to filter the data using the get_dhs_survey_data and get_dhs_ind_data functions, respectively. A simple example is shown below.

# Initiate the API and check the survey years:
Kenya$
  initiate_DHS_API()$
  dhs_survey_years

# Get data from the 2020 survey:
Kenya$
  get_dhs_survey_data(survey = 2020) %>% 
  head(10)

# Check surveys' indicators: 
Kenya$
  dhs_indicators %>% 
  head(10)

# Get data for the "Age specific fertility rate: 25-29" indicator:
Kenya$
  get_dhs_ind_data(
    indicator_name = 'FE_FRTR_W_A25', 
    filter_var = 'IndicatorId')

Please note that the FE_FRTR_W_A25, in the get_dhs_ind_data function, is the indicator's label or identifier, not name. The same function can be used with indicator names for example (Age specific fertility rate: 25-29), however, the filter_var must be changed to Indicator instead of IndicatorId.

The World Bank (WB) API:

Similar to the previous APIs, the WB API is initiated using initiate_WB_API function which fetches available WB indicators and stores them in the internal object wb_indicators.

# Initiate the API and search for the "GDP" indicator label/code:
Kenya$
  initiate_WB_API()$
  wb_indicators %>%
  dplyr::filter(grepl(pattern = "domestic product", x = name))

# Request data for the "Gross domestic product (in USD)" and investigate the results:
Kenya$
  set_wb_data(indicator_label = "C1.12")$
  get_wb_ind_data()

The Healthsites.io (HS) API:

The initiate_HS_API is the only function in this package that interacts with the Healthsites.io API. Once triggered/called, this function retrieves all health sites data available via the API and stores it in the Country_R6 object. The user can get the data returned from the HS API via the get_facilities_data, get_facilities_stats, and get_facilities_map functions. The first and second functions return the raw and processed health sites data, respectively; whereas, the last one returns a map showing the locations and characteristics of the fetched health sites.

# Initiate the API:
Kenya$
  initiate_HS_API()
# Retrieve raw data:
Kenya$
  get_facilities_data() %>% 
  head(10)
# Get facilities' counts:
Kenya$
  get_facilities_stats()
# Plot facilities data on a map:
Kenya$
  get_facilities_map()

Interacting indirectly with the R6 classes - via the shiny app:

The package is shipped with a demo shiny app the allows the user to interact swiftly with the APIs. Execute run_API_demo_App() in the console to run the app.

dark-peak-analytics/who_decide_AP documentation built on May 25, 2022, 8:31 p.m.