The geobr package provides quick and easy access to official spatial data sets of Brazil. The syntax of all geobr functions operate on a simple logic that allows users to easily download a wide variety of data sets with updated geometries and harmonized attributes and geographic projections across geographies and years. This vignette presents a quick intro to geobr.
Installation
You can install geobr from CRAN or the development version to use the latest features.
# From CRAN
install.packages("geobr")
# Development version
utils::remove.packages('geobr')
devtools::install_github("ipeaGIT/geobr", subdir = "r-package")Now let’s load the libraries we’ll use in this vignette.
General usage
Available data sets
The geobr package covers 27 spatial data sets, including a variety of political-administrative and statistical areas used in Brazil. You can view what data sets are available using the list_geobr() function.
# Available data sets
datasets <- list_geobr()
head(datasets, n=27)
#> function
#> 1 `read_country`
#> 2 `read_region`
#> 3 `read_state`
#> 4 `read_meso_region`
#> 5 `read_micro_region`
#> 6 `read_intermediate_region`
#> 7 `read_immediate_region`
#> 8 `read_municipality`
#> 9 `read_municipal_seat`
#> 10 `read_weighting_area`
#> 11 `read_census_tract`
#> 12 `read_statistical_grid`
#> 13 `read_metro_area`
#> 14 `read_urban_area`
#> 15 `read_amazon`
#> 16 `read_biomes`
#> 17 `read_conservation_units`
#> 18 `read_disaster_risk_area`
#> 19 `read_indigenous_land`
#> 20 `read_semiarid`
#> 21 `read_health_facilities`
#> 22 `read_health_region`
#> 23 `read_neighborhood`
#> 24 `read_schools`
#> 25 `read_comparable_areas`
#> 26 `read_urban_concentrations`
#> 27 `read_pop_arrangements`
#> geography
#> 1 Country
#> 2 Region
#> 3 States
#> 4 Meso region
#> 5 Micro region
#> 6 Intermediate region
#> 7 Immediate region
#> 8 Municipality
#> 9 Municipality seats (sedes municipais)
#> 10 Census weighting area (área de ponderação)
#> 11 Census tract (setor censitário)
#> 12 Statistical Grid of 200 x 200 meters
#> 13 Metropolitan areas
#> 14 Urban footprints
#> 15 Brazil's Legal Amazon
#> 16 Biomes
#> 17 Environmental Conservation Units
#> 18 Disaster risk areas
#> 19 Indigenous lands
#> 20 Semi Arid region
#> 21 Health facilities
#> 22 Health regions and macro regions
#> 23 Neighborhood limits
#> 24 Schools
#> 25 Historically comparable municipalities, aka Areas minimas comparaveis (AMCs)
#> 26 Urban concentration areas (concentrações urbanas)
#> 27 Population arrangements (arranjos populacioanis)
#> years
#> 1 1872, 1900, 1911, 1920, 1933, 1940, 1950, 1960, 1970, 1980, 1991, 2000, 2001, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020
#> 2 2000, 2001, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020
#> 3 1872, 1900, 1911, 1920, 1933, 1940, 1950, 1960, 1970, 1980, 1991, 2000, 2001, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020
#> 4 2000, 2001, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020
#> 5 2000, 2001, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020
#> 6 2017, 2019, 2020
#> 7 2017, 2019, 2020
#> 8 1872, 1900, 1911, 1920, 1933, 1940, 1950, 1960, 1970, 1980, 1991, 2000, 2001, 2005, 2007, 2010, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020
#> 9 1872, 1900, 1911, 1920, 1933, 1940, 1950, 1960, 1970, 1980, 1991, 2010
#> 10 2010
#> 11 2000, 2010, 2017, 2019, 2020
#> 12 2010
#> 13 1970, 2001, 2002, 2003, 2005, 2010, 2013, 2014, 2015, 2016, 2017, 2018
#> 14 2005, 2015
#> 15 2012
#> 16 2004, 2019
#> 17 201909
#> 18 2010
#> 19 201907, 202103
#> 20 2005, 2017
#> 21 2015
#> 22 1991, 1994, 1997, 2001, 2005, 2013
#> 23 2010
#> 24 2020
#> 25 1872,1900,1911,1920,1933,1940,1950,1960,1970,1980,1991,2000,2010
#> 26 2015
#> 27 2015
#> source
#> 1 IBGE
#> 2 IBGE
#> 3 IBGE
#> 4 IBGE
#> 5 IBGE
#> 6 IBGE
#> 7 IBGE
#> 8 IBGE
#> 9 IBGE
#> 10 IBGE
#> 11 IBGE
#> 12 IBGE
#> 13 IBGE
#> 14 IBGE
#> 15 MMA
#> 16 IBGE
#> 17 MMA
#> 18 CEMADEN and IBGE
#> 19 FUNAI
#> 20 IBGE
#> 21 CNES, DataSUS
#> 22 DataSUS
#> 23 IBGE
#> 24 INEP
#> 25 IBGE
#> 26 IBGE
#> 27 IBGEDownload spatial data as sf objects
The syntax of all geobr functions operate one the same logic, so the code to download the data becomes intuitive for the user. Here are a few examples.
Download an specific geographic area at a given year
# State of Sergige
state <- read_state(code_state="SE", year=2018)
# Municipality of Sao Paulo
muni <- read_municipality( code_muni = 3550308, year=2010 )Download all geographic areas within a state at a given year
# All municipalities in the state of Alagoas
muni <- read_municipality(code_muni= "AL", year=2007)
# All census tracts in the state of Rio de Janeiro
cntr <- read_census_tract(code_tract = "RJ", year = 2010)If the parameter code_ is not passed to the function, geobr returns the data for the whole country by default.
meso <- read_intermediate_region(year=2017)
states <- read_state(year=2019)Important note about data resolution
All functions to download polygon data such as states, municipalities etc. have a simplified argument. When simplified = FALSE, geobr will return the original data set with high resolution at detailed geographic scale (see documentation). By default, however, simplified = TRUE and geobr returns data set geometries with simplified borders to improve speed of downloading and plotting the data.
Plot the data
Once you’ve downloaded the data, it is really simple to plot maps using ggplot2.
# Remove plot axis
no_axis <- theme(axis.title=element_blank(),
axis.text=element_blank(),
axis.ticks=element_blank())
# Plot all Brazilian states
ggplot() +
geom_sf(data=states, fill="#2D3E50", color="#FEBF57", size=.15, show.legend = FALSE) +
labs(subtitle="States", size=8) +
theme_minimal() +
no_axis
Plot all the municipalities of a particular state, such as Rio de Janeiro:
# Download all municipalities of Rio
all_muni <- read_municipality( code_muni = "RJ", year= 2010)
# plot
ggplot() +
geom_sf(data=all_muni, fill="#2D3E50", color="#FEBF57", size=.15, show.legend = FALSE) +
labs(subtitle="Municipalities of Rio de Janeiro, 2000", size=8) +
theme_minimal() +
no_axis
Thematic maps
The next step is to combine data from geobr package with other data sets to create thematic maps. In this example, we will be using data from the (Atlas of Human Development (by Ipea/FJP and UNPD) to create a choropleth map showing the spatial variation of Life Expectancy at birth across Brazilian states.
Merge external data
First, we need a data.frame with estimates of Life Expectancy and merge it to our spatial database. The two-digit abbreviation of state name is our key column to join these two databases.
# Read data.frame with life expectancy data
df <- utils::read.csv(system.file("extdata/br_states_lifexpect2017.csv", package = "geobr"), encoding = "UTF-8")
states$name_state <- tolower(states$name_state)
df$uf <- tolower(df$uf)
# join the databases
states <- dplyr::left_join(states, df, by = c("name_state" = "uf"))Plot thematic map
ggplot() +
geom_sf(data=states, aes(fill=ESPVIDA2017), color= NA, size=.15) +
labs(subtitle="Life Expectancy at birth, Brazilian States, 2014", size=8) +
scale_fill_distiller(palette = "Blues", name="Life Expectancy", limits = c(65,80)) +
theme_minimal() +
no_axis