Skip to contents

microdatasus

O microdatasus baixa, lê e prepara microdados dos Sistemas de Informação em Saúde publicados pelo DataSUS. O pacote trabalha diretamente com arquivos DBC, seleciona os arquivos efetivamente disponíveis no servidor e oferece funções específicas para recodificar variáveis de SIM, SINASC, SIH, SIA, CNES e SINAN.

O pacote resolve a parte operacional do acesso aos dados. Para compreender a unidade de análise, a cobertura, os fluxos de produção e os cuidados de interpretação de cada sistema, consulte o livro Sistemas de Informação em Saúde no Brasil.

O que o pacote oferece

Os downloads fazem novas tentativas em falhas transitórias e podem usar um cache persistente, com checksum e proveniência. Quando stop_on_error = FALSE, os arquivos válidos podem ser retornados mesmo que parte da solicitação falhe.

Instalação

Este README acompanha a versão de desenvolvimento 3.0.0.9000; a versão publicada no CRAN pode oferecer um conjunto diferente de recursos.

Instale a versão estável publicada no CRAN:

install.packages("microdatasus")

Ou instale a versão de desenvolvimento:

# install.packages("remotes")
remotes::install_github("rfsaldanha/microdatasus", ref = "dev")

A leitura de DBC é interna ao pacote, não chama foreign::read.dbf() e não depende mais de read.dbc. A implementação foi adaptada do pacote healthbR. O pacote mantém foreign apenas para tabelas DBF auxiliares ou referenciadas pelos dicionários TabWin; esses arquivos não fazem parte do caminho de leitura de um DBC.

Windows

No Windows, a instalação pelo GitHub compila o código C do pacote e requer o Rtools compatível com o R instalado. A versão binária distribuída pelo CRAN não requer ferramentas de compilação.

Se você recebeu do mantenedor um binário DEV .zip para Windows, instale-o sem descompactar. Confirme que ele é compatível com a versão e a arquitetura do seu R, consultáveis com R.version.string e R.version$arch. Esse binário também dispensa Rtools, mas a instalação de um arquivo local não resolve as dependências automaticamente. Em uma sessão nova do R:

# Instala ou atualiza as dependências usando binários do CRAN
install.packages(
  c("cli", "curl", "data.table", "digest", "dplyr", "foreign",
    "magrittr", "stringi", "tibble", "zip"),
  repos = "https://cloud.r-project.org",
  type = "win.binary"
)

# Selecione o .zip binário fornecido pelo mantenedor
install.packages(file.choose(), repos = NULL, type = "win.binary")
library(microdatasus)
packageVersion("microdatasus")

A versão DEV requer dplyr >= 1.2.0. O primeiro comando precisa de internet; a instalação do .zip pode ser feita sem conexão se todas as dependências já estiverem instaladas. O mantenedor pode gerar esses binários com o Win-builder.

Primeiro download

O fluxo mais comum tem duas etapas: baixar os arquivos e aplicar o processador do sistema.

library(microdatasus)

sim_raw <- fetch_datasus(
  year_start = 2022,
  year_end = 2022,
  uf = "AC",
  information_system = "SIM-DO",
  vars = c("CODMUNRES", "DTOBITO", "CAUSABAS"),
  track_source = TRUE
)

if (!is.null(sim_raw)) {
  sim <- process_sim(sim_raw)
} else {
  message("Nenhum registro foi obtido; confira os avisos do download.")
}

process_sim() usa SIM-DO por padrão. Para os subconjuntos nacionais, informe o mesmo tipo usado no download, por exemplo process_sim(sim_fetal_raw, information_system = "SIM-DOFET"). O resultado padroniza datas como Date, quantidades como inteiros e variáveis rotuladas como fatores.

Os anos, meses e UFs solicitados identificam as partições publicadas pelo DataSUS. A data e o local analíticos devem ser escolhidos nas variáveis do registro. O capítulo sobre o SIM, por exemplo, distingue residência, ocorrência e outras dimensões territoriais e temporais do óbito.

Sistemas mensais, como SIH, SIA e CNES, exigem os meses inicial e final:

sih_raw <- fetch_datasus(
  year_start = 2023,
  month_start = 1,
  year_end = 2023,
  month_end = 2,
  uf = c("AC", "RO"),
  information_system = "SIH-RD",
  timeout = 600
)

if (!is.null(sih_raw)) {
  sih <- process_sih(sih_raw)
}

Sistemas suportados

Sistema Periodicidade dos arquivos Download Processamento Livro de SIS
SIM Anual SIM-DO, SIM-DOFET, SIM-DOEXT, SIM-DOINF, SIM-DOMAT process_sim() SIM
SINASC Anual SINASC process_sinasc() SINASC
SIH Mensal SIH-RD, SIH-RJ, SIH-SP, SIH-ER process_sih() SIH
SIA Mensal Doze layouts SIA-* process_sia() SIA
CNES Mensal Treze layouts CNES-* process_cnes() para os treze layouts CNES
SINAN Anual e nacional 58 famílias oficiais SINAN-* process_sinan() para as 58 famílias SINAN

Use datasus_information_systems() para consultar todos os 93 valores aceitos em information_system, seus nomes, periodicidade, abrangência, siglas usadas nos arquivos DBC e aliases.

A lista completa dos identificadores está na referência de fetch_datasus().

Controle do download

Algumas opções úteis de fetch_datasus():

  • vars limita as colunas retornadas. Sem processamento ou filtro de linhas, também evita alocar as demais colunas durante a leitura do DBC.
  • track_source = TRUE acrescenta o nome do DBC de origem de cada registro.
  • timeout controla o limite de cada operação de rede, sem alterar opções globais do R.
  • o nome do arquivo, o progresso da transferência, a leitura e o resumo final são exibidos; use quiet = TRUE para ocultar o progresso e todas as mensagens de status. Avisos e erros continuam visíveis.
  • stop_on_error = FALSE preserva sucessos parciais e informa as falhas com avisos; TRUE interrompe a solicitação em falhas de listagem, download, leitura ou processamento.
  • uf aceita uma UF, várias UFs ou "all". Arquivos nacionais, como os do SINAN, ignoram esse argumento com um alerta.

Consulte o artigo Download e rastreabilidade para exemplos de todas essas opções.

Falhas de conexão e uso sem internet

Ter internet não garante acesso ao FTP do DataSUS. O servidor pode estar indisponível ou bloquear determinada rede. No modo padrão (collect = TRUE, stop_on_error = FALSE), fetch_datasus() retorna os registros aproveitados ou NULL quando não há registros a retornar. Verifique esse resultado antes de chamar process_*(), como nos exemplos acima. Avisos de falha também podem acompanhar um resultado parcial.

O cache reaproveita arquivos, mas fetch_datasus() ainda consulta a listagem remota. Para trabalhar sem conexão, use read_dbc() em DBCs locais ou readRDS() nos resultados já salvos. Processadores e consultas de dicionários podem exigir downloads se os arquivos necessários ainda não estiverem em um cache válido. As tabelas incluídas no pacote, como tabMun, são locais. Consulte as perguntas frequentes para os detalhes desses comportamentos.

Dicionários, cache e tabelas grandes

Um diretório explícito reutiliza DBC e ZIP do TabWin entre sessões. Configure também a opção do pacote para que chamadas diretas a process_*() usem esse mesmo cache:

cache <- datasus_cache_dir(create = TRUE)
options(microdatasus.cache_dir = cache)
variables <- datasus_variables("SIM-DO", cache_dir = cache)
schema <- datasus_schema("SIM-DO", cache_dir = cache)
contract <- validate_datasus_schema(sim_do_sample, "SIM-DO", period = 2020, cache_dir = cache)
audit <- audit_datasus_dictionaries(c("SIM-DO", "SINASC"), cache_dir = cache)
datasus_cache_info(cache)

Os processadores aceitam labels = "factor", "character" ou "none". Com diagnostics = TRUE, processing_diagnostics() informa códigos ausentes das conversões, campos esperados ou não mapeados, falhas de coerção e a proveniência — fonte, definição e checksum — de cada dicionário usado.

As otimizações de processamento são automáticas: datas repetidas são convertidas uma vez por campo e formato; o desescape só é aplicado a textos com barras invertidas; preenchimentos de códigos e faixas CNV F são vetorizados; e a seleção de relações históricas acessa as colunas necessárias. A conversão textual para UTF-8 permanece ativa, preservando identificadores marcados como "bytes" na etapa de normalização.

Use labels = "none" se precisar dos códigos, municipality_data = FALSE se não precisar dos atributos territoriais e diagnostics = FALSE (padrão) se não precisar do relatório. labels = "none" não garante execução sem rede: SIA, CNES e SINAN ainda consultam os dicionários para determinar a semântica dos campos. Uma primeira chamada pode incluir download e análise desses arquivos; chamadas seguintes podem reutilizar o cache.

Para solicitações grandes, combine destination, collect = FALSE e process = TRUE: cada DBC é processado e gravado antes da leitura do próximo. O retorno é um manifesto com caminhos, número de linhas, origem e checksum.

Use row_filter para descartar linhas de cada DBC antes do processamento e reduzir memória e tempo. Novos manifests usam SHA-256; espelhos HTTP/FTP podem ser informados por options(microdatasus.mirrors = c("https://...")). Com process = TRUE ou row_filter, a leitura usa o layout completo, e vars é aplicado depois dessas etapas. Isso preserva os campos necessários para datas históricas, idades e relações entre colunas.

Com provenance = TRUE, datasus_lockfile(dados, "datasus.lock.rds") registra a consulta e os DBC. Acrescente process = TRUE e process_args = list(diagnostics = TRUE) para registrar também os dicionários e as tabelas de referência usados no processamento.

O enriquecimento municipal usa uma referência fixa, identificada por datasus_reference_tables() como datasus-territorio-2023-txt-20220516. Ela foi reconstruída sem alterar os valores de tabMun, usando os TXT oficiais congelados no pacote. Não representa automaticamente os limites territoriais vigentes no ano de cada registro. Use municipality_data = FALSE para aplicar outra referência; consulte tabMun para a origem e as transformações de compatibilidade.

O guia Dicionários, cache e processamento em escala apresenta o fluxo completo e um exemplo para medir o processamento dos seus dados. A documentação dos benchmarks explica o escopo dos testes de desempenho do repositório. O artigo Formatos DBC, DEF e CNV descreve as regras de leitura, precedência e diagnóstico. O suporte do SIM nesta versão é restrito a CID-10.

Arquivos DBC locais

Use read_dbc() quando o arquivo já estiver no computador:

dados <- read_dbc("arquivo.dbc")

# Preserva os tipos inferidos dos metadados DBF
dados_tipados <- read_dbc("arquivo.dbc", as_character = FALSE)

# Lê somente as colunas necessárias, sem alocar as demais
dados_selecionados <- read_dbc(
  "arquivo.dbc",
  vars = c("CODMUNRES", "DTOBITO")
)

# Para arquivos cujo marcador de code page esteja ausente ou incorreto
dados_latin1 <- read_dbc("arquivo.dbc", encoding = "latin1")

# Alguns arquivos históricos usam a página de código DOS CP850
dados_cp850 <- read_dbc("arquivo_historico.dbc", encoding = "CP850")

read_dbc() descomprime e interpreta os registros diretamente, sem criar um DBF intermediário. O fluxo completo, o layout DBF, os marcadores de registro e o CRC32 são validados mesmo quando vars seleciona poucas colunas.

encoding = "auto" combina o marcador DBF com evidência de bytes por coluna e por linha. Texto reconhecido é convertido para UTF-8; misturas ambíguas e alguns identificadores ofuscados são preservados sem perda como strings com codificação "bytes", acompanhadas de aviso. Um encoding explícito é estrito e interrompe a leitura diante de bytes inválidos. Isso inclui, em qualquer sistema operacional, os cinco valores indefinidos do Windows-1252 (81, 8D, 8F, 90 e 9D em hexadecimal).

Guias

Como citar

Ao utilizar o pacote, cite:

SALDANHA, Raphael de Freitas; BASTOS, Ronaldo Rocha; BARCELLOS, Christovam. Microdatasus: pacote para download e pré-processamento de microdados do Departamento de Informática do SUS (DATASUS). Cadernos de Saúde Pública, v. 35, n. 9, e00032419, 2019. https://doi.org/10.1590/0102-311x00032419.

Quando o livro apoiar a descrição ou a interpretação dos sistemas, cite também:

SALDANHA, Raphael de Freitas. Sistemas de Informação em Saúde no Brasil. Rio de Janeiro: Edição do autor, 2026. ISBN 978-65-01-37841-1. https://rfsaldanha.github.io/sis/.

Agradecimentos

O suporte a DBC foi construído a partir de contribuições de código aberto dos projetos read.dbc, de Daniela Petruzalek, e healthbR, de Sidney Bissoli.

Dúvidas e sugestões

Crie uma issue ou envie um e-mail para raphael.saldanha@fiocruz.br.