nowcasting-sus 1.1.0__py3-none-any.whl

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

nowcasting_sus/cli.py

@@ -0,0 +1,187 @@
+"""CLI para gerar relatório nowcasting com suporte a gráficos e modelo DOW."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+logger = logging.getLogger("nowcasting_sus.cli")
+
+
+def main():
+    """Ponto de entrada da CLI: ``nowcasting-report``.
+
+    Uso::
+
+        nowcasting-report dados.csv --agravo "Dengue" --grafico grafico.png
+        nowcasting-report dados.csv --modelo-dow --chains 6 --tune 2000
+        nowcasting-report dados.csv --dpi 300 --tema ggplot --formato svg
+    """
+    import argparse
+
+    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
+    from nowcasting_sus.report import generate_report
+
+    parser = argparse.ArgumentParser(
+        description="Nowcasting SUS — relatório epidemiológico com nowcasting bayesiano",
+        epilog="Exemplo: nowcasting-report dados.csv --agravo Dengue --grafico graf.png",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    # Argumento posicional obrigatório
+    parser.add_argument("csv", help="Caminho do CSV SINAN (colunas DT_SIN_PRI e DT_NOTIFIC)")
+
+    # Metadados epidemiológicos
+    parser.add_argument("--agravo", default="Chikungunya", help="Nome do agravo (default: Chikungunya)")
+    parser.add_argument("--uf", default="Bahia", help="Unidade federativa (default: Bahia)")
+    parser.add_argument("--cid", default="A92.0", help="Código CID-10 (default: A92.0)")
+
+    # Parâmetros de dados
+    parser.add_argument(
+        "--max-delay", type=int, default=30, metavar="DIAS",
+        help="Atraso máximo em dias (default: 30, range: 1-365)",
+    )
+    parser.add_argument(
+        "--min-year", type=int, default=None, metavar="ANO",
+        help="Ano mínimo para filtrar registros (ex: 2024)",
+    )
+    parser.add_argument(
+        "--date-onset", default="DT_SIN_PRI", metavar="COLUNA",
+        help="Nome da coluna com data de início dos sintomas (default: DT_SIN_PRI)",
+    )
+    parser.add_argument(
+        "--date-notif", default="DT_NOTIFIC", metavar="COLUNA",
+        help="Nome da coluna com data de notificação (default: DT_NOTIFIC)",
+    )
+
+    # Parâmetros do modelo
+    parser.add_argument(
+        "--modelo-dow", action="store_true",
+        help="Usar modelo com efeito de dia da semana (DOW)",
+    )
+    parser.add_argument(
+        "--chains", type=int, default=4, metavar="N",
+        help="Número de cadeias MCMC (default: 4)",
+    )
+    parser.add_argument(
+        "--tune", type=int, default=1000, metavar="N",
+        help="Iterações de tuning (default: 1000)",
+    )
+    parser.add_argument(
+        "--draws", type=int, default=1000, metavar="N",
+        help="Iterações amostradas por cadeia (default: 1000)",
+    )
+    parser.add_argument(
+        "--seed", type=int, default=42, metavar="N",
+        help="Semente aleatória (default: 42)",
+    )
+
+    # Parâmetros de saída
+    parser.add_argument(
+        "--output", "-o", default="./boletim_nowcasting.html",
+        metavar="ARQUIVO",
+        help="Caminho do relatório HTML (default: ./boletim_nowcasting.html)",
+    )
+    parser.add_argument(
+        "--grafico", default=None, metavar="ARQUIVO",
+        help="Caminho para salvar gráfico nowcasting (PNG/SVG/PDF)",
+    )
+    parser.add_argument(
+        "--painel", default=None, metavar="ARQUIVO",
+        help="Caminho para salvar painel diagnóstico (PNG/SVG/PDF)",
+    )
+    parser.add_argument(
+        "--dpi", type=int, default=150, metavar="N",
+        help="Resolução dos gráficos em DPI (default: 150)",
+    )
+    parser.add_argument(
+        "--tema", default="default", metavar="NOME",
+        help="Tema matplotlib ou interno (default, clean, dark, ggplot, seaborn-v0_8, etc.)",
+    )
+    parser.add_argument(
+        "--formato", default="png", metavar="EXT",
+        help="Formato dos gráficos: png, svg, pdf (default: png)",
+    )
+
+    args = parser.parse_args()
+
+    try:
+        # 1. Carregar dados
+        logger.info("Carregando dados: %s", args.csv)
+        df = load_sinan(
+            args.csv,
+            date_onset=args.date_onset,
+            date_notif=args.date_notif,
+            max_delay=args.max_delay,
+            min_year=args.min_year,
+        )
+        nmat, dates, obs_t, obs_d, counts = prepare_matrix(
+            df, max_delay=args.max_delay,
+        )
+
+        T, D = nmat.shape
+
+        # 2. Ajustar modelo
+        if args.modelo_dow:
+            import pandas as pd
+            dow = pd.to_datetime(dates).dayofweek.values  # type: ignore[attr-defined]
+            modelo = NowcastingModelDOW()
+            logger.info("Ajustando modelo DOW (%d cadeias)...", args.chains)
+            idata = modelo.fit(
+                obs_t, obs_d, counts, T=T, D=D,
+                dow=dow,
+                draws=args.draws, tune=args.tune,
+                chains=args.chains, random_seed=args.seed,
+            )
+        else:
+            modelo = NowcastingModel()
+            logger.info("Ajustando modelo base (%d cadeias)...", args.chains)
+            idata = modelo.fit(
+                obs_t, obs_d, counts, T=T, D=D,
+                draws=args.draws, tune=args.tune,
+                chains=args.chains, random_seed=args.seed,
+            )
+
+        median, low, high = modelo.get_nowcast_ci()
+
+        # 3. Gerar relatório HTML
+        logger.info("Gerando relatório HTML...")
+        generate_report(
+            nmat, median, low, high, dates,
+            agravo=args.agravo, uf=args.uf, cid=args.cid,
+            save_to=args.output,
+        )
+        print(f"[ok] Relatório: {args.output}")
+
+        # 4. Gráfico nowcasting (opcional)
+        if args.grafico:
+            fig = plot_nowcasting(
+                nmat, median, low, high, dates,
+                title=f"Nowcasting — {args.agravo}/{args.uf}",
+                save_to=args.grafico,
+                dpi=args.dpi, tema=args.tema, formato=args.formato,
+            )
+            print(f"[ok] Gráfico: {args.grafico}")
+
+        # 5. Painel diagnóstico (opcional)
+        if args.painel:
+            delay_p = idata.posterior["delay_p"].mean(dim=["chain", "draw"]).values
+            dow_eff = None
+            if args.modelo_dow:
+                dow_eff = modelo.get_dow_effect()
+            plot_panel(
+                nmat, median, low, high, delay_p, dates,
+                dow_effect=dow_eff,
+                save_to=args.painel,
+                dpi=args.dpi, tema=args.tema, formato=args.formato,
+            )
+            print(f"[ok] Painel: {args.painel}")
+
+    except KeyboardInterrupt:
+        logger.warning("Execução interrompida pelo usuário.")
+        sys.exit(1)
+    except Exception as exc:
+        logger.error("Erro na execução: %s", exc, exc_info=True)
+        sys.exit(1)

nowcasting_sus/data.py

@@ -0,0 +1,321 @@
+"""Carga e preparação de dados SINAN para nowcasting."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+
+__all__ = ["load_sinan", "prepare_matrix"]
+
+logger = logging.getLogger("nowcasting_sus.data")
+
+
+def _validate_types(
+    filepath: str,
+    date_onset: str,
+    date_notif: str,
+    max_delay: int,
+    min_year: int | None,
+) -> None:
+    """Valida tipos e ranges dos parâmetros de ``load_sinan``.
+
+    Raises
+    ------
+    TypeError
+        Se algum parâmetro tiver tipo inesperado.
+    ValueError
+        Se algum parâmetro estiver fora do range válido.
+    """
+    if not isinstance(filepath, str):
+        raise TypeError(
+            f"filepath deve ser str, recebeu {type(filepath).__name__}: {filepath!r}"
+        )
+    if not isinstance(date_onset, str):
+        raise TypeError(
+            f"date_onset deve ser str, recebeu {type(date_onset).__name__}: {date_onset!r}"
+        )
+    if not isinstance(date_notif, str):
+        raise TypeError(
+            f"date_notif deve ser str, recebeu {type(date_notif).__name__}: {date_notif!r}"
+        )
+    if not isinstance(max_delay, (int, np.integer)):
+        raise TypeError(
+            f"max_delay deve ser int, recebeu {type(max_delay).__name__}: {max_delay!r}"
+        )
+    if max_delay < 1 or max_delay > 365:
+        raise ValueError(
+            f"max_delay deve estar entre 1 e 365, recebeu {max_delay}"
+        )
+    if min_year is not None:
+        if not isinstance(min_year, (int, np.integer)):
+            raise TypeError(
+                f"min_year deve ser int | None, recebeu {type(min_year).__name__}: {min_year!r}"
+            )
+        if min_year < 1900 or min_year > 2100:
+            raise ValueError(
+                f"min_year deve estar entre 1900 e 2100, recebeu {min_year}"
+            )
+
+
+def load_sinan(
+    filepath: str,
+    date_onset: str = "DT_SIN_PRI",
+    date_notif: str = "DT_NOTIFIC",
+    max_delay: int = 30,
+    min_year: Optional[int] = None,
+) -> pd.DataFrame:
+    """Carrega e valida dados SINAN para nowcasting.
+
+    Parameters
+    ----------
+    filepath : str
+        Caminho do CSV com dados do SINAN.
+    date_onset : str
+        Nome da coluna com data de início dos sintomas (default: ``DT_SIN_PRI``).
+    date_notif : str
+        Nome da coluna com data de notificação (default: ``DT_NOTIFIC``).
+    max_delay : int
+        Atraso máximo em dias para filtrar (default: 30). Deve estar entre 1 e 365.
+    min_year : int, optional
+        Ano mínimo para filtrar (útil para remover registros antigos).
+        Deve estar entre 1900 e 2100.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame com colunas ``onset``, ``notif``, ``delay``.
+
+    Raises
+    ------
+    FileNotFoundError
+        Se o arquivo não existir.
+    ValueError
+        Se colunas obrigatórias estiverem ausentes, ou se nenhum registro
+        for válido após filtragem.
+    TypeError
+        Se tipos dos parâmetros estiverem incorretos.
+    """
+    _validate_types(filepath, date_onset, date_notif, max_delay, min_year)
+
+    logger.info("Carregando dados: %s", filepath)
+
+    try:
+        df = pd.read_csv(filepath, low_memory=False, encoding="utf-8")
+    except FileNotFoundError:
+        raise
+    except UnicodeDecodeError:
+        logger.warning("UTF-8 falhou, tentando encoding latin1...")
+        df = pd.read_csv(filepath, low_memory=False, encoding="latin1")
+    except Exception as exc:
+        raise ValueError(
+            f"Não foi possível ler o arquivo {filepath!r}: {exc}"
+        ) from exc
+
+    required = [date_onset, date_notif]
+    missing = [c for c in required if c not in df.columns]
+    if missing:
+        raise ValueError(
+            f"Colunas obrigatórias ausentes no arquivo {filepath!r}: {missing}. "
+            f"Colunas disponíveis: {list(df.columns[:20])}..."
+        )
+
+    df = df[[date_onset, date_notif]].copy()
+    df.columns = ["onset", "notif"]
+
+    # Converter datas — tenta formato automático
+    for col in ["onset", "notif"]:
+        df[col] = pd.to_datetime(df[col], dayfirst=False, errors="coerce")
+
+    # Se dayfirst=False falhou, tenta dayfirst=True
+    first_col = "onset"
+    if df[first_col].isna().sum() > len(df) * 0.5:
+        logger.info("dayfirst=False produziu muitos NaT, tentando dayfirst=True...")
+        for col in ["onset", "notif"]:
+            df[col] = pd.to_datetime(df[col], dayfirst=True, errors="coerce")
+
+    # Verificar se há datas mínimas plausíveis
+    valid_dates = df["onset"].dropna()
+    if len(valid_dates) > 0:
+        min_date = valid_dates.min()
+        if min_date < pd.Timestamp("1900-01-01"):
+            logger.warning(
+                "Datas muito antigas detectadas (mín: %s). Verifique o formato das datas.",
+                min_date,
+            )
+        if min_date > pd.Timestamp("2000-01-01") and len(valid_dates) < len(df) * 0.1:
+            logger.warning(
+                "Menos de 10%% das datas de onset são posteriores a 2000. "
+                "Possível erro de formato ou encoding."
+            )
+
+    # Remover nulos
+    before = len(df)
+    df = df.dropna(subset=["onset", "notif"])
+    n_invalid = before - len(df)
+    if n_invalid > 0:
+        ratio = n_invalid / before * 100
+        logger.warning(
+            "%d registros removidos por data inválida (%.1f%% do total)",
+            n_invalid, ratio,
+        )
+        if ratio > 50:
+            logger.warning(
+                "Mais de 50%% dos registros têm datas inválidas. "
+                "Verifique o formato das colunas %r e %r.",
+                date_onset, date_notif,
+            )
+
+    # Calcular delay em dias
+    df["delay"] = (df["notif"] - df["onset"]).dt.days
+
+    # Filtrar delays válidos
+    n_before_filter = len(df)
+    df = df[(df["delay"] >= 0) & (df["delay"] <= max_delay)].copy()
+
+    n_removed = n_before_filter - len(df)
+    if n_removed > 0:
+        logger.info(
+            "%d registros removidos por delay fora do intervalo [0, %d]",
+            n_removed, max_delay,
+        )
+
+    df = df.sort_values("onset").reset_index(drop=True)
+
+    if min_year is not None:
+        before_year = len(df)
+        df = df[df["onset"].dt.year >= min_year]
+        removed = before_year - len(df)
+        if removed > 0:
+            logger.info(
+                "%d registros removidos por ano < %d", removed, min_year
+            )
+
+    if len(df) == 0:
+        raise ValueError(
+            "Nenhum registro válido após filtragem. "
+            f"Verifique: max_delay={max_delay}, min_year={min_year}, "
+            f"colunas {date_onset!r}/{date_notif!r}"
+        )
+
+    logger.info(
+        "%d registros carregados (%s a %s)",
+        len(df),
+        df["onset"].min().date(),
+        df["onset"].max().date(),
+    )
+    return df
+
+
+def prepare_matrix(
+    df: pd.DataFrame,
+    max_delay: int = 30,
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """Prepara matriz onset × delay para o modelo nowcasting.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        DataFrame com colunas ``onset`` e ``delay`` (saída de :func:`load_sinan`).
+    max_delay : int
+        Atraso máximo (default: 30). Deve estar entre 1 e 365.
+
+    Returns
+    -------
+    n_matrix : np.ndarray (T × D)
+        Matriz de contagem: ``n[t, d]`` = casos com onset no dia **t** e delay **d**.
+    dates : np.ndarray
+        Array de datas correspondentes a cada índice **t**.
+    obs_t : np.ndarray
+        Índices **t** das observações (para o modelo PyMC).
+    obs_d : np.ndarray
+        Índices **d** das observações.
+    counts : np.ndarray
+        Contagens observadas.
+
+    Raises
+    ------
+    TypeError
+        Se **df** não for ``pd.DataFrame``.
+    ValueError
+        Se colunas obrigatórias estiverem ausentes ou dados forem inválidos.
+    """
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError(
+            f"df deve ser pd.DataFrame, recebeu {type(df).__name__}"
+        )
+    if not isinstance(max_delay, (int, np.integer)):
+        raise TypeError(
+            f"max_delay deve ser int, recebeu {type(max_delay).__name__}: {max_delay!r}"
+        )
+    if max_delay < 1 or max_delay > 365:
+        raise ValueError(
+            f"max_delay deve estar entre 1 e 365, recebeu {max_delay}"
+        )
+
+    required_cols = ["onset", "delay"]
+    missing = [c for c in required_cols if c not in df.columns]
+    if missing:
+        raise ValueError(
+            f"Colunas obrigatórias ausentes no DataFrame: {missing}. "
+            f"Colunas disponíveis: {list(df.columns)}"
+        )
+
+    if len(df) == 0:
+        raise ValueError("DataFrame vazio — não é possível preparar a matriz.")
+
+    # Criar índice de dias únicos de onset
+    date_range = pd.date_range(
+        start=df["onset"].min(),
+        end=df["onset"].max(),
+        freq="D",
+    )
+    dates = date_range.values
+    T = len(dates)
+    D = max_delay + 1
+
+    date_to_idx = {d.date(): i for i, d in enumerate(date_range)}
+
+    # Montar índice (t, d) para cada caso
+    df = df.copy()
+    df["t"] = df["onset"].dt.date.map(date_to_idx)
+
+    # Garantir que todos os onset dates estão no índice
+    unlinked = df["t"].isna().sum()
+    if unlinked > 0:
+        logger.warning(
+            "%d registros não puderam ser mapeados para a grade temporal",
+            unlinked,
+        )
+        df = df.dropna(subset=["t"])
+
+    df["d"] = df["delay"].clip(0, max_delay).astype(int)
+    df["t"] = df["t"].astype(int)
+
+    # Agregar contagens
+    agg = df.groupby(["t", "d"], observed=True).size().reset_index(name="count")
+
+    # Matriz densa T × D
+    n_matrix = np.zeros((T, D), dtype=int)
+    n_matrix[agg["t"].values, agg["d"].values] = agg["count"].values
+
+    # Vetores esparsos para o modelo
+    obs_t = agg["t"].values.astype(int)
+    obs_d = agg["d"].values.astype(int)
+    counts = agg["count"].values.astype(int)
+
+    total = counts.sum()
+    logger.info(
+        "Matriz %d dias × %d delays (%s casos)",
+        T, D, _fmt_num(total),
+    )
+
+    return n_matrix, dates, obs_t, obs_d, counts
+
+
+def _fmt_num(n: int) -> str:
+    """Formata número inteiro com separador de milhar (ponto)."""
+    return f"{n:,}"