Pacote RHCgen - Nota Técnica - Guia do Usuário

RHCgen: Um Pacote R para Automação, Padronização e Avaliação da Qualidade dos Dados do Registro Hospitalar de Câncer no Brasil

Anderson Lineu Siqueira dos Santos (https://orcid.org/0000-0002-1703-9310)¹; Tatyellen Natasha da Costa Oliveira (https://orcid.org/0000-0002-4781-3952)^1,2; Raphael de Freitas Saldanha (https://orcid.org/0000-0003-0652-8466)³; Raquel de Vasconcellos Carvalhaes de Oliveira (https://orcid.org/0000-0001-9387-8645)⁴

Como citar: Santos, A. L. S. dos ., Oliveira, T. N. da C., Saldanha, R. de F., & Oliveira, R. de V. C. de . (2026). RHCgen: Um Pacote R para Automação, Padronização e Avaliação da Qualidade dos Dados do Registro Hospitalar de Câncer no Brasil. Zenodo. https://doi.org/10.5281/zenodo.19962293 Disponibilizado em: 01-05-2026. O pacote RHCgen, bem como os conjuntos de dados utilizados nesta nota técnica, encontram-se depositados de forma aberta no repositório Zenodo. DOI:		1 Escola Nacional de Saúde Pública Sergio Arouca, Fundação Oswaldo Cruz, Rio de Janeiro, Brasil. 2 Seção de Ensino e Informação Científica, Instituto Evandro Chagas, Ananindeua, PA, Brasil. 3 Instituto de Comunicação e Informação Científica e Tecnológica em Saúde Fundação Oswaldo Cruz, Rio de Janeiro, RJ, Brasil. 4 Instituto Nacional de Infectologia, Fundação Oswaldo Cruz, Rio de Janeiro, RJ, Brasil. RESUMO Introdução: O Registro Hospitalar de Câncer (RHC) reúne dados clínicos e assistenciais de pacientes oncológicos atendidos em hospitais habilitados pelo Sistema Único de Saúde no Brasil, constituindo uma base estratégica para a vigilância e a pesquisa em oncologia. Contudo, a ausência de ferramentas padronizadas para seu processamento, aliada à heterogeneidade estrutural e semântica dos arquivos disponibilizados, impõe barreiras significativas à sua utilização em larga escala e de forma reprodutível. Objetivo: Descrever um pacote computacional de acesso aberto, implementado na linguagem R, voltado à automação, padronização do processamento e avaliação da qualidade dos dados do Registro Hospitalar de Câncer no Brasil. Métodos: Estudo metodológico que descreve o desenvolvimento do pacote RHCgen, implementado em R com o auxílio dos pacotes usethis, devtools e roxygen2. O pacote foi estruturado como um pipeline automatizado de extração, transformação e carga (ETL), composto por funções modulares para leitura e consolidação de arquivos no formato .dbf, padronização estrutural, variações semântica e recodificação de variáveis, além de fazer a avaliação de completude e consistência dos dados. A validação dos algoritmos foi realizada com base em documentos publicados pelo Instituto Nacional de Câncer. A aplicação do pacote foi demonstrada por meio do processamento de 24 arquivos nacionais do RHC, referentes ao período de 2000 a 2023. Resultados: O processamento resultou em uma base analítica consolidada com 5.394.771 registros de casos de câncer e 59 variáveis, com tempo de execução de 4,61 minutos e consumo aproximado de 2,01 GB de memória RAM. Conclusão: O RHCgen oferece uma solução padronizada, reprodutível e de acesso aberto para o processamento de dados do RHC, automatizando etapas que anteriormente demandavam rotinas manuais fragmentadas e sujeitas a erros. O pacote promove transparência e rigor na avaliação da qualidade dos dados, contribuindo para ampliar a produção científica baseada no RHC e fortalecer a vigilância oncológica no Brasil. Palavras-chave: Registros Hospitalares de Câncer; Processamento de Dados; Reprodutibilidade dos Resultados; Sistemas de Informação em Saúde; Neoplasias; Linguagem R; RHCgen

1 1.    INTRODUÇÃO

Nos últimos anos, observa-se aumento da quantidade de pesquisas que envolvem bases de dados de câncer, a fim de melhor compreender a dinâmica da evolução, tratamento e prevenção da doença [1]. Iniciativas como o Global Cancer Observatory, o Cancer Incidence in Five Continents e o CANCER TODAY, possuem abrangência global e disponibilizam dados sobre a incidência, mortalidade e prevalência de câncer em 185 países e mais de 300 regiões no mundo [2,3]. Em níveis locais, bases de dados norte-americanas como o Surveillance, Epidemiology, and End Results do National Cancer Institute, e o National Cancer Database, reúnem dados de mais de 1.500 hospitais, que cobre cerca de 48% da população dos EUA [2,4]. Na Europa, o European Cancer Information System, operado pela Comissão Europeia, coleta dados abrangentes de incidência, mortalidade e sobrevivência do câncer, permitindo análises comparativas entre regiões e subsidiando políticas de saúde pública eficazes [5,6].

O Brasil dispõe de duas bases de dados específicas para o registro de informações sobre câncer: os Registros de Câncer de Base Populacional (RCBP) e os Registros Hospitalares de Câncer (RHC), ambos mantidos pelo Instituto Nacional do Câncer (INCA). Enquanto o RCBP registra a ocorrência e as características dos casos novos na população, o RHC reúne informações clínicas e terapêuticas de pacientes atendidos em hospitais habilitados na Atenção Especializada em Oncologia do Sistema Único de Saúde (SUS). Os RHC são responsáveis pela coleta, armazenamento, processamento, análise e divulgação contínua desses dados, incluindo informações sobre identificação, características demográficas, diagnóstico, tratamento e evolução dos tumores. Obrigatórios em hospitais que atendem pacientes com câncer no SUS, esses registros subsidiam a gestão hospitalar, o acompanhamento clínico e a avaliação da qualidade da assistência e dos desfechos dos tratamentos [7].

No contexto da análise de dados em saúde no Brasil, destaca-se a ferramenta TabWin, desenvolvida pelo DATASUS [8], que desempenha um papel fundamental ao permitir a tabulação e o tratamento desses dados. Entretanto, apesar da sua capacidade de leitura de arquivos no formato DBC, construção de tabelas, indicadores, gráficos e mapas, o TabWin é restrito ao sistema operacional Windows e tem capacidades analíticas limitadas. Para estatísticas mais complexas existe a necessidade de exportação dos dados para pacotes estatísticos mais robustos, o que adiciona trabalho e potencial para erros [9–11].

Essas limitações têm impulsionado a busca por ferramentas mais eficientes e reprodutíveis para análise de dados, o que tem sido viabilizado por meio de ferramentas de ciência de dados, que têm transformado a preparação dos dados em pesquisa. A linguagem R, amplamente utilizada para análise estatística, destaca-se por permitir a organização e manipulação de grandes volumes de dados heterogêneos, comuns em epidemiologia em saúde pública, ao facilitar a conversão de dados brutos em formatos prontos para análise e contribuir para a produção de resultados científicos confiáveis [12].

Alguns pacotes em R específicos para manipulação e processamento de dados de saúde no Brasil facilitam o acesso e análise de informações de saúde pública, como por exemplo o microdatasus [10], pacote que viabiliza o download e pré-processamento de dados de alguns Sistemas de Informação do SUS diretamente do DATASUS e o Rtabnetsp [13], que permite a extração de indicadores de saúde dos servidores TabNet da Secretaria de Estado da Saúde de São Paulo. Entretanto, até o momento não há uma ferramenta que permita a automação e padronização integral do processamento do RHC. Como consequência, a utilização desses dados em larga escala permanece limitada por barreiras relevantes de interoperabilidade e reprodutibilidade. Na prática, a ausência de um pipeline estruturado obriga cada pesquisador a desenvolver rotinas próprias de limpeza, transformação e harmonização (isto é, padronização de formatos, códigos e categorias das variáveis), geralmente baseadas em scripts ad hoc. Esse cenário fragmentado implica não apenas repetição desnecessária das mesmas etapas de processamento por diferentes pesquisadores, mas também a introdução de decisões analíticas heterogêneas, que podem gerar estimativas divergentes a partir de uma mesma base de dados.

Diante desse cenário, a proposta de um pacote que estabeleça um padrão de governança dos dados se torna particularmente relevante, ao garantir que o processo de transformação do dado bruto em base analítica seja transparente, documentado e reprodutível. A padronização dessas etapas contribui para maior consistência entre estudos, além de facilitar auditorias, validações externas e o compartilhamento de métodos. O desenvolvimento de uma ferramenta com essas características responde diretamente a essa lacuna, ao oferecer uma estrutura sistematizada para organização, processamento e análise dos dados do RHC. Ao reduzir a dependência de procedimentos manuais e de soluções isoladas, essa abordagem tem o potencial de minimizar a ocorrência de erros, otimizar o tempo de processamento e ampliar a eficiência analítica, especialmente em bases com milhões de registros. Mais do que uma solução de conveniência, trata-se de uma infraestrutura metodológica que promove reprodutibilidade, padronização e escalabilidade.

Para tal, esta nota técnica tem como objetivo descrever e apresentar o pacote computacional de acesso aberto RHCgen, implementado na linguagem R, voltado à automação, padronização do processamento e avaliação da qualidade dos dados do Registro Hospitalar de Câncer no Brasil, descrevendo sua arquitetura, funcionalidades e potencial de aplicação em análises em larga escala com dados do RHC.

2 2.    MÉTODOS

Estudo metodológico que descreve o desenvolvimento e a implementação do RHCgen, pacote computacional para processamento padronizado dos dados do RHC. O pacote RHCgen foi implementado na linguagem R e organiza o processamento dos dados por meio de um pipeline composto por etapas sequenciais de leitura, padronização de variáveis, verificação de consistência e geração de bases analíticas. O processamento é realizado a partir de rotinas padronizadas aplicáveis a diferentes conjuntos de dados, assegurando consistência na transformação dos dados e rastreabilidade das etapas executadas. O pacote apresenta capacidade de processamento de arquivos provenientes de diferentes períodos (1985 a 2023).

2.1 2.1. FONTE DE DADOS: REGISTRO HOSPITALAR DE CÂNCER (RHC)

Os RHC em todo o território brasileiro coletam dados individualizados de pacientes com diagnóstico confirmado de câncer, obtidos de prontuários e outras fontes hospitalares, permitindo tanto a análise detalhada em nível individual quanto a avaliação agregada de desfechos clínicos e dos padrões diagnósticos mais frequentes [7].

O RHCgen é específico para ser utilizado com dados do RHC que são disponibilizados para download no IntegradorRHC (IRHC), no formato Data Base File (.dbf) através do link: https://irhc.inca.gov.br/RHCNet/ [14]. Implantado em 2007, o IntegradorRHC (IRHC) é um sistema público que consolida e disponibiliza informações processadas pelo Sistema de Informação de Registro Hospitalar de Câncer (SisRHC), com base em registros de pacientes atendidos em unidades habilitadas no SUS em todo o território nacional. A base de dados é não nominativa e estruturada a partir de registros padronizados pelas instituições participantes, sendo o SisRHC responsável pelos processos de entrada, validação e padronização das informações [7,14,15].

Para a construção do pacote e realização dos testes do pipeline, foram utilizados dados provenientes do IntegradorRHC. O período analisado compreendeu registros com ano do banco entre 1º de janeiro de 1985 e 31 de dezembro de 2023. Os dados foram extraídos em 11 de julho de 2025, considerando a versão da base disponível no sistema à época, cuja última atualização havia ocorrido em 7 de abril de 2025, assegurando a rastreabilidade dos dados utilizados.

2.2 2.2. DESENVOLVIMENTO DO RHCGEN

O desenvolvimento do RHCgen foi realizado com o uso da linguagem de programação R (versão 4.5.1) [16], no ambiente de desenvolvimento integrado RStudio (versão 2025.06.13) [17], com o auxílio dos pacotes usethis [18], devtools [19] e roxygen2 [20]. O usethis foi utilizado para configurar a estrutura do pacote e criar diretórios e arquivos padrão necessários para o desenvolvimento. O devtools auxiliou na construção, verificação e instalação do pacote, para assegurar que todas as dependências e configurações estivessem corretas. O roxygen2 foi empregado para gerar a documentação das funções do pacote.

O RHCgen está disponível no GitHub (https://github.com/andersonlineu/RHCgen), com o objetivo de facilitar seu uso, além de possibilitar a revisão e o aprimoramento por outros pesquisadores. Com o pacote remotes previamente instalado no R, a instalação do RHCgen pode ser realizada da seguinte forma:

remotes::install_github(“andersonlineu/RHCgen”)

O pacote foreign é instalado automaticamente no primeiro uso do RHCgen. Esse pacote tem a função específica de realizar a leitura de arquivos no formato .dbf, converte campos de caracteres em fatores e respeita, sempre que possível, os campos nulos.

Um guia construído para fornecer orientações ao usuário sobre como utilizar o pacote está disponível no link: https://andersonlineu.github.io/GuiaRHCgen/.

2.3 2.3. VALIDAÇÃO ALGORÍTMICA E CONSISTÊNCIA DOS DADOS

A validação dos algoritmos de recodificação implementados no RHCgen foi baseada na correspondência com as normas técnicas descritas no manual Registros Hospitalares de Câncer: Planejamento e Gestão[21] e no Dicionário de Variáveis do Sistema de Informação de Registro Hospitalar de Câncer (SisRHC)[22], ambos publicados pelo Instituto Nacional de Câncer (INCA). As rotinas de processamento foram construídas de forma determinística, assegurando que a transformação dos dados seguisse estritamente os padrões oficiais de codificação, incluindo mapeamentos institucionais (CNES), classificações clínicas (CID-O) e definições de desfechos.

A identificação dos estabelecimentos de saúde foi realizada por meio de vinculação determinística utilizando o código do Cadastro Nacional de Estabelecimentos de Saúde (CNES) presente na base do RHC. Esse identificador foi utilizado como chave única para integração com a base oficial do CNES, permitindo a padronização e recuperação das informações institucionais correspondentes.

A confiabilidade das funções foi avaliada por meio de testes unitários, nos quais valores de entrada previamente definidos foram comparados às saídas esperadas, com base nos dicionários oficiais. Para variáveis com grande número de categorias ou códigos possíveis, foram realizadas verificações de cobertura para garantir que todos os códigos válidos presentes no SisRHC fossem corretamente processados. Adicionalmente, foram realizados testes de integração para verificar o desempenho das funções em execução sequencial ao longo do pipeline, bem como comparações entre as saídas automatizadas e bases de referência previamente revisadas. Diferente de abordagens baseadas em simulações, todas as etapas de validação e estresse de volumetria utilizaram exclusivamente dados reais do RHC, permitindo atestar a estabilidade e o desempenho da ferramenta em condições operacionais reais.

2.4 2.4. PROCESSO ÚNICO

A arquitetura do RHCgen é centrada na função modular construir_banco, que opera como um pipeline automatizado de extração, transformação e carga (automated extract, transform, and load (ETL), conforme ilustrado na Figura 1. Diferente de abordagens convencionais, esta função orquestra a transição do dado bruto para a base analítica em quatro estágios críticos:

2. Harmonização Estrutural: Leitura e consolidação dinâmica de múltiplos arquivos .dbf, resolvendo inconsistências de nomenclatura e tipagem de colunas entre diferentes séries históricas para garantir uma base única e consistente.

4. Transformação de Tipos e Atributos: Conversão automática de variáveis importadas erroneamente como fatores para seus formatos originais (numérico para idade, data para eventos temporais e caractere para os demais campos) assegurando a integridade necessária para cálculos estatísticos.

6. Enriquecimento e Recodificação: Mapeamento de códigos técnicos, como CID-O, CNES e Estadiamento Clínico, para termos descritivos completos, utilizando os dicionários oficiais do INCA como referência [21,22].

8. Auditoria de qualidade: cálculo de indicadores de completude e consistência lógica para avaliação da qualidade dos dados da base, permitindo identificar níveis de preenchimento e incoerências entre variáveis, com base em escores descritos por Romero e Cunha [23] e Pinto et al. [24].

Figura 1. Fluxograma do pipeline de processamento de dados do pacote RHCgen. O diagrama ilustra a orquestração da função construir_banco(), que automatiza desde a leitura dos arquivos brutos (.dbf) até a geração de uma base analítica estruturada e relatórios de auditoria de qualidade.

2.5 2.5. LEITURA E INTEGRAÇÃO DOS ARQUIVOS DBF

2.5.1 2.5.1.      Função principal

lerarquivoDBF()

2.5.2 2.5.2.      Finalidade da função

A função lerarquivoDBF() realiza a leitura automática dos arquivos DBF do Registro Hospitalar de Câncer disponíveis no diretório de trabalho e combina esses arquivos em um único banco de dados. Além disso, cria a variável Ano_do_Banco, extraída do nome original do arquivo, permitindo identificar o ano de origem de cada registro.

2.5.3 2.5.3.      Problema que a função resolve

Os arquivos do RHC são disponibilizados separadamente, geralmente por ano, em formato DBF. Esse formato exige leitura específica e pode apresentar diferenças estruturais entre os arquivos, como presença ou ausência de determinadas colunas. A função reduz o trabalho manual de leitura, conferência e junção desses arquivos, automatizando a etapa inicial de construção do banco.

2.5.4 2.5.4.      Como a função opera

A função procura no diretório de trabalho todos os arquivos com nome iniciado por rhc e extensão .dbf, como rhc20.dbf. Em seguida, lê cada arquivo, verifica se há registros válidos, extrai o ano a partir do nome do arquivo e adiciona essa informação na nova coluna Ano_do_Banco. Quando existem diferenças entre os arquivos, a função identifica o conjunto total de colunas e adiciona colunas ausentes com valores NA, permitindo a combinação dos arquivos em uma estrutura única.

2.5.5 2.5.5.      Entrada esperada

A função não exige argumentos externos. Para funcionar corretamente, os arquivos DBF devem estar no diretório de trabalho e manter o nome original proveniente do Integrador RHC, com o padrão iniciado por rhc.

2.5.6 2.5.6.      Saída produzida

A função retorna um dataframe único contendo os registros combinados de todos os arquivos DBF identificados. Caso nenhum arquivo válido seja encontrado, ou caso não seja possível combinar os arquivos, a função retorna NULL.

2.5.7 2.5.7.      Importância no fluxo do RHCgen

Essa é a primeira etapa do pipeline do RHCgen. Ela cria a base inicial sobre a qual serão aplicadas as demais etapas de padronização, recodificação, conversão de tipos, harmonização territorial, validação e análise de qualidade dos dados.

2.5.8 2.5.8.      Exemplo de uso

dados_RHC_combinados <- lerarquivoDBF()

2.5.9 2.5.9.      Comportamento operacional da função lerarquivoDBF()

A função lerarquivoDBF() implementa um fluxo estruturado de leitura e integração de arquivos DBF, incorporando mecanismos explícitos de controle de execução, tratamento de exceções e padronização dinâmica da estrutura dos dados.

Inicialmente, a função verifica a disponibilidade do pacote necessário para leitura de arquivos DBF (foreign). Caso o pacote não esteja instalado, ele é automaticamente instalado e carregado, garantindo a execução autônoma da função sem dependências prévias explícitas.

Na sequência, é realizada a busca por arquivos no diretório de trabalho que atendam ao padrão de nomenclatura ^rhc.*\\.dbf$. Caso nenhum arquivo seja identificado, a função emite uma mensagem de erro informativa ao usuário e interrompe a execução retornando NULL. Esse comportamento evita a propagação de erros para etapas subsequentes do pipeline.

Quando arquivos válidos são encontrados, a função inicia o processamento iterativo utilizando lapply(). Para cada arquivo, são executadas as seguintes operações:

• Emissão de mensagem indicando o arquivo em processamento, permitindo rastreabilidade da execução;

• Leitura do arquivo por meio de foreign::read.dbf();

• Verificação de integridade básica: arquivos sem registros (número de linhas igual a zero) são ignorados e substituídos por NULL, acompanhados de mensagem de alerta;

• Extração do ano a partir do nome do arquivo utilizando expressão regular, com lógica de conversão para século (anos <50 atribuídos ao século XXI e ≥50 ao século XX);

• Criação da variável Ano_do_Banco, incorporada diretamente ao dataframe;

• Registro de mensagens de progresso ao longo da execução.

O uso de tryCatch() garante que erros individuais na leitura de arquivos não interrompam o processamento global. Em caso de falha na leitura de um arquivo específico, a função captura o erro, registra a mensagem correspondente e prossegue com os demais arquivos disponíveis.

Após o processamento individual, a função realiza uma etapa de limpeza da lista de resultados, removendo todos os objetos NULL, o que implica a exclusão de arquivos vazios ou com erro de leitura do processo de integração final.

Em seguida, é conduzida a harmonização estrutural dos dataframes. A função identifica o conjunto completo de colunas presentes em todos os arquivos e, para cada dataframe, adiciona automaticamente as colunas ausentes com valores NA. Essa estratégia permite compatibilizar estruturas heterogêneas entre diferentes anos do RHC, viabilizando a integração posterior.

Antes da combinação final, é realizada uma verificação de consistência estrutural baseada no número de colunas. Caso, após a harmonização, ainda existam divergências no número de variáveis entre os dataframes, a função interrompe a execução com erro explícito, evitando a geração de um banco inconsistente.

A integração final dos dados é realizada por meio de do.call(rbind, …), resultando em um único dataframe consolidado. Uma mensagem final é emitida indicando sucesso na operação e destacando a criação da variável Ano_do_Banco.

Caso todos os arquivos tenham sido descartados (por erro ou ausência de registros), a função emite mensagem informando a inexistência de dataframes válidos e retorna NULL.

2.6 2.6. PADRONIZAÇÃO DOS NOMES DAS VARIÁVEIS

2.6.1 2.6.1.      Função principal

renomear_colunas()

2.6.2 2.6.2.      Finalidade da função

A função renomear_colunas() realiza a padronização dos nomes das variáveis presentes no dataframe, substituindo as nomenclaturas originais dos arquivos DBF por nomes mais descritivos, consistentes e adequados ao uso analítico. Essa etapa tem como objetivo melhorar a legibilidade do banco e facilitar sua utilização em análises epidemiológicas e produção científica.

2.6.3 2.6.3.      Problema que a função resolve

Os arquivos do Registro Hospitalar de Câncer utilizam nomes de variáveis abreviados, frequentemente pouco intuitivos e, em alguns casos, inconsistentes ao longo do tempo. Essa característica dificulta a interpretação dos dados, aumenta a probabilidade de erros na análise e compromete a reprodutibilidade. A função resolve esse problema ao aplicar uma padronização sistemática baseada em um mapeamento predefinido.

2.6.4 2.6.4.      Como a função opera

A função recebe um dataframe e utiliza uma lista de mapeamento que associa os nomes originais das variáveis a novos nomes descritivos. Para cada variável listada, a função verifica sua existência no dataframe e, quando presente, realiza a substituição do nome. Variáveis não encontradas são ignoradas, sem interromper o fluxo de execução.

2.6.5 2.6.5.      Entrada esperada

Um dataframe previamente estruturado, contendo as variáveis originais provenientes dos arquivos DBF do RHC.

2.6.6 2.6.6.      Saída produzida

Um dataframe com os nomes das variáveis padronizados, mantendo inalterado o conteúdo dos dados.

2.6.7 2.6.7.      Importância no fluxo do RHCgen

Essa etapa é essencial para garantir consistência semântica ao banco de dados, facilitando as etapas subsequentes de tipagem, recodificação, validação e análise. A padronização dos nomes reduz ambiguidades e melhora a comunicação dos resultados.

2.6.8 2.6.8.      Exemplo de uso

data <- renomear_colunas(data)

2.6.9 2.6.9.      Comportamento operacional da função renomear_colunas()

A função renomear_colunas() executa um processo iterativo de verificação e substituição dos nomes das variáveis, com controle explícito de execução e registro detalhado de mensagens.

Inicialmente, a função emite uma mensagem indicando o início do processo de renomeação. Em seguida, define internamente uma lista de mapeamento (new_names), que estabelece a correspondência entre os nomes originais das variáveis e suas versões padronizadas. O processamento é realizado por meio de um loop sobre todos os elementos da lista de mapeamento. Para cada variável:

• É emitida uma mensagem informando que a existência da coluna está sendo verificada no dataframe;

• Caso a coluna esteja presente, a função emite uma mensagem indicando a renomeação e realiza a substituição direta do nome da variável no objeto, utilizando indexação sobre o vetor de nomes (names(data));

• Um contador interno (contador_renomeadas) é incrementado a cada renomeação bem-sucedida;

• Caso a coluna não esteja presente, a função emite uma mensagem informando que a variável será ignorada, sem interromper a execução.

Esse comportamento garante robustez frente a variações estruturais do banco, permitindo que a função opere corretamente mesmo quando determinadas variáveis não estão presentes em todos os arquivos ou períodos.

Ao final do processamento, a função emite uma mensagem consolidada destacando o número total de colunas renomeadas com sucesso. Essa mensagem é formatada com destaque visual, facilitando a identificação do resultado da operação.

A função não implementa mecanismos de interrupção para colunas ausentes, nem validação de duplicidade de nomes após a renomeação. Dessa forma, assume-se que o mapeamento fornecido é consistente e que não gera conflitos de nomenclatura.

O objeto resultante é então retornado com os nomes atualizados, mantendo a estrutura e os dados originais intactos.

Quadro 1. Mapeamento dos nomes originais das variáveis do RHC para a nomenclatura padronizada adotada pelo RHCgen (47 variáveis)

	Nome original no DBF		Nome padronizado no RHCgen
	TPCASO		Tipo_de_Caso
	SEXO		Sexo
	IDADE		Idade
	LOCALNAS		Local_Nascimento
	RACACOR		Raca_Cor
	INSTRUC		Escolaridade
	CLIATEN		Clinica_Atendimento
	CLITRAT		Clinica_Tratamento
	HISTFAMC		Historico_Familiar_Cancer
	ALCOOLIS		Consumo_Alcool
	TABAGISM		Tabagismo
	ESTADRES		Estado_Residencia
	PROCEDEN		Codigo_Municipio_Residencia
	ANOPRIDI		Ano_Primeiro_Diagnostico
	ORIENC		Origem_do_Encaminhamento
	EXDIAG		Exames_Relevantes_para_Diagnostico
	ESTCONJ		Estado_conjugal
	ANTRI		Ano_Triagem
	DTPRICON		Ano_Primeira_Consulta
	DIAGANT		Diagnosticos_e_Tratamentos_Anterior
	BASMAIMP		Base_Mais_Importante_Diagnostico
	LOCTUDET		Localizacao_Primaria_3D
	LOCTUPRI		Localizacao_Primaria_4D
	TIPOHIST		Tipo_Histologico
	LATERALI		Lateralidade
	LOCTUPRO		Local_Provavel_Tumor
	MAISUMTU		Mais_de_Um_Tumor
	TNM		Classificacao_TNM
	ESTADIAM		Estadiamento_Clinico
	OUTROESTA		Outro_Estadiamento_Clinico
	PTNM		TNM_Patologico
	RZNTR		Razao_Nao_Tratamento
	DTINITRT		Ano_Inicio_Tratamento
	PRITRATH		Primeiro_Tratamento_Hospital
	ESTDFIMT		Estado_Doenca_Final_Tratamento
	DTTRIAGE		Data_Triagem
	DATAPRICON		Data_Primeira_Consulta
	BASDIAGSP		Base_Mais_Importante_Diagnostico_Sem_Patologicas
	CNES		CNES_Hospital
	UFUH		UF_Unidade_Hospital
	MUUH		Municipio_Unidade_Hospital
	OCUPACAO		Ocupacao_Paciente
	DTDIAGNO		Data_Diagnostico
	DATAINITRT		Data_Inicio_Primeiro_Tratamento
	DATAOBITO		Data_Obito
	VALOR_TOT		Valor_Total
	ESTADIAG		Estadiamento_Clinico_TNM_grupo_1985_1999

2.7 2.7. CONVERSÃO E TIPAGEM DAS VARIÁVEIS

2.7.1 2.7.1.      Função principal

modificar_tipo_variavel()

2.7.2 2.7.2.      Finalidade da função

A função modificar_tipo_variavel() realiza a padronização dos tipos das variáveis de um dataframe, convertendo sistematicamente os campos para formatos apropriados ao processamento analítico. De forma geral, as variáveis são convertidas para o tipo character, com exceção da variável Idade, que é convertida para numérico, e das variáveis de data, que são convertidas para o tipo Date.

2.7.3 2.7.3.      Problema que a função resolve

Arquivos oriundos do formato DBF frequentemente apresentam inconsistências na tipagem das variáveis após a importação para o R, incluindo leitura inadequada de datas, variáveis numéricas tratadas como fatores ou caracteres e presença de formatações heterogêneas. Esses problemas podem gerar erros analíticos silenciosos, dificultar operações estatísticas e comprometer a integridade das análises. A função padroniza os tipos das variáveis, reduzindo essas inconsistências e garantindo maior confiabilidade no uso dos dados.

2.7.4 2.7.4.      Como a função opera

A função percorre todas as variáveis do dataframe e converte seus valores para o tipo character, com exceção da variável Idade. Em seguida, converte explicitamente a variável Idade para o tipo numérico. Posteriormente, identifica um conjunto predefinido de variáveis de data e realiza sua conversão para o formato Date, utilizando um padrão específico de formatação.

2.7.5 2.7.5.      Entrada esperada

Um dataframe contendo variáveis previamente padronizadas em termos de nomenclatura, conforme etapa anterior do pipeline.

2.7.6 2.7.6.      Saída produzida

Um dataframe com os tipos das variáveis ajustados, contendo variáveis categóricas em formato character, a variável Idade em formato numérico e variáveis de data convertidas para o tipo Date.

2.7.7 2.7.7.      Importância no fluxo do RHCgen

Essa etapa é essencial para garantir consistência na manipulação dos dados e evitar erros decorrentes de tipagem inadequada. A correta definição dos tipos das variáveis é condição necessária para análises estatísticas, modelagem, cálculos de indicadores e manipulação temporal dos dados.

2.7.8 2.7.8.      Exemplo de uso

data <- modificar_tipo_variavel(data)

2.7.9 2.7.9.      Comportamento operacional da função modificar_tipo_variavel()

A função modificar_tipo_variavel() implementa um processo sequencial de conversão de tipos, com controle explícito de execução e registro contínuo de mensagens informativas.

Inicialmente, a função emite uma mensagem indicando o início da etapa de conversão dos tipos de variáveis. Em seguida, define internamente um vetor contendo os nomes das variáveis que devem ser tratadas como datas. O processamento é iniciado com um loop que percorre todas as variáveis do dataframe. Para cada variável:

• É verificado se o nome da coluna é diferente de Idade;

• Caso positivo, a variável é convertida para o tipo character utilizando as.character();

• Uma mensagem é emitida indicando a variável que está sendo convertida.

Esse procedimento garante uma padronização inicial dos tipos, eliminando inconsistências decorrentes da importação de dados em formatos heterogêneos. Na sequência, a função verifica explicitamente a existência da variável Idade. Caso presente:

• A variável é convertida para character e, posteriormente, para numeric, utilizando as.numeric(as.character());

• Uma mensagem é emitida indicando a conversão.

Essa abordagem em duas etapas evita problemas comuns associados à conversão direta de fatores para valores numéricos. Posteriormente, a função realiza a conversão das variáveis de data. Para cada variável listada no vetor de colunas de data:

• É verificada sua existência no dataframe;

• Caso presente, a função emite uma mensagem indicando a conversão;

• A variável é convertida para o tipo Date utilizando a função as.Date() com o formato explícito %d/%m/%Y;

• Após a conversão, é realizada uma verificação de integridade: caso todos os valores resultem em NA, a função emite uma mensagem de alerta destacando possível incompatibilidade no formato da data;

• Caso a conversão seja bem-sucedida (ou parcialmente bem-sucedida), um contador interno de variáveis convertidas é incrementado.

Esse mecanismo permite identificar problemas de formatação nas datas sem interromper o fluxo de execução. Ao final do processamento, a função emite uma mensagem indicando a conclusão bem-sucedida da conversão dos tipos de variáveis, utilizando formatação destacada para facilitar a identificação no console.

A função não interrompe a execução em caso de falhas na conversão de variáveis específicas, operando de forma tolerante a erros parciais. Essa característica é particularmente relevante em bases com inconsistências de preenchimento, permitindo que o processamento global seja concluído mesmo na presença de registros problemáticos. O dataframe resultante é retornado com os tipos de variáveis ajustados, mantendo a estrutura original e possibilitando o uso adequado nas etapas subsequentes do pipeline.

2.8 2.8. RECODIFICAÇÃO DAS VARIÁVEIS

2.8.1 2.8.1.      Função principal

recodificar_variaveis()

2.8.2 2.8.2.      Finalidade da função

A função recodificar_variaveis() realiza a transformação de variáveis categóricas originalmente codificadas em formato numérico ou textual para categorias interpretáveis, com base no dicionário de variáveis do Registro Hospitalar de Câncer. As variáveis são recodificadas e convertidas para o tipo fator (factor), com níveis definidos, garantindo consistência semântica e padronização para análise.

2.8.3 2.8.3.      Problema que a função resolve

Os dados do RHC apresentam variáveis categóricas codificadas por números (por exemplo, “1”, “2”, “9”), que não possuem interpretação direta sem consulta ao dicionário. Essa codificação dificulta a análise, aumenta o risco de erro na interpretação e compromete a comunicação dos resultados. A função resolve esse problema ao traduzir sistematicamente esses códigos em categorias descritivas e padronizadas.

2.8.4 2.8.4.      Como a função opera

A função identifica um conjunto predefinido de variáveis categóricas esperadas e verifica sua presença no dataframe. Para cada variável existente, aplica regras de recodificação específicas, substituindo os códigos originais por descrições textuais e convertendo o resultado em fator com níveis previamente definidos. Variáveis ausentes são identificadas e reportadas, sem interromper o fluxo de execução.

2.8.5 2.8.5.      Entrada esperada

Um dataframe com variáveis previamente padronizadas em nomenclatura e tipagem, conforme etapas anteriores do pipeline.

2.8.6 2.8.6.      Saída produzida

Um dataframe com variáveis categóricas recodificadas e convertidas para fatores, com níveis definidos e padronizados.

2.8.7 2.8.7.      Importância no fluxo do RHCgen

Essa etapa é fundamental para tornar os dados interpretáveis e prontos para análise estatística, construção de tabelas, modelagem e comunicação científica. A recodificação padroniza categorias e garante consistência na análise entre diferentes bases e períodos.

2.8.8 2.8.8.      Exemplo de uso

data <- recodificar_variaveis(data)

2.8.9 2.8.9.      Comportamento operacional da função recodificar_variaveis()

A função recodificar_variaveis() implementa um processo estruturado de recodificação condicional, com controle explícito de execução, rastreamento de variáveis processadas e tolerância a variações na estrutura do banco.

Inicialmente, a função emite uma mensagem indicando o início da etapa de recodificação. Em seguida, define internamente um vetor contendo as variáveis categóricas esperadas para o processo.

A função realiza então a separação entre variáveis presentes e ausentes no dataframe:

• Variáveis presentes são elegíveis para recodificação;

• Variáveis ausentes são identificadas e listadas em mensagem informativa, sem interrupção da execução.

O processo de recodificação ocorre de forma sequencial, variável a variável, utilizando estruturas condicionais (if) combinadas com funções ifelse(). Para cada variável:

• É verificada sua existência no dataframe;

• Caso presente, a função emite uma mensagem indicando o início da recodificação;

• Os códigos originais são substituídos por categorias descritivas, conforme regras específicas de cada variável;

• A variável é convertida para o tipo fator (factor), com definição explícita da ordem e dos níveis possíveis;

• Um contador interno de recodificações (contador_recodificacoes) é incrementado;

• O nome da variável recodificada é armazenado em um vetor de rastreamento (variaveis_recodificadas).

As regras de recodificação são específicas para cada variável e seguem o padrão do dicionário do RHC, incluindo categorias como:

• “Sem informação”

• “Não se aplica”

• Categorias clínicas, sociodemográficas e assistenciais

A função não realiza validação da consistência dos códigos de entrada, assumindo que os valores seguem o padrão esperado do sistema RHC. Valores não previstos nas regras de recodificação são mantidos sem alteração.

Ao final do processamento:

• É emitida uma mensagem consolidada listando as variáveis recodificadas;

• Caso existam variáveis ausentes, estas são novamente reportadas;

• Uma mensagem final indica o total de variáveis recodificadas com sucesso, com destaque visual.

A função opera de forma tolerante a erros parciais, permitindo que o processo seja concluído mesmo na ausência de algumas variáveis ou na presença de valores não padronizados.

O dataframe resultante é retornado com as variáveis categóricas transformadas em fatores com níveis definidos, mantendo a estrutura geral dos dados e permitindo sua utilização direta em análises estatísticas e epidemiológicas.

Quadro 2. Variáveis categóricas recodificadas pelo RHCgen, segundo domínio temático e categorias padronizadas

	Domínio		Variável		Categorias padronizadas
	Identificação do caso		Tipo_de_Caso		Analítico; Não Analítico; Outro
	Sociodemográficas		Sexo		Masculino; Feminino; Outro
			Raca_Cor		Branca; Preta; Amarela; Parda; Indígena; Sem informação
			Escolaridade		Nenhuma; Fundamental incompleto; Fundamental completo; Nível médio; Nível superior incompleto; Nível superior completo; Sem informação
			Estado_conjugal		Solteiro; Casado; Viúvo; Separado judicialmente; União consensual; Sem informação
	Histórico e hábitos		Historico_Familiar_Cancer		Sim; Não; Sem informação
			Consumo_Alcool		Nunca; Ex-consumidor; Sim; Não avaliado; Não se aplica; Sem informação
			Tabagismo		Nunca; Ex-consumidor; Sim; Não avaliado; Não se aplica; Sem informação
	Acesso e diagnóstico		Origem_do_Encaminhamento		SUS; Não SUS; Veio por conta própria; Não se aplica; Sem informação
			Exames_Relevantes_para_Diagnostico		Exame clínico e patologia clínica; Exames por imagem; Endoscopia e cirurgia exploradora; Anatomia patológica; Marcadores tumorais; Não se aplica; Sem informação
			Base_Mais_Importante_Diagnostico		Clínica; Pesquisa clínica; Exame por imagem; Marcadores tumorais; Citologia; Histologia da metástase; Histologia do tumor primário; Sem informação
			Base_Mais_Importante_Diagnostico_Sem_Patologicas		Exame clínico; Recursos auxiliares não microscópicos; Confirmação microscópica; Sem informação
	Características clínicas		Lateralidade		Direita; Esquerda; Bilateral; Não se aplica; Sem informação
			Mais_de_Um_Tumor		Sim; Não; Duvidoso
			Estadiamento_Clinico_TNM_grupo_1985_1999		Estádio I; Estádio II; Estádio III; Estádio IV; Não se aplica; Sem informação
	Histórico assistencial		Diagnosticos_e_Tratamentos_Anterior		Sem diagnóstico e sem tratamento; Com diagnóstico e sem tratamento; Com diagnóstico e com tratamento; Outros; Sem informação
	Tratamento		Primeiro_Tratamento_Hospital		Nenhum; Cirurgia; Radioterapia; Quimioterapia; Hormonioterapia; Transplante de medula óssea; Imunoterapia; Outras; Sem informação
			Razao_Nao_Tratamento		Recusa do tratamento; Tratamento realizado fora; Doença avançada ou comorbidades; Abandono; Complicações; Óbito; Outras razões; Não se aplica; Sem informação
	Desfecho		Estado_Doenca_Final_Tratamento		Sem evidência da doença; Remissão parcial; Doença estável; Doença em progressão; Suporte terapêutico; Óbito; Não se aplica; Sem informação

Ver dicionário de variáveis no IntegradorRHC:

 https://irhc.inca.gov.br/RHCNet/documentosTabWin.action?doc=dicionario.dados

2.9 2.9. HARMONIZAÇÃO TERRITORIAL DAS VARIÁVEIS GEOGRÁFICAS

2.9.1 2.9.1.      Funções principais

renomear_siglas_estados()

renomear_codigo_municipio_residencia()

renomear_codigo_municipio_hospital()

2.9.2 2.9.2.      Finalidade das funções

As funções de harmonização territorial realizam a conversão de códigos geográficos utilizados no Registro Hospitalar de Câncer em informações textuais interpretáveis, adicionando novas variáveis ao dataframe. Especificamente, convertem siglas das Unidades da Federação e códigos de municípios em seus respectivos nomes completos, tanto para o local de residência do paciente quanto para a unidade hospitalar de atendimento.

2.9.3 2.9.3.      Problema que as funções resolvem

Os dados do RHC utilizam codificações abreviadas para representação geográfica, como siglas de estados e códigos numéricos de municípios. Esses formatos dificultam a interpretação direta, limitam a análise descritiva e comprometem a visualização espacial dos dados. Além disso, exigem consultas externas a tabelas de correspondência. As funções resolvem esse problema ao incorporar, diretamente no banco, variáveis com nomes completos e padronizados.

2.9.4 2.9.4.      Como as funções operam

As funções utilizam estruturas de mapeamento predefinidas para converter valores codificados em nomes completos. A conversão é realizada por meio de indexação vetorizada, criando novas colunas no dataframe sem alterar as variáveis originais. Cada função atua sobre uma dimensão territorial específica: unidade da federação ou município.

2.9.5 2.9.5.      Entrada esperada

Um dataframe contendo, conforme o caso, as seguintes variáveis:

• Estado_Residencia

• UF_Unidade_Hospital

• Codigo_Municipio_Residencia

• Municipio_Unidade_Hospital

2.9.6 2.9.6.      Saída produzida

Um dataframe com novas variáveis territoriais adicionadas:

• Nome_Estado_Residencia

• Nome_Estado_Hospital

• Nome_Municipio_Residencia

• Nome_Municipio_Hospital

2.9.7 2.9.7.      Importância no fluxo do RHCgen

Essa etapa é fundamental para análises espaciais, estudos de acessibilidade geográfica, avaliação de fluxos de deslocamento de pacientes e construção de indicadores territoriais. A presença de nomes completos facilita a interpretação dos dados, a geração de mapas e a comunicação dos resultados em contextos científicos e institucionais.

2.9.8 2.9.8.      Exemplo de uso

data <- renomear_siglas_estados(data)

data <- renomear_codigo_municipio_residencia(data)

data <- renomear_codigo_municipio_hospital(data)

2.9.9 2.9.9.      Comportamento operacional das funções de harmonização territorial

As funções de harmonização territorial implementam processos vetorizados de mapeamento categórico e geográfico, com controle explícito de execução, verificação de pré-condições e tratamento de inconsistências estruturais.

2.9.10 2.9.10.   Conversão das siglas das Unidades da Federação

A função renomear_siglas_estados() inicia emitindo mensagem indicativa do início do processamento. Em seguida, define internamente um vetor nomeado contendo o mapeamento entre as siglas das Unidades da Federação e seus nomes completos.

A função verifica a existência das variáveis Estado_Residencia e UF_Unidade_Hospital no dataframe:

• Para cada variável presente, é criada uma nova coluna com o nome completo do estado por meio de indexação direta no vetor de mapeamento;

• Mensagens informativas são emitidas para cada operação realizada;

• Um contador interno registra o número de colunas adicionadas.

Caso nenhuma das variáveis esteja presente, a função interrompe a execução com erro explícito (stop()), evitando a continuidade do processamento em condições inválidas.

Valores não reconhecidos no mapeamento resultam em NA, sem interrupção do fluxo.

2.9.11 2.9.11.   Conversão dos códigos de municípios

As funções renomear_codigo_municipio_residencia() e renomear_codigo_municipio_hospital() seguem lógica operacional semelhante, aplicada a diferentes variáveis de entrada.

Inicialmente, cada função emite mensagem indicando o início do processamento. Em seguida, define internamente uma estrutura de dados contendo o mapeamento entre códigos de municípios e seus respectivos nomes completos. Antes da conversão, cada função verifica a existência da variável necessária no dataframe:

• Caso a variável não esteja presente, a função interrompe a execução com erro explícito (stop()), indicando ausência da condição mínima para operação;

• Caso presente, a função procede com a criação de um vetor nomeado para mapeamento.

A conversão é realizada por indexação vetorizada, transformando os códigos em nomes completos e armazenando o resultado em uma nova coluna:

• Nome_Municipio_Residencia, para a variável de residência;

• Nome_Municipio_Hospital, para a variável da unidade hospitalar.

Mensagens informativas são emitidas ao longo do processo, incluindo confirmação da criação das novas colunas.

2.9.12 2.9.12.   Características operacionais gerais

As funções de harmonização territorial compartilham as seguintes características:

• Operam de forma vetorizada, garantindo eficiência em grandes volumes de dados;

• Preservam as variáveis originais, adicionando novas colunas ao dataframe;

• Implementam verificação explícita da existência das variáveis de entrada;

• Utilizam interrupção controlada (stop()) quando condições mínimas não são atendidas;

• Não validam a consistência dos códigos de entrada, assumindo conformidade com o padrão do RHC;

• Mantêm valores não mapeados como NA, assegurando integridade estrutural do banco.

2.10 2.10.   PADRONIZAÇÃO DE CÓDIGOS DIAGNÓSTICOS E CLÍNICOS

2.10.1 2.10.1.   Funções principais

renomear_CID_3digitos()

renomear_CID_4digitos()

renomear_tipo_histologico()

renomear_estadiamento_clinico()

2.10.2 2.10.2.   Finalidade das funções

As funções de padronização de códigos diagnósticos e clínicos realizam a conversão de códigos estruturados do RHC, como CID-O, tipo histológico e estadiamento clínico, em descrições completas e interpretáveis. Essas funções adicionam novas variáveis ao dataframe contendo a descrição textual das informações clínicas, mantendo os códigos originais.

2.10.3 2.10.3.   Problema que as funções resolvem

Os dados do RHC utilizam codificações padronizadas que, embora essenciais para interoperabilidade, apresentam baixa interpretabilidade direta. Códigos de localização tumoral, histologia e estadiamento clínico exigem consulta a dicionários externos e frequentemente apresentam heterogeneidade de preenchimento. Essa característica dificulta análises descritivas, validação clínica e comunicação dos resultados. As funções resolvem esse problema ao incorporar descrições padronizadas diretamente no banco.

2.10.4 2.10.4.   Como as funções operam

As funções utilizam estruturas internas de mapeamento, nas quais códigos diagnósticos e clínicos são associados a descrições textuais completas ou categorias mais agregadas. A conversão é realizada por indexação vetorizada, criando novas colunas no dataframe. Cada função atua sobre um tipo específico de codificação clínica.

2.10.5 2.10.5.   Entrada esperada

Um dataframe contendo, conforme o caso:

• Localizacao_Primaria_3D

• Localizacao_Primaria_4D (quando aplicável)

• Tipo_Histologico

• Estadiamento_Clinico

2.10.6 2.10.6.   Saída produzida

Um dataframe com novas variáveis clínicas adicionadas:

• CID3d

• CID4d (quando aplicável)

• Tipo_Histologico_Completo

• Nome_Estadiamento_Clinico

2.10.7 2.10.7.   Importância no fluxo do RHCgen

Essa etapa é essencial para garantir interpretabilidade clínica e comparabilidade analítica dos dados. Permite a estratificação por localização tumoral, tipo histológico e estágio da doença, sendo fundamental para estudos epidemiológicos, análise de sobrevida, avaliação de qualidade da assistência e modelagem estatística.

2.10.8 2.10.8.   Exemplo de uso

data <- renomear_CID_3digitos(data)

data <- renomear_tipo_histologico(data)

data <- renomear_estadiamento_clinico(data)

2.10.9 2.10.9.   Comportamento operacional das funções de padronização clínica

As funções de padronização clínica implementam processos vetorizados de mapeamento semântico, com verificação de pré-condições, controle de execução e tratamento de inconsistências nos códigos de entrada.

2.10.10 2.10.10.   Conversão dos códigos CID-O (3 dígitos)

A função renomear_CID_3digitos() inicia emitindo mensagem indicativa do início do processamento. Em seguida, define internamente uma estrutura de mapeamento entre códigos CID-O e suas descrições completas.

Antes da conversão, verifica a existência da variável Localizacao_Primaria_3D:

• Caso ausente, interrompe a execução com erro explícito (stop());

• Caso presente, realiza o mapeamento por meio de vetor nomeado.

A nova variável CID3d é criada contendo descrições completas das localizações tumorais. Após essa etapa, a função executa uma rotina adicional de classificação (classificacao_CID_0()), integrando a informação em uma camada analítica ampliada .

2.10.11 2.10.11.   Conversão dos códigos de tipo histológico

A função renomear_tipo_histologico() realiza a conversão dos códigos presentes na variável Tipo_Histologico em descrições completas.

A função:

• Verifica a existência da variável no dataframe;

• Interrompe a execução em caso de ausência (stop());

• Realiza mapeamento vetorizado utilizando vetor nomeado;

• Cria a variável Tipo_Histologico_Completo.

Essa etapa amplia significativamente a interpretabilidade dos dados clínicos .

2.10.12 2.10.12.   Conversão do estadiamento clínico

A função renomear_estadiamento_clinico() implementa um processo de recodificação do estadiamento clínico para categorias mais gerais e comparáveis.

Inicialmente, a função emite mensagem indicando o início do processamento e define internamente uma estrutura de mapeamento entre diferentes formatos de codificação do estadiamento (por exemplo: “1”, “I”, “1A”, “01”) e categorias padronizadas (“Estádio I”, “Estádio II”, etc.).

A função verifica a existência da variável Estadiamento_Clinico:

• Caso ausente, interrompe a execução com erro explícito (stop());

• Caso presente, realiza o mapeamento vetorizado.

A nova variável Nome_Estadiamento_Clinico é criada, contendo a classificação agregada do estágio da doença.

Esse procedimento resolve inconsistências decorrentes da coexistência de múltiplos formatos de registro do estadiamento no RHC, promovendo padronização e comparabilidade entre registros.

Valores não reconhecidos no mapeamento são mantidos como NA, sem interrupção do fluxo.

2.10.13 2.10.13.   Características operacionais gerais

As funções deste bloco apresentam comportamento consistente:

• Operam por mapeamento vetorizado, garantindo eficiência em grandes bases;

• Preservam as variáveis originais, adicionando novas colunas ao dataframe;

• Implementam verificação explícita das variáveis de entrada;

• Utilizam interrupção controlada (stop()) quando pré-condições não são atendidas;

• Mantêm valores não mapeados como NA;

• Incorporam estratégias de padronização para lidar com heterogeneidade estrutural dos dados.

2.11 2.11.   CLASSIFICAÇÃO DAS NEOPLASIAS MALIGNAS SEGUNDO AGRUPAMENTOS CID-O

2.11.1 2.11.1.   Função principal

classificacao_CID_0()

2.11.2 2.11.2.   Finalidade da função

A função classificacao_CID_0() classifica as neoplasias malignas em grandes grupos anatômicos, a partir dos códigos registrados na variável Localizacao_Primaria_3D. A função cria a variável Classificacao_CID_O, que agrupa os códigos CID-O em categorias mais amplas, como neoplasias malignas dos órgãos digestivos, órgãos respiratórios, mama, órgãos genitais masculinos, órgãos urinários e tecidos linfático/hematopoético.

Problema que a função resolve

A variável Localizacao_Primaria_3D contém códigos topográficos específicos, úteis para identificação detalhada da localização tumoral, mas pouco práticos para análises agregadas. A função resolve esse problema ao criar uma classificação sintética por grupos anatômicos, facilitando análises descritivas, estratificações epidemiológicas e comparações entre grandes grupos de câncer.

Como a função opera

A função utiliza um vetor interno de mapeamento que associa cada código CID-O de três dígitos a uma categoria anatômica agregada. Em seguida, percorre os valores da variável Localizacao_Primaria_3D e atribui a classificação correspondente. Códigos ausentes permanecem como NA, códigos reconhecidos recebem a categoria definida no mapeamento e códigos não previstos são classificados como “Outros”.

2.11.3 2.11.3.   Entrada esperada

Um dataframe contendo a variável:

• Localizacao_Primaria_3D

2.11.4 2.11.4.   Saída produzida

Um dataframe com a nova variável:

• Classificacao_CID_O

2.11.5 2.11.5.   Importância no fluxo do RHCgen

Essa função complementa a padronização dos códigos diagnósticos, pois transforma a topografia tumoral detalhada em uma classificação agregada e analiticamente mais manejável. Ela é especialmente útil para estudos que comparam grupos de câncer, análises de qualidade dos dados, descrição epidemiológica geral e construção de indicadores por grandes categorias anatômicas.

2.11.6 2.11.6.   Exemplo de uso

data <- classificacao_CID_0(data)

2.11.7 2.11.7.   Comportamento operacional da função classificacao_CID_0()

A função inicia verificando se a variável Localizacao_Primaria_3D está presente no dataframe. Caso a coluna esteja ausente, a função emite uma mensagem de erro e retorna NULL, interrompendo apenas essa etapa de classificação.

Quando a variável está disponível, a função emite mensagem informando o início da classificação das neoplasias malignas conforme o CID-O. Em seguida, define internamente um vetor nomeado (cid_classificacao), no qual cada código CID-O de três dígitos é associado a uma categoria anatômica agregada.

A classificação é realizada com sapply(), percorrendo cada valor da variável Localizacao_Primaria_3D. Para cada registro, a função aplica três decisões sequenciais:

• se o código é NA, o resultado permanece NA;

• se o código está presente no vetor de mapeamento, recebe a categoria correspondente;

• se o código não está previsto no mapeamento, recebe a categoria “Outros”.

Ao final, a função cria a nova coluna Classificacao_CID_O no dataframe e emite mensagem indicando que a classificação foi concluída com sucesso.

A função preserva a variável original Localizacao_Primaria_3D, não remove registros e não altera códigos existentes. Seu papel é adicionar uma camada derivada de classificação, mantendo a rastreabilidade entre o código original e o agrupamento analítico produzido.

2.11.8 2.11.8.   Características operacionais relevantes

• Verifica a existência da variável necessária antes da execução;

• Utiliza mapeamento interno por vetor nomeado;

• Cria uma variável derivada sem alterar a variável original;

• Preserva valores ausentes como NA;

• Classifica códigos não previstos como “Outros”;

• Retorna o dataframe acrescido da classificação agregada.

2.12 2.12.   PADRONIZAÇÃO DE CÓDIGOS ASSISTENCIAIS E HOSPITALARES

2.12.1 2.12.1.   Funções principais

renomear_clinica()

renomear_CNES()

2.12.2 2.12.2.   Finalidade das funções

As funções de padronização assistencial e hospitalar realizam a conversão de códigos utilizados para identificar clínicas de atendimento e estabelecimentos de saúde em descrições completas e interpretáveis. Essas funções adicionam novas variáveis ao dataframe, permitindo identificar de forma clara o perfil assistencial e as unidades responsáveis pelo atendimento.

2.12.3 2.12.3.   Problema que as funções resolvem

Os dados do RHC utilizam códigos numéricos para representar clínicas médicas e identificadores CNES para os estabelecimentos de saúde. Esses códigos não são autoexplicativos e exigem consulta a tabelas externas para interpretação. Essa limitação dificulta análises sobre organização da assistência, perfil de atendimento e avaliação de serviços de saúde. As funções resolvem esse problema ao incorporar diretamente no banco as descrições completas dessas estruturas.

2.12.4 2.12.4.   Como as funções operam

As funções utilizam estruturas internas de mapeamento que associam códigos assistenciais a seus respectivos nomes completos. A conversão é realizada por indexação vetorizada, criando novas variáveis no dataframe, sem alterar os códigos originais.

2.12.5 2.12.5.   Entrada esperada

Um dataframe contendo:

• Clinica_Atendimento

• Clinica_Tratamento

• CNES_Hospital

2.12.6 2.12.6.   Saída produzida

Um dataframe com novas variáveis adicionadas:

• Nome_Clinica_Atendimento

• Nome_Clinica_Tratamento

• Estabelecimento_Hospitalar

2.12.7 2.12.7.   Importância no fluxo do RHCgen

Essa etapa permite incorporar a dimensão organizacional da assistência ao banco de dados, viabilizando análises sobre perfil de atendimento, especialidades envolvidas no cuidado oncológico e identificação dos estabelecimentos responsáveis pelo tratamento. É especialmente relevante para estudos de acesso, fluxo de pacientes e avaliação da rede assistencial.

2.12.8 2.12.8.   Exemplo de uso

data <- renomear_clinica(data)

data <- renomear_CNES(data)

2.12.9 2.12.9.   Comportamento operacional das funções de padronização assistencial

Conversão das clínicas de atendimento e tratamento

A função renomear_clinica() inicia com a emissão de mensagem indicando o início do processamento. Em seguida, define internamente uma estrutura de mapeamento entre códigos numéricos e nomes completos das clínicas.

Antes da conversão, a função verifica a existência das variáveis Clinica_Atendimento e Clinica_Tratamento:

• Caso qualquer uma das variáveis esteja ausente, a função interrompe a execução com erro explícito (stop()), garantindo controle estrutural;

• Caso ambas estejam presentes, o processamento é iniciado.

A conversão é realizada por meio de vetor nomeado (setNames), aplicado separadamente às duas variáveis:

• Criação da variável Nome_Clinica_Atendimento;

• Criação da variável Nome_Clinica_Tratamento.

Mensagens informativas são emitidas durante o processo, incluindo confirmação da criação das novas colunas. Valores não reconhecidos no mapeamento são atribuídos como NA, sem interrupção da execução.

Ver dicionário de códigos da clínica:

 https://irhc.inca.gov.br/RHCNet/documentosTabWin.action?doc=tabela.clinicas

Conversão dos códigos CNES

A função renomear_CNES() realiza o mapeamento dos códigos CNES para os nomes completos dos estabelecimentos de saúde.

Inicialmente, a função emite mensagem indicando o início do processamento e define internamente uma estrutura de mapeamento contendo códigos CNES e seus respectivos nomes institucionais .

A função verifica a existência da variável CNES_Hospital:

• Caso ausente, a execução é interrompida com erro explícito (stop());

• Caso presente, a função realiza o mapeamento vetorizado.

A nova variável Estabelecimento_Hospitalar é criada, contendo o nome completo do estabelecimento.

Mensagens são emitidas ao longo do processo, incluindo confirmação da criação da nova variável.

Valores não encontrados no mapeamento são mantidos como NA.

2.12.10 2.12.10.   Organização estrutural do banco de dados

2.12.11 2.12.11.   Função principal

ordenando_colunas()

2.12.12 2.12.12.   Finalidade da função

A função ordenando_colunas() organiza as variáveis do dataframe em uma ordem predefinida, alinhada à lógica analítica do RHCgen. Essa ordenação padroniza a estrutura do banco final, facilitando a leitura, interpretação e utilização dos dados.

2.12.13 2.12.13.   Problema que a função resolve

Após as etapas de leitura, padronização, recodificação e criação de novas variáveis, o dataframe resultante apresenta colunas em ordem arbitrária, muitas vezes definida pela sequência de processamento. Essa desorganização dificulta a navegação no banco, a identificação de variáveis e a reprodutibilidade das análises. A função resolve esse problema ao estabelecer uma ordem lógica e consistente entre as variáveis.

2.12.14 2.12.14.   Como a função opera

A função define internamente um vetor com a ordem desejada das colunas. Em seguida, compara esse vetor com as colunas efetivamente presentes no dataframe e reorganiza o banco mantendo apenas as colunas existentes, na ordem especificada.

2.12.15 2.12.15.   Entrada esperada

Um dataframe contendo variáveis já processadas pelas etapas anteriores do RHCgen.

2.12.16 2.12.16.   Saída produzida

Um dataframe com as colunas reorganizadas de acordo com a ordem predefinida, contendo apenas as variáveis presentes no banco.

2.12.17 2.12.17.   Importância no fluxo do RHCgen

Essa etapa padroniza a estrutura final do banco, permitindo maior consistência na análise, documentação e compartilhamento dos dados. A organização das variáveis segue uma lógica que integra dimensões sociodemográficas, clínicas, assistenciais e temporais, facilitando a utilização do banco em estudos epidemiológicos.

2.12.18 2.12.18.   Exemplo de uso

data <- ordenando_colunas(data)

2.12.19 2.12.19.   Comportamento operacional da função ordenando_colunas()

A função ordenando_colunas() implementa um processo de reorganização estrutural com verificação explícita de consistência e controle de execução.

Inicialmente, a função define um vetor contendo a ordem desejada das variáveis, incluindo tanto variáveis originais quanto aquelas criadas ao longo do pipeline.

Em seguida, a função identifica eventuais discrepâncias entre o conjunto esperado e o conjunto efetivamente presente no dataframe:

• As colunas definidas no vetor que não estão presentes no dataframe são identificadas por meio da função setdiff();

• Caso existam colunas ausentes, a função emite mensagens listando essas variáveis, sem interromper a execução;

• Caso todas as colunas estejam presentes, é emitida mensagem informando a conformidade estrutural.

Na sequência, a função identifica as colunas que estão simultaneamente no vetor de ordenação e no dataframe (intersect()), garantindo que apenas variáveis válidas sejam consideradas.

A reorganização do dataframe é realizada por indexação direta das colunas, respeitando a ordem definida e preservando a integridade dos dados (drop = FALSE). No final do processo, a função emite uma mensagem indicando a conclusão bem-sucedida da reorganização.

A função não adiciona colunas ausentes nem interrompe a execução quando variáveis não estão disponíveis, operando de forma tolerante à variação estrutural do banco.

O dataframe resultante é retornado com as colunas organizadas em uma estrutura padronizada, adequada para análise e documentação.

2.12.20 2.12.20.   Observação técnica

Essa etapa representa a consolidação da estrutura do banco de dados, organizando as variáveis em uma sequência lógica que reflete o fluxo analítico do RHCgen. Embora não altere o conteúdo dos dados, sua importância reside na padronização da apresentação e na facilitação do uso do banco em diferentes contextos analíticos.

2.13 2.13.   AVALIAÇÃO DA QUALIDADE DOS DADOS

2.13.1 2.13.1.   Função principal

analise_qualidade_dos_dados()

2.13.2 2.13.2.   Funções acionadas internamente

analise_completude()

tabela_inconsistencias()

2.13.3 2.13.3.   Finalidade da função

A função analise_qualidade_dos_dados() executa uma avaliação automatizada da qualidade do banco processado pelo RHCgen. Essa etapa reúne análises de completude e consistência, permitindo identificar variáveis com maior proporção de dados ausentes, códigos inválidos, idades inconsistentes, inconsistências temporais e incompatibilidades entre sexo e topografia tumoral.

2.13.4 2.13.4.   Problema que a função resolve

Mesmo após a padronização estrutural do banco, os dados podem apresentar problemas de preenchimento, ausência de informação, códigos inexistentes e incoerências lógico-clínicas. A função resolve esse problema ao centralizar, em uma única rotina, verificações que permitem diagnosticar a qualidade da base antes de sua utilização analítica.

2.13.5 2.13.5.   Como a função opera

A função organiza a avaliação em duas grandes etapas. Primeiro, executa a análise de completude por meio da função analise_completude(). Em seguida, executa a verificação de inconsistências por meio da função tabela_inconsistencias(). A segunda etapa é protegida por tryCatch(), permitindo que eventuais erros na verificação de inconsistências sejam capturados e apresentados ao usuário sem comprometer a conclusão geral da rotina.

2.13.6 2.13.6.   Entrada esperada

Um dataframe já processado pelas etapas anteriores do RHCgen.

2.13.7 2.13.7.   Saída produzida

A função não retorna um novo dataframe. Ela exibe mensagens de progresso, executa a análise de completude, gera tabelas e gráficos de dados ausentes e, quando possível, produz um relatório HTML com as verificações de inconsistência.

2.13.8 2.13.8.   Importância no fluxo do RHCgen

Essa etapa transforma o pipeline em uma rotina de auditoria inicial da qualidade dos dados. Ela permite que o usuário avalie a confiabilidade do banco antes de conduzir análises epidemiológicas, modelagens estatísticas ou interpretações substantivas.

2.13.9 2.13.9.   Exemplo de uso

analise_qualidade_dos_dados(data)

2.13.10 2.13.10.   Comportamento operacional da função analise_qualidade_dos_dados()

A função analise_qualidade_dos_dados() implementa uma rotina sequencial de avaliação da qualidade do banco, organizada em duas dimensões analíticas complementares: completude dos dados e consistência das informações.

2.13.11 2.13.11.   Avaliação da completude dos dados

A análise de completude é executada por meio da função analise_completude(), sendo a primeira etapa da rotina.

Inicialmente, a função emite mensagem indicando o início do processo. Em seguida, realiza o cálculo do número total de registros do dataframe e identifica o intervalo temporal da base a partir da variável Ano_do_Banco.

Para cada variável do banco, a função calcula o número de valores ausentes, considerando tanto valores NA quanto registros explicitamente classificados como “Sem informação”. A partir desses valores, é estimada a proporção de dados ausentes e, consequentemente, a completude percentual de cada variável.

Quando a variável Data_Obito está presente, é aplicada uma regra específica: a completude é ajustada considerando apenas registros em que o desfecho foi óbito, permitindo uma avaliação mais adequada dessa variável no contexto clínico.

Os resultados são organizados em uma tabela contendo:

• Nome da variável

• Percentual de completude

• Número absoluto de dados ausentes

• Classificação da completude

A classificação segue o escore proposto por Romero e Cunha, com categorias que variam de “Excelente” a “Muito Ruim”, conforme o percentual de completude.

A tabela é ordenada de acordo com a quantidade de dados ausentes, facilitando a identificação das variáveis com maior comprometimento.

Adicionalmente, a função gera um gráfico de barras horizontal, no qual cada variável é representada pelo número de dados ausentes, acompanhado do percentual de completude e da classificação correspondente. Esse gráfico é renderizado diretamente no ambiente gráfico do R.

Ao final da etapa, a função emite mensagem indicando a conclusão da análise de completude.

2.13.12 2.13.12.   Avaliação da consistência dos dados

A análise de consistência é executada por meio da função tabela_inconsistencias(), sendo organizada como a segunda etapa da rotina.

A execução dessa etapa é envolvida em um bloco tryCatch(), permitindo capturar eventuais erros sem interromper o fluxo geral da função.

A função realiza um conjunto de verificações estruturadas em duas dimensões principais:

2. Validação de códigos e preenchimento formal

   • Identificação de códigos inexistentes ou inválidos

   • Verificação de preenchimento inadequado das variáveis

4. Coerência lógico-clínica entre variáveis

   • Plausibilidade da idade

   • Coerência temporal entre datas clínicas (diagnóstico, consulta, tratamento e óbito)

   • Coerência cronológica entre anos dos eventos

   • Consistência entre sexo e topografia tumoral

Para cada verificação, a função calcula:

• Número absoluto de inconsistências

• Proporção relativa

• Classificação de gravidade (Baixo, Moderado, Alto, Crítico)

Os resultados são organizados em tabelas estruturadas e apresentados em um relatório HTML, que inclui:

• Resumo executivo

• Tabelas analíticas por dimensão

• Interpretação automática dos achados

• Classificação da gravidade das inconsistências

• Notas metodológicas

• Limitações da análise

• Referências utilizadas

Esse relatório é salvo automaticamente e aberto no navegador padrão do sistema ao final da execução.

Caso ocorra erro durante essa etapa, a função captura a falha e exibe uma mensagem destacada no console, informando o problema identificado, sem interromper a execução da função principal.

2.13.13 2.13.13.   Características operacionais gerais

A função apresenta as seguintes características:

• Executa análises complementares de completude e consistência

• Não altera o dataframe original

• Utiliza mensagens progressivas para rastreabilidade da execução

• Implementa tratamento de erros para robustez operacional

• Produz saídas múltiplas: console, gráfico e relatório HTML

2.13.14 2.13.14.   Avaliação da consistência dos dados

A análise de consistência é executada pela função tabela_inconsistencias(), que reúne diferentes rotinas de verificação em um único relatório analítico. Cada verificação avalia um tipo específico de inconsistência e retorna uma tabela com o número absoluto de registros inconsistentes, a proporção correspondente e, quando aplicável, o número de registros completos utilizados como denominador.

2.13.15 2.13.15.   Verificação de códigos inconsistentes

Função: verificar_codigos_inconsistentes()

Esta função avalia se os valores registrados em variáveis selecionadas pertencem ao conjunto de códigos ou categorias esperadas para cada campo. Para isso, define internamente uma lista de valores válidos para variáveis sociodemográficas, clínicas, territoriais, diagnósticas e assistenciais, como Sexo, Raca_Cor, Escolaridade, Localizacao_Primaria_3D, Localizacao_Primaria_4D, Tipo_Histologico, CNES_Hospital e UF_Unidade_Hospital.

A função percorre cada variável da lista e verifica se ela está presente no dataframe. Quando a variável existe, são considerados apenas os registros não ausentes. Em seguida, os valores observados são comparados com o conjunto de valores esperados. Valores não incluídos nessa lista são classificados como códigos inconsistentes. A proporção é calculada dividindo-se o número de códigos inconsistentes pelo número de registros não ausentes da variável. Quando a variável não está presente, a função emite mensagem de ausência, mas não interrompe a execução. Códigos como 99, 999, 88 e 888, quando previstos no dicionário interno, são tratados como categorias válidas, e não como inconsistências.

2.13.16 2.13.16.   Verificação de idades inconsistentes

Função: verificar_idades_inconsistentes()

Esta função avalia a plausibilidade da variável Idade. Inicialmente, verifica se a coluna está presente no dataframe. Caso esteja ausente, emite mensagem de erro e retorna NULL, interrompendo apenas essa verificação.

Quando a variável existe, a função seleciona os registros não ausentes e aplica dois critérios de inconsistência: idade menor que 0 e idade maior que 150 anos. Adicionalmente, o script inclui uma regra para identificar valores com possível erro de preenchimento associado a zeros à esquerda. As inconsistências identificadas são combinadas em um único vetor lógico. O quantitativo final corresponde à soma dos registros classificados como inconsistentes, e a proporção é calculada usando como denominador o total de registros não ausentes em Idade.

A função emite uma mensagem específica quando encontra idades inconsistentes, informando o número absoluto e a proporção. Quando não identifica inconsistências, informa que nenhuma idade inconsistente foi encontrada. Ao final, retorna uma tabela com a variável analisada, o quantitativo de idades inconsistentes e a respectiva proporção.

2.13.17 2.13.17.   Verificação de inconsistências entre anos

Função: verificar_anos_inconsistentes()

Esta função avalia a coerência cronológica entre os anos dos principais eventos clínicos e assistenciais. Antes de executar as regras, verifica se todas as colunas necessárias estão presentes: Ano_Primeiro_Diagnostico, Ano_Primeira_Consulta, Ano_Triagem e Ano_Inicio_Tratamento. Se qualquer uma estiver ausente, a função emite mensagem de erro e retorna NULL.

A análise é baseada em cinco comparações lógicas. São consideradas inconsistentes as situações em que o ano do diagnóstico aparece antes da primeira consulta, o ano do diagnóstico aparece antes da triagem, o início do tratamento aparece antes da primeira consulta, o início do tratamento aparece antes da triagem ou o início do tratamento aparece antes do primeiro diagnóstico.

Para cada regra, a função calcula o número de registros inconsistentes e a proporção em relação ao total de linhas do dataframe. Cada comparação gera uma linha na tabela de saída, com a descrição da inconsistência, o quantitativo e a proporção. A função também emite mensagens durante a execução, indicando se cada regra identificou inconsistências ou se nenhuma inconsistência foi encontrada naquela comparação.

2.13.18 2.13.18.   Verificação de inconsistência entre sexo e topografia tumoral

Função: verificar_cancer_sexo_inconsistentes()

Esta função avalia a compatibilidade entre a variável Sexo e a localização primária do tumor, considerando topografias anatomicamente relacionadas ao sexo. Antes da análise, verifica se as colunas Localizacao_Primaria_3D e Sexo estão presentes. Caso alguma esteja ausente, emite mensagem de erro e retorna NULL.

A função define dois grupos de códigos CID-O: um grupo de topografias relacionadas a órgãos genitais femininos, incluindo colo do útero, corpo do útero, ovário, vulva e vagina; e outro grupo relacionado a órgãos genitais masculinos, incluindo pênis, próstata e testículos. Em seguida, calcula denominadores específicos: registros completos com topografia feminina e sexo preenchido, e registros completos com topografia masculina e sexo preenchido.

A inconsistência é definida de forma específica para cada grupo. Para os cânceres femininos, são inconsistentes os registros em que o sexo é diferente de “Feminino”. Para os cânceres masculinos, são inconsistentes os registros em que o sexo é diferente de “Masculino”. A proporção é calculada usando como denominador apenas os registros completos pertencentes ao respectivo grupo topográfico, e não o total do banco. Essa decisão evita distorção da estimativa, pois a regra só se aplica aos tumores anatomicamente relacionados ao sexo.

2.13.19 2.13.19.   Organização dos resultados no relatório

Após a execução de cada verificação, a função tabela_inconsistencias() padroniza os resultados por meio da função interna preparar_resultado(). Essa etapa renomeia colunas, extrai a proporção em formato numérico, reformata percentuais, ordena os resultados em ordem decrescente de magnitude e aplica a classificação de gravidade.

A gravidade é definida pelas seguintes faixas:

	Proporção de inconsistência		Classificação
	< 1%		Baixo
	1% a < 5%		Moderado
	5% a < 20%		Alto
	≥ 20%		Crítico

Ao final, os resultados são integrados em um relatório HTML com resumo executivo, tabelas por dimensão, interpretação automatizada, notas metodológicas, implicações analíticas, limitações e referências.

2.13.20 2.13.20.   Construção do relatório analítico

Os resultados são organizados em um relatório HTML estruturado, que inclui:

• Resumo executivo com principais inconsistências

• Tabelas ordenadas por magnitude do problema

• Classificação de gravidade com codificação visual

• Interpretação automatizada por seção

• Notas metodológicas específicas para cada análise

• Seção de implicações analíticas

• Seção de limitações

O relatório é gerado por concatenação de blocos HTML e salvo automaticamente no diretório de trabalho, sendo aberto no navegador padrão ao final da execução.

2.14 2.14.   ANÁLISE DE COMPLETUDE DOS DADOS POR ANO

2.14.1 2.14.1.   Função principal

analise_completude_ano()

2.14.2 2.14.2.   Finalidade da função

A função analise_completude_ano() calcula a completude de cada variável estratificada por ano do banco, utilizando a variável Ano_do_Banco como eixo temporal. O resultado permite avaliar a variação anual do preenchimento das variáveis e identificar períodos com maior ou menor qualidade de informação.

2.14.3 2.14.3.   Problema que a função resolve

A análise global de completude resume a qualidade do preenchimento para todo o período, mas pode ocultar diferenças importantes entre anos. Essa função resolve esse problema ao distribuir a completude por ano, permitindo identificar mudanças temporais no padrão de preenchimento, possíveis efeitos de alterações na ficha do RHC e variações na qualidade dos registros ao longo do tempo.

2.14.4 2.14.4.   Como a função opera

A função verifica inicialmente se a variável Ano_do_Banco está presente no dataframe. Em seguida, identifica os anos existentes na base e calcula, para cada ano e para cada variável, a proporção de dados preenchidos. São considerados ausentes os valores NA e os registros preenchidos como “Sem informação”. A completude é apresentada em percentual, acompanhada de uma classificação abreviada baseada no escore de Romero e Cunha.

2.14.5 2.14.5.   Entrada esperada

Um dataframe contendo a variável:

• Ano_do_Banco

2.14.6 2.14.6.   Saída produzida

Um dataframe em formato tabular, no qual cada linha representa uma variável e cada coluna corresponde a um ano. As células apresentam o percentual de completude e sua respectiva classificação, no formato:

95.2% (E)

2.14.7 2.14.7.   Importância no fluxo do RHCgen

Essa função complementa a análise global de qualidade dos dados ao permitir uma avaliação temporal da completude. É especialmente útil para identificar descontinuidades, mudanças estruturais no banco, piora ou melhora progressiva do preenchimento e possíveis impactos de alterações na coleta ou na codificação das variáveis.

2.14.8 2.14.8.   Exemplo de uso

tabela_completude_ano <- analise_completude_ano(dados_RHC_combinados)

2.14.9 2.14.9.   Comportamento operacional da função analise_completude_ano()

A função inicia emitindo uma mensagem indicando o início da análise de completude por ano. Em seguida, verifica se a coluna Ano_do_Banco existe no dataframe. Caso a variável esteja ausente, a execução é interrompida com erro explícito (stop()), pois essa coluna é indispensável para a estratificação temporal.

Após essa verificação, a função identifica todas as variáveis do banco e extrai os anos únicos presentes em Ano_do_Banco, ordenando-os em ordem crescente.

A função define internamente uma rotina de classificação da completude, baseada no escore de Romero e Cunha, utilizando abreviações:

	Percentual de completude		Classificação		Sigla
	≥ 95%		Excelente		E
	90% a < 95%		Bom		B
	80% a < 90%		Regular		R
	50% a < 80%		Ruim		RU
	< 50%		Muito Ruim		MR

Em seguida, a função inicia um loop sobre os anos identificados. Para cada ano:

• emite uma mensagem indicando o ano em processamento;

• filtra o dataframe para manter apenas os registros daquele ano;

• verifica se há registros disponíveis;

• caso não haja registros para o ano, interrompe a execução com stop();

• calcula o número de dados ausentes em cada variável;

• considera como ausentes os valores NA e os registros “Sem informação”;

• calcula a completude percentual de cada variável no ano;

• arredonda a completude para uma casa decimal;

• aplica a classificação abreviada;

• armazena o resultado em uma lista, no formato “percentual + sigla”.

Após processar todos os anos, a função constrói a tabela final. A primeira coluna contém o nome das variáveis, e as colunas seguintes correspondem aos anos presentes no banco. Para cada combinação entre variável e ano, a célula apresenta o percentual de completude acompanhado da classificação.

Ao final, a função imprime no console a legenda das classificações e a referência metodológica utilizada. Em seguida, emite uma mensagem de conclusão e retorna o dataframe de completude por ano.

2.14.10 2.14.10.   Características operacionais relevantes

• Exige a presença da variável Ano_do_Banco;

• Interrompe a execução se a variável temporal estiver ausente;

• Calcula completude separadamente para cada ano;

• Considera NA e “Sem informação” como ausência;

• Usa classificação abreviada para facilitar a leitura da tabela;

• Retorna um dataframe, diferentemente da função global de completude;

• Não altera o dataframe original.

2.15 2.15.   RELATÓRIO FINAL DE PROCESSAMENTO

Ao término da execução, a função construir_banco() apresenta um relatório final com indicadores operacionais do processamento realizado. Esse relatório sintetiza três dimensões principais: tempo de execução, uso de memória e estrutura final do banco gerado.

A rotina calcula inicialmente o tamanho do objeto final em memória por meio da função object.size(), apresentando o resultado em megabytes e gigabytes. Em seguida, estima a dimensão do banco processado, informando o número total de registros e de variáveis. O tempo total de execução é calculado pela diferença entre o horário de início e o horário de término do processamento, sendo convertido para minutos.

As informações exibidas ao final incluem:

• tempo total de execução, em minutos;

• memória utilizada pelo objeto final;

• número total de registros de câncer;

• número total de variáveis no banco final.

Esse relatório tem função documental e operacional. Ele permite registrar o desempenho do processamento, dimensionar o custo computacional da rotina, verificar a estrutura final da base e apoiar a reprodutibilidade das análises realizadas com o RHCgen.

2.15.1 2.15.1.   Comportamento operacional do relatório final

A geração do relatório final ocorre como etapa terminal da função construir_banco(), após a execução completa de todas as rotinas de leitura, padronização, recodificação e organização estrutural do banco.

Inicialmente, a função registra o tempo de início do processamento por meio da função Sys.time(). Ao final da execução, um segundo registro temporal é capturado, permitindo o cálculo da duração total do processamento como a diferença entre os dois instantes.

O cálculo do tempo é realizado em unidades de minutos, utilizando coerção explícita com as.numeric(…, units = “mins”), garantindo padronização da medida independentemente do ambiente de execução.

A mensuração do uso de memória é feita diretamente sobre o objeto final do dataframe, utilizando object.size(data). Esse valor é convertido para megabytes e gigabytes por operações de divisão sucessiva por potências de 1024, permitindo interpretação mais intuitiva do volume de dados processado.

A dimensão estrutural do banco é obtida por meio de:

• nrow(data), para o total de registros;

• ncol(data), para o total de variáveis.

Esses valores refletem o resultado final após todas as etapas de transformação do pipeline.

 função responsável por consolidar essas informações (exibir_informacoes_finais) é definida internamente e executada imediatamente após o cálculo das métricas, garantindo encapsulamento da lógica de apresentação.

A saída é exibida exclusivamente no console por meio de message(), com formatação destacada em cores (códigos ANSI), permitindo rápida identificação visual das métricas principais durante a execução. Espaçamentos adicionais são inseridos com cat() para melhorar a legibilidade do output.

A rotina não grava os resultados em arquivo nem retorna objeto adicional. Seu propósito é exclusivamente informativo e diagnóstico, permitindo ao usuário avaliar o desempenho do processamento em tempo real.

2.16 2.16.   PRODUTO FINAL

O produto final da rotina consiste em um dataframe consolidado, padronizado, recodificado e estruturado, resultante da integração de todas as etapas do pipeline do RHCgen. Esse banco incorpora variáveis harmonizadas em termos de nomenclatura, tipagem, conteúdo semântico e organização estrutural, além de incluir variáveis derivadas que ampliam o potencial analítico dos dados.

O dataframe final encontra-se preparado para uso direto em análises epidemiológicas, estudos de qualidade dos dados, análises espaciais, avaliação de acessibilidade geográfica ao tratamento oncológico e construção de indicadores assistenciais e de saúde. A estrutura resultante permite a aplicação imediata de métodos estatísticos, modelagem multivariada e integração com bases territoriais.

A função construir_banco() atua como eixo central do RHCgen ao operacionalizar, de forma automatizada e sequencial, todas as etapas necessárias para transformar arquivos brutos do Registro Hospitalar de Câncer em uma base analítica estruturada, consistente e reprodutível.

2.16.1 2.16.1.   Comportamento operacional do produto final

A geração do produto final ocorre ao término da execução da função construir_banco(), após a aplicação sequencial de todas as rotinas de leitura, padronização, recodificação, harmonização territorial, organização estrutural e avaliação da qualidade dos dados.

O dataframe final é mantido em memória e retornado diretamente ao ambiente de execução do usuário por meio do comando return(data). Não há salvamento automático em disco, o que permite maior flexibilidade para que o usuário defina estratégias próprias de exportação e armazenamento.

A estrutura do banco final reflete decisões operacionais implementadas ao longo do pipeline:

• manutenção das variáveis originais, preservando a rastreabilidade dos dados;

• inclusão de variáveis derivadas com descrições completas (clínicas, territoriais e assistenciais);

• padronização de tipos de dados, garantindo compatibilidade com funções analíticas;

• ordenação lógica das colunas, facilitando a leitura e utilização do banco;

• preservação de valores não mapeados como NA, evitando introdução de vieses artificiais.

A função não realiza validação final ou filtragem dos dados, mantendo integralmente todos os registros processados. Dessa forma, o produto final reflete fielmente o conteúdo do banco após as etapas de transformação, cabendo ao usuário definir critérios adicionais de elegibilidade ou análise.

2.16.2 2.16.2.   Características do produto final

• Estrutura tabular única e consolidada

• Variáveis padronizadas e semanticamente interpretáveis

• Inclusão de variáveis clínicas, territoriais e assistenciais derivadas

• Tipagem consistente das variáveis

• Organização lógica das colunas

• Compatibilidade com análises estatísticas e espaciais

• Reprodutibilidade do processo de construção

2.16.3 2.16.3.   Observação técnica

O produto final do RHCgen representa a transição de um conjunto de arquivos administrativos heterogêneos para uma base analítica integrada. Apesar de refletir fielmente a estrutura do banco original, os resultados devem ser interpretados à luz das limitações inerentes aos registros hospitalares, incluindo possíveis inconsistências, incompletude e heterogeneidade de preenchimento.

3 3.    APLICAÇÃO

Foram processados 24 arquivos do RHC, correspondentes ao período de 2000 a 2023, resultando na construção de uma base analítica consolidada com 5.394.771 registros e 59 variáveis. O processamento foi realizado por meio da função construir_banco, que integrou automaticamente os dados provenientes de diferentes anos e promoveu a padronização estrutural e semântica das variáveis. O tempo total de execução foi de 4,61 minutos, com utilização aproximada de 2,01 GB de memória RAM.

4 4.    DISCUSSÃO

O RHCgen demonstrou ser uma ferramenta eficiente para a automação e padronização do processamento de dados do Registro Hospitalar de Câncer no Brasil, ao consolidar 5.394.771 registros provenientes de 24 arquivos anuais (2000–2023) em uma única base analítica estruturada em 4,61 minutos e com consumo de aproximadamente 2,01 GB de memória. Esse resultado evidencia a viabilidade técnica do pacote para o manejo de grandes volumes de dados epidemiológicos em saúde, corroborando o potencial das ferramentas de ciência de dados de código aberto para transformar fluxos de trabalho em pesquisa em saúde pública [10,25,12].

A utilização da linguagem R como plataforma de desenvolvimento se mostrou adequada para os objetivos propostos. Diferentemente do TabWin, ferramenta amplamente utilizada no contexto do DATASUS, mas restrita ao sistema operacional Windows e com capacidades analíticas limitadas, o RHCgen opera em ambiente multiplataforma, integra-se nativamente ao ecossistema estatístico do R e elimina a necessidade de exportação dos dados para análises complementares [11,25]. Esse aspecto é relevante porque a dependência de etapas manuais de exportação e recodificação constitui uma fonte recorrente de erros e inconsistências no processamento de sistemas de informação em saúde no Brasil [9]. Nesse sentido, o RHCgen se alinha a iniciativas brasileiras anteriores voltadas à superação dessas limitações, como o microdatasus [10] e o Rtabnetsp [13], ampliando o conjunto de ferramentas disponíveis para o processamento de dados do SUS em R.

O RHCgen, ao automatizar a análise de completude e classificar as variáveis segundo critérios validados, oferece ao pesquisador um diagnóstico imediato da qualidade do banco, favorecendo decisões informadas sobre a viabilidade de determinadas análises e a necessidade de estratégias de imputação ou restrição de subgrupos.

Adicionalmente, mudanças estruturais nas fichas do RHC ao longo do período analisado podem contribuir para a incompatibilidade entre registros históricos e regras de validação mais recentes. Esse padrão reflete a heterogeneidade estrutural dos arquivos anuais, um dos principais desafios identificados no desenvolvimento do RHCgen, e reforça a necessidade de ferramentas que realizem harmonização das bases, como a função lerarquivoDBF implementada no pacote. O fato de o RHCgen quantificar e estratificar inconsistências temporais por tipo de verificação representa um avanço metodológico concreto em relação ao processamento convencional, que em geral não contempla essa camada de validação de forma automatizada e reprodutível.

Do ponto de vista da contribuição para a ciência aberta e para a reprodutibilidade da pesquisa em oncologia, o RHCgen alinha-se a um movimento mais amplo de valorização de ferramentas de código aberto no contexto da saúde pública [12,26]. A disponibilização do pacote no GitHub, acompanhada de guia de uso acessível, reduz a barreira de entrada para pesquisadores sem formação específica em ciência de dados, democratizando o acesso a uma base de dados com mais de cinco milhões de registros oncológicos de relevância nacional. Iniciativas análogas, como o microdatasus e o Rtabnetsp, demonstraram que pacotes R voltados a dados do SUS têm ampla adoção pela comunidade científica brasileira [10,13], o que sugere potencial similar para o RHCgen.

Algumas limitações do estudo merecem ser reconhecidas. A necessidade de download manual dos arquivos do IRHC, uma vez que a plataforma não disponibiliza acesso remoto automatizado via FTP ou API, impõe uma etapa não automatizável que pode constituir obstáculo para usuários menos familiarizados com o processo de coleta de dados. Adicionalmente, os registros mais recentes do IRHC podem ainda estar em fase de validação, com maior proporção de campos incompletos ou revisados, o que pode afetar a qualidade de análises baseadas nos anos mais próximos da data de extração. Por fim, embora o tempo de processamento de 4,61 minutos para a base completa seja razoável para aplicações analíticas convencionais, o consumo de 2,01 GB de memória RAM pode representar limitação em ambientes computacionais com recursos reduzidos, aspecto que deve ser considerado por usuários que trabalhem com infraestrutura restrita.

5 5.    CONCLUSÕES

O RHCgen constitui uma contribuição metodológica para o campo da epidemiologia oncológica no Brasil, ao oferecer uma solução padronizada, reprodutível e de acesso aberto para o processamento de dados do Registro Hospitalar de Câncer. A capacidade de consolidar mais de cinco milhões de registros distribuídos ao longo de 24 anos em uma única base analítica estruturada, por meio de um fluxo automatizado e auditável, representa um avanço concreto em relação aos métodos convencionais de manipulação manual de dados, historicamente sujeitos a inconsistências e de difícil reprodução entre diferentes equipes de pesquisa.

Do ponto de vista técnico, o pacote demonstrou desempenho satisfatório em termos de tempo de execução e integridade das transformações aplicadas, validadas contra os dicionários oficiais do SisRHC. A implementação de funções modulares permite ao usuário tanto a execução integrada do fluxo completo de processamento quanto o controle granular de etapas específicas, adaptando-se a diferentes demandas analíticas e níveis de experiência com dados do SUS.

A análise de completude e consistência automaticamente gerada pelo RHCgen fornece ao pesquisador um diagnóstico imediato da qualidade do banco, elemento indispensável para decisões metodológicas sobre a viabilidade de análises, a necessidade de restrição de subgrupos ou a adoção de estratégias de tratamento de dados faltantes. Nesse sentido, o pacote não apenas facilita o acesso aos dados do RHC, mas também promove uma cultura de transparência e rigor na avaliação da qualidade das informações utilizadas em pesquisas epidemiológicas.

A disponibilização pública do RHCgen no GitHub, acompanhada de documentação acessível, posiciona a ferramenta como um recurso colaborativo e em contínuo aperfeiçoamento, alinhado aos princípios da ciência aberta. Espera-se que sua adoção contribua para ampliar a produção científica baseada nos dados do RHC, fortalecer a vigilância oncológica no país e subsidiar a formulação de políticas de saúde mais bem fundamentadas em evidências epidemiológicas robustas.

6 6.    REFERÊNCIAS

1. Bray F, Laversanne M, Sung H, Ferlay J, Siegel RL, Soerjomataram I, et al. Global cancer statistics 2022: GLOBOCAN estimates of incidence and mortality worldwide for 36 cancers in 185 countries. CA Cancer J Clin. 2024;74:229–63. https://doi.org/10.3322/caac.21834

2. SEER. SEER Program [Internet]. SEER. 2025 [cited 2025 Sept 13]. https://seer.cancer.gov/about/overview.html. Accessed 13 Sept 2025

3. Cancer Today. Cancer Today [Internet]. 2025 [cited 2025 Sept 13]. https://gco.iarc.who.int/today/. Accessed 13 Sept 2025

4. ACS. National Cancer Database [Internet]. ACS. 2025 [cited 2025 Sept 13]. https://www.facs.org/quality-programs/cancer-programs/national-cancer-database/. Accessed 13 Sept 2025

5. EORTC. European Organisation For Research And Treatment Of Cancer [Internet]. EORTC. 2017 [cited 2025 Nov 6]. https://www.eortc.org/. Accessed 6 Nov 2025

6. ECIS. Página inicial | ECIS - Sistema Europeu de Informação sobre o Cancro [Internet]. 2025 [cited 2025 Nov 6]. https://ecis.jrc.ec.europa.eu/en. Accessed 6 Nov 2025

7. INCA. Registro Hospitalar de Câncer - Rotinas e Procedimentos. Ministério da Saúde [Internet]. 1st ed. 2000. https://www.inca.gov.br/publicacoes/manuais/registros-hospitalares-de-cancer

8. Brasil. PROGRAMA CAPACITAÇÃO E ATUALIZAÇÃO EM ABORDAGENS DO ESPAÇO EM ANÁLISES DE SAÚDE PÚBLICA [Internet]. 2025 [cited 2025 Nov 6]. https://www.capacita.geosaude.icict.fiocruz.br/links.php. Accessed 6 Nov 2025

9. Jorge M, Laurenti R, Gotlieb S. Avaliação dos sistemas de informação em saúde no Brasil. Cad saúde colet, (Rio J) [Internet]. 2010 [cited 2024 July 28]; https://pesquisa.bvsalud.org/portal/resource/pt/lil-621256. Accessed 28 July 2024

10. Saldanha R de F, Bastos RR, Barcellos C. Microdatasus: pacote para download e pré-processamento de microdados do Departamento de Informática do SUS (DATASUS). Cad Saúde Pública. Escola Nacional de Saúde Pública Sergio Arouca, Fundação Oswaldo Cruz; 2019;35:e00032419. https://doi.org/10.1590/0102-311X00032419

11. Silva NP da. A utilização dos programas TABWIN e TABNET como ferramentas de apoio a disseminação das informações em saúde. The use of programs and TABWIN TABNET as tools to support the dissemination of health information [Internet]. 2009 [cited 2024 July 28]; https://www.arca.fiocruz.br/handle/icict/2300. Accessed 28 July 2024

12. Lowndes JSS, Best BD, Scarborough C, Afflerbach JC, Frazier MR, O’Hara CC, et al. Our path to better science in less time using open data science tools. Nat Ecol Evol. 2017;1:160. https://doi.org/10.1038/s41559-017-0160

13. Morais JH de A, Konstantyner TCR de O, Fazenda ÁL, Sala A, Martins CB. Rtabnetsp: pacote R para extração de indicadores de saúde do estado de São Paulo. Epidemiol Serv Saúde. Secretaria de Vigilância em Saúde e Ambiente - Ministério da Saúde do Brasil; 2021;30:e2020576. https://doi.org/10.1590/S1679-4974202100020

14. INCA. IntegradorRHC: ferramenta para a vigilância hospitalar de câncer no Brasil [Internet]. INCA; 2011. https://www.inca.gov.br/sites/ufu.sti.inca.local/files//media/document//folder-integrador-rhc-2011.pdf

15. Decit. Departamento de Ciência e Tecnologia do Ministério da Saúde. Informes Técnicos Institucionais. Integração de informações dos registros de câncer brasileiros. Rev Saúde Pública. Faculdade de Saúde Pública da Universidade de São Paulo; 2007;41:865–8. https://doi.org/10.1590/S0034-89102007000500024

16. R Core Team. R: A language and environment for statistical computing. R Foundation for Statistical Computing, Vienna, Austria. [Internet]. 2024 [cited 2025 Mar 10]. https://www.r-project.org/. Accessed 10 Mar 2025

17. R: The R Project for Statistical Computing [Internet]. [cited 2024 Mar 19]. https://www.r-project.org/. Accessed 19 Mar 2024

18. usethis: Automatize a configuração de pacotes e projetos [Internet]. [cited 2024 July 28]. https://cran.r-project.org/web/packages/usethis/index.html. Accessed 28 July 2024

19. Wickham H, Hester J, Chang W, Bryan J, RStudio. devtools: Tools to Make Developing R Packages Easier [Internet]. 2022 [cited 2024 July 28]. https://cran.r-project.org/web/packages/devtools/index.html. Accessed 28 July 2024

20. Wickham H, Danenberg P, Csárdi G, Eugster M, Software P, PBC. roxygen2: In-Line Documentation for R [Internet]. 2024 [cited 2024 July 28]. https://cran.r-project.org/web/packages/roxygen2/index.html. Accessed 28 July 2024

21. INCA. Registros hospitalares de câncer: planejamento e gestão. Ministério da Saúde [Internet]. 2nd ed. 2010. https://www.inca.gov.br/sites/ufu.sti.inca.local/files//media/document//registros-hospitalares-de-cancer-2010.pdf

22. INCA. Dicionário das Variáveis da Base de Dados do Sistema de Informação de Registros Hospitalares de Câncer (SisRHC). Atualizado em 30 de março de 2020. [Internet]. 2020 [cited 2024 July 27]. https://irhc.inca.gov.br/RHCNet/documentosTabWin.action?doc=dicionario.dados. Accessed 27 July 2024

23. Romero DE, Cunha CB da. Avaliação da qualidade das variáveis sócio-econômicas e demográficas dos óbitos de crianças menores de um ano registrados no Sistema de Informações sobre Mortalidade do Brasil (1996/2001). Cad Saúde Pública. Escola Nacional de Saúde Pública Sergio Arouca, Fundação Oswaldo Cruz; 2006;22:673–81. https://doi.org/10.1590/S0102-311X2006000300022

24. Pinto IV, Ramos DN, Costa M do CE da, Ferreira CBT, Rebelo MS. Completude e consistência dos dados dos registros hospitalares de câncer no Brasil. Cad saúde colet, (Rio J). 2012;113–20.

25. Chan BKC. Data Analysis Using R Programming. Adv Exp Med Biol. 2018;1082:47–122. https://doi.org/10.1007/978-3-319-93791-5_2

26. Jalal H, Pechlivanoglou P, Krijkamp E, Alarid-Escudero F, Enns E, Hunink MGM. An Overview of R in Health Decision Sciences. Med Decis Making. SAGE Publications Inc STM; 2017;37:735–46. https://doi.org/10.1177/0272989X16686559

7 7.    GUIA PRÁTICO PARA INSTALAÇÃO E USO DO RHCgen

Este guia tem como objetivo orientar, de forma simples, a instalação e o uso inicial do pacote RHCgen. O pacote foi desenvolvido para automatizar o processamento dos arquivos do Registro Hospitalar de Câncer (RHC), disponibilizados pelo IntegradorRHC no formato .dbf.

O RHCgen permite transformar vários arquivos brutos do RHC em uma base única, padronizada, recodificada e pronta para análises epidemiológicas, estudos de qualidade dos dados e produção de indicadores.

7.1 O que o usuário precisa ter instalado no computador

Antes de usar o RHCgen, é necessário ter dois programas instalados:

1. R

2. RStudio

O R é a linguagem utilizada para executar o pacote. O RStudio é o programa que facilita o uso do R, permitindo escrever comandos, visualizar resultados e organizar arquivos.

Recomenda-se instalar primeiro o R e depois o RStudio.

7.2 Onde obter os arquivos do RHC

Os arquivos utilizados pelo RHCgen devem ser baixados no IntegradorRHC, disponível no endereço:

https://irhc.inca.gov.br/RHCNet/

No sistema, os dados são disponibilizados em arquivos no formato .dbf. Esses arquivos geralmente possuem nomes iniciados por rhc, como:

rhc00.dbf

rhc01.dbf

rhc02.dbf

rhc20.dbf

rhc21.dbf

rhc22.dbf

rhc23.dbf

É importante manter os nomes originais dos arquivos, pois o RHCgen utiliza esses nomes para identificar o ano do banco e criar automaticamente a variável Ano_do_Banco.

7.3 Como organizar os arquivos antes de começar

Antes de usar o pacote, recomenda-se criar uma pasta exclusiva no computador para armazenar os arquivos do RHC.

Exemplo de organização:

C:/RHCgen/dados_rhc/

Dentro dessa pasta, devem ser colocados todos os arquivos .dbf baixados do IntegradorRHC.

Exemplo:

C:/RHCgen/dados_rhc/rhc00.dbf

C:/RHCgen/dados_rhc/rhc01.dbf

C:/RHCgen/dados_rhc/rhc02.dbf

C:/RHCgen/dados_rhc/rhc03.dbf

Todos os arquivos que serão processados devem estar na mesma pasta.

7.4 Como abrir o RStudio

Após instalar o R e o RStudio, abra o programa RStudio.

A tela do RStudio geralmente é dividida em quatro áreas:

1. Console: local onde os comandos são executados.

2. Script: local onde os comandos podem ser escritos e salvos.

3. Environment: local onde aparecem os objetos criados.

4. Files/Plots/Packages: local onde aparecem arquivos, gráficos e pacotes.

Para usuários iniciantes, recomenda-se escrever os comandos em um script e executá-los linha por linha.

Para criar um novo script:

File > New File > R Script

7.5 Como definir a pasta de trabalho

Antes de executar o RHCgen, o R precisa saber em qual pasta estão os arquivos .dbf.

Para isso, use o comando setwd().

Exemplo:

setwd(“C:/RHCgen/dados_rhc/”)

Atenção: o caminho da pasta deve ser adaptado ao local onde os arquivos foram salvos no computador do usuário.

Para verificar se o R está usando a pasta correta, execute:

getwd()

Para listar os arquivos disponíveis na pasta, execute:

list.files()

Se os arquivos .dbf aparecerem na lista, a pasta foi definida corretamente.

7.6 Como instalar o pacote RHCgen

O RHCgen está disponível no GitHub. Para instalá-lo, primeiro é necessário instalar o pacote remotes, que permite instalar pacotes diretamente do GitHub.

Execute o comando abaixo no Console do RStudio:

install.packages(“remotes”)

Depois, instale o RHCgen com o comando:

remotes::install_github(“andersonlineu/RHCgen”)

A instalação pode levar alguns minutos, especialmente se o R precisar instalar outros pacotes auxiliares.

7.7 Como carregar o pacote RHCgen

Após a instalação, o pacote precisa ser carregado para uso.

Execute:

library(RHCgen)

Esse comando deve ser executado sempre que o RStudio for aberto novamente e o usuário quiser utilizar o pacote.

7.8 Como processar os dados do RHC de forma automática

A forma mais simples de usar o RHCgen é por meio da função principal:

construir_banco()

Essa função executa automaticamente as principais etapas do processamento:

1. leitura dos arquivos .dbf;

2. junção dos arquivos em um banco único;

3. criação da variável Ano_do_Banco;

4. padronização dos nomes das variáveis;

5. conversão dos tipos das variáveis;

6. recodificação das categorias;

7. harmonização de estados e municípios;

8. padronização de códigos clínicos e hospitalares;

9. organização das colunas;

10. avaliação da qualidade dos dados.

Para gerar o banco final, execute:

data_rhc_final <- construir_banco()

O objeto data_rhc_final será criado no ambiente do RStudio e conterá o banco processado.

7.9 Como verificar se o banco foi criado corretamente

Após executar a função, o banco aparecerá na aba Environment do RStudio.

Também é possível verificar o tamanho do banco com os comandos abaixo:

dim(data_rhc_final)

Esse comando mostra o número de linhas e colunas do banco.

Para visualizar os primeiros registros:

head(data_rhc_final)

Para visualizar os nomes das variáveis:

names(data_rhc_final)

Para ver a estrutura das variáveis:

str(data_rhc_final)

7.10 Como filtrar o banco conforme o objetivo do estudo

Após a construção do banco completo, o usuário pode utilizar a função filtrar_banco() para selecionar apenas os registros de interesse para sua análise. Essa função permite extrair subconjuntos do banco do RHC a partir de diferentes critérios, como tipo de câncer, período, idade, sexo, tipo de caso, estado de residência, unidade hospitalar, primeiro tratamento hospitalar e origem do encaminhamento.

Essa etapa é útil porque o banco completo do RHC contém registros de diferentes tipos de câncer, anos, hospitais e perfis de pacientes. Na maioria dos estudos, o usuário precisa trabalhar apenas com uma parte específica desse banco. Por exemplo, pode ser necessário selecionar apenas casos de câncer de pele, câncer de próstata, câncer de mama, registros de determinado período ou pacientes residentes em uma Unidade da Federação específica.

A estrutura geral da função é:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  argumento = valor

)

Nesse exemplo, dados_filtrados é o nome do novo banco que será criado após a filtragem. O objeto data_rhc_final  representa o banco original que será filtrado.

7.10.1 Filtrar por CID-O de três dígitos

Para selecionar registros de um tipo de câncer a partir do código CID-O de três dígitos, utilize o argumento cid3digitos.

Exemplo para selecionar registros com código C44:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  cid3digitos = “C44”

)

Também é possível selecionar mais de um código:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  cid3digitos = c(“C44”, “C50”, “C61”)

)

7.10.2 Filtrar por CID-O de quatro dígitos

Para selecionar registros a partir do código CID-O de quatro dígitos, utilize o argumento cid4digitos.

Exemplo para selecionar registros com código C44.0:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  cid4digitos = “C44.0”

)

7.10.3 Filtrar por ano de triagem

Para selecionar registros segundo o ano de triagem, utilize os argumentos ano_inicio_triagem e ano_fim_triagem.

Exemplo para selecionar registros com triagem entre 2018 e 2020:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  ano_inicio_triagem = 2018,

  ano_fim_triagem = 2020

)

7.10.4 Filtrar por ano do diagnóstico

Para selecionar registros segundo o ano do primeiro diagnóstico, utilize os argumentos ano_inicio_diagnostico e ano_fim_diagnostico.

Exemplo para selecionar registros com diagnóstico entre 2015 e 2019:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  ano_inicio_diagnostico = 2015,

  ano_fim_diagnostico = 2019

)

7.10.5 Filtrar por ano da primeira consulta

Para selecionar registros segundo o ano da primeira consulta, utilize os argumentos ano_inicio_primeira_consulta e ano_fim_primeira_consulta.

Exemplo para selecionar registros com primeira consulta entre 2016 e 2020:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  ano_inicio_primeira_consulta = 2016,

  ano_fim_primeira_consulta = 2020

)

7.10.6 Filtrar por ano de início do tratamento

Para selecionar registros segundo o ano de início do tratamento, utilize os argumentos ano_inicio_tratamento e ano_fim_tratamento.

Exemplo para selecionar registros com início do tratamento entre 2014 e 2019:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  ano_inicio_tratamento = 2014,

  ano_fim_tratamento = 2019

)

7.10.7 Filtrar por idade

Para selecionar registros segundo a idade dos pacientes, utilize os argumentos idade_inicio e idade_fim.

Exemplo para selecionar pacientes com idade entre18 e 80 anos:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  idade_inicio = 18,

  idade_fim = 80

)

7.10.8 Filtrar por tipo de caso

Para selecionar registros segundo o tipo de caso, utilize o argumento tipo_de_caso.

Exemplo para selecionar apenas casos analíticos:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  tipo_de_caso = “Analítico”

)

7.10.9 Filtrar por sexo

Para selecionar registros segundo o sexo, utilize o argumento sexo.

Exemplo para selecionar registros do sexo feminino:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  sexo = “Feminino”

)

Caso o usuário não queira aplicar filtro por sexo em uma filtragem com múltiplos critérios, deve usar sexo = NULL.

7.10.10 Filtrar por estado de residência

Para selecionar registros segundo a Unidade da Federação de residência do paciente, utilize o argumento estado_residencia.

Exemplo para selecionar pacientes residentes no estado do Rio de Janeiro:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  estado_residencia = “RJ”

)

Também é possível selecionar mais de uma Unidade da Federação:

DADOS <- filtrar_banco(

  dados = data_rhc_final ,

  estado_residencia = c(“RJ”, “MG”)

)

7.10.11 Filtrar por Unidade da Federação da unidade hospitalar

Para selecionar registros segundo a Unidade da Federação do hospital, utilize o argumento uf_unidade_hospital.

Exemplo para selecionar registros de hospitais localizados no estado do Rio de Janeiro:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  uf_unidade_hospital = “RJ”

)

Também é possível selecionar hospitais de mais de uma Unidade da Federação:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  uf_unidade_hospital = c(“RJ”, “MG”)

)

7.10.12 Filtrar por primeiro tratamento hospitalar

Para selecionar registros segundo o primeiro tratamento recebido no hospital, utilize o argumento primeiro_tratamento_hospital.

Exemplo para selecionar registros cujo primeiro tratamento hospitalar foi cirurgia:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  primeiro_tratamento_hospital = “Cirurgia”

)

7.10.13 Filtrar por origem do encaminhamento

Para selecionar registros segundo a origem do encaminhamento, utilize o argumento origem_do_encaminhamento.

Exemplo para selecionar registros encaminhados pelo SUS:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  origem_do_encaminhamento = “SUS”

)

7.10.14 Filtrar por ano do banco

Para selecionar registros segundo o ano do banco, utilize os argumentos ano_do_banco_inicio e ano_do_banco_fim.

Exemplo para selecionar registros de bancos entre 2014 e 2019:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  ano_do_banco_inicio = 2014,

  ano_do_banco_fim = 2019

)

7.10.15 Usar múltiplos filtros ao mesmo tempo

A função filtrar_banco() permite combinar vários critérios de filtragem em uma única execução. Isso é útil quando o usuário deseja criar um banco muito específico.

Exemplo:

dados_filtrados <- filtrar_banco(

  dados = data_rhc_final ,

  cid3digitos = “C44”,

  cid4digitos = “C44.0”,

  ano_inicio_triagem = 2018,

  ano_fim_triagem = 2020,

  ano_inicio_diagnostico = 2015,

  ano_fim_diagnostico = 2019,

  ano_inicio_primeira_consulta = 2016,

  ano_fim_primeira_consulta = 2020,

  idade_inicio = 20,

  idade_fim = 80,

  tipo_de_caso = “Analítico”,

  sexo = NULL,

  estado_residencia = c(“RJ”, “MG”),

  uf_unidade_hospital = c(“RJ”, “MG”),

  primeiro_tratamento_hospital = “Cirurgia”,

  ano_inicio_tratamento = 2014,

  ano_fim_tratamento = 2019,

  origem_do_encaminhamento = “SUS”,

  ano_do_banco_inicio = 2014,

  ano_do_banco_fim = 2019

)

Nesse exemplo, o argumento sexo = NULL indica que nenhum filtro será aplicado para a variável sexo. Portanto, registros de todos os sexos serão mantidos, desde que atendam aos demais critérios definidos.

7.10.16 Conferir o banco filtrado

Após executar a filtragem, recomenda-se verificar o tamanho do novo banco:

dim(dados_filtrados)

Esse comando mostra quantas linhas e colunas existem no banco filtrado.

Para visualizar os primeiros registros:

head(dados_filtrados)

Para conferir os nomes das variáveis:

names(dados_filtrados)

7.10.17 Salvar o banco filtrado

Depois de filtrar os dados, recomenda-se salvar o novo banco em formato .rds:

saveRDS(dados_filtrados, “banco_filtrado.rds”)

Para abrir esse banco posteriormente:

DADOS <- readRDS(“banco_filtrado.rds”)

Observação importante

A função filtrar_banco() não altera o banco original. Ela cria um novo dataframe contendo apenas os registros que atendem aos critérios definidos pelo usuário. Por isso, recomenda-se manter o banco completo preservado e salvar os bancos filtrados com nomes claros.

Exemplo:

banco_pele <- filtrar_banco(

  dados = data_rhc_final ,

  cid3digitos = “C44”

)

banco_prostata <- filtrar_banco(

  dados = data_rhc_final ,

  cid3digitos = “C61”

)

banco_mama <- filtrar_banco(

  dados = data_rhc_final ,

  cid3digitos = “C50”

)

Dessa forma, o usuário pode criar diferentes bancos analíticos a partir da mesma base original, conforme o objetivo de cada estudo.

7.11 Como salvar o banco processado

A função construir_banco() cria o banco no ambiente do R, mas não salva automaticamente o arquivo no computador.

Por isso, depois de processar os dados, recomenda-se salvar o banco.

1. Salvar em formato RDS

O formato .rds é recomendado quando o banco será usado novamente no R.

saveRDS(data_rhc_final, “data_rhc_final.rds”)

Para abrir esse arquivo em outro momento:

data_rhc_final <- readRDS(“data_rhc_final.rds”)

2. Salvar em formato CSV

O formato .csv pode ser aberto em outros programas, como Excel, LibreOffice ou softwares estatísticos.

write.csv(data_rhc_final, “data_rhc_final.csv”, row.names = FALSE)

Em bases muito grandes, o arquivo .csv pode ficar pesado. Para análises no R, o formato .rds costuma ser mais adequado.

7.12 Como executar apenas a leitura dos arquivos DBF

Caso o usuário queira apenas juntar os arquivos .dbf, sem executar todo o pipeline, pode usar a função:

dados_RHC_combinados <- lerarquivoDBF()

Essa função lê todos os arquivos iniciados por rhc e com extensão .dbf presentes na pasta de trabalho.

Ela retorna um único banco com todos os arquivos combinados e cria automaticamente a variável Ano_do_Banco.

7.13 Como executar as etapas separadamente

Embora o uso mais simples seja pela função construir_banco(), também é possível executar as etapas uma por uma.

Exemplo:

data <- lerarquivoDBF()

data <- renomear_colunas(data)

data <- modificar_tipo_variavel(data)

data <- recodificar_variaveis(data)

data <- renomear_siglas_estados(data)

data <- renomear_codigo_municipio_residencia(data)

data <- renomear_codigo_municipio_hospital(data)

data <- renomear_CID_3digitos(data)

data <- renomear_tipo_histologico(data)

data <- renomear_estadiamento_clinico(data)

data <- classificacao_CID_0(data)

data <- renomear_clinica(data)

data <- renomear_CNES(data)

data <- ordenando_colunas(data)

Esse modo é útil quando o usuário deseja acompanhar cada etapa do processamento separadamente.

7.14 Como avaliar a qualidade dos dados

Após a construção do banco, é possível executar a análise de qualidade dos dados.

Use:

analise_qualidade_dos_dados(data_rhc_final)

Essa função realiza duas avaliações principais:

1. completude dos dados;

2. consistência dos dados.

A análise de completude identifica variáveis com maior proporção de dados ausentes ou preenchidos como “Sem informação”.

A análise de consistência identifica possíveis problemas, como:

1. códigos inválidos;

2. idades inconsistentes;

3. inconsistências entre anos de diagnóstico, consulta e tratamento;

4. incompatibilidades entre sexo e localização primária do tumor;

5. problemas lógicos entre variáveis clínicas e assistenciais.

Quando possível, a função também gera um relatório em HTML com os resultados da auditoria.

7.15 Como avaliar a completude por ano

Para verificar a completude das variáveis em cada ano do banco, use:

tabela_completude_ano <- analise_completude_ano(data_rhc_final)

Essa função retorna uma tabela com as variáveis nas linhas e os anos nas colunas.

Cada célula mostra o percentual de completude e uma classificação abreviada.

As classificações seguem a seguinte lógica:

	Percentual de completude		Classificação		Sigla
	≥ 95%		Excelente		E
	90% a < 95%		Bom		B
	80% a < 90%		Regular		R
	50% a < 80%		Ruim		RU
	< 50%		Muito ruim		MR

Exemplo de resultado:

95.2% (E)

78.4% (RU)

42.1% (MR)

7.16 Exemplo completo de uso do RHCgen

Abaixo está um exemplo completo para um usuário iniciante.

# 1. Definir a pasta onde estão os arquivos DBF

setwd(“C:/RHCgen/dados_rhc/”)

# 2. Instalar o pacote remotes, caso ainda não esteja instalado

install.packages(“remotes”)

# 3. Instalar o RHCgen diretamente do GitHub

remotes::install_github(“andersonlineu/RHCgen”)

# 4. Carregar o pacote

library(RHCgen)

# 5. Construir o banco final automaticamente

data_rhc_final <- construir_banco()

# 6. Verificar o tamanho do banco

dim(data_rhc_final)

# 7. Visualizar as primeiras linhas

head(data_rhc_final)

# 8. Avaliar a qualidade dos dados

analise_qualidade_dos_dados(data_rhc_final)

# 9. Avaliar a completude por ano

tabela_completude_ano <- analise_completude_ano(data_rhc_final)

# 10. Salvar o banco final em formato RDS

saveRDS(data_rhc_final, “data_rhc_final.rds”)

# 11. Salvar a tabela de completude por ano

write.csv(tabela_completude_ano, “tabela_completude_ano.csv”, row.names = FALSE)

7.17 Problemas comuns e como resolver

7.17.1 O R informa que não encontrou arquivos DBF

Mensagem possível:

Nenhum arquivo DBF foi encontrado

Possíveis causas:

1. os arquivos não estão na pasta correta;

2. a pasta de trabalho não foi definida corretamente;

3. os arquivos não têm extensão .dbf;

4. os arquivos não começam com o nome rhc.

Como resolver:

getwd()

list.files()

Verifique se os arquivos aparecem na lista. Caso não apareçam, ajuste a pasta com:

setwd(“C:/caminho/correto/da/pasta/”)

7.17.2 O pacote não instala

Se o comando abaixo gerar erro:

remotes::install_github(“andersonlineu/RHCgen”)

Verifique se o pacote remotes foi instalado corretamente:

install.packages(“remotes”)

Depois, tente novamente:

remotes::install_github(“andersonlineu/RHCgen”)

7.17.3 O R não reconhece a função construir_banco()

Mensagem possível:

could not find function “construir_banco”

Isso geralmente ocorre quando o pacote não foi carregado.

Execute:

library(RHCgen)

Depois, tente novamente:

data_rhc_final <- construir_banco()

7.17.4 O processamento demora muito

O banco do RHC pode conter muitos registros, especialmente quando vários anos são processados ao mesmo tempo. Por isso, o tempo de execução pode variar conforme:

1. quantidade de arquivos;

2. tamanho dos arquivos;

3. memória disponível no computador;

4. velocidade do processador.

Em bases grandes, recomenda-se fechar outros programas antes de executar o processamento.

7.17.5 O banco ficou muito grande

Bases com muitos anos de RHC podem ocupar bastante memória. Nesses casos, recomenda-se salvar o resultado em formato .rds:

saveRDS(data_rhc_final, “data_rhc_final.rds”)

Esse formato costuma ser mais eficiente para uso posterior no R.

7.18 Recomendações para uso adequado

Antes de iniciar qualquer análise epidemiológica, recomenda-se:

1. verificar se todos os arquivos .dbf desejados estão na pasta correta;

2. manter os nomes originais dos arquivos baixados do IntegradorRHC;

3. executar a função construir_banco();

4. salvar o banco processado;

5. executar a análise de qualidade dos dados;

6. avaliar a completude das variáveis de interesse;

7. documentar a data de extração dos dados;

8. registrar a versão do R, do RStudio e do RHCgen utilizada.

Esses cuidados aumentam a rastreabilidade, a transparência e a reprodutibilidade das análises realizadas com dados do RHC.

7.19 Observação final

O RHCgen automatiza o processamento dos arquivos do Registro Hospitalar de Câncer, mas não substitui a avaliação crítica do pesquisador. Os resultados obtidos a partir do banco processado devem ser interpretados considerando as características dos registros hospitalares, incluindo possíveis diferenças de preenchimento entre instituições, anos, regiões e tipos de variáveis.

O pacote organiza, padroniza e facilita o uso dos dados, mas a definição dos critérios de inclusão, exclusão, análise estatística e interpretação epidemiológica permane sob responsabilidade do usuário.

Informações do Projeto

GitHub	Versão Zenodo e DOI