R/gho_data.R

In gpw13/ghost: R Client for the Global Health Observatory API

#' Load data from the GHO
#'
#' `gho_data()` loads data on any number of indicators from the GHO into a single data frame.
#'
#' @param inds A character vector of indicator codes from the GHO database. Takes any of the codes in the `IndicatorCode` column of the data frame generated by [gho_indicators()].
#' @param query A character vector of strings fitting the [Odata protocol](https://www.odata.org/documentation/odata-version-2-0/uri-conventions/) that must start with \code{"$filter="}.
#'   If one string provided, query will be recycled for each value in `inds`, otherwise the length of `inds` and `query` must match.
#' @param year_range A string specifying whether the beginning and end values of the year range should be `"numeric"`, the default,
#'   or `"date"`.
#'
#' @return A data frame.
#'
#' @export
gho_data <- function(inds,
                     query = NULL,
                     year_range = "numeric") {
  assert_indicator(inds)
  if (length(inds) == length(query)) {
    ret <- purrr::map2(inds, query, ~ gho_api(.x, .y)[["content"]])
  } else {
    ret <- lapply(inds, function(x) gho_api(x, query = query)[["content"]])
  }
  ret <- dplyr::bind_rows(ret)
  convert_year_range(ret, year_range)
}

#' @title Load available dimensions from the GHO
#'
#' @description \code{gho_dimensions()} provides a data frame of all available [dimensions in the GHO](https://www.who.int/data/gho/info/gho-odata-api#exe1).
#'
#' @param query A string fitting the [Odata protocol](https://www.odata.org/documentation/odata-version-2-0/uri-conventions/) that must start with \code{"$filter="}.
#'
#' @return A data frame.
#'
#' @export
gho_dimensions <- function(query = NULL) {
  resp <- gho_api("DIMENSION", query = query)
  resp$content
}

#' @title Load available indicators from the GHO
#'
#' @description \code{gho_indicators()} provides a data frame of all available [indicators in the GHO](https://www.who.int/data/gho/info/gho-odata-api#exe3).
#'
#' @param query A string fitting the [Odata protocol](https://www.odata.org/documentation/odata-version-2-0/uri-conventions/) that must start with \code{"$filter="}.
#'
#' @return A data frame.
#'
#' @export
gho_indicators <- function(query = NULL) {
  resp <- gho_api("INDICATOR", query = query)
  resp$content
}

#' @title Load values for specific GHO dimension
#'
#' @description \code{gho_dimension_values()} provides a data frame of all [available values for a specific dimension](https://www.who.int/data/gho/info/gho-odata-api#exe2).
#'
#' @param dim A string of the dimension code from the GHO. Takes one of the codes in the \code{Code} column of the data frame generated by [gho_dimensions()].
#' @param query A string fitting the [Odata protocol](https://www.odata.org/documentation/odata-version-2-0/uri-conventions/) that must start with \code{"$filter="}.
#'
#' @return A data frame.
#'
#' @export
gho_dimension_values <- function(dim, query = NULL) {
  assert_dimension(dim)
  resp <- gho_api(paste0("DIMENSION/", dim, "/DimensionValues"), query = query)
  resp$content
}