Metadata-Version: 2.4
Name: nowcasting-sus
Version: 1.1.0
Summary: Nowcasting bayesiano para dados do SINAN — correção de atraso de notificação em tempo real
Author-email: Marcos Malveira <mvmlima@hotmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MVMLima/nowcasting-sus
Project-URL: Documentation, https://github.com/MVMLima/nowcasting-sus#readme
Project-URL: Repository, https://github.com/MVMLima/nowcasting-sus
Project-URL: Changelog, https://github.com/MVMLima/nowcasting-sus/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/MVMLima/nowcasting-sus/issues
Keywords: nowcasting,nowcast,bayesian,pymc,sinan,epidemiology,surveillance,health,dengue,chikungunya,arbovirus,brazil,sus,data-science,time-series,mcmc,markov-chain-monte-carlo
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Natural Language :: Portuguese (Brazilian)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: matplotlib>=3.7
Requires-Dist: pymc>=5.0
Requires-Dist: arviz>=0.16
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Dynamic: license-file

# nowcasting-sus

[![CI](https://github.com/MVMLima/nowcasting-sus/actions/workflows/ci.yml/badge.svg)](https://github.com/MVMLima/nowcasting-sus/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/nowcasting-sus)](https://pypi.org/project/nowcasting-sus/)
[![Python Versions](https://img.shields.io/pypi/pyversions/nowcasting-sus)](https://pypi.org/project/nowcasting-sus/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Nowcasting bayesiano para dados do SINAN** — correção de atraso de notificação em tempo real usando PyMC.

> ⚕️ Desenvolvido no Departamento de Vigilância em Saúde da Secretaria de Estado de Saúde do Acre
> Agora open source para qualquer equipe de vigilância do Brasil.

---

## O Problema

Os dados do SINAN chegam **atrasados**. Não por falha do sistema — é da natureza da notificação epidemiológica:

1. Um caso ocorre (data de início dos sintomas)
2. Leva **dias ou semanas** até ser digitado no SINAN
3. Se você olha o número **bruto** de hoje, está sempre subestimando a realidade

O **nowcasting** (ou "previsão do presente") resolve isso: modela o padrão histórico de atraso de notificação e estima quantos casos **já ocorreram mas ainda não foram notificados**.

---

## Instalação

```bash
pip install nowcasting-sus
```

**Requisitos:** Python ≥ 3.10, PyMC ≥ 5.0

---

## Uso Rápido

### Python

```python
from nowcasting_sus.data import load_sinan, prepare_matrix
from nowcasting_sus.models import NowcastingModel, NowcastingModelDOW
from nowcasting_sus.plot import plot_nowcasting, plot_panel

# 1. Carregar dados do SINAN (qualquer CSV com DT_SIN_PRI e DT_NOTIFIC)
df = load_sinan("dados_sinan.csv")

# 2. Preparar matriz onset × delay para o modelo
nmat, dates, obs_t, obs_d, counts = prepare_matrix(df)

# 3. Ajustar modelo nowcasting
modelo = NowcastingModel()
idata = modelo.fit(obs_t, obs_d, counts, T=nmat.shape[0], D=nmat.shape[1])

# 4. Obter estimativas corrigidas
median, low, high = modelo.get_nowcast_ci()
# median[t] = casos esperados no dia t (já corrigindo atraso)

# 5. Visualizar
fig = plot_nowcasting(nmat, median, low, high, dates)
```

### Modelo com Efeito de Dia da Semana (DOW)

```python
import pandas as pd

modelo_dow = NowcastingModelDOW()
dow = pd.to_datetime(dates).dayofweek.values  # 0=segunda .. 6=domingo
idata = modelo_dow.fit(obs_t, obs_d, counts, T=T, D=nmat.shape[1], dow=dow)

# Ver efeito de cada dia da semana
print(modelo_dow.get_dow_effect())
# Exemplo: {'Seg': 1.12, 'Dom': 0.65} → domingo tem 35% menos notificações
```

### CLI — Relatório HTML

```bash
nowcasting-report dados_sinan.csv --agravo "Chikungunya" --uf "Bahia" -o boletim.html
```

Gera um boletim epidemiológico completo com:
- Resumo executivo (observado × estimado × não notificados)
- Tabela com estimativas dos últimos 14 dias
- Interpretação automática dos resultados

---

## Modelos

| Modelo | Descrição | Quando usar |
|--------|-----------|-------------|
| `NowcastingModel` | Random Walk 1ª ordem + Negative Binomial | Uso geral, padrão |
| `NowcastingModelDOW` | RW1 + NB + efeito dia da semana (ZeroSumNormal) | Quando há padrão claro de menor notificação em fins de semana |

### Parâmetros Ajustáveis

| Parâmetro | Default | Descrição |
|-----------|---------|-----------|
| `sigma_rw` | 0.1 | Suavidade da tendência temporal (menor = mais suave) |
| `alpha_nb` | 10.0 | Dispersão da NegativeBinomial (maior = menos dispersão) |
| `alpha_scale` | 3.0 | Escala do prior Dirichlet para distribuição de atraso |
| `sigma_dow` | 0.3 | (DOW) Magnitude do efeito dia da semana |

---

## Estrutura do Pacote

```
nowcasting-sus/
├── nowcasting_sus/
│   ├── __init__.py    # Exporta API pública
│   ├── data.py        # Carga e preparação de dados SINAN
│   ├── models.py      # Modelos PyMC (NowcastingModel, NowcastingModelDOW)
│   ├── plot.py        # Visualização (curva, painel, efeito DOW)
│   ├── report.py      # Geração de boletim HTML
│   └── cli.py         # Interface de linha de comando
├── tests/             # Suite de testes (65+ testes, pytest)
├── examples/          # Exemplos de uso
├── .github/workflows/ # CI/CD automatizado
└── pyproject.toml     # Configuração do pacote
```

---

## Exemplo Completo

Veja [`examples/example_real.py`](examples/example_real.py) para um pipeline completo que:
1. Carrega dados do SINAN
2. Ajusta modelo base e modelo DOW
3. Gera gráfico de painel 2×3
4. Exporta relatório HTML

---

## API Detalhada

### `data.load_sinan(filepath, date_onset, date_notif, max_delay, min_year)`
Carrega CSV do SINAN, valida colunas, converte datas, calcula delay e filtra registros inválidos.

### `data.prepare_matrix(df, max_delay)`
Converte DataFrame em matriz `T × D` (dias de onset × dias de delay) para o modelo.

### `models.NowcastingModel.fit(obs_t, obs_d, counts, T, D, draws, tune, chains)`
Ajusta o modelo MCMC via PyMC. Retorna `arviz.InferenceData`.

### `models.NowcastingModel.get_nowcast_ci(prob=0.95)`
Retorna `(mediana, inferior, superior)` — estimativas nowcast na escala original (casos/dia).

### `plot.plot_nowcasting(...)`, `plot.plot_panel(...)`, `plot.plot_dow_effect(...)`
Funções de visualização. Todas retornam `matplotlib.figure.Figure`.

### `report.generate_report(...)`
Gera boletim epidemiológico em HTML. Aceita parâmetros personalizados (agravo, UF, CID).

---

## Contribuindo

Contribuições são bem-vindas!

1. Fork o repositório
2. Crie uma branch: `git checkout -b minha-feature`
3. Faça suas alterações
4. Execute os testes: `pytest tests/ -v`
5. Envie um PR

---

## Licença

MIT — use, modifique e distribua livremente. Atribuição apreciada.

---

## Contato

**Marcos Malveira** — mvmlima@hotmail.com

---

**Prefira dados corrigidos a dados atrasados.** 🧬📈
