From 3a8dc99a459fcdf414ec2363c76e4a43e3f57217 Mon Sep 17 00:00:00 2001 From: Daniel Herszenhut Date: Tue, 22 Oct 2024 16:54:42 -0300 Subject: [PATCH] atualizando vignette --- vignettes/enderecopadrao.Rmd | 147 ++++++++++++++++++++++++++++------- 1 file changed, 121 insertions(+), 26 deletions(-) diff --git a/vignettes/enderecopadrao.Rmd b/vignettes/enderecopadrao.Rmd index e790c17..cbd2766 100644 --- a/vignettes/enderecopadrao.Rmd +++ b/vignettes/enderecopadrao.Rmd @@ -21,32 +21,42 @@ probabilísticas entre strings. ## Instalação -O pacote ainda não se encontra no CRAN. Para baixar a última versão estável, use -o código abaixo: +Para usar o pacote, é necessário primeiro instalá-lo. A última versão estável +pode ser baixada do CRAN com o comando a seguir: ```r -# install.packages("remotes") -remotes::install_github("ipeaGIT/enderecopadrao@v0.1.0") +install.packages("enderecopadrao") ``` -Para baixar a versão em desenvolvimento, use o seguinte código: +Caso prefira, a versão em desenvolvimento também pode ser usada. Para isso, use +o seguinte comando: ```r +# install.packages("remotes") remotes::install_github("ipeaGIT/enderecopadrao") ``` ## Utilização -O pacote fornece funções para padronizar diferentes campos de um endereço. A -`padronizar_enderecos()` padroniza diversos campos simultaneamente, recebendo, -para isso, um dataframe e uma relação de correspondência entre as colunas desse -dataframe e os campos a serem padronizados: +O **enderecopadrao** disponibiliza funções para padronizar os diversos campos de +um endereço. Essas funções agem tanto sobre campos individuais quanto sobre um +conjunto de campos. Vamos ver, primeiro, como funcionam as funções que agem +sobre múltiplos campos simultaneamente. + +### Padronização de múltiplos campos simultaneamente + +A `padronizar_enderecos()`, carro-chefe do pacote, atua de forma simultânea +sobre os vários campos que podem compor um endereço. Para isso, ela recebe um +dataframe e a correspondência entre suas colunas e os campos a serem +padronizados: ```{r} library(enderecopadrao) enderecos <- data.frame( - logradouro = "r ns sra da piedade", + id = 1, + tipo = "r", + logradouro = "ns sra da piedade", nroLogradouro = 20, complemento = "qd 20", cep = 25220020, @@ -56,6 +66,7 @@ enderecos <- data.frame( ) campos <- correspondencia_campos( + tipo_de_logradouro = "tipo", logradouro = "logradouro", numero = "nroLogradouro", complemento = "complemento", @@ -71,13 +82,86 @@ padronizar_enderecos(enderecos, campos_do_endereco = campos) Note que no exemplo acima nós também utiliza a função `correspondencia_campos()`, que facilita o processo de especificação de correspondência entre as colunas do dataframe e os campos do endereço a serem -padronizados. Na prática, no entanto, essa função é opcional, e poderíamos -passar um vetor de caracteres no argumento `campos_do_endereco` (a -`correspondencia_campos()` realiza alguns testes no input, garantindo que o -vetor a ser passado pra `padronizar_enderecos()` esteja corretamente formatado). +padronizados. Com ela, nós especificamos que a coluna que contém a informação de +tipo de logradouro se chama `"tipo"`, que a coluna de número do logradouro se +chama `"nroLogradouro"`, etc. Na prática, no entanto, essa função é opcional, e +poderíamos simplesmente passar um vetor de caracteres no formato +`c(tipo_de_logradouro = "tipo", logradouro = "logradouro", ...)`. A +`correspondencia_campos()`, no entanto, realiza alguns testes no input, +garantindo que o vetor a ser passado pra `padronizar_enderecos()` esteja +corretamente formatado. + +A `padronizar_enderecos()` contém, ainda, dois parâmetros adicionais. O +`manter_cols_extras` determina as colunas incluídas no output da função. Caso +seja `TRUE` (valor padrão), todas as colunas do dataframe original são mantidas; +caso seja `FALSE`, apenas as colunas usadas na padronização e seus respectivos +resultados são preservados. O bloco abaixo demonstra essa funcionalidade: + +```{r} +campos <- correspondencia_campos( + tipo_de_logradouro = "tipo", + logradouro = "logradouro" +) + +padronizar_enderecos(enderecos, campos, manter_cols_extras = TRUE) -Por trás dos panos, a `padronizar_enderecos()` utiliza diversas outras funções -que padronizam campos de forma individual. Cada uma delas recebe um vetor com +padronizar_enderecos(enderecos, campos, manter_cols_extras = FALSE) +``` + +O `combinar_logradouro`, por sua vez, determina se os campos que compõem o +logradouro (tipo, nome e número) devem ser combinados em um único campo +padronizado de logradouro completo. Caso seja `FALSE`(valor padrão), os campos +permanecem separados; se for `TRUE`, são combinados. Nesse caso, o parâmetro +`logradouro` da `correspondencia_campos()` deve ser interpretado como o *nome* +do logradouro. A seguir, demonstramos essa funcionalidade: + +```{r} +enderecos <- data.frame( + tipo = "r", + logradouro = "ns sra da piedade", + nroLogradouro = 20 +) + +campos <- correspondencia_campos( + tipo_de_logradouro = "tipo", + logradouro = "logradouro", + numero = "nroLogradouro" +) + +padronizar_enderecos(enderecos, campos, combinar_logradouro = FALSE) + +padronizar_enderecos(enderecos, campos, combinar_logradouro = TRUE) +``` + +O parâmetro `combinar_logradouro` aciona, de forma oculta, outra função que lida +com múltiplos campos simultaneamente: a `padronizar_logradouros_completos()`. +Essa função também pode ser usada de forma separada e, de forma similiar à +`padronizar_enderecos()`, recebe um dataframe com as informações do logradouro +(tipo, nome e número) e a correspondência entre suas colunas e os campos a serem +padronizados: + +```{r} +campos <- correspondencia_logradouro( + tipo_de_logradouro = "tipo", + nome_do_logradouro = "logradouro", + numero = "nroLogradouro" +) + +padronizar_logradouros_completos(enderecos, campos_do_logradouro = campos) +``` + +Note que, nesse caso, usamos a função `campos_do_logradouro()` para estabelecer +a correspondência entre colunas e campos do endereço, mas também poderíamos +passar um vetor de caracteres no argumento `campos_do_logradouro`. A +`padronizar_logradouros_completos()` também inclui os parâmetros +`manter_cols_extras` e `checar_tipos`, que funcionam de forma idêntica aos +parâmetros de mesmo nome da `padronizar_enderecos()`. + +### Padronização de campos individuais + +Por trás dos panos, tanto a `padronizar_enderecos()` quanto a +`padronizar_logradouros_completos()` utilizam diversas outras funções que +padronizam campos de forma individual. Cada uma delas recebe um vetor com valores não padronizados e retorna um vetor de mesmo tamanho com os respectivos valores padronizados. As funções atualmente disponíveis são: @@ -87,6 +171,7 @@ valores padronizados. As funções atualmente disponíveis são: - `padronizar_ceps()` - `padronizar_logradouros()` - `padronizar_numeros()` +- `padronizar_tipos_de_logradouro()` - `padronizar_complementos()` A `padronizar_estados()` aceita vetores de strings e números. Caso numérico, o @@ -111,10 +196,10 @@ padronizar_estados(estados) A função de padronização de campos de município, `padronizar_municipios()`, funciona de forma muito semelhante, aceitando também valores numéricos representando os códigos dos municípios e strings. As mesmas manipulações de -remoção de espaços, conversão para caixa alta são aplicadas e conversão para -caracteres são aplicadas (assim como nos demais tratamentos de vetores de -strings que serão apresentados a seguir), mas a função também verifica erros -ortográficos frequentemente observados nos nomes dos municípios (e.g. Moji Mirim +remoção de espaços, conversão para caixa alta e conversão para caracteres são +aplicadas (assim como nos demais tratamentos de vetores de strings que serão +apresentados a seguir), mas a função também verifica erros ortográficos +frequentemente observados nos nomes dos municípios (e.g. Moji Mirim -> Mogi Mirim, Parati -> Paraty). ```{r} @@ -156,12 +241,12 @@ números. Caso o input seja numérico, a função verifica se os valores possuem comprimentos compatíveis com um CEP, adicionando zeros à esquerda se necessário (é muito comum que leitores de CSV, por exemplo, erroneamente leiam valores de CEP como números e excluam zeros à esquerda por considerá-los redundantes). Caso -o input seja formado por strings, a função remove frequentemente são usados para -separar partes do CEP (e.g. pontos, vírgulas, espaços em branco) e verifica se o -hífen separando os cinco primeiros dígitos dos três últimos está presente, -adicionando-o caso contrário. A função ainda produz erros se recebe como input -valores que não podem ser corretamente convertidos em CEPs, como no caso de -strings contendo caracteres não numéricos e de strings com caracteres em +o input seja formado por strings, a função remove caracteres que frequentemente +são usados para separar partes do CEP (e.g. pontos, vírgulas, espaços em branco) +e verifica se o hífen separando os cinco primeiros dígitos dos três últimos está +presente, adicionando-o caso contrário. A função ainda produz erros se recebe +como input valores que não podem ser corretamente convertidos em CEPs, como no +caso de strings contendo caracteres não numéricos e de strings com caracteres em excesso. ```{r, error=TRUE} @@ -207,6 +292,16 @@ numeros <- c(210, 1, 10000) padronizar_numeros(numeros) ``` +Outra função que atua sobre uma informação específica do logradouro, caso essa +seja fornecida separadamente, é a `padronizar_tipos_de_logradouro()`. Fora o +tratamento usual dado a strings, a função também expande abreviações +frequentemente observadas no campo de tipo de logradouro. + +```{r} +tipos <- c("r", "R.", "AVN", "AVE", "JDM", "QD") +padronizar_tipos_de_logradouro(tipos) +``` + Por fim, a `padronizar_complementos()` age de forma similar às funções de padronização de logradouros e bairros, porém agindo de forma mais específica em abreviações e observações frequentemente observados na especificação de