susflow 0.1.1__tar.gz

susflow-0.1.1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# Cache local da biblioteca
+.susflow/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testes
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Mapas FTP gerados
+tools/mapas/mapa_ftp_*.txt
+NEXT.md

susflow-0.1.1/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: susflow
+Version: 0.1.1
+Summary: Acesso programático aos dados do DATASUS
+Project-URL: Homepage, https://github.com/OncoAtlas/susflow
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: dbfread
+Requires-Dist: pandas
+Requires-Dist: pyreaddbc
+Description-Content-Type: text/markdown
+
+# SUSFlow
+
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Formato de Saída](https://img.shields.io/badge/output-pandas.DataFrame-orange.svg)](#)
+
+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](./docs/cnes.md)
+- [**PNI** — Programa Nacional de Imunizações](./docs/pni.md)
+- [**SIM** — Sistema de Informações sobre Mortalidade](./docs/sim.md)
+- [**SINAN** — Sistema de Informação de Agravos de Notificação](./docs/sinan.md)
+- [**SINASC** — Sistema de Informações sobre Nascidos Vivos](./docs/sinasc.md)
+- [**SIASUS** — Sistema de Informações Ambulatoriais do SUS](./docs/siasus.md) (Em breve)
+- [**SIHSUS** — Sistema de Informações Hospitalares do SUS](./docs/sihsus.md) (Em breve)
+
+---
+
+## Instalação
+
+Como o projeto está em desenvolvimento ativo, instale em modo editável (-e):
+
+```bash
+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
+
+```python
+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)
+
+```python
+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)
+
+```python
+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:
+
+```text
+~/.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:
+
+```python
+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:
+
+```python
+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:
+
+```bash
+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
+
+```text
+ ┌───────────────────────┐
+ │  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:
+
+```bash
+# 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!

susflow-0.1.1/README.md

@@ -0,0 +1,183 @@
+# SUSFlow
+
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Formato de Saída](https://img.shields.io/badge/output-pandas.DataFrame-orange.svg)](#)
+
+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](./docs/cnes.md)
+- [**PNI** — Programa Nacional de Imunizações](./docs/pni.md)
+- [**SIM** — Sistema de Informações sobre Mortalidade](./docs/sim.md)
+- [**SINAN** — Sistema de Informação de Agravos de Notificação](./docs/sinan.md)
+- [**SINASC** — Sistema de Informações sobre Nascidos Vivos](./docs/sinasc.md)
+- [**SIASUS** — Sistema de Informações Ambulatoriais do SUS](./docs/siasus.md) (Em breve)
+- [**SIHSUS** — Sistema de Informações Hospitalares do SUS](./docs/sihsus.md) (Em breve)
+
+---
+
+## Instalação
+
+Como o projeto está em desenvolvimento ativo, instale em modo editável (-e):
+
+```bash
+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
+
+```python
+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)
+
+```python
+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)
+
+```python
+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:
+
+```text
+~/.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:
+
+```python
+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:
+
+```python
+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:
+
+```bash
+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
+
+```text
+ ┌───────────────────────┐
+ │  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:
+
+```bash
+# 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!

susflow-0.1.1/docs/cnes.md

@@ -0,0 +1,160 @@
+# CNES — Cadastro Nacional de Estabelecimentos de Saúde
+
+Base FTP: `ftp.datasus.gov.br/dissemin/publicos/CNES/200508_/Dados/`
+
+---
+
+## Tipos de dados disponíveis
+
+| Tipo | Função | Retorno | Descrição |
+|------|--------|---------|-----------|
+| Por UF | `ler(uf, ano, mes)` | `DataFrame` | Dados cadastrais de um subtipo para uma UF |
+| Por UF | `baixar(uf, ano, mes)` | `Path` | Arquivo `.dbc` bruto |
+
+---
+
+## Subtipos disponíveis
+
+**Padrão de arquivo:** `{TYPE}/{TYPE}{UF}{YY}{MM}.dbc`  
+**Granularidade:** mensal / por UF  
+
+> O arquivo fica dentro de um subdiretório com o mesmo nome do subtipo:  
+> ex: `ST/STSP2501.dbc` → estabelecimentos de SP, janeiro de 2025.
+
+```python
+from susflow.systems import cnes
+
+# ver todos os subtipos disponíveis
+print(cnes.subtipos())
+
+# Estabelecimentos — subtipo padrão
+df = cnes.ler(uf="SP", ano=2025, mes=1)
+df = cnes.ler(uf="SP", ano=2025, mes=1, tipo="ST")
+
+# outros subtipos
+df = cnes.ler(uf="SP", ano=2025, mes=1, tipo="PF")   # profissionais
+df = cnes.ler(uf="RJ", ano=2024, mes=6, tipo="LT")   # leitos
+df = cnes.ler(uf="MG", ano=2023, mes=3, tipo="EQ")   # equipamentos
+
+# só baixar
+path = cnes.baixar(uf="SP", ano=2025, mes=1)
+path = cnes.baixar(uf="SP", ano=2025, mes=1, tipo="PF")
+
+# listar arquivos disponíveis
+cnes.listar()                       # todos os ST
+cnes.listar(uf="SP")                # ST de SP
+cnes.listar(uf="SP", tipo="PF")     # profissionais de SP
+```
+
+### Subtipos ativos
+
+| Tipo | Arquivo exemplo | Conteúdo | Cobertura |
+|------|----------------|----------|-----------|
+| `ST` | `STSP2501.dbc` | **Estabelecimentos** — identificação, localização, tipo | 2005–2026 |
+| `PF` | `PFSP2501.dbc` | **Profissionais de saúde** — vínculos e CBO | 2005–2026 |
+| `DC` | `DCSP2501.dbc` | Dados complementares do estabelecimento | 2005–2026 |
+| `EQ` | `EQSP2501.dbc` | Equipamentos disponíveis | 2005–2026 |
+| `SR` | `SRSP2501.dbc` | Serviços especializados ofertados | 2005–2026 |
+| `LT` | `LTSP0510.dbc` | Leitos (SUS e não-SUS) | 2005–2026 |
+| `HB` | `HBSP0703.dbc` | Habilitações e certificações | 2007–2026 |
+| `EF` | `EFSP0703.dbc` | Centros cirúrgicos e obstétricos | 2007–2026 |
+| `EP` | `EPSP0704.dbc` | Equipes de saúde (eSF, eAP, etc.) | 2007–2026 |
+| `RC` | `RCSP0703.dbc` | Regras contratuais | 2007–2026 |
+| `IN` | `INSP0711.dbc` | Incentivos financeiros | 2007–2026 |
+| `GM` | `GMSP1407.dbc` | Gestão e metas | 2014–2026 |
+
+### Subtipos encerrados (ainda disponíveis no FTP)
+
+| Tipo | Arquivo exemplo | Conteúdo | Cobertura | Observação |
+|------|----------------|----------|-----------|------------|
+| `EE` | `EESP0703.dbc` | Equipamentos e produções | 2007–2019 | Encerrado em dez/2019 |
+
+---
+
+## Principais variáveis por subtipo
+
+### ST — Estabelecimentos
+
+| Variável | Tipo | Descrição |
+|----------|------|-----------|
+| `CNES` | str | Código CNES (identificador único) |
+| `CODUFMUN` | str | Código IBGE do município |
+| `REGSAUDE` | str | Região de saúde |
+| `MICR_REG` | str | Microrregião de saúde |
+| `DISTRSAN` | str | Distrito sanitário |
+| `DISTRADM` | str | Distrito administrativo |
+| `TPGESTAO` | str | Tipo de gestão (M=municipal, E=estadual, D=dupla) |
+| `PF_PJ` | str | Pessoa física ou jurídica |
+| `CPF_CNPJ` | str | CPF ou CNPJ |
+| `NIV_DEP` | str | Nível de dependência |
+| `CNPJ_MAN` | str | CNPJ da mantenedora |
+| `ESFERA_A` | str | Esfera administrativa |
+| `ATIVIDAD` | str | Atividade de ensino/pesquisa |
+| `RETENCAO` | str | Tipo de retenção |
+| `NATUREZA` | str | Natureza jurídica |
+| `CLIENTEL` | str | Clientela atendida |
+| `TP_UNID` | str | Tipo de unidade |
+| `TURNO_AT` | str | Turno de atendimento |
+| `NIV_HIER` | str | Nível hierárquico |
+| `TERCEIRO` | str | Indicador de terceirização |
+| `COMPETEN` | str | Competência (AAAAMM) |
+
+### PF — Profissionais
+
+| Variável | Tipo | Descrição |
+|----------|------|-----------|
+| `CNES` | str | Código CNES do estabelecimento |
+| `CBO` | str | Código CBO da ocupação |
+| `NOMEPROF` | str | Nome do profissional |
+| `CNS_PROF` | str | CNS do profissional |
+| `CONSELHO` | str | Conselho profissional |
+| `REGISTRO` | str | Número de registro no conselho |
+| `VINCULAC` | str | Tipo de vínculo |
+| `SUBVINCUL` | str | Subtipo de vínculo |
+| `TP_SUS` | str | Atende pelo SUS |
+| `COMPETEN` | str | Competência (AAAAMM) |
+
+### LT — Leitos
+
+| Variável | Tipo | Descrição |
+|----------|------|-----------|
+| `CNES` | str | Código CNES do estabelecimento |
+| `TP_LEITO` | str | Tipo de leito |
+| `CODLEITO` | str | Código do leito |
+| `QT_EXIST` | str | Quantidade existente |
+| `QT_CONTR` | str | Quantidade contratada (SUS) |
+| `QT_SUS` | str | Quantidade SUS |
+| `COMPETEN` | str | Competência (AAAAMM) |
+
+---
+
+## Fluxo recomendado
+
+```
+1. Explorar o que existe
+   print(cnes.subtipos())              ← todos os subtipos e descrições
+   cnes.listar(uf="SP")                ← arquivos ST de SP disponíveis
+   cnes.listar(uf="SP", tipo="PF")     ← profissionais de SP
+
+2. Baixar os dados
+   df = cnes.ler(uf="SP", ano=2025, mes=1)              ← estabelecimentos
+   df = cnes.ler(uf="SP", ano=2025, mes=1, tipo="PF")   ← profissionais
+   df = cnes.ler(uf="SP", ano=2025, mes=1, tipo="LT")   ← leitos
+
+3. Combinar meses em série histórica
+   import pandas as pd
+   dfs = [cnes.ler(uf="SP", ano=2024, mes=m) for m in range(1, 13)]
+   df_ano = pd.concat(dfs, ignore_index=True)
+```
+
+---
+
+## Notas
+
+- Arquivos `.dbc` são DBF comprimidos com o algoritmo proprietário **blast** (PKWARE). A biblioteca descomprime automaticamente via `pyreaddbc`.
+- O ano usa **2 dígitos** e o mês **2 dígitos com zero à esquerda**: `STSP2501.dbc` = SP, janeiro de 2025.
+- O arquivo fica dentro de um subdiretório com o mesmo nome do subtipo — isso é tratado automaticamente pela biblioteca.
+- Cada subtipo tem sua própria cobertura temporal. Tentar baixar `EE` para 2022 levanta erro com a cobertura correta (2007–2019).
+- `ST` e `PF` são os subtipos mais usados: `ST` para análises de distribuição de estabelecimentos, `PF` para análises de força de trabalho em saúde.
+- O campo `CNES` é a chave de cruzamento entre todos os subtipos — use-o para enriquecer `ST` com dados de `LT`, `EQ`, `PF`, etc.
+- Para cruzar municípios com nomes, use `CADMUN.DBF` disponível no SIM (`sim.baixar_tabelas("CADMUN.DBF")`).

susflow-0.1.1/docs/pni.md

@@ -0,0 +1,76 @@
+# PNI — Programa Nacional de Imunizações
+
+Base FTP: `/dissemin/publicos/PNI/DADOS/`
+
+---
+
+## Tipos de dados disponíveis
+
+| Tipo   | Função            | Retorno     | Descrição                                      |
+| ------ | ----------------- | ----------- | ---------------------------------------------- |
+| Por UF | `ler(uf, ano)`    | `DataFrame` | Dados de imunização registrados na UF, por ano |
+| Por UF | `baixar(uf, ano)` | `Path`      | Arquivo `.DBF` bruto da UF                     |
+
+---
+
+## Dados por UF e Ano — `DADOS/`
+
+**Padrão de arquivo:** `DPNI{UF}{YY}.DBF` (Sufixo do ano com 2 dígitos)
+
+**Cobertura:** 1994–2019, todas as 27 UFs
+
+**Granularidade:** anual / por UF
+
+```python
+from susflow.systems import pni
+
+# Baixa (se necessário) e carrega os dados em um DataFrame
+df = pni.ler(uf="SP", ano=2015)
+
+# Apenas realiza o download do arquivo bruto
+path = pni.baixar(uf="RJ", ano=2010)
+
+# Lista os arquivos filtrando por uma UF específica
+arquivos = pni.listar(uf="PB")
+
+```
+
+### Principais variáveis do DataFrame
+
+> **Nota de Variabilidade:** Como a cobertura do PNI é extensa (1994–2019), a estrutura de colunas dos arquivos `.DBF` pode variar significativamente dependendo do período e das atualizações do sistema de informação do Ministério da Saúde. Abaixo estão listadas as variáveis base mais comuns encontradas nas séries históricas de coberturas vacinais e doses aplicadas:
+
+| Variável               | Tipo        | Descrição                                                             |
+| ---------------------- | ----------- | --------------------------------------------------------------------- |
+| `CODMUNRES` / `MUNCOD` | str         | Código IBGE do município (geralmente 6 dígitos)                       |
+| `CODVAC` / `VACCOD`    | str         | Código da vacina (ex: BCG, Poliomielite, Tríplice Viral)              |
+| `DOSE`                 | str         | Tipo/Número da dose (1ª dose, 2ª dose, reforço, dose única)           |
+| `FXETARIA` / `FAIXA`   | str         | Código identificador da faixa etária do vacinado                      |
+| `QTDE` / `NUM_DOSES`   | int / float | Quantidade de doses aplicadas registradas                             |
+| `COBER` / `COBERTURA`  | float       | Taxa de cobertura vacinal calculada para a região (quando disponível) |
+| `POPULACAO`            | int / float | População alvo estimada para o cálculo da cobertura                   |
+
+---
+
+## Fluxo recomendado
+
+```
+1. Explorar o que existe no FTP
+   pni.listar(uf="PB")                           ← lista todos os anos da Paraíba
+
+2. Baixar e processar os dados
+   df = pni.ler(uf="SP", ano=2015)               ← dados de imunização de SP em 2015
+
+3. Persistir localmente de forma otimizada
+   # Recomendado converter para Parquet após a leitura para melhorar a performance
+   df.to_parquet("pni_sp_2015.parquet", index=False)
+
+```
+
+---
+
+## Notas
+
+- **Formato dos Arquivos:** Diferente de outros sistemas do DATASUS (como o SINASC), os arquivos do PNI nesta pasta estão em formato **.DBF puro** (sem compressão proprietária _blast_). Eles são lidos diretamente pela biblioteca utilizando o `dbfread` interno do módulo `reader.py`.
+- **Regra de Sufixo do Ano:** O arquivo utiliza o ano com 2 dígitos (`YY`). Anos de 1994 a 1999 usam `94` a `99`, enquanto anos de 2000 a 2009 utilizam `00` a `09`. A normalização é feita de forma transparente pela biblioteca utilizando o operador `ano % 100`.
+- **Limites da Série Histórica:** A cobertura de dados deste diretório FTP encerra-se estritamente em **2019**. Não existem dados preliminares ou anos posteriores a este período mapeados neste módulo (`year_range: 1994–2019`). Tentativas de passar anos fora deste escopo resultarão em um `ValueError`.
+- **Códigos de Municípios:** Assim como no SINASC, os municípios são identificados por seus códigos IBGE. Caso precise realizar o cruzamento com o nome das localidades ou regionalizações de saúde, recomenda-se correlacionar com as tabelas auxiliares (`CADMUN`).