omnisus

Importa bases públicas de saúde do Brasil (DATASUS, IBGE, CNES) para um lake DuckLake, no seu computador, no Google Drive ou na nuvem, com a procedência necessária para citar cada resultado.

Brazilian public health data (DATASUS, IBGE, CNES) in a DuckLake lake (on your computer, on Google Drive or in the cloud), with the provenance needed to cite it. Documentation: https://raphaelfh.github.io/omnisus/.

Instalação

Python 3.12 ou mais novo, com o uv:

uv add omnisus          # num projeto uv
uv pip install omnisus  # num ambiente virtual já criado

No Colab, !uv pip install -q omnisus. Sem uv, pip install omnisus. Para atualizar, uv pip install -U omnisus, ou uv sync --upgrade-package omnisus num projeto.

Em Linux x86_64, macOS (arm64/x86_64) e Windows x86_64 isso instala também o decodificador Rust omnisus-dbf. Nas demais plataformas, o Python decodifica os mesmos arquivos.

Início rápido

Sem instalar nada:

O Colab baixa os óbitos de Roraima em 2023, põe rótulos, confere as colunas e imprime a citação, com o lake opcionalmente no seu Google Drive. O molab abre os notebooks marimo de cada base. Outros caminhos (marimo no seu computador, Jupyter) estão em Comece aqui.

Em Python:

import omnisus as sus

dados = sus.load("sim_obitos", years=[2023], ufs=["RR"])             # baixa e devolve as linhas
dados = sus.label("sim_obitos", dados, columns=["sexo", "racacor"])  # + sexo_rotulo, racacor_rotulo
sus.check_columns("sim_obitos", dados)                               # vazios, códigos sem rótulo, datas

O lake fica em data/raw/ no diretório de trabalho, e um segundo load do mesmo recorte não baixa nada. Toda função documenta seus parâmetros com um exemplo: help(sus.load).

Para ir além:

• Guia do pesquisador: qual base responde a cada pergunta, o que um registro representa e como citar.
• Notebooks: um por base, com as mesmas seis etapas, que abrem no navegador pelo molab.
• Getting Started: onde fica o lake, Colab, linha de comando e lakes na nuvem.
• Bases e argumentos: cada base, com o que passar em years, ufs e months e quais colunas têm rótulo. É gerada do código a cada versão, como a API; help(sus.load) mostra o mesmo na versão instalada.

Confira antes de usar

• Contagens. Compare o total de linhas com o que o DATASUS publica (TabNet, painéis oficiais) antes de analisar. sus.check_columns mostra, por coluna, a proporção de vazios, os códigos que o dicionário não conhece e as datas mínima e máxima.

• Rótulos. Um código que o dicionário não conhece fica sem rótulo (None); ele nunca é adivinhado. Cada mapa de códigos diz se foi conferido no documento oficial:

  campo = next(f for f in sus.describe_dataset("sim_obitos")["fields"]
               if f["field"]["name"] == "sexo")
  [(c["status"], c["evidence"]) for c in campo["claims"] if c["target"] == "/field/codes"]
  # status: verified_in_source, conflicting ou unreviewed; evidence: documento e página
  

  Só use um rótulo unreviewed ou conflicting depois de conferir o documento você mesmo.

• Escopo das regras. Idade em anos, sexo e datas harmonizados só aparecem para os arquivos cujo SHA-256 foi auditado (describe_dataset(...)["analytics"]); os outros saem como publicados.

De onde vêm os dados e os rótulos

O dicionário de dados explica como ler esses arquivos e como conferir um rótulo.

Como contribuir

Leia o CONTRIBUTING.md. Em resumo: todo fato no código ou na documentação vem do servidor do DATASUS ou de um arquivo com SHA-256 registrado, todo teste roda sobre trechos de arquivos reais, e o repositório é público. Um rótulo errado, uma base que falta ou uma contagem que não bate com o DATASUS são boas primeiras issues.

Licença

MIT.