diff --git a/DESCRIPTION b/DESCRIPTION index 0ed6d57..2c67847 100644 --- a/DESCRIPTION +++ b/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 = "fcorrea@curso-r.com", role = c("cre", "aut")), person("Julio", "Trecenti", email = "jtrecenti@curso-r.com", role = c("aut")), diff --git a/NEWS.md b/NEWS.md new file mode 100644 index 0000000..0a8b4fd --- /dev/null +++ b/NEWS.md @@ -0,0 +1,3 @@ +# munifacil 1.0.0 + +* Improved documentation. diff --git a/R/incluir_codigo_ibge.R b/R/incluir_codigo_ibge.R index 3aa90d0..472c4ee 100644 --- a/R/incluir_codigo_ibge.R +++ b/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"]])) diff --git a/README.Rmd b/README.Rmd index 3c942fa..cd9e630 100644 --- a/README.Rmd +++ b/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) -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). diff --git a/README.md b/README.md index 91f4bb5..fd49f8e 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,10 @@ 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()`). +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 @@ -26,25 +27,30 @@ 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 -# Carregar o pacote munifacil library(munifacil) +library(tidyverse) +``` -# Importar uma base de dados usada neste exemplo +``` r arquivo <- system.file("extdata/exemplo.csv", package = "munifacil") -base_de_exemplo_bruta <- readr::read_csv(arquivo) -#> Rows: 6786 Columns: 6 -#> ── Column specification ──────────────────────────────────────────────────────── -#> Delimiter: "," -#> chr (5): Cidade abrangida, Código do IBGE - cidade abrangida, Cidade abrangi... -#> dbl (1): Indicador Valor -#> -#> ℹ Use `spec()` to retrieve the full column specification for this data. -#> ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message. - -# 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) +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) #> Rows: 6,786 #> Columns: 6 #> $ `Cidade abrangida` "ABADIA DE GOIÁS", "ABADIA DOS DOU… @@ -53,40 +59,115 @@ dplyr::glimpse(base_de_exemplo_bruta) #> $ `Tribunal UF` "GO", "MG", "GO", "MG", "PA", "CE"… #> $ `Tribunal município` "GUAPO", "COROMANDEL", "ABADIÂNIA"… #> $ `Indicador Valor` 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0… +``` + +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) +#> Rows: 5,534 +#> Columns: 6 +#> $ cidade_abrangida "ABADIA DE GOIÁS", "ABADIA DOS DOURADO… +#> $ codigo_do_ibge_cidade_abrangida "5200050", "3100104", "5200100", "3100… +#> $ cidade_abrangida_uf "GO", "MG", "GO", "MG", "PA", "CE", "P… +#> $ tribunal_uf "GO", "MG", "GO", "MG", "PA", "CE", "P… +#> $ tribunal_municipio "GUAPO", "COROMANDEL", "ABADIÂNIA", "A… +#> $ indicador_valor 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,… +``` -# 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) +### Utilizando o pacote `munifacil` +Agora, vamos usar o pacote `munifacil` para incluir o código do IBGE na +base de dados. -# ver novamente a base de exemplo limpa -dplyr::glimpse(base_de_exemplo) -#> Rows: 4,578 -#> Columns: 3 +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) +#> Rows: 5,534 +#> Columns: 8 #> $ cidade_abrangida "ABADIA DE GOIÁS", "ABADIA DOS DOURADO… #> $ codigo_do_ibge_cidade_abrangida "5200050", "3100104", "5200100", "3100… #> $ cidade_abrangida_uf "GO", "MG", "GO", "MG", "PA", "CE", "P… +#> $ tribunal_uf "GO", "MG", "GO", "MG", "PA", "CE", "P… +#> $ tribunal_municipio "GUAPO", "COROMANDEL", "ABADIÂNIA", "A… +#> $ indicador_valor 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,… +#> $ uf_join "GO", "MG", "GO", "MG", "PA", "CE", "P… +#> $ muni_join "abadia de goias", "abadia dos dourado… +``` -# Usar o munifacil +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. -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 incluir o código do IBGE na base de dados. Isso é feito com +a função `incluir_codigo_ibge()`. + +``` r +resultado <- base_colunas_limpas %>% incluir_codigo_ibge() -#> • Ainda faltam 1 (0%) casos... São eles: -#> • - - - +#> ✔ Uhul! Deu certo! +``` + +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. -# ver o resultado -dplyr::glimpse(resultado) -#> Rows: 4,578 -#> Columns: 11 +- `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) +#> Rows: 5,539 +#> Columns: 14 #> $ cidade_abrangida "ABADIA DE GOIÁS", "ABADIA DOS DOURADO… #> $ codigo_do_ibge_cidade_abrangida "5200050", "3100104", "5200100", "3100… #> $ cidade_abrangida_uf "GO", "MG", "GO", "MG", "PA", "CE", "P… +#> $ tribunal_uf "GO", "MG", "GO", "MG", "PA", "CE", "P… +#> $ tribunal_municipio "GUAPO", "COROMANDEL", "ABADIÂNIA", "A… +#> $ indicador_valor 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,… #> $ uf_join "GO", "MG", "GO", "MG", "PA", "CE", "P… #> $ muni_join "abadia de goias", "abadia dos dourado… #> $ id_municipio "5200050", "3100104", "5200100", "3100… @@ -95,25 +176,69 @@ dplyr::glimpse(resultado) #> $ existia_1991 FALSE, TRUE, TRUE, TRUE, TRUE, TRUE, T… #> $ existia_2000 TRUE, TRUE, TRUE, TRUE, TRUE, TRUE, TR… #> $ existia_2010 TRUE, TRUE, TRUE, TRUE, TRUE, TRUE, TR… +``` -# resultados que nao receberam o id do municipio -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) +#> Rows: 5,539 +#> Columns: 7 +#> $ cidade_abrangida "ABADIA DE GOIÁS", "ABADIA DOS DOURADO… +#> $ codigo_do_ibge_cidade_abrangida "5200050", "3100104", "5200100", "3100… +#> $ cidade_abrangida_uf "GO", "MG", "GO", "MG", "PA", "CE", "P… +#> $ tribunal_uf "GO", "MG", "GO", "MG", "PA", "CE", "P… +#> $ tribunal_municipio "GUAPO", "COROMANDEL", "ABADIÂNIA", "A… +#> $ indicador_valor 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,… +#> $ id_municipio "5200050", "3100104", "5200100", "3100… +``` + +### Verificando o resultado + +- Quantidade de resultados que não receberam o ID do município: + +``` r +resultado_limpo %>% dplyr::filter(is.na(id_municipio)) -#> # A tibble: 1 × 11 -#> cidade_abrangida codigo_do_ibge_cidade…¹ cidade_abrangida_uf uf_join muni_join -#> -#> 1 - - - - - -#> # ℹ abbreviated name: ¹​codigo_do_ibge_cidade_abrangida -#> # ℹ 6 more variables: id_municipio , manual , atencao , -#> # existia_1991 , existia_2000 , existia_2010 +#> # A tibble: 0 × 7 +#> # ℹ 7 variables: cidade_abrangida , codigo_do_ibge_cidade_abrangida , +#> # cidade_abrangida_uf , tribunal_uf , tribunal_municipio , +#> # indicador_valor , id_municipio +``` +Todos os municípios receberam o ID do IBGE! + +- Mas esses IDs estão corretos? + +``` r # Verificando a quantidade de resultados corretos -resultado %>% - dplyr::count(codigo_do_ibge_cidade_abrangida == id_municipio) -#> # A tibble: 3 × 2 -#> `codigo_do_ibge_cidade_abrangida == id_municipio` n -#> -#> 1 FALSE 14 -#> 2 TRUE 4563 -#> 3 NA 1 +resultado_limpo %>% + mutate(resultado_correto = codigo_do_ibge_cidade_abrangida == id_municipio) %>% + count(resultado_correto) %>% + mutate(porcentagem = formattable::percent(n / sum(n))) %>% + knitr::kable() ``` + +| resultado_correto | n | porcentagem | +|:------------------|-----:|------------:| +| TRUE | 5539 | 100.00% | + +## 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). diff --git a/docs/404.html b/docs/404.html index 2d54de6..4d9bbe3 100644 --- a/docs/404.html +++ b/docs/404.html @@ -7,8 +7,8 @@ Page not found (404) • munifacil - - + + License • munifacilLicense • munifacil @@ -10,7 +10,7 @@ munifacil - 0.0.0.9000 + 1.0.0 + + + + + +
+
+
+ +
+

munifacil 1.0.0

+
  • Improved documentation.
  • +
+
+ + +
+ + + +
+ + + + + + + diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml index 4b263d3..b9c6ffd 100644 --- a/docs/pkgdown.yml +++ b/docs/pkgdown.yml @@ -2,5 +2,5 @@ pandoc: 3.1.1 pkgdown: 2.0.7 pkgdown_sha: ~ articles: {} -last_built: 2023-06-16T17:27Z +last_built: 2024-02-28T23:22Z diff --git a/docs/reference/depara_muni_codigo.html b/docs/reference/depara_muni_codigo.html index e3b5a45..9eba230 100644 --- a/docs/reference/depara_muni_codigo.html +++ b/docs/reference/depara_muni_codigo.html @@ -1,6 +1,6 @@ Lista de candidatos a municipios do Brasil — depara_muni_codigo • munifacilLista de candidatos a municipios do Brasil — depara_muni_codigo • munifacilRealizar diagnóstico do join — diagnostico_join • munifacil + Skip to contents + + +
+
+
+ +
+

Realizar diagnóstico do join

+
+ +
+

Usage

+
diagnostico_join(resultado)
+
+ +
+

Arguments

+
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()

+ +
+
+

Value

+ + +

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.

+
+ +
+ + +
+ + + +
+ + + + + + + diff --git a/docs/reference/incluir_codigo_ibge.html b/docs/reference/incluir_codigo_ibge.html index b600dfc..e9c0b7d 100644 --- a/docs/reference/incluir_codigo_ibge.html +++ b/docs/reference/incluir_codigo_ibge.html @@ -1,5 +1,5 @@ -Incluir o codigo do IBGE — incluir_codigo_ibge • munifacilIncluir o codigo do IBGE — incluir_codigo_ibge • munifacil @@ -10,7 +10,7 @@ munifacil - 0.0.0.9000 + 1.0.0