◆ Rust · dados da saúde pública brasileira

Arquivos .dbc do DATASUS, um leitor para todo lugar.

Um leitor para os arquivos dBase comprimidos que o DATASUS publica e três formas de usar: um crate Rust sem dependências, uma linha de comando que grava Parquet e CSV e um pacote Python que devolve tabelas Arrow.

CI crates.io PyPI DOI 10.5281/zenodo.24329435 Licença MIT

Um leitor pequeno que faz uma coisa só

O DATASUS distribui internações, produção ambulatorial, nascimentos, óbitos e cadastro de estabelecimentos em .dbc: um arquivo dBase III com os registros comprimidos pela PKWare Data Compression Library. Este projeto lê esses arquivos, e mais nada.

🦀

Núcleo sem dependências

O datasus-core usa só a biblioteca padrão: descompressão, detecção do contêiner e leitura do dBase. Compila rápido, tem pouco a auditar e é fácil de embutir.

🧩

Um núcleo, três interfaces

A linha de comando, o pacote Python e o seu código Rust chamam o mesmo leitor, então um arquivo é lido do mesmo jeito em todos.

🏹

Arrow de fábrica

Lotes tipados vão direto para Parquet, pyarrow, polars ou DuckDB. O Python recebe um fluxo pela interface PyCapsule do Arrow, sem cópias.

🎚️

Leia só o que precisa

Escolha colunas, limite as linhas, defina tipos, converta datas. Os campos não escolhidos são pulados, e não lidos para depois descartar.

🛡️

Seguro com arquivo ruim

Cabeçalhos malformados são recusados. A descompressão para no tamanho que o cabeçalho declara e nunca passa de 4 GiB, então um arquivo forjado não se expande sem limite.

🔁

Mesmo resultado em qualquer plataforma

Espaço em branco são os seis caracteres ASCII e Latin-1 é ISO-8859-1 estrito, seja qual for o locale ou o sistema operacional.

Instalar e usar

Escolha a interface que serve. Todas aceitam as mesmas opções: colunas a manter, máximo de linhas, remoção de espaços, codificação, inferência de tipos, tipos explícitos e conversão de datas.

Linha de comando

Converter para Parquet ou CSV, inspecionar, descomprimir.

$ brew install strategicprojects/tap/datasus
# ou
$ cargo install datasus-cli
# vários arquivos, um Parquet para cada (zstd)
$ datasus convert *.dbc --out-dir parquet/

# duas colunas, 1000 primeiras linhas, em CSV
$ datasus convert RDPE2401.dbc -o rd.csv \
    --select uf_zi,val_tot --n-max 1000

# de volta a um .dbf simples
$ datasus decompress RDPE2401.dbc

A saída é gravada num arquivo .part e renomeada no sucesso; para sobrescrever uma saída existente, use --force.

Python

datasuspy: wheels para Linux, macOS e Windows, Python 3.10 ou mais novo.

$ pip install datasuspy
import datasuspy

# um pyarrow.Table
table = datasuspy.read_dbc(
    "RDPE2401.dbc",
    select=["uf_zi", "val_tot"],
)
df = table.to_pandas()

import polars as pl
df = pl.from_arrow(
    datasuspy.read_dbc("RDPE2401.dbc"))

# em lotes, para qualquer consumidor de Arrow
reader = datasuspy.open_dbc(
    "RDPE2401.dbc", batch_size=100_000)

Opções e comportamento no PyPI.

Rust

datasus-core para o leitor, datasus-arrow para lotes Arrow. Rust 1.80 ou mais novo.

$ cargo add datasus-core
$ cargo add datasus-arrow
use datasus_core::{open, ReadOptions};

let opts = ReadOptions {
    parse_dates: true,
    ..ReadOptions::default()
};
let table = open("RDPE2401.dbc", &opts)?;
println!("{} linhas x {} colunas",
    table.n_rows(), table.n_cols());

// Vec<ColumnData>, um por coluna
let columns = table.collect();

Referência (em inglês): datasus-core · datasus-arrow, também no docs.rs.

Usa R? O pacote datasusr lê os mesmos arquivos em tibbles e tem o que este projeto deixa de fora de propósito: o catálogo das fontes do DATASUS, a listagem da FTP, os downloads e um cache.

Como funciona

O núcleo nunca decide onde os valores ficam. Ele lê um registro e entrega cada valor a um Sink; as colunas pertencem à interface.

O arquivo DBC é um cabeçalho dBase seguido de uma área de registros comprimida. O núcleo detecta o contêiner, descomprime os registros até o tamanho que o cabeçalho declara e os interpreta, gravando cada valor num sink fornecido pela interface: lotes Arrow para a linha de comando e o Python, ou buffers seus.
01

Detectar

DBC, DBC de arquivo inteiro, DBF simples ou DBF truncado: o formato é reconhecido pelos bytes.

02

Descomprimir

Uma tradução para Rust do blast.c de Mark Adler, com limite para a saída.

03

Tipar as colunas

Campos numéricos sem decimais são inteiros, a não ser que algum valor não caiba em 32 bits.

04

Encher o sink

Em lotes de qualquer tamanho, para que um arquivo grande nunca fique duas vezes na memória.

openfrom_bytesReadOptionsTableCursorSinkColumnDatadecode_with_limitblastdatasus_arrow::BatchReaderdatasus_arrow::schema

Registros marcados como apagados são descartados e n_max conta só os vivos. Colunas de texto nunca são nulas: campo em branco é string vazia. Campos de data são texto, a menos que parse_dates esteja ligado, e data inválida vira nulo. Um cabeçalho que declara mais registros do que o arquivo tem gera um aviso, não um erro.

Velocidade

Tempo para ler um arquivo inteiro para a memória, com todas as colunas, num notebook macOS arm64. Menor é melhor.

Segundos para ler um arquivo

Melhor de três execuções, exceto pyreaddbc + dbfread (uma execução, só no segundo arquivo).

datasuspy → pyarrow datasusr 0.1.1 (leitor C) → R pyreaddbc + dbfread → pandas

A comparação com o R não é de igual para igual: o R paga para criar as próprias strings, o Arrow não. Com o mesmo destino, uma versão experimental do datasusr sobre este núcleo leu 14 arquivos reais de 1,5 a 1,9 vez mais rápido que o leitor C. A linha de comando, que além de ler comprime e grava o Parquet, levou 1,68 s e 0,52 s nos dois arquivos acima (uma execução cada).

Conferido com o leitor C

O núcleo é um port do leitor C do pacote R datasusr (versão 0.1.1, no CRAN). Um script do repositório lê o mesmo arquivo com os dois e compara todos os valores: 140 de 140 comparações são idênticas, em arquivos sintéticos e em 11 reais (hospitalar, ambulatorial, estabelecimentos, tabelas territoriais), variando seleção de colunas, limite de linhas, tipos, datas, remoção de espaços e codificação.

Onde os dois diferem, de propósitoLeitor C no Rdatasus-rs
Espaços removidos de um campoisspace(): depende do locale; no macOS em UTF-8 também remove 0xA0Os seis espaços ASCII, em qualquer lugar
Texto Latin-1O R no macOS e no Windows converte como Windows-1252ISO-8859-1 estrito
Sequências inválidas com encoding = "utf-8"Mantidas como estãoTrocadas por U+FFFD
Campo numérico contendo 0x1A ou nan(...) (não ocorre nos arquivos do DATASUS)Lido como número, porque o strtod() aceitaNulo: só número decimal é número
✅

CI em três sistemas

clippy com -D warnings e os testes em Linux, macOS e Windows; o pacote Python é compilado e testado a cada push.

🧪

Os testes do R, portados

Os testes do leitor do datasusr rodam aqui também, em arquivos dBase sintéticos criados no próprio teste, mais casos de entrada truncada, preenchimento e limite de saída.

⚖️

MIT

O descompressor é uma tradução do blast.c de Mark Adler, distribuído sob a licença zlib. Cite o projeto pelo DOI.