## ----setup, include = FALSE---------------------------------------------------
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5,
  fig.align = "center",
  message = FALSE,
  warning = FALSE
)

## ----load-packages------------------------------------------------------------
library(datacommons)
library(dplyr)
library(stringr)
library(ggplot2)
library(scales)
library(knitr)

## ----un-setup-----------------------------------------------------------------
un_base_url <- "https://unsd-datacommons.gcp.un-icc.cloud/core/api/v2/"
dc_set_base_url(un_base_url)

## ----un-check, echo=FALSE-----------------------------------------------------
# Skip live queries during R CMD check on CRAN. R CMD build doesn't set
# _R_CHECK_PACKAGE_NAME_, so the vignette shipped in the tarball still renders
# fully.
on_cran_check <- nzchar(Sys.getenv("_R_CHECK_PACKAGE_NAME_")) &&
  !identical(Sys.getenv("NOT_CRAN"), "true")

if (on_cran_check) {
  knitr::knit_exit()
}

un_reachable <- tryCatch(
  {
    dc_get_node(
      nodes = "country/RWA",
      expression = "->name", return_type = "list"
    )
    TRUE
  },
  error = function(e) FALSE
)

if (!un_reachable) {
  message(
    "This vignette requires network access to the UN System Data Commons."
  )
  knitr::knit_exit()
}

## ----inspect-place------------------------------------------------------------
rwanda_regions <- dc_get_node(
  nodes = "country/RWA",
  expression = "->containedInPlace",
  return_type = "list"
)

rwanda_regions$data$`country/RWA`$arcs$containedInPlace$nodes |>
  lapply(\(x) {
    data.frame(
      name = x$name,
      types = paste(x$types, collapse = ", ")
    )
  }) |>
  bind_rows() |>
  kable(caption = "Places containing Rwanda")

## ----inspect-variable---------------------------------------------------------
dc_get_node(
  nodes = "undata/unicef/DM_POP.SEX--F",
  expression = "->[name, populationType]",
  return_type = "list"
) |>
  str(max.level = 5)

## ----population-by-sex--------------------------------------------------------
east_africa <- c(
  "country/BDI",
  "country/KEN",
  "country/RWA",
  "country/TZA",
  "country/UGA"
)

pop_by_sex <- dc_get_observations(
  date = "latest",
  variable_dcids = c(
    "undata/unicef/DM_POP.SEX--F",
    "undata/unicef/DM_POP.SEX--M"
  ),
  entity_dcids = east_africa,
  return_type = "data.frame"
) |>
  mutate(sex = if_else(str_detect(variable_name, "Female"), "Female", "Male"))

pop_by_sex |>
  select(country = entity_name, sex, value) |>
  arrange(country, sex) |>
  kable(caption = "Latest population by sex, East Africa")

## ----population-by-sex-plot---------------------------------------------------
ggplot(
  pop_by_sex,
  aes(x = reorder(entity_name, value), y = value, fill = sex)
) +
  geom_col(position = "dodge") +
  coord_flip() +
  scale_y_continuous(labels = label_comma()) +
  labs(
    title = "Population by Sex, East African Countries",
    x = NULL,
    y = "Population",
    fill = "Sex",
    caption = "Source: UNICEF via UN System Data Commons"
  )

## ----resolve-places-----------------------------------------------------------
dc_get_resolve(
  nodes = c("Kenya", "Uganda"),
  expression = "<-description->dcid",
  return_type = "list"
) |>
  str()