Perguntas frequentes

Como instalar a versão DEV no Windows sem Rtools?

Use um binário .zip para Windows fornecido pelo mantenedor, compatível com a versão e a arquitetura do seu R. Instale primeiro as dependências e depois o arquivo com install.packages(file.choose(), repos = NULL, type = "win.binary"), sem descompactá-lo. A instalação de um arquivo local não instala dependências automaticamente. Consulte os comandos completos na seção Windows da página inicial.

A instalação pelo GitHub usa o código-fonte e requer Rtools. Para informar seu ambiente ao solicitar um binário, execute R.version.string e R.version$arch.

O período e a UF do download são necessariamente os do evento?

Não. Os argumentos de fetch_datasus() selecionam as partições em que o DataSUS publicou os registros. A pergunta analítica pode exigir outra dimensão, como município de residência, município de ocorrência, competência, data da notificação ou data de encerramento.

Escolha e filtre as variáveis do próprio registro depois do download. Em uma análise de óbitos ocorridos em 2020, por exemplo:

library(microdatasus)

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

sim <- process_sim(sim_raw)

sim_2020 <- sim[!is.na(sim$DTOBITO) & format(sim$DTOBITO, "%Y") == "2020", ]

Os capítulos do livro sobre SIM, SINASC, SIH, SIA, SINAN e CNES explicam quais dimensões temporais e territoriais existem em cada sistema.

Quando devo informar os meses?

SIH, SIA e CNES são mensais e exigem month_start e month_end. SIM, SINASC e SINAN são anuais; meses informados para esses sistemas são ignorados com uma mensagem.

Um único mês ainda precisa aparecer nos dois argumentos:

dados <- fetch_datasus(
  year_start = 2023,
  month_start = 4,
  year_end = 2023,
  month_end = 4,
  uf = "PE",
  information_system = "SIH-RD"
)

Como aumentar o timeout?

Use timeout em fetch_datasus(), fetch_cadger() ou fetch_sigtab(). A função aplica o valor diretamente a cada operação de rede e não altera options(timeout):

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

Falhas transitórias recebem até duas novas tentativas. Aumentar o timeout ajuda com arquivos grandes ou conexões lentas, mas não corrige um arquivo ausente ou inválido.

O que acontece quando apenas parte do download falha?

Com stop_on_error = FALSE, que é o padrão, os arquivos válidos são retornados e as falhas são resumidas ao final. No modo padrão, collect = TRUE, o retorno é NULL quando não há registros a retornar.

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
)

if (is.null(dados)) {
  message("Nenhum arquivo foi obtido.")
}

Com stop_on_error = TRUE, uma falha de listagem, download, leitura ou processamento interrompe a chamada. Combinações de UF e período que não constam da listagem geram avisos em ambos os modos; confira a cobertura dos resultados.

E quando o computador está sem internet ou o DataSUS está indisponível?

Com stop_on_error = FALSE e collect = TRUE, fetch_datasus() informa as falhas de conexão com avisos e retorna NULL quando não há registros a retornar. Verifique esse retorno antes de chamar uma função process_*(). Ter acesso à internet não garante acesso ao FTP do DataSUS: o servidor também pode estar indisponível ou bloquear conexões de determinadas redes ou países.

Os exemplos de download da ajuda só executam em sessões interativas com acesso à internet. Os testes automáticos usam arquivos locais e conexões simuladas; os testes que acessam o DataSUS precisam ser ativados explicitamente e não executam no CRAN. Assim, os exemplos e testes do pacote não dependem da disponibilidade do servidor. A verificação de links da documentação é separada e ainda pode apontar endereços indisponíveis.

Ter arquivos DBC no cache não torna fetch_datasus() offline: ela continua consultando as listagens remotas. Use read_dbc() para arquivos locais ou readRDS() para resultados salvos. Os processadores podem precisar de dicionários ainda não armazenados; nesse caso, uma chamada direta pode falhar. Veja como preparar o cache.

As tabelas de referência incluídas no pacote, como tabMun, podem ser usadas sem conexão. O pacote também inclui os arquivos de origem necessários para reconstruir essa referência municipal.

Como saber de qual arquivo veio cada linha?

Use track_source = TRUE:

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

unique(dados$source)

Essa coluna é preservada quando vars é usado. A função não sobrescreve uma coluna source já existente no DBC.

Como reduzir o uso de memória?

Comece selecionando apenas as colunas necessárias:

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

Para muitos anos, meses ou UFs, baixe lotes menores e grave cada lote em um banco de dados. Outra opção é fetch_datasus(process = TRUE, collect = FALSE, destination = "dados"), que grava um RDS por arquivo e retorna um manifesto. O maior DBC descomprimido, os dicionários e os objetos temporários ainda devem caber em memória.

O exemplo abaixo usa SQLite e processa o layout completo antes de selecionar as colunas de saída:

library(DBI)
library(RSQLite)

con <- dbConnect(SQLite(), "sih.sqlite")

grade <- expand.grid(
  ano = 2022:2023,
  mes = 1:12,
  uf = c("AC", "RO"),
  stringsAsFactors = FALSE
)

for (i in seq_len(nrow(grade))) {
  lote <- fetch_datasus(
    year_start = grade$ano[i],
    month_start = grade$mes[i],
    year_end = grade$ano[i],
    month_end = grade$mes[i],
    uf = grade$uf[i],
    information_system = "SIH-RD",
    vars = c("MUNIC_RES", "DT_INTER", "DIAG_PRINC", "SEXO"),
    process = TRUE,
    process_args = list(municipality_data = FALSE, labels = "character"),
    track_source = TRUE,
    timeout = 600,
    stop_on_error = FALSE
  )

  if (is.null(lote)) {
    next
  }

  dbWriteTable(
    con,
    "sih",
    lote,
    append = dbExistsTable(con, "sih")
  )
}

dbDisconnect(con)

Consulte depois sem carregar toda a tabela:

library(dplyr)

con <- dbConnect(SQLite(), "sih.sqlite")

tbl(con, "sih") |>
  count(SEXO, DIAG_PRINC) |>
  arrange(desc(n)) |>
  collect()

dbDisconnect(con)

Como acelerar o processamento?

As funções já convertem datas repetidas uma vez por campo e formato, restringem o desescape de texto e usam operações vetorizadas em códigos e limites CNV. Essas otimizações não exigem um argumento adicional.

Ative o cache persistente para reutilizar dicionários:

options(microdatasus.cache_dir = datasus_cache_dir(create = TRUE))

Desative apenas o que sua análise não precisa: municipality_data = FALSE omite atributos territoriais, e diagnostics = FALSE (padrão) evita construir o relatório. Use labels = "none" se quiser os códigos categóricos. Essa opção não garante execução sem rede: SIA, CNES e SINAN ainda consultam os DEFs e podem avaliar suas relações.

Ao medir desempenho, separe a leitura do DBC da primeira chamada do processador e das chamadas com dicionários já em cache. Sempre reutilize a entrada bruta. Consulte o exemplo de medição em Dicionários, cache e processamento em escala.

`vars` sempre reduz a memória de leitura?

Sem process e sem row_filter, as colunas solicitadas são selecionadas pelo leitor de DBC. Com processamento ou filtro, o layout completo é lido e vars seleciona a saída depois dessas etapas. Isso permite usar campos derivados e conservar as colunas necessárias às relações históricas. Selecionar poucas colunas de saída não torna a leitura inicial menor nesse segundo caso.

Quais tipos as funções de processamento retornam?

As funções process_*() mantêm tipos coerentes com o papel de cada campo. Datas completas são Date; contagens e componentes de idade são inteiros; valores contínuos podem ser double; identificadores e texto livre permanecem character; e campos categóricos são fatores por padrão.

Confira os tipos antes de aplicar transformações específicas da análise:

sim <- process_sim(sim_raw)

class(sim$DTOBITO)
class(sim$IDADEanos)
class(sim$SEXO)

Use labels = "character" para devolver descrições categóricas como texto ou labels = "none" para manter os códigos de origem. Códigos não cobertos pela relação oficial continuam visíveis, em vez de serem transformados silenciosamente em NA. Com diagnostics = TRUE, falhas de coerção e códigos desconhecidos ficam disponíveis em processing_diagnostics().

Posso baixar várias UFs de uma vez?

Sim:

dados <- fetch_datasus(
  year_start = 2023,
  month_start = 1,
  year_end = 2023,
  month_end = 1,
  uf = c("AC", "RO", "AM"),
  information_system = "CNES-ST"
)

Use uf = "all" para todas as UFs. Não combine "all" com códigos individuais. Nos sistemas nacionais, como SINAN, uf é ignorado com um alerta; filtre a variável territorial do registro depois do download.

O apêndice de códigos de municípios discute códigos IBGE, códigos usados nos SIS e mudanças territoriais.

Como são escolhidos dados atuais, históricos e preliminares?

A escolha é automática para cada período, UF e fragmento. Dados definitivos ou atuais têm prioridade sobre preliminares; cópias atuais têm prioridade sobre diretórios históricos. A função informa quando usa publicações preliminares ou históricas.

Essas versões podem diferir em cobertura, crítica e layout. Para séries temporais, consulte a linha do tempo e os cuidados de interpretação do capítulo correspondente no livro de SIS.

Posso ler um arquivo DBC que já tenho?

Sim:

dados <- read_dbc("arquivo.dbc")

Por padrão, todas as colunas são texto. Para manter os tipos inferidos do DBF:

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

O pacote descomprime e interpreta o fluxo diretamente, sem criar um DBF intermediário. Layout, registros e CRC32 são validados antes do retorno. Use vars para ler somente as colunas necessárias sem deixar de verificar a estrutura completa do arquivo.

O que fazer diante de aviso de codificação ou caracteres multibyte?

O padrão encoding = "auto" combina o marcador de página de código do DBF com evidência dos bytes de cada coluna e linha. Texto identificado com segurança é convertido para UTF-8. Sequências ambíguas e identificadores binários são preservados sem perda com Encoding(x) == "bytes" e produzem um aviso.

Se a origem do arquivo for conhecida, um valor explícito exige uma leitura estrita:

dados_cp850 <- read_dbc("arquivo_historico.dbc", encoding = "CP850")

Uma sequência incompatível com o encoding informado gera microdatasus_dbc_encoding_error; nenhum caractere substituto é inserido. Os cinco bytes indefinidos do Windows-1252 são tratados da mesma forma no Windows, Linux e macOS. Consulte Formatos DBC, DEF e CNV antes de forçar uma codificação.

Como são resolvidos códigos repetidos em CNV ou DBF?

O parser usa a última ocorrência física aplicável, como o TabWin. Em CNV, um código posterior substitui o anterior e uma categoria repetida usa sua última descrição não vazia. Em tabelas DBF relacionadas, a última linha com a mesma chave é usada.

Conflitos de chave DBF e divergências entre a quantidade de categorias declarada e observada no CNV não são ocultados: datasus_variables() os marca como fallback, com issue_class e mensagem explicativa. Relações ambíguas não são escolhidas por aproximação.

Por que o DataSUS não está acessível?

O download depende de acesso FTP ao servidor do DataSUS. Indisponibilidade temporária, bloqueios de rede corporativa e restrições geográficas podem impedir a conexão. Verifique o diagnóstico consolidado da função, tente outro momento ou outra rede e evite múltiplas chamadas paralelas.