README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```
# simplefeaturesbr

The goal of simplefeaturesbr is to make [Simple Features](https://en.wikipedia.org/wiki/Simple_Features) tidy data frames of Brazilian states and municipalities easily available in R. Original JSON files from [here](https://github.com/tbrugz/geodata-br).  

## Installation

You can install simplefeaturesbr with:  

``` r
remotes::install_github("BrazilianPublicData/simplefeaturesbr")
```

## Usage

simplefeaturesbr has a main dataset, `br_municipalities`, and some simple convenience functions to select from this dataset. You can access the data with: 

```{r}
library(simplefeaturesbr)
data("br_municipalities")
``` 

It looks like this: 

```{r}
head(br_municipalities)
```

You can use some convenience functions to look at certain states and municipalities. These will load the main dataset too, so you of course just do this yourself quite easily. But...

If you are interested in a specific state, use `select_state()`: 
```{r}
select_state("SP") %>% head()
``` 

If you'd like to get data for a specific municipality, use `select_municipality()`:
```{r}
select_municipality("Sao Paulo")
``` 

There are two other things to help you. If you can't remember which [IBGE](https://www.ibge.gov.br/en/home-eng.html) code (two-letter abbreviations of Brazilian states) you need, use `UF()` (copy of a simple function from [congressbr](https://github.com/BrazilianPublicData/congressbr)):

```{r}
UF()
```

## Why?

Simple features make _much_ smaller dataframes than spatial polygons. You can plot them easily with ggplot2's `geom_sf()`. For example, we can download the Municipal Human Development Index data (using 2010, most recent year) from the [Atlas Brasil](http://www.atlasbrasil.org.br/2013/en/download/) webpage and plot 'er up:

```{r message = FALSE, warning = FALSE}
library(tidyverse); library(readxl)

hdi <- read_excel("~/Downloads/atlas2013_dadosbrutos_pt.xlsx",
                  sheet = 2) %>% 
  select(year = ANO, ibge_code = Codmun7, hdi = ESPVIDA) %>% 
  filter(year == 2010) %>% 
  mutate(ibge_code = as.character(ibge_code))

select_state("RJ") -> rj

rio <- left_join(rj, hdi)

ggplot(rio, aes(fill = hdi)) + 
  geom_sf() + 
  scale_fill_viridis_c() +
  theme_minimal() +
  theme(legend.position = c(0.2, 0.8),
        axis.text = element_blank()) +
  guides(fill = guide_legend(title = "Life Expectancy",
                             reverse = TRUE))
```

Nice. Well, the graph, not the fact that living in richer areas in Rio can increase your life expectancy by **four** years.  

I lived in São Paulo for some years, I wonder what that's like?  
```{r }

select_state("SP") -> sp

sao <- left_join(sp, hdi)

ggplot(sao, aes(fill = hdi)) + 
  geom_sf(size = 0.1) + 
  scale_fill_viridis_c() +
  theme_minimal() +
  theme(axis.text = element_blank()) +
  guides(fill = guide_legend(title = "Life Expectancy",
                             reverse = TRUE))
```

And all of Brazil:  
```{r}
brazil <- left_join(br_municipalities, hdi)

ggplot(brazil, aes(fill = hdi)) + 
  geom_sf(size = 0.1) + 
  scale_fill_viridis_c() +
  theme_minimal() +
  theme(axis.text = element_blank(), 
        legend.position = "none")
``` 

See? Simple Features tidy dataframes are *kewl*.