Skip to contents

Download e rastreabilidade

Source: vignettes/articles/download-e-rastreabilidade.Rmd
download-e-rastreabilidade.Rmd

Como fetch_datasus() trabalha

fetch_datasus() lista os diretórios necessários, cria um manifesto com os arquivos realmente publicados pelo DataSUS, baixa cada arquivo e combina os registros. Se houver mais de uma publicação para a mesma combinação de sistema, período, UF e fragmento, dados definitivos ou atuais têm prioridade sobre dados preliminares e cópias históricas.

Os downloads são sequenciais para evitar sobrecarga no servidor. Antes de cada transferência, a função anuncia o nome do arquivo e exibe o progresso informado pelo curl; depois, anuncia a leitura do DBC e apresenta um resumo final do lote. Use quiet = TRUE quando quiser ocultar o progresso e todas as mensagens de status; avisos e erros permanecem visíveis. Arquivos temporários são removidos depois da leitura, inclusive quando ocorre uma falha. Com cache_dir, arquivos válidos e seus manifests persistem para reutilização entre sessões. Uma nova chamada ainda consulta a listagem do DataSUS, mas pode reutilizar o DBC em cache; refresh = TRUE solicita um novo download.

Argumentos principais

Argumento Uso
year_start, year_end Primeiro e último ano, inclusive
month_start, month_end Obrigatórios para SIH, SIA e CNES; ignorados nos sistemas anuais
uf Uma UF, várias UFs ou "all"
information_system Identificador do sistema e do layout
vars Colunas que devem ser mantidas
track_source Acrescenta o nome do arquivo DBC de origem
timeout Limite, em segundos, de cada operação de rede
quiet Oculta mensagens de status e progresso quando TRUE
stop_on_error Define se uma falha interrompe toda a solicitação
cache_dir, refresh Reutiliza arquivos persistidos ou solicita novo download
process, process_args Processa cada arquivo e configura rótulos, diagnósticos e outras opções
row_filter Filtra linhas brutas antes do processamento e da seleção de colunas
destination, collect Grava RDS por arquivo; collect = FALSE retorna o manifesto
provenance, keep_files Registra metadados da execução e permite reter os DBCs em destination

Use datasus_information_systems() para consultar os 93 identificadores preferenciais, seus sistemas, nomes completos, periodicidade, abrangência, siglas de arquivo e aliases retrocompatíveis.

A referência de fetch_datasus() contém a lista completa dos identificadores aceitos e seus limites históricos.

Sistemas anuais

SIM, SINASC e SINAN usam intervalos anuais. Não informe meses:

sim_raw <- fetch_datasus(
  year_start = 2020,
  year_end = 2022,
  uf = "AC",
  information_system = "SIM-DO"
)

Os arquivos SIM-DO e SINASC são organizados por UF. Os subconjuntos especiais do SIM e os agravos SINAN suportados são nacionais; nesses casos, uf é ignorado com um alerta.

Para escolher corretamente a dimensão temporal e territorial da análise, consulte os capítulos de SIM, SINASC e SINAN.

Sistemas mensais

SIH, SIA e CNES exigem os dois meses, mesmo quando apenas um mês é solicitado:

sih_raw <- fetch_datasus(
  year_start = 2023,
  month_start = 12,
  year_end = 2024,
  month_end = 2,
  uf = "MG",
  information_system = "SIH-RD"
)

O intervalo pode atravessar anos. Os capítulos de SIH, SIA e CNES explicam o significado de competência, produção e posição cadastral em cada sistema.

Uma, várias ou todas as UFs

Uma UF:

uf = "RJ"

Várias UFs, na ordem desejada:

uf = c("AC", "RO", "AM")

Todas as UFs:

uf = "all"

"all" não pode ser combinado com UFs individuais. Solicitações amplas podem consumir muita rede, memória e tempo; prefira dividir o trabalho em lotes quando for necessário persistir grandes volumes.

O apêndice sobre códigos de municípios ajuda a interpretar e compatibilizar campos territoriais.

Selecionar variáveis

vars é aplicado a cada arquivo antes da combinação final. Sem process ou row_filter, a seleção é encaminhada ao leitor, evitando alocar as demais colunas. A validação estrutural e o CRC32 continuam cobrindo o arquivo completo:

sim_raw <- fetch_datasus(
  year_start = 2022,
  year_end = 2022,
  uf = "SP",
  information_system = "SIM-DO",
  vars = c("DTOBITO", "CODMUNRES", "CAUSABAS", "IDADE", "SEXO")
)

Nomes inexistentes produzem erro para evitar uma seleção silenciosamente incompleta. Se o estudo usa causas ou diagnósticos, consulte também o apêndice sobre a CID.

Com process = TRUE ou row_filter, o leitor carrega o layout completo. O filtro recebe os códigos brutos e deve retornar um lógico por linha sem NA; depois ocorrem o processamento, se solicitado, e a seleção de vars. Assim, é possível selecionar campos derivados na saída:

sim <- fetch_datasus(
  year_start = 2022,
  year_end = 2022,
  uf = "AC",
  information_system = "SIM-DO",
  process = TRUE,
  process_args = list(municipality_data = FALSE, diagnostics = TRUE),
  row_filter = function(x) !is.na(x$SEXO) & x$SEXO == "1",
  vars = c("DTOBITO", "CODMUNRES", "IDADEanos"),
  cache_dir = datasus_cache_dir(create = TRUE),
  provenance = TRUE
)

Esse fluxo conserva durante o processamento as colunas de competência e os campos usados em relações DEF que atravessam colunas físicas. A seleção final reduz o resultado, mas não a memória necessária à leitura inicial.

Rastrear o arquivo de origem

Com track_source = TRUE, cada registro recebe uma coluna source com o nome do DBC:

sih_raw <- fetch_datasus(
  year_start = 2023,
  month_start = 1,
  year_end = 2023,
  month_end = 2,
  uf = c("AC", "RO"),
  information_system = "SIH-RD",
  vars = c("MUNIC_RES", "DT_INTER", "DIAG_PRINC"),
  track_source = TRUE
)

table(sih_raw$source)

source é preservada mesmo quando não aparece em vars. Se o arquivo original já contiver uma coluna com esse nome, a função interrompe a operação para não sobrescrever dados.

Timeout e novas tentativas

Use o argumento timeout da própria função. Não é necessário alterar options(timeout):

sia_raw <- fetch_datasus(
  year_start = 2023,
  month_start = 1,
  year_end = 2023,
  month_end = 1,
  uf = "BA",
  information_system = "SIA-PA",
  timeout = 600
)

Falhas transitórias de rede recebem até duas novas tentativas. Arquivo inexistente, vazio ou DBC inválido não é baixado repetidamente.

Sucesso parcial ou interrupção

O padrão stop_on_error = FALSE tenta aproveitar os arquivos válidos. Ao final, as falhas são reunidas em um único diagnóstico:

dados <- fetch_datasus(
  year_start = 2023,
  month_start = 1,
  year_end = 2023,
  month_end = 12,
  uf = c("AC", "RO"),
  information_system = "SIH-RD",
  stop_on_error = FALSE
)

O retorno é NULL quando nenhum arquivo pode ser obtido. Sempre verifique antes de processar ou persistir:

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

Use stop_on_error = TRUE quando o conjunto só for válido se todos os arquivos forem obtidos:

dados <- fetch_datasus(
  year_start = 2023,
  month_start = 1,
  year_end = 2023,
  month_end = 12,
  uf = "AC",
  information_system = "SIH-RD",
  stop_on_error = TRUE
)

Dados atuais, históricos e preliminares

A escolha entre publicações é automática. Para a mesma unidade solicitada, a função prefere dados definitivos ou atuais; preliminares e históricos são usados quando são a publicação disponível. Mensagens informam quando o manifesto inclui arquivos preliminares ou diretórios históricos.

Mudanças de formulário, classificação e cobertura podem afetar séries longas. Antes de combinar anos distantes, consulte a linha do tempo e a seção de estrutura de dados do capítulo correspondente no livro de SIS.

Ler um DBC local

Se o arquivo já foi obtido por outro meio, use read_dbc():

dados <- read_dbc("arquivo.dbc")
dados_tipados <- read_dbc("arquivo.dbc", as_character = FALSE)

O leitor descomprime e interpreta o DBC diretamente, sem gravar um DBF intermediário. Também valida a estrutura e o CRC32 completo. Consulte Formatos DBC, DEF e CNV para projeção de colunas, codificações históricas e classes de erro.

Boas práticas para downloads grandes

  • Solicite somente os períodos e layouts necessários.
  • Use vars sempre que a análise não precisar do layout completo.
  • Divida consultas nacionais ou de muitos anos em lotes recuperáveis.
  • Use process = TRUE, collect = FALSE e destination para processar e salvar cada DBC sem acumular todos os resultados em memória.
  • Ative cache_dir para reutilizar DBCs e dicionários entre sessões.
  • Registre os argumentos, a data de extração e, quando necessário, track_source.
  • Confira avisos de períodos, UFs e arquivos ausentes antes da análise.
  • Não dispare chamadas paralelas contra o FTP do DataSUS.

Veja as Perguntas frequentes para um exemplo de persistência incremental em SQLite e Dicionários, cache e processamento em escala para medir tempo e planejar memória.