Metadata-Version: 2.5
Name: omnisus
Version: 0.2.1
Summary: Python library for ingesting Brazilian public health databases into DuckLake
Project-URL: Homepage, https://github.com/raphaelfh/omnisus
Project-URL: Documentation, https://raphaelfh.github.io/omnisus
Project-URL: Repository, https://github.com/raphaelfh/omnisus
Author-email: Raphael Federicci <rfh.federicci@gmail.com>
License: MIT
License-File: LICENSE
Keywords: brazil,datasus,duckdb,ducklake,epidemiology,health,polars
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.12
Requires-Dist: dbfread2<2.0,>=0.1.0
Requires-Dist: duckdb<2.0,>=1.5.5
Requires-Dist: httpx>=0.28.1
Requires-Dist: omnisus-dbf<0.3,>=0.2.0; (sys_platform == 'linux' and platform_machine == 'x86_64') or sys_platform == 'darwin' or (sys_platform == 'win32' and platform_machine == 'AMD64')
Requires-Dist: polars<2.0,>=1.44.2
Requires-Dist: pyarrow>=25.0.1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=13.8.0
Requires-Dist: structlog>=26.1.0
Requires-Dist: typer>=0.27.2
Requires-Dist: tzdata>=2026.3; sys_platform == 'win32'
Provides-Extra: dev
Requires-Dist: frictionless>=5.19.0; extra == 'dev'
Requires-Dist: hypothesis>=6.168.0; extra == 'dev'
Requires-Dist: marimo<0.26,>=0.25.0; extra == 'dev'
Requires-Dist: mypy>=2.3.1; extra == 'dev'
Requires-Dist: pre-commit>=4.6.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=5.3.0; extra == 'dev'
Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
Requires-Dist: pytest>=9.1.1; extra == 'dev'
Requires-Dist: respx>=0.23.1; extra == 'dev'
Requires-Dist: ruff>=0.16.6; extra == 'dev'
Requires-Dist: sqlglot>=30.18.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12.20260906; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.7.7; extra == 'docs'
Requires-Dist: mkdocs<2.0,>=1.6.1; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=1.0.6; extra == 'docs'
Provides-Extra: notebooks
Requires-Dist: marimo<0.26,>=0.25.0; extra == 'notebooks'
Requires-Dist: sqlglot>=30.18.0; extra == 'notebooks'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.3.5; extra == 'postgres'
Description-Content-Type: text/markdown

# omnisus

Importa bases públicas de saúde do Brasil (DATASUS, IBGE, CNES) para um lake
[DuckLake](https://ducklake.select), 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/>.*

> [!WARNING]
> **Trabalho em construção.** A API ainda pode mudar entre versões menores, e
> nem todo dicionário foi conferido contra o documento oficial. Antes de publicar um
> número, confira as contagens, as colunas e os rótulos (veja
> [Confira antes de usar](#confira-antes-de-usar)). Um rótulo errado é um bug:
> [abra uma issue](https://github.com/raphaelfh/omnisus/issues/new/choose).

## Instalação

Python 3.12 ou mais novo, com o [uv](https://docs.astral.sh/uv/):

```bash
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:

[![Abrir no Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/raphaelfh/omnisus/blob/main/notebooks/colab.ipynb)
[![Open in molab](https://molab.marimo.io/molab-shield.svg)](https://molab.marimo.io/github/raphaelfh/omnisus/blob/main/notebooks/sim_obitos.py)

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](https://raphaelfh.github.io/omnisus/pesquisa/).

Em Python:

```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](https://raphaelfh.github.io/omnisus/pesquisa/): qual base
  responde a cada pergunta, o que um registro representa e como citar.
- [Notebooks](https://github.com/raphaelfh/omnisus/blob/main/notebooks/README.md): um por base, com as mesmas seis etapas, que abrem no
  navegador pelo molab.
- [Getting Started](https://raphaelfh.github.io/omnisus/guides/getting-started/):
  onde fica o lake, Colab, linha de comando e lakes na nuvem.
- [Bases e argumentos](https://raphaelfh.github.io/omnisus/datasets/): 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](https://raphaelfh.github.io/omnisus/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:

  ```python
  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 que | Onde |
| --- | --- |
| Arquivo de origem de cada linha importada | `reader.publications()` e `sus.cite(reader)` num `sus.LakeReader()`: caminho no servidor, SHA-256, `snapshot_id` |
| Diretório do FTP de cada base | [Bases e argumentos](https://raphaelfh.github.io/omnisus/datasets/) |
| Dicionários (de-para de códigos, descrições, tipos) | [`src/omnisus/data/dicionarios/<base>.yaml`](https://github.com/raphaelfh/omnisus/tree/main/src/omnisus/data/dicionarios), campo `x-decode` |
| Documentos oficiais citados (PDF, TabWin), com URL e SHA-256 | [`src/omnisus/data/dicionarios/sources/registry.json`](https://github.com/raphaelfh/omnisus/blob/main/src/omnisus/data/dicionarios/sources/registry.json) |
| Tabelas CNV do TabWin de onde saem muitos rótulos | [`src/omnisus/data/dicionarios/sources/cnv/`](https://github.com/raphaelfh/omnisus/tree/main/src/omnisus/data/dicionarios/sources/cnv) |
| Auditorias que sustentam as regras (contagens, hashes, reprodução) | [`evidence/`](https://github.com/raphaelfh/omnisus/tree/main/evidence) |

O [dicionário de dados](https://raphaelfh.github.io/omnisus/dicionario/) explica como
ler esses arquivos e como conferir um rótulo.

## Como contribuir

Leia o [CONTRIBUTING.md](https://github.com/raphaelfh/omnisus/blob/main/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](https://github.com/raphaelfh/omnisus/blob/main/LICENSE).
