Merge pull request #18 from curso-r/live-28-02

Alterações feitas na live de 28/02

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: munifacil
 Title: Pacote para facilitar o join com nome de municipios
-Version: 0.0.0.9000
+Version: 1.0.0
 Authors@R: c(
     person("Fernando", "Correa", email = "[email protected]", role = c("cre", "aut")),
     person("Julio", "Trecenti", email =  "[email protected]", role = c("aut")),

NEWS.md

@@ -0,0 +1,3 @@
+# munifacil 1.0.0
+
+* Improved documentation.

R/incluir_codigo_ibge.R

@@ -22,6 +22,14 @@ incluir_codigo_ibge <- function (data_set,
   resultado
 }
 
+#' Realizar diagnóstico do join
+#'
+#' @param resultado Tibble que é resultado do left_join entre a tabela de referência
+#' e a base de dados passada para a função `incluir_codigo_ibge()`
+#'
+#' @return A função imprime um diagnóstico na tela, informando se o join foi bem
+#' sucedido ou não. Caso o join tenha falhado, a função imprime uma lista com os
+#' municípios que não foram encontrados na tabela de referência.
 diagnostico_join <- function(resultado) {
 
   quantidade_na <- sum(is.na(resultado[["id_municipio"]]))

README.Rmd

@@ -21,7 +21,9 @@ knitr::opts_chunk$set(
 [![R-CMD-check](https://github.com/curso-r/munifacil/actions/workflows/R-CMD-check.yaml/badge.svg)](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()`).
+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
 
@@ -34,48 +36,131 @@ remotes::install_github("curso-r/munifacil")
 
 ## Exemplo de uso
 
-```{r, eval = TRUE}
-# Carregar o pacote munifacil
+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)
+```
 
-# Importar uma base de dados usada neste exemplo
+```{r, warning=FALSE, message=FALSE}
 arquivo <- system.file("extdata/exemplo.csv", package = "munifacil")
-base_de_exemplo_bruta <- readr::read_csv(arquivo)
+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: 
 
-# ver quais são as colunas disponíveis
-# Nessa base, temos o nome do município, a UF, e o código do IBGE que usaremos para validar posteriormente
-dplyr::glimpse(base_de_exemplo_bruta)
+```{r}
+glimpse(base_de_exemplo_bruta)
+```
 
-# vamos limpar o nome das colunas
-base_de_exemplo <- base_de_exemplo_bruta |> 
-  janitor::clean_names() |> 
-  # buscar apenas linhas distintas segundo essas colunas
-  dplyr::distinct(cidade_abrangida, codigo_do_ibge_cidade_abrangida, cidade_abrangida_uf)
+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.
 
-# ver novamente a base de exemplo limpa
-dplyr::glimpse(base_de_exemplo)
+```{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)
+```
 
-# Usar o munifacil
+### Utilizando o pacote `munifacil`
 
-resultado <- base_de_exemplo %>% 
-  # aqui é necessario indicar o nome da coluna que contém o nome das cidades, e 
-  # o nome da coluna que contém o nome das UFs
-  limpar_colunas(col_muni = cidade_abrangida, col_uf = cidade_abrangida_uf) %>% 
-  # cria uma coluna "id_municipio"
+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`.
 
-# ver o resultado
-dplyr::glimpse(resultado)
+A função `incluir_codigo_ibge()` adiciona as seguintes colunas na base de dados:
 
-# resultados que nao receberam o id do municipio
-resultado %>% 
+  - `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))
+```
 
-# Verificando a quantidade de resultados corretos
-resultado %>% 
-  dplyr::count(codigo_do_ibge_cidade_abrangida == 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).