Package 'idbr'

Get Data from the US Census Bureau's International Data Base API

Description

Get Data from the US Census Bureau's International Data Base API

Usage

get_idb(
  country,
  year,
  variables = NULL,
  concept = NULL,
  age = NULL,
  sex = NULL,
  geometry = FALSE,
  resolution = c("low", "high"),
  api_key = NULL
)

Arguments

country	A country name or vector of country names. Can be specified as ISO-2 codes as well. Use country = "all" to request all countries available in the IDB.
year	A single year or vector of years for which you'd like to request data.
variables	A character string or vector of variables representing data you would like to request. If you are specifying an age or sex subset, this should be kept as NULL as the function will return data from the 1-year-of-age IDB API. If filtering by age or sex, should be NULL.
concept	Variables in the IDB are organized by concepts; if specified, request all variables for a given concept. Use idb_concepts() to view available concepts.
age	A vector of ages for which you would like to request population data. If specified, will return data from the 1-year-age-band IDB API. Should not be used when variables is not NULL.
sex	One or more of "both", "male", or "female". If specified, will return data from the 1-year-age-band IDB API. Should not be used when variables is not NULL.
geometry	If TRUE, returns country simple feature geometry along with your data which can be used for mapping. Geometry is obtained using the rnaturalearthdata R package.
resolution	one of "low" for lower-resolution (less-detailed) geometry, or #' "high" for more detailed geometry. It is recommended to use the low- resolution geometries for smaller-scale (e.g. world) mapping, and the higher-resolution geometries for medium-scale (e.g. regional) mapping.
api_key	Your Census API key. Can be supplied as part of the function call or set globally with the idb_api_key() function. If you are a tidycensus user with your API key already stored, get_idb() will pick up the API key from there, and no further action from you is required.

Value

A tibble or sf tibble of data from the International Data Base API.

Examples

## Not run: 
# Get data from the 1-year-age-band dataset by sex for China from
# 1990 through 2021

library(idbr)

china_data <- get_idb(
  country = "China",
  year = 1990:2021,
  age = 1:100,
  sex = c("male", "female")
 )

# Get data on life expectancy at birth for all countries in 2021 and
# make a map with ggplot2

library(idbr)
library(tidyverse)

lex <- get_idb(
  country = "all",
  year = 2021,
  variables = c("name", "e0"),
  geometry = TRUE
)
ggplot(lex, aes(fill = e0)) +
  theme_bw() +
  geom_sf() +
  coord_sf(crs = 'ESRI:54030') +
  scale_fill_viridis_c() +
  labs(fill = "Life expectancy at birth (2021)")

## End(Not run)

---

Set the Census API key

Description

Use to set the Census API key in an idbr session so that the key does not have to be passed to each idb1 or idb5 function call.

Usage

idb_api_key(api_key)

Arguments

api_key

The idbr user's Census API key. Can be obtained from https://api.census.gov/data/key_signup.html.

Examples

## Not run: 

idb_api_key('Your API key goes here')


## End(Not run)

---

Print the available concepts to pass to the 'idb5()' function.

Description

Print the available concepts to pass to the 'idb5()' function.

Usage

idb_concepts()

---

View the available variables for use in idbr

Description

The first column, "Name", details the variable names that can be passed the function. The second column, "Label", describes the content of the variables.

Usage

idb_variables()

---

(DEPRECATED) Retrieve data from the single-year-of-age IDB dataset.

Description

(DEPRECATED) Retrieve data from the single-year-of-age IDB dataset.

Usage

idb1(
  country,
  year,
  variables = c("AGE", "AREA_KM2", "NAME", "POP"),
  start_age = NULL,
  end_age = NULL,
  sex = NULL,
  api_key = NULL
)

Arguments

country	The two-character country FIPS code, or a valid country name.
year	The year for which you'd like to retrieve data
variables	A vector of variables. If left blank, will return age, area in square kilometers, the name of the country, and the population size of the age group.
start_age	(optional) The first age for which you'd like to retrieve data.
end_age	(optional) The second age group for which you'd like to retrieve data.
sex	(optional) One of 'both', 'male', or 'female'.
api_key	The user's Census API key. Can be supplied here or set globally in an idbr session with idb_api_key(api_key).

Value

A data frame with the requested data.

See Also

https://api.census.gov/data/timeseries/idb/1year.html

Examples

## Not run: 

# Projected population pyramid of China in 2050 with idbr and plotly

library(idbr)
library(plotly)
library(dplyr)

idb_api_key('Your API key goes here')

male <- idb1('CH', 2050, sex = 'male') %>%
  mutate(POP = POP * -1,
         SEX = 'Male')

female <- idb1('CH', 2050, sex = 'female') %>%
   mutate(SEX = 'Female')
china <- rbind(male, female) %>%
   mutate(abs_pop = abs(POP))
plot_ly(china, x = POP, y = AGE, color = SEX, type = 'bar', orientation = 'h',
        hoverinfo = 'y+text+name', text = abs_pop, colors = c('red', 'gold')) %>%
  layout(bargap = 0.1, barmode = 'overlay',
         xaxis = list(tickmode = 'array', tickvals = c(-10000000, -5000000, 0, 5000000, 10000000),
                     ticktext = c('10M', '5M', '0', '5M', '10M')),
         title = 'Projected population structure of China, 2050')


## End(Not run)

---

(DEPRECATED) Retrieve data from the five-year-age-group IDB dataset.

Description

(DEPRECATED) Retrieve data from the five-year-age-group IDB dataset.

Usage

idb5(
  country,
  year,
  variables = NULL,
  concept = NULL,
  country_name = FALSE,
  api_key = NULL
)

Arguments

country	A two-character FIPS code or country name, or a vector of FIPS codes or country names, of the countries for which you'd like to retrieve data.
year	A year, or a vector of years, for which you'd like to retrieve data.
variables	A vector of variables. Use idb_variables() for a full list.
concept	A concept for which you'd like to retrieve data. Use idb_concepts() for a list of options.
country_name	If TRUE, returns a column with the long country name along with the FIPS code.
api_key	The user's Census API key. Can be supplied here or set globally in an idbr session with idb_api_key(api_key).

Value

A data frame with the requested data.

See Also

https://api.census.gov/data/timeseries/idb/5year.html

Examples

## Not run: 

# World map of infant mortality rates by country for 2016 with plotly

library(idbr)
library(plotly)
library(viridis)

idb_api_key('Your API key goes here')

df <- idb5(country = 'all', year = 2016, variable = 'IMR', country_name = TRUE)

plot_ly(df, z = IMR, text = NAME, locations = NAME, locationmode = 'country names',
        type = 'choropleth', colors = viridis(99), hoverinfo = 'text+z') %>%
  layout(title = 'Infant mortality rate (per 1000 live births), 2016',
         geo = list(projection = list(type = 'robinson')))



## End(Not run)

---

Access the Census International Data Base (IDB) from R

Description

This R package grants users access to the US Census Bureau's International Data Base (IDB) API, and returns queries as R data frames. The IDB includes historical demographic data, current population estimates, and demographic projections to 2100 for countries of population 5,000 or greater that are recognized by the US Department of State. Demographic indicators in the IDB include mid-year population; population counts by sex and age; and fertility, mortality, and migration variables such as net migration, infant mortality rates, and total fertility rates. Future projections of these indicators are estimated using the cohort-component method. For details on the US Census Bureau's methodology for producing population estimates, please visit https://www2.census.gov/programs-surveys/international-programs/technical-documentation/methodology/idb-methodology.pdf.

Note

This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau.

Author(s)

Kyle Walker

See Also

Census API terms of service: https://www.census.gov/data/developers/about/terms-of-service.html

US Census Bureau IDB API home page: https://www.census.gov/data/developers/data-sets/international-database.html

---

Dataset with variable and concept descriptions for the IDB

Description

Built-in dataset for use with the idb_variables and idb_concepts functions. To access the data directly, issue the command data(variables5).

• Name: The variable name; can be passed to the idb5 function

• Label: Description of the variable

• Concept: The concept that a given variable belongs to

• Required: Whether or not the variable is required in the API call (idbr users can ignore this)

• Predicate.Type: variable type from the Census; idbr will convert these appropriately

Usage

data(variables5)

Format

A data frame with 98 rows and 5 columns

Details

Dataset with variable and concept descriptions for the IDB

---