| Title: | Limpa e Simplifica Nomes de Pessoas (Name Cleaner and Simplifier) |
|---|---|
| Description: | Limpa e simplifica nomes de pessoas para auxiliar no pareamento de banco de dados na ausência de chaves únicas não ambíguas. Detecta e corrige erros tipográficos mais comuns, simplifica opcionalmente termos sujeitos eventualmente a omissão em cadastros, e simplifica foneticamente suas palavras, aplicando variação própria do algoritmo metaphoneBR. (Cleans and simplifies person names to assist in database matching when unambiguous unique keys are unavailable. Detects and corrects common typos, optionally simplifies terms prone to omission in records, and applies phonetic simplification using a custom variation of the metaphoneBR algorithm.) Mation (2025) <doi:10.6082/uchicago.15104>. |
| Authors: | Rodrigo Borges [aut, cre] (ORCID: <https://orcid.org/0000-0003-2076-1424>), Lucas Mation [aut] (ORCID: <https://orcid.org/0000-0002-7461-932X>), Ipea - Institue for Applied Economic Research [cph, fnd] |
| Maintainer: | Rodrigo Borges <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-02-26 06:32:52 UTC |
| Source: | https://github.com/ipea/nomesbr |
Realiza uma consulta a uma tabela de nomes em um banco de dados DuckDB, retornando todas as colunas para os nomes que correspondem à lista de entrada.
consulta_nome_em_central(nomes, mestre, usar_hash = TRUE)consulta_nome_em_central(nomes, mestre, usar_hash = TRUE)
nomes |
Um vetor de caracteres (character vector) contendo os nomes ou hashes a serem consultados. |
mestre |
Uma string com o caminho para o banco de dados DuckDB (arquivo '.duckdb'). |
usar_hash |
Logico. Se |
A função se conecta a um banco de dados DuckDB especificado pelo caminho em 'mestre'. A consulta é otimizada para buscar múltiplos nomes de uma vez, gerando uma instrução SQL com parâmetros para evitar injeção de SQL.
O parâmetro 'usar_hash' permite escolher a coluna para a busca:
Se TRUE (padrão), a busca é feita na coluna
'nome_original_hash'. Isso é ideal se os nomes na tabela
estão armazenados como hashes (ex: SHA-256), pois pode ser mais rápido
e seguro para comparações exatas.
Se FALSE, a busca é feita na coluna 'nome_original',
que deve conter os nomes em formato de texto.
A fun\ç\ão gerencia automaticamente a conex\ão com o banco de dados, garantindo que ela seja fechada ao final da execu\ç\ão, mesmo que ocorra um erro.
Um data.frame contendo os resultados da consulta. Se nenhum
nome for encontrado, retorna um data.frame com zero linhas e as
colunas da tabela nomes_limpos.
## Not run: # Exemplo de uso com hash (padrão) # Suponha que 'caminho/para/meu_banco.duckdb' existe e tem a tabela 'nomes_limpos' # com uma coluna 'nome_original_hash'. hashes_para_buscar <- c("a1b2c3...", "d4e5f6...") resultados_hash <- consulta_nome_em_central( nomes = hashes_para_buscar, mestre = "caminho/para/meu_banco.duckdb" ) # Exemplo de uso com texto # Suponha que a tabela 'nomes_limpos' também tem uma coluna 'nome_original'. nomes_para_buscar <- c("João da Silva", "Maria Oliveira") resultados_texto <- consulta_nome_em_central( nomes = nomes_para_buscar, mestre = "caminho/para/meu_banco.duckdb", usar_hash = FALSE ) ## End(Not run)## Not run: # Exemplo de uso com hash (padrão) # Suponha que 'caminho/para/meu_banco.duckdb' existe e tem a tabela 'nomes_limpos' # com uma coluna 'nome_original_hash'. hashes_para_buscar <- c("a1b2c3...", "d4e5f6...") resultados_hash <- consulta_nome_em_central( nomes = hashes_para_buscar, mestre = "caminho/para/meu_banco.duckdb" ) # Exemplo de uso com texto # Suponha que a tabela 'nomes_limpos' também tem uma coluna 'nome_original'. nomes_para_buscar <- c("João da Silva", "Maria Oliveira") resultados_texto <- consulta_nome_em_central( nomes = nomes_para_buscar, mestre = "caminho/para/meu_banco.duckdb", usar_hash = FALSE ) ## End(Not run)
Adiciona Nome Próprio Validado de 'nomes_proprios_compostos' .
identificar_adicionar_nome_proprio(dt, s) add_nome_proprio_to_word1_and_word2p(dt, s)identificar_adicionar_nome_proprio(dt, s) add_nome_proprio_to_word1_and_word2p(dt, s)
dt |
Um 'data.table'. |
s |
Nome da coluna (string) base para derivação das colunas de palavras (por exemplo, se 's = "nome_simpl"', espera 'nome_simpl1', 'nome_simpl2p'). |
O 'data.table' 'dt' com colunas '_v2' adicionadas.
dt_nomes <- data.table::data.table(nome=c("MARIA DO SOCORRO SILVA", "ANA PAULA DE OLIVEIRA","JOSE DAS FLORES")) dt_nomes <- identificar_adicionar_nome_proprio(dt_nomes,"nome") print(dt_nomes)dt_nomes <- data.table::data.table(nome=c("MARIA DO SOCORRO SILVA", "ANA PAULA DE OLIVEIRA","JOSE DAS FLORES")) dt_nomes <- identificar_adicionar_nome_proprio(dt_nomes,"nome") print(dt_nomes)
Processa uma coluna de nomes em um 'data.table', aplicando uma série de regras de limpeza para identificar e corrigir/marcar problemas comuns como menções a "FALECIDO", "CARTORIO", erros de digitação, espaços indevidos, etc.
limpar_nomes(d, s) find_and_clean_NAnames_and_extra_spaces(d, s)limpar_nomes(d, s) find_and_clean_NAnames_and_extra_spaces(d, s)
d |
Um objeto 'data.table'. |
s |
O nome da coluna (em string) dentro de 'd' que contém os nomes a serem processados. |
A função executa os seguintes passos principais:
Cria uma cópia da coluna de nomes para limpeza.
Detecta e trata menções a "FALECIDO(A)".
Detecta e trata menções a "CARTORIO" e nomes de cidades comuns em registros.
Corrige espaçamento perto de caracteres especiais com 'limpa_espaco_acento_til_apostrofe'.
Identifica e trata nomes contendo termos problemáticos como "PAI", "MAE", "SEM", "NAO", exceto em contextos aceitáveis.
Identifica e trata casos de "NADA CONSTA" e variações.
Corrige E, DA, DE e variantes com caracter prévio indevido (ex: "EDAS" para "DAS" se aplicável).
Remove saudações como "SR.", "SRA.".
Remove termos como "IGNORADO", "DESCONHECIDO".
Remove repetições de partículas de ligação (ex: "DE DE").
Limpa letras repetidas no início ou meio de palavras.
Um 'data.table' modificado, contendo a coluna original, uma nova coluna com sufixo "_clean" com os nomes limpos, e colunas booleanas indicando a detecção de cada tipo de problema (ex: 'falecido', 'cartorio').
# Supondo que 'meu_DT' é um data.table com uma coluna 'nome_sujo' DT_exemplo <- data.table::data.table( id = 1:3, nome_sujo = c("MARIA FALECIDA SSILVA", "CARTORIO DE PAZ", "JOAO D ARC") ) DT_limpo <- limpar_nomes(DT_exemplo, "nome_sujo") print(DT_limpo)# Supondo que 'meu_DT' é um data.table com uma coluna 'nome_sujo' DT_exemplo <- data.table::data.table( id = 1:3, nome_sujo = c("MARIA FALECIDA SSILVA", "CARTORIO DE PAZ", "JOAO D ARC") ) DT_limpo <- limpar_nomes(DT_exemplo, "nome_sujo") print(DT_limpo)
Remove Partículas, Agnomes e algumas Patentes de Nomes
remove_PARTICULAS_AGNOMES(s)remove_PARTICULAS_AGNOMES(s)
s |
Vetor de caracteres contendo nomes. |
Vetor de caracteres com nomes simplificados.
vct_nomes <- c("JOAO DA SILVA FILHO","CORONEL JACINTO") remove_PARTICULAS_AGNOMES(vct_nomes)vct_nomes <- c("JOAO DA SILVA FILHO","CORONEL JACINTO") remove_PARTICULAS_AGNOMES(vct_nomes)
Adiciona Colunas com Partes do Nome (w1, w2, w3, w2p, w12p)
segmentar_nomes(dt, s) add_string_w1_w2_w3_and_w2p(dt, s)segmentar_nomes(dt, s) add_string_w1_w2_w3_and_w2p(dt, s)
dt |
Um 'data.table'. |
s |
Nome da coluna (string) em 'dt' contendo os nomes. |
O 'data.table' 'dt' modificado por referência, com novas colunas.
dt_nomes <- data.table::data.table(nome=c("MARIA DO SOCORRO SILVA", "ANA PAULA DE OLIVEIRA")) dt_nomes <- segmentar_nomes(dt_nomes,"nome") print(dt_nomes)dt_nomes <- data.table::data.table(nome=c("MARIA DO SOCORRO SILVA", "ANA PAULA DE OLIVEIRA")) dt_nomes <- segmentar_nomes(dt_nomes,"nome") print(dt_nomes)
Cria coluna com agnomes, algumas patentes/cargos as remove, remove partículas
simplifica_PARTICULAS_AGNOMES_PATENTES(d, s = "nome_clean")simplifica_PARTICULAS_AGNOMES_PATENTES(d, s = "nome_clean")
d |
um objeto 'data.table' |
s |
string com nome da coluna de caracteres contendo nomes para simplificar. Por padrão, "nome_clean". |
data.table com novas colunas de nome simplificado e de marca agnomes_titulos
dt_nomes <- data.table::data.table(nome = c("JOAO DA SILVA FILHO", "CORONEL JACINTO")) dt_nomes <- simplifica_PARTICULAS_AGNOMES_PATENTES(d=dt_nomes,s="nome") print(dt_nomes)dt_nomes <- data.table::data.table(nome = c("JOAO DA SILVA FILHO", "CORONEL JACINTO")) dt_nomes <- simplifica_PARTICULAS_AGNOMES_PATENTES(d=dt_nomes,s="nome") print(dt_nomes)
Cria uma tabela resumo contabilizando o número de ocorrências para cada tipo de problema detectado pela função 'marcar_problemas_e_limpar_nomes'.
tabular_problemas_em_nomes(d, s) tabulate_name_poblems(d, s)tabular_problemas_em_nomes(d, s) tabulate_name_poblems(d, s)
d |
O 'data.table' retornado por 'marcar_problemas_e_limpar_nomes'. |
s |
O nome da coluna original (string) que foi processada. |
Um 'data.table' com as colunas:
'condition': O nome da condição/problema verificado.
'N_detected': Número de vezes que a condição foi detectada.
'N_made_NA': Número de detecções que resultaram na limpeza para 'NA'.
'N_replaced': Número de detecções onde o nome foi alterado (não para 'NA').
DT_limpo <- data.table::data.table(nome = c("JOSEE SILVA", "RAIMUNDA DA DA SILVA"), nome_clean = c("JOSE SILVA", "RAIMUNDA DA SILVA"), falecido = NA, cartorio = NA, espaco_TilAcentoApostrofe = NA, nome_P_M_S_N = NA, nada_nao = NA, nada_nao_consta2 = NA, final_missing = NA, Xartigo = NA, sr_sra = NA, ignorado = NA, dededada = 1, letra_repetida = 1) sumario <- tabular_problemas_em_nomes(DT_limpo, "nome") print(sumario)DT_limpo <- data.table::data.table(nome = c("JOSEE SILVA", "RAIMUNDA DA DA SILVA"), nome_clean = c("JOSE SILVA", "RAIMUNDA DA SILVA"), falecido = NA, cartorio = NA, espaco_TilAcentoApostrofe = NA, nome_P_M_S_N = NA, nada_nao = NA, nada_nao_consta2 = NA, final_missing = NA, Xartigo = NA, sr_sra = NA, ignorado = NA, dededada = 1, letra_repetida = 1) sumario <- tabular_problemas_em_nomes(DT_limpo, "nome") print(sumario)