Referência da API

MicroSUS

Microdados do DATASUS em Julia, com leitura streaming de arquivos .dbc (PKWare DCL) e .dbf: memória constante do arquivo comprimido até o sink, seleção de colunas e filtro de linhas no leitor, transcodificação CP850/Latin-1 → UTF-8, schemas tipados por sistema (SIM, SINASC, SIH, SIA, CNES) e interface Tables.jl com partições.

Uso básico:

using MicroSUS, DataFrames

caminho = baixar(:sim, "PE"; ano = 2023)          # cache local (Scratch.jl)
df = DataFrame(ler(caminho))                       # tudo tipado

# nacional sem estourar RAM: colunas + filtro no leitor
t = ler(caminho; colunas = [:DTOBITO, :CAUSABAS, :CODMUNRES, :IDADE, :SEXO],
        filtro = r -> eh_agressao(r[:CAUSABAS]))   # CVLI: X85–Y09

# streaming direto para Arrow (requer `using Arrow`)
converter(caminho, "do_pe_2023.arrow"; colunas = [:DTOBITO, :CAUSABAS, :CODMUNRES])

Formato .dbc = cabeçalho DBF em claro + 4 bytes de CRC + registros comprimidos com PKWare DCL ("implode"). O descompressor é um porte puro Julia do blast.c de Mark Adler, com janela de 4 KiB emitida em chunks — é isso que permite a leitura em memória constante.

ler(caminho; colunas = nothing, filtro = nothing,
    tamanho_lote = 100_000, schema = :auto, encoding = :auto,
    pool = true, ignorar_ausentes = false) -> TabelaDBC

Abre um .dbc ou .dbf do DATASUS como tabela preguiçosa (Tables.jl, com Tables.partitions). Nada é lido até a iteração.

• colunas: Vector{Symbol} com os campos desejados — os demais nem são materializados. nothing = todos.
• filtro: função RegistroDBF -> Bool aplicada antes do parse das colunas; r[:CAMPO] devolve o texto do campo sob demanda. Ex.: r -> r[:CODMUNRES] == "261110".
• schema: :auto (deduz pelo prefixo do arquivo: DO→SIM, DN→SINASC, RD→SIH, PA→SIA, ST→CNES), um Symbol (:sim, ...), um Dict{Symbol,Symbol} próprio, ou nothing (só a tipagem do DBF).
• encoding: :auto (language driver do cabeçalho; DATASUS ⇒ cp850), ou :cp850, :latin1, :cp1252, :utf8.
• ignorar_ausentes: quando true, colunas de colunas que não existem no layout deste arquivo são descartadas em vez de lançar ArgumentError. É o que torna prática a leitura multi-ano do SIH, cujo layout ganhou campos em 2011, 2013 e 2014 — sem isso, pedir :DIAGSEC1 derruba a leitura de 2010. As colunas descartadas saem por @debug; se nenhuma das pedidas existir, ainda assim é erro, porque aí o problema é outro (arquivo errado ou nome digitado errado);
• pool: usa PooledArray nas colunas categóricas do schema (equivalente ao factor do R, opt-in).

Uso: DataFrame(ler(caminho)) materializa tudo; for lote in Tables.partitions(ler(caminho)) processa em lotes; Arrow.write(saida, ler(caminho)) converte em streaming.

TabelaDBC

Tabela preguiçosa sobre um .dbc/.dbf, criada por ler. Nada é lido do disco até a iteração. Implementa a interface Tables.jl: Tables.partitions produz lotes de tamanho_lote linhas (cada lote é um NamedTuple de vetores) e Tables.columns materializa tudo via materializar — então DataFrame(t), Arrow.write(io, t) e afins funcionam diretamente.

materializar(t::TabelaDBC) -> NamedTuple

Consome todas as partições e concatena as colunas. É o que DataFrame(t) chama por baixo via Tables.columns.

converter(entrada, saida; kwargs...)

Converte um .dbc/.dbf para Arrow em streaming (um record batch por lote), sem materializar o arquivo inteiro. Requer using Arrow na sessão (extensão condicional). Aceita os mesmos kwargs de ler.

descomprime_dbc_para_dbf(entrada, saida) -> saida

Converte .dbc → .dbf em streaming (equivalente ao dbc2dbf do read.dbc, memória constante).

baixar(sistema, uf; ano = nothing, mes = nothing,
       forcar = false, quieto = false) -> String

Baixa (com cache local via Scratch.jl) um arquivo do DATASUS e devolve o caminho no disco. Chamadas repetidas não rebaixam; forcar = true ignora o cache.

baixar(sistema, uf; anos, meses = nothing) -> Vector{String}

Forma plural: baixa vários períodos em paralelo (asyncmap).

url_arquivo(sistema, uf; ano = nothing, mes = nothing,
            prelim = false) -> String

URL FTP do arquivo .dbc no DATASUS. Sistemas anuais (:sim, :sinasc) pedem ano; mensais (:sih, :sia, :cnes) pedem ano e mes. prelim = true aponta para a pasta de dados preliminares (anos ainda não consolidados; só :sim e :sinasc).

Ex.: url_arquivo(:sim, "PE"; ano = 2023) → .../SIM/CID10/DORES/DOPE2023.dbc.

baixar_sinan(agravo; ano, prelim = false, forcar = false,
             quieto = false) -> String
baixar_sinan(agravo; anos, kwargs...) -> Vector{String}

Baixa (com cache) o arquivo nacional do SINAN de um agravo. Se prelim não for informado e o arquivo FINAIS não existir, tenta automaticamente a pasta PRELIM (com aviso). Forma plural baixa vários anos em paralelo.

url_sinan(agravo; ano, prelim = false) -> String

URL FTP do arquivo NACIONAL do SINAN para um agravo. Os arquivos do SINAN cobrem o Brasil inteiro (DENGBR20.dbc), então não há UF — filtre por residência no ler (SG_UF/ID_MN_RESI). prelim = true aponta para a pasta de dados preliminares.

Agravos: :dengue, :chikungunya, :zika, :meningite, :tuberculose, :hanseniase, :hepatites, :violencia, … (ver MicroSUS._SINAN_AGRAVO).

Ex.: url_sinan(:dengue; ano = 2020) → .../SINAN/DADOS/FINAIS/DENGBR20.dbc.

limpar_cache()

Remove todos os .dbc baixados do cache local.

UFS

Siglas das 27 unidades federativas aceitas por url_arquivo e baixar.

fetch_datasus(fonte::Symbol; uf = :all, anos, meses = nothing,
              processar = true, cache = true, verbose = true) -> DataFrame

Baixa, descomprime, lê e concatena microdados públicos do DATASUS.

Argumentos

• fonte: identificador da fonte — ver fontes. Ex.: :SIM_DO, :SINASC, :SIH_RD, :SIA_PA, :CNES_ST, :SINAN_DENGUE;
• uf: sigla ("PE"), vetor de siglas (["PE", "BA"]) ou :all para as 27 unidades federativas. Ignorado em fontes de abrangência nacional (SINAN);
• anos: ano (2023) ou coleção de anos (2019:2023);
• meses: mês ou coleção de meses (1:12), obrigatório apenas para fontes mensais (SIH, SIA, CNES);
• processar: aplica a padronização da fonte quando disponível (process_sim, process_sinasc);
• cache: reutiliza arquivos já baixados (ver MicroSUS.limpar_cache);
• verbose: registra progresso via @info/@warn.

Arquivos ausentes no FTP (ano ainda não publicado para uma UF, mês sem partição extra) geram um @warn e são pulados; o resultado concatena tudo que foi encontrado, unindo colunas por nome (cols = :union). As colunas UF_ARQUIVO, ANO_ARQUIVO e, se aplicável, MES_ARQUIVO identificam a origem de cada linha.

Exemplos

# Óbitos de Pernambuco, 2019–2023, já padronizados
do_pe = fetch_datasus(:SIM_DO; uf = "PE", anos = 2019:2023)

# Nascidos vivos, PE e BA, sem padronização (códigos brutos)
dn = fetch_datasus(:SINASC; uf = ["PE", "BA"], anos = 2022, processar = false)

# Internações hospitalares de PE no primeiro semestre de 2024
rd = fetch_datasus(:SIH_RD; uf = "PE", anos = 2024, meses = 1:6)

# Dengue no Brasil inteiro (fonte nacional: uf é ignorada)
dengue = fetch_datasus(:SINAN_DENGUE; anos = 2024)

fontes() -> Vector{NamedTuple}

Lista as fontes de microdados disponíveis no pacote, com identificador, descrição, periodicidade, abrangência e faixa de anos.

Exemplo

using MicroSUS, DataFrames
DataFrame(fontes())

fonte(id::Symbol) -> FonteDATASUS

Devolve a especificação registrada da fonte id (ver fontes para a lista de identificadores disponíveis). Lança ArgumentError para um identificador desconhecido.

process_sim(df::DataFrame) -> DataFrame

Padroniza microdados do SIM (:SIM_DO): converte datas (DTOBITO, DTNASC, ...) para Date, rotula variáveis categóricas (sexo, raça/cor, estado civil, escolaridade, local de ocorrência, circunstância do óbito etc.) e cria IDADE_ANOS a partir do campo codificado IDADE.

Colunas ausentes no layout do ano são simplesmente ignoradas; a coluna original IDADE é preservada. Chamado automaticamente por fetch_datasus quando processar = true.

process_sinasc(df::DataFrame) -> DataFrame

Padroniza microdados do SINASC (:SINASC): converte datas (DTNASC, DTNASCMAE, ...) para Date, rotula variáveis categóricas (sexo, tipo de parto, gravidez, escolaridade e estado civil da mãe, raça/cor, consultas de pré-natal, local de nascimento) e converte numéricos armazenados como texto (PESO, IDADEMAE, APGAR1, APGAR5, SEMAGESTAC, ...).

Colunas ausentes no layout do ano são ignoradas. Chamado automaticamente por fetch_datasus quando processar = true.

process_sih(df::DataFrame) -> DataFrame

Padroniza microdados do SIH/SUS (:SIH_RD): rotula as variáveis categóricas de domínio fechado (SEXO, RACA_COR, IDENT, CAR_INT, MORTE) e cria IDADE_ANOS a partir de IDADE + COD_IDADE.

Colunas ausentes no layout do ano são ignoradas — o layout do SIH mudou em 2011, 2013 e 2014, e a rotina é escrita para sobreviver a isso. As colunas originais são preservadas.

Chamada automaticamente por fetch_datasus quando processar = true.

decodifica_idade_sim(s) -> Union{Missing,Float64}

Idade do SIM (campo IDADE, 3 dígitos: 1º = unidade, 2º–3º = valor) convertida para anos:

Ex.: "425" → 25.0; "501" → 101.0; "310" → 10/12; "999" → missing.

decodifica_idade_sinan(s) -> Union{Missing,Float64}

Idade do SINAN (campo NU_IDADE_N, 4 dígitos: 1º = unidade, 3º–4º = valor 0–99) convertida para anos. Mesma escala de unidades do SIM, mas com 4 dígitos: "4025" → 25.0; "3006" → 0.5 (6 meses); "2015" → 15/365.25 (15 dias); "5010" → 110.0; "999"/inválido → missing.

idade_sih(idade, cod_idade) -> Union{Int,Missing}

Idade em anos completos a partir do par IDADE + COD_IDADE do SIH. O COD_IDADE é a unidade: 0 minutos, 1 horas, 2 dias, 3 meses, 4 anos, 5 anos acima de 100 (IDADE = 5, COD_IDADE = 5 ⇒ 105 anos). Idades abaixo de um ano resultam em 0.

Diferente do SIM, onde unidade e valor vêm no mesmo campo de 3 dígitos (decodifica_idade_sim), aqui são duas colunas — por isso a função recebe dois argumentos.

Aceita tanto os valores já tipados pelo schema quanto o texto cru.

SCHEMAS :: Dict{Symbol,Dict{Symbol,Symbol}}

Registro de schemas por sistema (:sim, :sinasc, :sih, :sia, :cnes): campo → tipo lógico (:texto, :pool, :inteiro, :float, :data_ddmmyyyy, :data_yyyymmdd, :idade_sim). Campos ausentes caem na tipagem do DBF. Mutável de propósito — dá para estender em runtime: MicroSUS.SCHEMAS[:sim][:OCUP] = :texto.

detecta_sistema(caminho) -> Union{Nothing,Symbol}

Deduz o sistema pelo prefixo do nome do arquivo (DOPE2023.dbc → :sim, DNPE2023.dbc → :sinasc, RDPE2301.dbc → :sih, ...).

dv_ibge(cod6) -> Int

Dígito verificador do código de município IBGE (algoritmo módulo 10 com pesos alternados 1,2 e redução de produtos ≥ 10). Aceita Integer ou string de 6 dígitos. Ex.: dv_ibge(261110) == 1 (Petrolina → 2611101).

codigo7_ibge(cod6) -> Int

Código de 7 dígitos a partir do de 6 (SIM/SINASC usam 6; IBGE moderno usa 7). codigo7_ibge(261110) == 2611101.

codigo6_ibge(cod7; validar = true) -> Int

Código de 6 dígitos a partir do de 7, opcionalmente validando o dígito verificador.

capitulo_cid10(cod) -> Union{Nothing,NamedTuple}

Capítulo CID-10 de um código como "X954" ou "I219": (numeral = "XX", nome = "Causas externas ..."), ou nothing se o código for inválido/vazio.

eh_agressao(cid) -> Bool

true se a causa básica é agressão (homicídio): X85–Y09, mais Y87.1 (sequelas de agressões) — o recorte usual de CVLI a partir do SIM.

CabecalhoDBF

Cabeçalho de um DBF/DBC: contagem de registros, tamanhos do cabeçalho e do registro, language driver (ldid, decide o encoding) e os CampoDBF na ordem do arquivo (+ um índice por nome). Obtenha com MicroSUS.cabecalho sem ler nenhum dado.

CampoDBF

Descritor de um campo DBF: nome, tipo ('C' texto, 'N' numérico, 'D' data aaaammdd, 'F', 'L'), largura, decimais e offset (0-based dentro do registro; o byte 0 é a flag de deleção).

cabecalho(caminho) -> CabecalhoDBF

Lê apenas o cabeçalho de um .dbc ou .dbf (campos, larguras, contagem de registros), sem descomprimir nem tocar nos dados.

É o primeiro comando de qualquer análise multi-ano: o layout do DATASUS muda entre anos, e conferir treze cabeçalhos custa menos que uma leitura.

cab = cabecalho("RDPE2201.dbc")
cab.n_registros                              # 48562
[c.nome for c in cab.campos]                 # nomes disponíveis
:DIAGSEC1 in keys(cab.indice)                # o campo existe neste ano?

Para ler apenas as colunas que existem em cada arquivo de uma série, combine com ler(...; ignorar_ausentes = true).

dcl_descomprime(io::IO, sink) -> Int

Descomprime um fluxo PKWare DCL ("implode") lido de io, chamando sink(chunk::AbstractVector{UInt8}) com blocos de até 4096 bytes à medida que a janela enche. Retorna o total de bytes descomprimidos. Memória constante (janela de 4 KiB). Porte do blast.c.

dcl_descomprime(io::IO) -> Vector{UInt8}

Versão de conveniência que materializa tudo num vetor (para arquivos pequenos ou testes). Prefira a versão com sink em produção.