nowcasting-sus 1.1.0__tar.gz

nowcasting_sus-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcos Malveira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nowcasting_sus-1.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE
+include README.md

nowcasting_sus-1.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+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.** 🧬📈

nowcasting_sus-1.1.0/README.md

@@ -0,0 +1,184 @@
+# 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.** 🧬📈

nowcasting_sus-1.1.0/nowcasting_sus/__init__.py

@@ -0,0 +1,90 @@
+"""Nowcasting SUS — correção de atraso de notificação para dados do SINAN.
+
+Nowcasting bayesiano que estima o número real de casos em tempo real,
+corrigindo o atraso entre a data de início dos sintomas e a notificação.
+
+Módulos disponíveis:
+    - data: carga e preparação de dados SINAN
+    - models: modelos PyMC (base e com efeito dia da semana)
+    - plot: visualização dos resultados
+    - report: geração de boletim epidemiológico
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+from importlib.metadata import version as _version
+
+__all__ = [
+    "load_sinan",
+    "prepare_matrix",
+    "NowcastingModel",
+    "NowcastingModelDOW",
+    "plot_nowcasting",
+    "plot_panel",
+    "plot_dow_effect",
+    "generate_report",
+    "setup_logging",
+    "__version__",
+]
+
+try:
+    __version__ = _version("nowcasting-sus")
+except Exception:
+    __version__ = "1.0.0"
+
+
+def setup_logging(
+    level: int | str | None = None,
+    fmt: str | None = None,
+) -> logging.Logger:
+    """Configura o logger do pacote ``nowcasting_sus``.
+
+    Parameters
+    ----------
+    level : int or str, optional
+        Nível de logging. Pode ser ``logging.DEBUG``, ``"DEBUG"``, ``"INFO"``, etc.
+        Se ``None``, usa a variável de ambiente ``NOWCASTING_LOG_LEVEL`` ou ``INFO``.
+    fmt : str, optional
+        Formato da mensagem. Se ``None``, usa o formato padrão.
+
+    Returns
+    -------
+    logging.Logger
+        Logger configurado.
+    """
+    logger = logging.getLogger("nowcasting_sus")
+
+    # Só adiciona handler se ainda não houver
+    if logger.handlers:
+        return logger
+
+    if level is None:
+        level = os.environ.get("NOWCASTING_LOG_LEVEL", "INFO").upper()
+
+    if isinstance(level, str):
+        level = getattr(logging, level.upper(), logging.INFO)
+
+    logger.setLevel(level)
+
+    if fmt is None:
+        fmt = "[%(asctime)s] %(levelname)-8s %(name)s: %(message)s"
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setLevel(level)
+    handler.setFormatter(logging.Formatter(fmt, datefmt="%Y-%m-%d %H:%M:%S"))
+    logger.addHandler(handler)
+
+    return logger
+
+
+# Configura logging na importação do pacote
+_logger = setup_logging()
+
+from nowcasting_sus.data import load_sinan, prepare_matrix  # noqa: E402
+from nowcasting_sus.models import NowcastingModel, NowcastingModelDOW  # noqa: E402
+from nowcasting_sus.plot import plot_nowcasting, plot_panel, plot_dow_effect  # noqa: E402
+from nowcasting_sus.report import generate_report  # noqa: E402