RcensusPkg (version 0.1.5)

get_idb_data: get_idb_data

Description

Get data from the Census Bureau's Time Series International Database for a specific dataset: Single Year of Age and Sex("1year") or 5-Year Age Groups and Sex("5year"), year, variables, and country. See Census Bureau's publicly available International Database for dataset descriptions.

Usage

get_idb_data(
  dataset = NULL,
  years = 2023,
  vars = NULL,
  group = FALSE,
  wide_to_long = FALSE,
  countries = NULL,
  ages = 1:100,
  sex = c(0, 1, 2),
  key = Sys.getenv("CENSUS_KEY")
)

Value

A data.table

Arguments

dataset

A required string that selects the dataset of interest. Acceptable values are "1year" or "5year".

years

An optional numeric vector that sets the years of interest. The default is 2023.

vars

An optional string vector of variable names to be acquired. The default is GEO_ID,NAME,GENC,POP for either "1year" or "5year".

group

A logical that if TRUE returns all the variables from the "5year" dataset. The default is FALSE.

wide_to_long

The returned data.table is normally in a wide format with all the variables as columns. If this logical parameter is TRUE then a long format is returned with variable names in one column (named "estimate") and their respective values in another column (named "value").

countries

An optional string vector of country/area abbreviations (GENC Standard Countries and Areas) of interest. GENC codes are available here.

ages

An optional numeric that selects specific ages(0 to 100 range) from the 1year dataset. Default is all ages.

sex

An optional numeric vector to select the sex of interest from the 1year dataset. Acceptable values 0 - Both, 1 - Male, 2 - Female. Default is all three values for sex.

key

A string that sets the access key. All Census Bureau API requests require an access key. Sign-up for a key is free and can be obtained here. The function will check for a global setting of the key via Sys.getenv("CENSUS_KEY"). Run usethis::edit_r_environ() and edit your .Renviron file with the line: CENSUS_KEY=your key to create the global association. This is a required parameter.

Details

For the "1year", a data.table is returned with the following columns:

GEO_ID	char - geo id string
NAME	char - name of the country
GENC	char - GENC country abbreviation
POP	char - the total population for a specific age and sex in the country
YR	char - the year of the estimate
AGE	char - the specific age are values from 1 to 100
SEX	char - the specific sex with values 0 - Both, 1 - Male, 2 - Female

More details are available here.

For the "5year", see 5year and the 119 variable names and descriptions.

Examples

if (FALSE) {
  # Requires Census Bureau API key
  library(data.table)
  library(httr2)
  library(jsonlite)
  library(RcensusPkg)

  # 1year wide form, default variables, 2 countries
  # (Botswana, Norway)
  one_year_dt <- RcensusPkg::get_idb_data(
    dataset = "1year",
    years = c(2023, 2024),
    countries = c("BW", "NO")
  )

  # 5year long form, all variables, 2023, country = US
  five_year_US_long_group_dt <- RcensusPkg::get_idb_data(
    dataset = "5year",
    years = 2023,
    group = TRUE,
    countries = "US",
    wide_to_long = TRUE
  )
}