-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathREADME.Rmd
166 lines (110 loc) · 5.81 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
---
output: github_document
editor_options:
chunk_output_type: console
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# munifacil
<!-- badges: start -->
[](https://github.com/curso-r/munifacil/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
O pacote [munifacil](https://curso-r.github.io/munifacil/) tem como objetivo facilitar a união de colunas de nome de município com o respectivo código do IBGE.
Isso é útil para posteriormente realizar procedimentos de `join` usando como chave a coluna do código do IBGE (como o `dplyr::left_join()`).
## Instalação
Este pacote atualmente não está disponível no CRAN, podendo ser instalado através do GitHub, utilizando o código abaixo:
```r
install.packages("remotes")
remotes::install_github("curso-r/munifacil")
```
## Exemplo de uso
Neste exemplo, vamos usar uma base de dados que contém o nome de municípios e a UF, e vamos incluir o código do IBGE.
### Preparando os dados
Primeiro, vamos carregar os pacotes necessários e importar a base de dados que usaremos neste exemplo.
```{r, warning=FALSE, message=FALSE}
library(munifacil)
library(tidyverse)
```
```{r, warning=FALSE, message=FALSE}
arquivo <- system.file("extdata/exemplo.csv", package = "munifacil")
base_de_exemplo_bruta <- read_csv(arquivo)
```
Vamos dar uma olhada na base de dados que usaremos como exemplo. Nessa base, temos o nome do município, a UF, e o código do IBGE que usaremos para validar posteriormente:
```{r}
glimpse(base_de_exemplo_bruta)
```
Agora, vamos limpar o nome das colunas e remover uma linha que não tem informação. Alguns valores da coluna `codigo_do_ibge_cidade_abrangida` estão com mais de 7 dígitos, então vamos manter apenas os 7 primeiros dígitos (o número de dígitos utilizado pelo IBGE para identificar os municípios).
Essa etapa é feita apenas para facilitar a visualização do exemplo, e não é necessária para o uso do pacote.
```{r}
base_de_exemplo <- base_de_exemplo_bruta |>
janitor::clean_names() |>
filter(cidade_abrangida != "-",
codigo_do_ibge_cidade_abrangida != "-") |>
mutate(
# manter apenas os 7 primeiros dígitos da coluna codigo_do_ibge_cidade_abrangida
codigo_do_ibge_cidade_abrangida = str_sub(codigo_do_ibge_cidade_abrangida, 1, 7))
glimpse(base_de_exemplo)
```
### Utilizando o pacote `munifacil`
Agora, vamos usar o pacote `munifacil` para incluir o código do IBGE na base de dados.
A primeira etapa necessária é limpar o nome das colunas que contém o nome do município e a UF. Isso é feito com a função `limpar_colunas()`.
```{r}
base_colunas_limpas <- base_de_exemplo %>%
limpar_colunas(col_muni = cidade_abrangida,
col_uf = cidade_abrangida_uf)
glimpse(base_colunas_limpas)
```
Na base `base_colunas_limpas`, agora temos duas novas colunas: `uf_join` e `muni_join`. Essas colunas estão "limpas", de forma que facilite a união com a tabela de "de-para" que contém os códigos do IBGE para cada município.
Agora, vamos incluir o código do IBGE na base de dados. Isso é feito com a função `incluir_codigo_ibge()`.
```{r warning=FALSE}
resultado <- base_colunas_limpas %>%
incluir_codigo_ibge()
```
Veja que ao usar a função `incluir_codigo_ibge()`, por padrão uma mensagem sobre a quantidade de resultados que não receberam o id do município é impressa. Isso é útil para verificar se existem municípios que não foram encontrados na base de "de-para". Essa mensagem pode ser desativada com o argumento `diagnostico = FALSE`.
A função `incluir_codigo_ibge()` adiciona as seguintes colunas na base de dados:
- `id_municipio` - código do IBGE para cada município.
- `manual` - a informação utilizada para unir os valores foram incluídos manualmente na tabela de de-para.
- `atencao` - indica que é importante ter atenção nesses casos. Por exemplo: podem ser municípios com nomes similares, o mesmo nome de município em UFs diferentes, etc.
- `existia_1991` - O municipio existia em 1991?
- `existia_2000` - O municipio existia em 2000?
- `existia_2010` - O municipio existia em 2010?
Dentre as colunas citadas acima, a principal é a `id_municipio`, que é o código do IBGE para cada município. As outras colunas são úteis para verificar se a união foi feita corretamente.
```{r}
glimpse(resultado)
```
Podemos remover as colunas que foram adicionadas e não são necessárias para a análise.
```{r}
resultado_limpo <- resultado %>%
select(-c(manual, atencao, starts_with("existia"),
uf_join, muni_join))
```
Verificando o resultado final:
```{r}
glimpse(resultado_limpo)
```
### Verificando o resultado
- Quantidade de resultados que não receberam o ID do município:
```{r}
resultado_limpo %>%
dplyr::filter(is.na(id_municipio))
```
Todos os municípios receberam o ID do IBGE!
- Mas esses IDs estão corretos?
```{r, eval = TRUE}
# Verificando a quantidade de resultados corretos
resultado_limpo %>%
mutate(resultado_correto = codigo_do_ibge_cidade_abrangida == id_municipio) %>%
count(resultado_correto) %>%
mutate(porcentagem = formattable::percent(n / sum(n))) %>%
knitr::kable()
```
## Como contribuir?
Caso encontre alguma variação de escrita de nomes de municípios que não seja na tabela "de-para" atual do pacote munifacil, você pode contribuir com o pacote enviando essa sugestão.
Para isso, você pode [abrir uma issue](https://github.com/curso-r/munifacil/issues/new/choose), ou enviar um [pull request adicionando a sugestão no arquivo `inst/depara_muni_codigo.csv`](https://github.com/curso-r/munifacil/blob/main/inst/depara_muni_codigo.csv).