<p><div><div><div><div data-width="100" data-show-faces="false" data-send="true" data-layout="button_count" data-height="21" data-href="http://www.r-bloggers.com/idbr-access-the-us-census-bureau-international-data-base-in-r/"></div></div><div><a data-url="http://www.r-bloggers.com/idbr-access-the-us-census-bureau-international-data-base-in-r/" data-counturl="http://www.r-bloggers.com/idbr-access-the-us-census-bureau-international-data-base-in-r/" data-count="horizontal" data-text="idbr: access the US Census Bureau International Data Base in R" class="twitter-share-button" data-via="rbloggers" href="https://twitter.com/share"></a></div><div></div></div><div></div></div>
<div>
(This article was first published on <strong><a href="http://www.arilamstein.com/blog/2016/06/06/idbr-access-us-census-bureau-international-data-base-r/"> R – AriLamstein.com</a></strong>, and kindly contributed to <a rel="nofollow" href="http://www.r-bloggers.com/">R-bloggers)</a> </div>
<p><i>Today’s post is by <a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cDovL3BlcnNvbmFsLnRjdS5lZHUva3lsZXdhbGtlci8%3D&feed-stats-url-post-id=2642">Kyle Walker</a>, a professor of geography at Texas Christian University. I’ve been a fan of Kyle’s work for a while. When I saw that he wrote a package for accessing the Census Bureau’s International Data Base, I asked him to write a guest post about it.</i></p>
<p>The <a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cDovL3d3dy5jZW5zdXMuZ292L3BvcHVsYXRpb24vaW50ZXJuYXRpb25hbC9kYXRhL2lkYi9pbmZvcm1hdGlvbkdhdGV3YXkucGhw&feed-stats-url-post-id=2642">US Census Bureau’s International Data Base</a> (IDB) is one of the best resources on the web for obtaining both historical and future projections of international demographic indicators. I’ve long used the IDB in my teaching, generally using its web interface to download data extracts. However, the Census Bureau also makes the IDB accessible via its API, which makes it much more convenient for programmers to access the data. Earlier this year, I wrote the R package idbr (<a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cHM6Ly9naXRodWIuY29tL3dhbGtlcmtlL2lkYnI%3D&feed-stats-url-post-id=2642">https://github.com/walkerke/idbr</a>) to help R programmers use the IDB in their projects.</p>
<div>
<div>
<b>Bonus:</b> Download the code from this post!
</div>
<div><a target="_blank" href="http://www.arilamstein.com/blog/2016/06/06/idbr-access-us-census-bureau-international-data-base-r/#content_upgrade_popup_2669">Download</a></div>
</div>
<p>In this post, I’ll go over the basics of the idbr package and illustrate its functionality with animated GIF visualizations of IDB data using <a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cDovL2dncGxvdDIub3JnLw%3D%3D&feed-stats-url-post-id=2642">ggplot2</a> and <a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cHM6Ly9naXRodWIuY29tL2RncnR3by9nZ2FuaW1hdGU%3D&feed-stats-url-post-id=2642">gganimate</a>.</p>
<p>idbr is available on CRAN, and can be installed with the command <code>install.packages('idbr')</code>. Once installed, start up your idbr session with the following code:</p>
<pre>
library(idbr)

idb_api_key('Your API key goes here')
</pre>
<p>To use the US Census Bureau API, you’ll need to get an API key from <a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cDovL2FwaS5jZW5zdXMuZ292L2RhdGEva2V5X3NpZ251cC5odG1s&feed-stats-url-post-id=2642">http://api.census.gov/data/key_signup.html</a>. It is free and doesn’t take long for you to get the key. Supply the key to the <code>idb_api_key</code> function to set your API key as an environment variable in your R session; you only need to do this once per session.</p>
<p>There are two main functions in idbr: <code>idb1</code> and <code>idb5</code>. <code>idb1</code> taps into the 1-year-age-band IDB dataset; this dataset includes population counts for single years of age, optionally for specific age ranges or by sex. At its simplest, a user can request data for a given country in a given year. Countries are identified by their FIPS 10-4 codes, which can be looked up with the <a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cHM6Ly9jcmFuLnItcHJvamVjdC5vcmcvd2ViL3BhY2thZ2VzL2NvdW50cnljb2RlL2luZGV4Lmh0bWw%3D&feed-stats-url-post-id=2642">countrycode</a> package if you don’t know the code for your country of interest.</p>
<pre>
library(countrycode)
countrycode('Canada', 'country.name', 'fips104')

[1] &quot;CA&quot;
</pre>
<p>The country code for Canada is “CA”; this can now be supplied to the <code>idb1</code>  function.</p>
<pre>
ca &lt;- idb1('CA', 2016)

head(ca)

Source: local data frame [6 x 6]

AGE AREA_KM2 NAME POP FIPS time
(dbl) (dbl) (chr) (dbl) (chr) (dbl)
1 0 9093507 Canada 361796 CA 2016
2 1 9093507 Canada 361650 CA 2016
3 2 9093507 Canada 361299 CA 2016
4 3 9093507 Canada 360863 CA 2016
5 4 9093507 Canada 360321 CA 2016
6 5 9093507 Canada 360143 CA 2016
</pre>
<p>The function returns a data frame with the default variables available in the 1-year dataset.</p>
<p>More demographic indicators are available via the <code>idb5</code> function, which includes population data by 5-year age bands as well as measurements of birth, death, and migration rates. Variables are accessible by supplying a variable name or a <em>concept</em>, which refers to a group of variables. To get a list of available variable and concept names, call <code>idb_variables()</code> or <code>idb_concepts()</code>.</p>
<p>For example, we can specify the concept “Fertility rates” to get all of the fertility variables for Canada in 2016:</p>
<pre>
idb5('CA', 2016, concept = 'Fertility rates')

Source: local data frame [1 x 12]

ASFR15_19 ASFR20_24 ASFR25_29 ASFR30_34 ASFR35_39 ASFR40_44 ASFR45_49 GRR SRB TFR FIPS time
(dbl) (dbl) (dbl) (dbl) (dbl) (dbl) (dbl) (dbl) (dbl) (dbl) (chr) (dbl)
1 13.8 53.3 101.9 101.4 41.7 7.1 0.3 0.7767 1.0563 1.5972 CA 2016
</pre>
<p>The <code>idb5</code> function as called above returns age-specific fertility rates for five-year age bands, as well as the gross reproduction rate, sex ratio at birth, and total fertility rate.</p>
<p>These demographic indicators are even more useful, however, when you can compare them across countries or over time. You can supply a vector of years to the <code>idb1</code> function to get single-year-of-age population counts over multiple years; <code>idb5</code> accepts both a vector of country codes and a vector of years. From here, you can design analyses or data visualizations to examine these temporal or cross-country comparisons.</p>
<p>Two animated examples with code are below. The examples use the <a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cHM6Ly9naXRodWIuY29tL2RncnR3by9nZ2FuaW1hdGU%3D&feed-stats-url-post-id=2642">gganimate</a> extension to <a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cDovL2dncGxvdDIub3JnLw%3D%3D&feed-stats-url-post-id=2642">ggplot2</a> which wraps the <a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cHM6Ly9jcmFuLnItcHJvamVjdC5vcmcvd2ViL3BhY2thZ2VzL2FuaW1hdGlvbi9pbmRleC5odG1s&feed-stats-url-post-id=2642">animation</a> package, so to reproduce the examples, you’ll need <a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cDovL3d3dy5pbWFnZW1hZ2ljay5vcmcvc2NyaXB0L2luZGV4LnBocA%3D%3D&feed-stats-url-post-id=2642">ImageMagick</a> installed on your machine and on your system PATH.</p>
<p><strong>Animated population pyramid of Nigeria, 1990-2050 (projected)</strong></p>
<pre>
library(idbr) 
library(ggplot2)
library(dplyr)
library(gganimate)
library(animation)

idb_api_key(&quot;Your key goes here&quot;)

male &lt;- idb1('NI', 1990:2050, sex = 'male') %>%
  mutate(POP = POP * -1,
         SEX = 'Male')

female &lt;- idb1('NI', 1990:2050, sex = 'female') %>%
  mutate(SEX = 'Female')

nigeria &lt;- rbind(male, female) 

g1 &lt;- ggplot(nigeria, aes(x = AGE, y = POP, fill = SEX, width = 1, frame = time)) +
  coord_fixed() +
  coord_flip() +
  geom_bar(data = subset(nigeria, SEX == &quot;Female&quot;), stat = &quot;identity&quot;, position = 'identity') +
  geom_bar(data = subset(nigeria, SEX == &quot;Male&quot;), stat = &quot;identity&quot;, position = 'identity') +
  scale_y_continuous(breaks = seq(-5000000, 5000000, 2500000),
                     labels = c('5m', '2.5m', '0', '2.5m', '5m'),
                     limits = c(min(nigeria$POP), max(nigeria$POP))) +
  theme_minimal(base_size = 14, base_family = &quot;Tahoma&quot;) +
  scale_fill_manual(values = c('#98df8a', '#2ca02c')) +
  ggtitle('Population structure of Nigeria,') + 
  ylab('Population') +
  xlab('Age') +
  theme(legend.position = &quot;bottom&quot;, legend.title = element_blank()) +
  labs(caption = 'Chart by @kyle_e_walker | Data source: US Census Bureau IDB via the idbr R package') + 
  guides(fill = guide_legend(reverse = TRUE))

gg_animate(g1, interval = 0.1, ani.width = 700, ani.height = 600)
</pre>
<p><a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cDovL3d3dy5hcmlsYW1zdGVpbi5jb20vd3AtY29udGVudC91cGxvYWRzLzIwMTYvMDYvbmlnZXJpYV9weXJhbWlkLTEuZ2lm&feed-stats-url-post-id=2642"><img sizes="(max-width: 700px) 100vw, 700px" srcset="http://i0.wp.com/www.arilamstein.com/wp-content/uploads/2016/06/nigeria_pyramid-1.gif?w=700 700w, http://i0.wp.com/www.arilamstein.com/wp-content/uploads/2016/06/nigeria_pyramid-1.gif?resize=300%2C257 300w, http://i0.wp.com/www.arilamstein.com/wp-content/uploads/2016/06/nigeria_pyramid-1.gif?resize=676%2C579 676w" alt="nigeria_pyramid" class="wp-image-2658" src="http://i0.wp.com/www.arilamstein.com/wp-content/uploads/2016/06/nigeria_pyramid-1.gif?resize=676%2C579" data-recalc-dims="1"></a></p>
<p> </p>
<p><strong>Life expectancy at birth by sex in the former USSR, 1989-2016</strong> (click the image for a clearer version)</p>
<pre>
library(idbr)
library(dplyr)
library(ggplot2)
library(tidyr)
library(countrycode)
library(gganimate)
library(tweenr)

ctrys &lt;- countrycode(c('Russia', 'Ukraine', 'Belarus', 'Moldova', 'Georgia', 'Kazakhstan', 
                       'Uzbekistan', 'Lithuania', 'Latvia', 'Estonia', 'Kyrgyzstan', 
                       'Tajikistan', 'Turkmenistan', 'Armenia', 'Azerbaijan'), 
            'country.name', 'fips104')

idb_api_key(&quot;Your API key here&quot;)

full &lt;- idb5(country = ctrys, year = 1989:2016, 
             variables = c('E0_F', 'E0_M'), country_name = TRUE)

tmp &lt;- full %>%
  filter(time == 1989) %>%
  arrange(E0_F)

ord &lt;- as.character(as.vector(tmp$NAME))

dft &lt;- full %>%
  mutate(diff = E0_F - E0_M, ease = 'cubic-in-out') %>%
  select(-FIPS) %>%
  rename(Male = E0_M, Female = E0_F) %>%
  tween_elements(time = 'time', group = 'NAME', ease = 'ease', 
                      nframes = 500) %>%
  gather(Sex, value, Male, Female, -diff, -.group) %>%
  mutate(.group = factor(.group, levels = ord))

g &lt;- ggplot() + 
  geom_point(data = dft, aes(x = value, y = .group, color = Sex, frame = .frame), 
             size = 14) + 
  scale_color_manual(values = c('darkred', 'navy')) + 
  geom_text(data = dft, aes(x = value, y = .group, frame = .frame,
                              label = as.character(round(dft$value, 1))),
            color = 'white', fontface = 'bold') +
  geom_text(data = dft, aes(x = 80, y = 1.5, frame = .frame, 
                label = round(dft$time, 0)), color = 'black', size = 12) + 
  theme_minimal(base_size = 16, base_family = &quot;Tahoma&quot;) + 
  theme(panel.grid.major.x = element_blank(), 
        panel.grid.minor.x = element_blank()) + 
  labs(y = '', 
       x = '', 
       color = '', 
       caption = 'Data source: US Census Bureau IDB via the idbr R package; chart by @kyle_e_walker', 
       title = 'Life expectancy at birth in the former USSR, 1989-2016')

gg_animate(g, interval = 0.05, ani.width = 750, ani.height = 650, title_frame = FALSE)
</pre>
<p><a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cDovL3d3dy5hcmlsYW1zdGVpbi5jb20vd3AtY29udGVudC91cGxvYWRzLzIwMTYvMDYvdXNzcl9sZXgyLmdpZg%3D%3D&feed-stats-url-post-id=2642"><img class="wp-image-2665" src="http://i2.wp.com/www.arilamstein.com/wp-content/uploads/2016/06/ussr_lex2.gif?resize=676%2C586" data-recalc-dims="1"></a></p>
<p> </p>
<p>Please let me know if you have any feedback about the package, and let me know how you are using it! I’m on the web at <a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cDovL3BlcnNvbmFsLnRjdS5lZHUva3lsZXdhbGtlci8%3D&feed-stats-url-post-id=2642">http://personal.tcu.edu/kylewalker/</a>, and on Twitter at <a target="_blank" href="http://www.arilamstein.com/?feed-stats-url=aHR0cHM6Ly90d2l0dGVyLmNvbS9reWxlX2Vfd2Fsa2Vy&feed-stats-url-post-id=2642">@kyle_e_walker</a>.</p>
<div>
<div>
<b>Bonus:</b> Download the code from this post!
</div>
<div><a target="_blank" href="http://www.arilamstein.com/blog/2016/06/06/idbr-access-us-census-bureau-international-data-base-r/#content_upgrade_popup_2669">Download</a></div>
</div>
<p> <img height="1" width="1" src="http://www.arilamstein.com/?feed-stats-post-id=2642">
<p>The post <a target="_blank" rel="nofollow" href="http://www.arilamstein.com/blog/2016/06/06/idbr-access-us-census-bureau-international-data-base-r/">idbr: access the US Census Bureau International Data Base in R</a> appeared first on <a target="_blank" rel="nofollow" href="http://www.arilamstein.com/">AriLamstein.com</a>.</p>
<p><div><div><div><div data-width="55" data-show-faces="false" data-send="true" data-layout="box_count" data-height="62" data-href="http://www.r-bloggers.com/idbr-access-the-us-census-bureau-international-data-base-in-r/"></div></div><div><a data-url="http://www.r-bloggers.com/idbr-access-the-us-census-bureau-international-data-base-in-r/" data-counturl="http://www.r-bloggers.com/idbr-access-the-us-census-bureau-international-data-base-in-r/" data-count="vertical" data-text="idbr: access the US Census Bureau International Data Base in R" class="twitter-share-button" data-via="rbloggers" href="https://twitter.com/share"></a></div><div></div></div><div></div></div>
<div>
<div>To <strong>leave a comment</strong> for the author, please follow the link and comment on their blog: <strong><a href="http://www.arilamstein.com/blog/2016/06/06/idbr-access-us-census-bureau-international-data-base-r/"> R – AriLamstein.com</a></strong>.</div>
<hr>
<a rel="nofollow" href="http://www.r-bloggers.com/">R-bloggers.com</a> offers <strong><a rel="nofollow" href="http://feedburner.google.com/fb/a/mailverify?uri=RBloggers">daily e-mail updates</a></strong> about <a title="The R Project for Statistical Computing" rel="nofollow" href="http://www.r-project.org/">R</a> news and <a title="R tutorials" rel="nofollow" href="http://www.r-bloggers.com/?s=tutorial">tutorials</a> on topics such as: <a title="Data science" rel="nofollow" href="http://www.r-bloggers.com/?s=data%20science">Data science</a>, <a title="Big Data" rel="nofollow" href="http://www.r-bloggers.com/?s=Big%20Data">Big Data, <a title="R jobs" rel="nofollow" href="http://www.r-users.com/">R jobs</a>, visualization (<a title="ggplot and ggplot2 tutorials" rel="nofollow" href="http://www.r-bloggers.com/?s=ggplot2">ggplot2</a>, <a title="Boxplots using lattice and ggplot2 tutorials" rel="nofollow" href="http://www.r-bloggers.com/?s=boxplot">Boxplots</a>, <a title="Maps and gis" rel="nofollow" href="http://www.r-bloggers.com/?s=map">maps</a>, <a title="Animation in R" rel="nofollow" href="http://www.r-bloggers.com/?s=animation">animation</a>), programming (<a title="RStudio IDE for R" rel="nofollow" href="http://www.r-bloggers.com/?s=RStudio">RStudio</a>, <a title="Sweave and literate programming" rel="nofollow" href="http://www.r-bloggers.com/?s=sweave">Sweave</a>, <a title="LaTeX in R" rel="nofollow" href="http://www.r-bloggers.com/?s=LaTeX">LaTeX</a>, <a title="SQL and databases" rel="nofollow" href="http://www.r-bloggers.com/?s=SQL">SQL</a>, <a title="Eclipse IDE for R" rel="nofollow" href="http://www.r-bloggers.com/?s=eclipse">Eclipse</a>, <a title="git and github, Version Control System" rel="nofollow" href="http://www.r-bloggers.com/?s=git">git</a>, <a title="Large data in R using Hadoop" rel="nofollow" href="http://www.r-bloggers.com/?s=hadoop">hadoop</a>, <a title="Web Scraping of google, facebook, yahoo, twitter and more using R" rel="nofollow" href="http://www.r-bloggers.com/?s=Web+Scraping">Web Scraping</a>) statistics (<a title="Regressions and ANOVA analysis tutorials" rel="nofollow" href="http://www.r-bloggers.com/?s=regression">regression</a>, <a title="principal component analysis tutorial" rel="nofollow" href="http://www.r-bloggers.com/?s=PCA">PCA</a>, <a title="Time series" rel="nofollow" href="http://www.r-bloggers.com/?s=time+series">time series</a>, <a title="finance trading" rel="nofollow" href="http://www.r-bloggers.com/?s=trading">trading</a>) and more...
<img height="1" alt="" width="1" src="http://feeds.feedburner.com/~r/RBloggers/~4/5560JNqKrJs"></a></div>