murabei_models — Dynamic Linear Models (DLM)

Pacote Python para modelos DLM com regressoras exógenas, incluindo ajuste, previsão, atualização online e backtesting, voltado para séries temporais de negócios.

Instalação

• Fonte local (desenvolvimento):

  • git clone <URL_DO_REPO>
  • cd <PASTA_DO_REPO>
  • pip install -r src/requirements/python_requirements.txt
  • bash build.bash
  • pip install dist/murabei_models-.tar.gz

• Requisitos principais (definidos no pyproject.toml e requirements):

  • pandas==2.3.1
  • numpy==2.3.2
  • statsmodels==0.14.5
  • scipy==1.16.1
  • tqdm==4.67.1
  • pyarrow==21.0.0
  • dynm (via URL zip: https://github.com/EduardoGPinheiro/dynm/archive/refs/tags/v0.0.2.zip)

Observações:

• Garanta acesso à Internet para instalar a dependência dynm via URL.
• Python mínimo recomendado conforme o ambiente do projeto (definir python_requires no empacotamento, se aplicável).

Exemplo rápido

Exemplo mínimo baseado em src/dlm/zzz__model_example.py com fit, predict, update e cross-validate:

import numpy as np
import pandas as pd
from dlm.model import DynamicLinearModel

# Dados sintéticos
np.random.seed(123)
n = 24
time = pd.date_range(start="2020-01-01", periods=n, freq="MS")
x1 = np.linspace(0, 1, n) + 0.1 * np.random.randn(n)
x2 = np.linspace(1, 0, n) + 0.1 * np.random.randn(n)
y = 0.7 * x1 - 0.4 * x2 + 0.1 * np.random.randn(n)

data = pd.DataFrame({"time": time, "y": y, "x1": x1, "x2": x2}).set_index("time")
y = data[["y"]]
X = data[["x1", "x2"]]

# Instancia e ajusta
dlm_model = DynamicLinearModel(
    trend=False,
    monitoring=True,
    start_predictions_at=12,
)
dlm_model.fit(X=X, y=y)

# Predição
X_new = np.array([[1.15, 0.05], [1.20, 0.04], [1.25, 0.03]])
y_pred = dlm_model.predict(X=X_new)

# Atualização online
y_new = 0.72
X_new = np.array([[1.18, 0.06]])
dlm_model.update(y=y_new, X=X_new)

# Backtesting / Cross-validation
dlm_model.cross_validate(X=X, y=y, K=12)

# Acessos úteis (atributos/métodos)
_ = dlm_model.get_predictive
_ = dlm_model.get_params
_ = dlm_model.get_monitor
_ = dlm_model.summary
_ = dlm_model.llk

Estrutura do projeto

• src/dlm/

  • model.py: implementação principal do modelo DLM
  • data/aux.py: utilitários de dados
  • update/intervention.py: rotinas de atualização/intervenções
  • utils/summary.py: sumários e utilidades
  • zzz__model_example.py: exemplo completo de uso

• src/tests/

  • test_template.py e data/00__data.parquet para reprodução local

• Empacotamento:

  • Layout src/, MANIFEST.in e package_data incluindo arquivos .parquet (dlm.data.examples)

• Automação e scripts:

  • bitbucket-pipelines.yml, build.sh, check_local_linter.bash

• Versionamento:

  • VERSION (usado no setup.py)
  • changelog.md

Desenvolvimento

• Estilo e lint:

  • Ruff habilitado com: Pyflakes (F), pycodestyle (E, W), pydocstyle (D, convenção Google), isort (I), pandas-vet (PD), pep8-naming (N), bandit (S)
  • Largura de linha: 79
  • ignore: E402, N806, I001

• Fluxo sugerido:

  • Criar venv e instalar localmente: pip install -e .
  • Lint: ./check_local_linter.bash
  • Testes: pytest em src/tests

Guia de uso

• Importação principal:

  • from dlm.model import DynamicLinearModel

• Fluxo típico:

  • Preparar X (regressoras) e y (alvo) como pandas/numpy
  • Ajustar: model.fit(X=X, y=y)
  • Prever: model.predict(X=X_new)
  • Atualizar online: model.update(y=y_new, X=X_new)
  • Backtesting: model.cross_validate(X=X, y=y, K=...)

• Atributos e diagnósticos:

  • model.get_predictive, model.get_params, model.get_monitor, model.summary, model.llk

Autores

Áurea Fonseca, Eduardo Pinheiro, Izabel Nolau e Lucas Ribeiro.

Build local