am_data: Retrieve Data from the Database

Description

This is the main function of the package to retrieve data from the database.

Usage

am_data(
  ctry = africamonitor::am_countries$ISO3,
  series = NULL,
  from = NULL,
  to = NULL,
  labels = TRUE,
  wide = TRUE,
  expand.date = FALSE,
  drop.1iso3c = TRUE,
  ordered = TRUE,
  return.query = FALSE,
  ...
)

Value

A data.table with the result of the query.

Arguments

ctry: character. (Optional) the ISO3 code of countries (see am_countries). Default is to load data for all African countries. Putting NULL gets data for all countries (codes available in am_countries_wld).
series: character. (Optional) codes of series matching the 'Series' column of the series table (retrieved using am_series()).
from: set the start time of the data retrieved by either supplying a start date, a date-string of the form "YYYY-MM-DD" or "YYYY-MM", year-quarters of the form "YYYYQN" or "YYYY-QN", a numeric year YYYY (numeric or character), or a fiscal year of the form "YYYY/YY". These expressions are converted to a regular date by am_as_date.
to: same as from: to set the time period until which data is retrieved. For expressions that are not full "YYYY-MM-DD" dates, the last day of the period is chosen.
labels: logical. TRUE will also return labels (series descriptions) along with the series codes.
wide: logical. TRUE calls am_pivot_wider on the result. FALSE returns the data in a long format without missing values (suitable for ggplot2).
expand.date: logical. TRUE will call am_expand_date on the result.
drop.1iso3c: logical. If only one country is selected through ctry, TRUE will drop the 'ISO3' column in the output.
ordered: logical. TRUE orders the result by 'Date' and, if labels = TRUE, by series, maintaining a fixed column-order of series. FALSE returns the result in a random order, to the benefit of faster query execution.
return.query: logical. TRUE will not query the database but instead return the constructed SQL query as a character string (for debugging purposes).
...: further arguments passed to am_pivot_wider (if wide = TRUE) or am_expand_date (if expand.date = TRUE).

Details

If labels = FALSE, the series table is not joined to the data table, and ordered = TRUE will order series retrieved in alphabetic order. If labels = TRUE data is ordered by series and date, preserving the order of columns in the dataset. If multiple countries are received they are ordered alphabetically according to the 'ISO3' column.

Series at different frequencies can be queried, but, if wide = TRUE, this will result in missing values for all but the first observations per period in the lower frequency series.

Examples

Run this code

# \donttest{
# Return all indicators for Kenya from 2000
am_data("KEN", from = 2000)

# Return all indicators for Kenya from 2000 in long format
am_data("KEN", from = 2000, wide = FALSE)

# Return with date expanded
am_data("KEN", from = 2000, expand.date = TRUE)

# Same thing in multiple steps (with additional customization options):
am_data("KEN", from = 2000, wide = FALSE) |> am_pivot_wider() |> am_expand_date()

# Getting only GDP growth
am_data("KEN", "NGDP_RPCH", from = 2000)

# Getting GDP growth for all countries
am_data(series = "NGDP_RPCH", from = 2000)

# Reshaping to wider format
am_data(series = "NGDP_RPCH", from = 2000) |>
  am_pivot_wider(id_cols = "Date",
                 names_from = "ISO3",
                 values_from = "NGDP_RPCH")

# Getting growth and inflation for the EAC countries (all available years)
am_data(ctry = c("UGA", "KEN", "TZA", "RWA", "BDI", "SSD"),
        series = c("NGDP_RPCH", "PCPIPCH"))

# }