susflow 0.1.1

Acesso programático aos dados do DATASUS

SUSFlow

Biblioteca Python moderna para automação, download e engenharia de dados dos sistemas de informação do DATASUS. O susflow abstrai de forma transparente o protocolo FTP governamental, gerencia cache local, lida com a descompressão de arquivos proprietários .dbc e entrega dados limpos diretamente em estruturas do Pandas.

---

Sumário de Documentação Técnica

Os guias detalhados sobre layouts de arquivos, variáveis específicas e regras de cada sistema de informação estão localizados na pasta /docs. Navegue diretamente por aqui:

• CNES — Cadastro Nacional de Estabelecimentos de Saúde
• PNI — Programa Nacional de Imunizações
• SIM — Sistema de Informações sobre Mortalidade
• SINAN — Sistema de Informação de Agravos de Notificação
• SINASC — Sistema de Informações sobre Nascidos Vivos
• SIASUS — Sistema de Informações Ambulatoriais do SUS (Em breve)
• SIHSUS — Sistema de Informações Hospitalares do SUS (Em breve)

---

Instalação

Como o projeto está em desenvolvimento ativo, instale em modo editável (-e):

git clone [https://github.com/seu-usuario/susflow.git](https://github.com/seu-usuario/susflow.git)
cd susflow
pip install -e .

Requisitos Base

• pandas (Manipulação de dados)
• pyreaddbc (Motor de descompressão do algoritmo BLAST)
• dbfread (Leitor nativo de estruturas DBF)
• pyarrow / fastparquet (Opcional, altamente recomendado para cache de alta performance)

---

Como Usar (Exemplos Rápidos)

1. SINASC — Nascidos Vivos

from susflow.systems import sinasc

# Listar arquivos disponíveis no servidor FTP
sinasc.listar(uf="PB")

# Baixar e carregar diretamente em um DataFrame pronto para análise
df_sinasc = sinasc.ler(uf="SP", ano=2022)

2. PNI — Imunizações (Formato DBF Puro)

from susflow.systems import pni

# Cobertura histórica anual por UF (1994 a 2019)
df_pni = pni.ler(uf="RJ", ano=2015)

3. CNES — Estabelecimentos de Saúde (Granularidade Mensal)

from susflow.systems import cnes

# Leitura mensal parametrizada por tipo de tabela (ex: "ST" = Estabelecimentos)
df_cnes = cnes.ler(uf="MG", ano=2022, mes=5, tipo="ST")

---

Gerenciamento de Cache Inteligente

Para evitar sobrecarregar o servidor do DATASUS e acelerar seus scripts, o susflow implementa um cache local persistente em ~/.susflow/cache/, espelhando fielmente a árvore de diretórios do FTP original:

~/.susflow/cache/
└── dissemin/publicos/
    ├── SINASC/NOV/DNRES/DNSP2022.dbc
    ├── PNI/DADOS/DPNISP15.DBF
    └── CNES/200508_/Dados/ST/STPB2201.dbc

• Validação: Se o arquivo solicitado já existir no diretório local, a biblioteca pula o download e faz a leitura imediata.
• Sobrescrita: Para atualizar dados preliminares ou forçar uma nova cópia do servidor, utilize o parâmetro forcar=True:

df = sinasc.ler(uf="BA", ano=2023, forcar=True)

---

Dicas de Desempenho e Memória

Bases de dados de saúde pública do Brasil podem ser massivas, frequentemente congelando ou travando o Jupyter Notebook se não tratadas corretamente. Siga as boas práticas abaixo:

1. Otimização de Tipos (Downcasting): Converta colunas de strings altamente repetitivas (como códigos de UF, Sexo ou Municípios) para o tipo category do Pandas. Reduza tipos de inteiros int64 genéricos para int16 ou int8 no seu pipeline. Isso pode reduzir o consumo de RAM em até 80%.
2. Transição de Formato de Longo Prazo: Arquivos .DBF e .DBC são extremamente lentos para leitura analítica. Após efetuar o primeiro pni.ler() ou cnes.ler(), salve o DataFrame resultante em formato Parquet:

df.to_parquet("meus_dados.parquet", compression="snappy")

3. Ajuste do Jupyter IOPub: Se o seu Jupyter travar ao exibir ou processar DataFrames massivos, inicialize-o via terminal expandindo os limites de taxa de dados:

jupyter notebook --NotebookApp.iopub_data_rate_limit=1.0e10

---

Escopo e Mapeamento dos Sistemas

v1 — Matriz de Implementação Atual

Sistema	Sigla	Granularidade	Formato	Status
Sistema de Informações sobre Nascidos Vivos	SINASC	Anual / Por UF	.dbc	Concluído
Sistema de Informações sobre Mortalidade (Geral)	SIM	Anual / Por UF	.dbc	Concluído
Sistema de Informações sobre Mortalidade (Especial)	SIM	Anual / Nacional	.dbc	Concluído
Sistema de Informação de Agravos de Notificação	SINAN	Anual / Nacional	.dbc	Concluído
Cadastro Nacional de Estabelecimentos de Saúde	CNES	Mensal / Por UF	.dbc	Concluído
Programa Nacional de Imunizações	PNI	Anual / Por UF	.dbf	Concluído
Sistema de Informações Hospitalares	SIHSUS	Mensal / Por UF	.dbc	Planejado
Sistema de Informações Ambulatoriais	SIASUS	Mensal / Por UF	.dbc	Planejado

---

Engenharia Reversa do Fluxo de Dados

 ┌───────────────────────┐
 │  FTP DATASUS (.dbc)   │  <- Arquivo compactado no servidor público
 └──────────┬────────────┘
            │  (Susflow faz o download & valida cache)
            ▼
 ┌───────────────────────┐
 │ Descompressão BLAST   │  <- Traduz .dbc para .dbf estruturado em Python puro
 └──────────┬────────────┘
            │  (Motor de parsing do reader)
            ▼
 ┌───────────────────────┐
 │   Pandas DataFrame    │  <- Pronto para análise, gráficos e ML
 └───────────────────────┘

---

Ferramentas de Mapeamento (Diretório tools/)

O DATASUS frequentemente altera de forma silenciosa os caminhos ou padrões de nomenclatura de arquivos no FTP. A pasta tools/ contém scripts utilitários robustos para varredura e auditoria desses diretórios:

# Mapear e atualizar de forma automática os caminhos base da v1
python tools/mapear_ftp.py

# Executar mapeamento silencioso salvando o log estruturado em json/csv
python tools/mapear_ftp.py --salvar --quiet

# Auditar uma árvore de diretórios específica no FTP profundo
python tools/mapear_ftp.py --alvo /dissemin/publicos/SINAN/DADOS --profundo

---

Desenvolvido para simplificar a pesquisa epidemiológica e a ciência de dados em saúde no Brasil. Contribuições e pull requests são bem-vindos!