autohybts 1.0.0rc1__tar.gz

autohybts-1.0.0rc1/.gitignore

@@ -0,0 +1,36 @@
+*.md
+!README.md
+!.github/SECURITY.md
+docs/
+
+.venv/
+.venv-*/
+__pycache__/
+.ipynb_checkpoints/
+
+data/raw/
+artifacts/
+.claude/
+.agents/
+lightning_logs/
+
+# Tooling and build outputs
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+build/
+dist/
+*.egg-info/
+runs/
+
+# Documentation build and notebooks copied at build time
+documentation/_build/
+documentation/tutorials/notebooks/
+documentation/user_guide/_generated/
+documentation/en/tutorials/notebooks/
+documentation/en/user_guide/_generated/

autohybts-1.0.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 João Ataíde
+
+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.

autohybts-1.0.0rc1/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: autohybts
+Version: 1.0.0rc1
+Summary: Automated Hybrid Time Series Forecasting: guarded search and incremental selection of standalone and hybrid forecasters.
+Project-URL: Homepage, https://github.com/jvataidee/AutoHybTS
+Project-URL: Documentation, https://autohybts.readthedocs.io/
+Project-URL: Source, https://github.com/jvataidee/AutoHybTS
+Project-URL: Issues, https://github.com/jvataidee/AutoHybTS/issues
+Author: João Ataíde
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automl,forecasting,hybrid models,residual correction,time series
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Dist: scikit-learn>=1.4
+Provides-Extra: boosting
+Requires-Dist: catboost>=1.2; extra == 'boosting'
+Requires-Dist: lightgbm>=4; extra == 'boosting'
+Requires-Dist: xgboost>=2; extra == 'boosting'
+Provides-Extra: datasets
+Requires-Dist: rdata>=0.11; extra == 'datasets'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: packaging>=22; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.1; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.5.6; extra == 'docs'
+Requires-Dist: myst-nb>=1.1; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
+Requires-Dist: sphinx>=7.3; extra == 'docs'
+Provides-Extra: nixtla-stats
+Requires-Dist: statsforecast>=2; extra == 'nixtla-stats'
+Provides-Extra: notebook
+Requires-Dist: ipykernel>=6.29; extra == 'notebook'
+Requires-Dist: matplotlib>=3.10; extra == 'notebook'
+Requires-Dist: nbclient>=0.10; extra == 'notebook'
+Requires-Dist: nbformat>=5.10; extra == 'notebook'
+Provides-Extra: optuna
+Requires-Dist: optuna>=3.5; extra == 'optuna'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.10; extra == 'plot'
+Provides-Extra: stats
+Requires-Dist: statsmodels>=0.14; extra == 'stats'
+Provides-Extra: tensorflow
+Requires-Dist: packaging>=22; extra == 'tensorflow'
+Requires-Dist: tensorflow>=2.16; extra == 'tensorflow'
+Provides-Extra: torch
+Requires-Dist: packaging>=22; extra == 'torch'
+Requires-Dist: torch>=2.2; extra == 'torch'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jvataidee/AutoHybTS/main/figures/AutoHybTS.png" alt="AutoHybTS" width="260">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+">
+  <a href="https://autohybts.readthedocs.io/"><img src="https://readthedocs.org/projects/autohybts/badge/?version=latest" alt="Documentação"></a>
+  <a href="https://github.com/jvataidee/AutoHybTS/actions/workflows/ci.yml"><img src="https://github.com/jvataidee/AutoHybTS/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/jvataidee/AutoHybTS/blob/main/LICENSE"><img src="https://img.shields.io/badge/licen%C3%A7a-MIT-green.svg" alt="Licença MIT"></a>
+</p>
+
+# AutoHybTS
+
+**Automated Hybrid Time Series Forecasting.** Biblioteca Python que automatiza a comparação de modelos individuais de previsão e a descoberta de **sistemas híbridos residuais** (modelo-base + corretor do erro), aceitando complexidade adicional só quando critérios de validação temporal definidos pelo usuário são satisfeitos.
+
+A interface é inspirada no [PyCaret](https://pycaret.org) — um experimento, métodos curtos, resultados prontos para tabela e gráfico —, mas o foco é outro: reunir num só fluxo, com validação sem vazamento, os modelos híbridos residuais para previsão de séries temporais e as estratégias de montá-los (correção aditiva, vários estágios, decomposição, combinação).
+
+> **Status: candidata à v1 (`1.0.0rc1`).** A API funciona para uma série ou um painel de séries, nas variantes A (multipasso) e B (rolling de um passo com parâmetros congelados). Esta é uma pré-versão para validação; a `1.0.0` estável depende da conferência final e do estudo em séries reais. Veja as [notas e a política de compatibilidade](documentation/releasing.rst).
+
+## Instalação
+
+Requer Python 3.11 ou mais novo.
+
+Para testar o código antes da publicação da candidata, instale direto do repositório:
+
+```bash
+pip install "autohybts[stats,plot] @ git+https://github.com/jvataidee/AutoHybTS.git"
+```
+
+A publicação de `v1.0.0rc1` será feita primeiro no TestPyPI. As instruções para instalar
+a candidata pelo índice de testes estão nas [notas de release](documentation/releasing.rst).
+
+Para usar modelos próprios em PyTorch ou TensorFlow, acrescente os extras `torch` e/ou `tensorflow` (ex.: `autohybts[stats,plot,torch]`).
+
+## Início rápido
+
+```python
+from autohybts import AutoHybridExperiment, load_model, save_model
+from autohybts.datasets import get_data
+
+y = get_data("synthetic_daily")  # pd.Series diária
+exp = AutoHybridExperiment(fh=14, session_id=42).fit(y)  # sela os últimos 14 pontos
+
+result = exp.compare_models()  # busca em V_search + seleção incremental em V_select
+result.leaderboard  # todas as candidatas avaliadas na busca
+result.decisions  # cada desafiante (ex.: arima-mlp): aceito ou não, e por quê
+
+final = exp.finalize_model(result.best)  # reajuste no histórico anterior ao teste
+exp.predict_model(final).predictions  # previsões indexadas por data
+exp.evaluate_external(final).metrics  # teste selado, uma única vez
+
+path = save_model(final, "artifacts/champion")
+model = load_model(path, trusted=True)  # trusted=True: só para arquivos de confiança
+```
+
+Carregar um modelo executa código (pickle). Para artefatos que passam por outras mãos,
+assine com `save_model(..., signing_key=chave)` e confira com
+`load_model(..., signing_key=chave)`, ou fixe o hash com `load_model(..., sha256=...)`.
+
+### Estratégias de montar o sistema híbrido
+
+```python
+result = exp.compare_models(
+    include=("standalone", "residual", "multistage", "decomposition", "combination")
+)
+result.strategies  # melhor e mediana de cada estratégia
+result.plot("pareto")  # erro × custo; também x="complexity" e "strategies"
+
+exp.create_hybrid("arima", "mlp")  # ŷ = b + α·r̂
+exp.create_hybrid("arima", "mlp", extra_stages=["linear"])  # correção da correção
+exp.create_decomposition("linear", "mlp", method="ma")  # suave + volátil
+exp.create_combination(["arima", "knn"], weights="inverse_mse")
+exp.tune_model("knn", n_trials=20)  # só em V_search; Optuna se instalado
+```
+
+### Comparação e validação cruzada temporal
+
+```python
+cv = exp.cross_validate(folds=8, step=7)  # mesmas origens para todos os modelos
+cv.summary  # média, desvio, posto médio
+cv.tests()  # Wilcoxon e Diebold-Mariano com Holm (relatório)
+cv.plot("critical_difference")  # também: leaderboard, boxplot, win_rate, forecasts
+exp.nested_cross_validate(outer_folds=3)  # o procedimento inteiro, dobra a dobra
+```
+
+### Modelos próprios (PyTorch, TensorFlow, qualquer biblioteca)
+
+```python
+from autohybts.models import keras_model, keras_zoo, torch_model
+from autohybts.models.torch_zoo import LSTMNet, MambaNet
+
+exp.register_model(
+    "lstm",
+    torch_model(LSTMNet, hidden=32, lags=28, differencing=1),
+    family="deep",
+    requires={"torch": ">=2.2"},
+    version="1",
+)
+exp.register_model(
+    "mamba",
+    torch_model(MambaNet, d_model=32, lags=28, differencing=1),
+    family="deep",
+    requires={"torch": ">=2.2"},
+    version="1",
+)
+exp.register_model(
+    "keras_lstm",
+    keras_model(keras_zoo.lstm, units=32, lags=28),
+    family="deep",
+    requires={"tensorflow": ">=2.16"},
+    version="1",
+)
+# depois, os nomes valem em base_models, correctors, create_hybrid, tune_model ...
+```
+
+### Várias séries
+
+```python
+exp = AutoHybridExperiment(fh=14).fit({"loja_a": y_a, "loja_b": y_b})
+result = exp.compare_models()  # ranking pela média dos postos entre séries
+model = exp.finalize_model(result.best)  # PanelForecaster: um modelo por série
+exp.evaluate_external(model).metrics  # uma linha por série + média
+```
+
+## Datasets
+
+Copie o nome e passe para `get_data`; o resultado é uma `pd.Series` pronta para o `fit`.
+
+```python
+from autohybts.datasets import get_data
+
+y = get_data("ozone")
+```
+
+| Nome | O que é | Frequência | Pontos |
+|---|---|---|---|
+| `synthetic_daily` | sintética: tendência, sazonalidade semanal e ruído AR(1) (offline) | diária | 730 |
+| `white_noise_daily` | sintética: nível + ruído branco, controle negativo (offline) | diária | 730 |
+| `air_passengers` | passageiros aéreos, 1949–1960 | mensal | 144 |
+| `nottem` | temperatura em Nottingham, 1920–1939 | mensal | 240 |
+| `us_acc_deaths` | mortes acidentais nos EUA, 1973–1978 | mensal | 72 |
+| `sunspots_monthly` | manchas solares, 1749–1983 | mensal | 2820 |
+| `uk_gas` | consumo de gás no Reino Unido, 1960–1986 | trimestral | 108 |
+| `johnson_johnson` | lucro por ação da Johnson & Johnson, 1960–1980 | trimestral | 84 |
+| `ozone` | ozônio total em Halley Bay (Antártida), 1956–2000 | anual | 45 |
+| `nile` | vazão do rio Nilo, 1871–1970 | anual | 100 |
+| `lynx` | linces capturados no Canadá, 1821–1934 | anual | 114 |
+| `lake_huron` | nível do lago Huron, 1875–1972 | anual | 98 |
+| `sunspots` | manchas solares, 1700–1988 | anual | 289 |
+| `m4:D1` | M4: troque `D1` por `Y…`, `Q…`, `M…`, `W…`, `D…` ou `H…` (100 mil séries) | várias | — |
+| `m3:N1402` | M3: 3.003 séries; exige o extra `datasets` | várias | — |
+
+As sintéticas são geradas na hora. As outras são baixadas na primeira vez e ficam em cache
+(`~/.cache/autohybts/datasets`); as reais vêm do [Rdatasets](https://vincentarelbundock.github.io/Rdatasets/).
+
+Nas séries do M4 e do M3 o teste oficial da competição vem no fim; sele-o com `test_size`:
+
+```python
+from autohybts.datasets import load_benchmark
+
+series = load_benchmark("m4", subset="daily", series_id="D1")
+exp = AutoHybridExperiment(fh=series.descriptor.horizon, test_size=len(series.test)).fit(
+    series.full()
+)
+```
+
+Qualquer outra série do Rdatasets entra por `load_dataset`, dizendo qual coluna é o tempo,
+qual é o alvo e a frequência (veja a documentação, *Datasets*). A biblioteca não preenche
+valores ausentes: trate-os antes do `fit`.
+
+## Documentação e tutoriais
+
+- Documentação: <https://autohybts.readthedocs.io/>
+- Tutoriais em notebook, salvos com as saídas: [`notebooks/`](https://github.com/jvataidee/AutoHybTS/tree/main/notebooks)
+
+Para configurar a publicação no Read the Docs, veja
+[`Publicação no Read the Docs`](documentation/contributing.rst).
+O projeto em português (`/pt-br/latest/`) deve usar **Language: Portuguese (Brazil)**
+e **Build configuration file: `documentation/.readthedocs.yaml`**. O YAML da raiz
+(`.readthedocs.yaml`) compila a versão em inglês.
+
+## Princípios
+
+- Validade temporal antes de automação: nenhuma informação posterior à origem de previsão entra como feature, e o teste selado nunca alimenta busca ou seleção.
+- Seleção incremental guardada: um desafiante só substitui o campeão atual se superar critérios pareados de ganho e vitórias; caso contrário, a estrutura anterior (inclusive um modelo individual) é mantida.
+- Rastreabilidade: candidatas, tentativas e decisões têm identidade estável e ficam registradas, inclusive rejeições e falhas.
+
+## Limitações atuais
+
+- Decomposição, combinação fixa e estágios múltiplos só entram na busca quando pedidos em `compare_models(include=...)`; a CV aninhada é só para uma série; a seleção dinâmica (`dynamic`) só existe na variante B.
+- `compare_models` com o orçamento padrão (`small`), o espaço completo e 7 origens por camada leva alguns minutos numa série de ~700 pontos, sobretudo por causa do ARIMA com ordem automática; use `budget="smoke"`, `fold=3` ou `base_models=[...]` para explorar.
+- A regra de aceite (ganho mediano ≥ 5 %, vitórias ≥ 60 %, variabilidade ≥ 0,05, com 7 origens por camada quando a série comporta) foi calibrada em controles sintéticos: aceitou estruturas espúrias em 2–4 % das séries de ruído branco e ganhos reais em 54–56 % das séries com resíduo previsível. Não é controle de erro estatístico; em séries curtas, com menos origens, a taxa de falso aceite é maior (veja o guia de seleção).
+
+## Créditos
+
+Inspirada na ergonomia do [PyCaret](https://pycaret.org); o PyCaret não é dependência.
+
+## Licença
+
+[MIT](https://github.com/jvataidee/AutoHybTS/blob/main/LICENSE) © João Ataíde.

autohybts-1.0.0rc1/README.md

@@ -0,0 +1,200 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jvataidee/AutoHybTS/main/figures/AutoHybTS.png" alt="AutoHybTS" width="260">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+">
+  <a href="https://autohybts.readthedocs.io/"><img src="https://readthedocs.org/projects/autohybts/badge/?version=latest" alt="Documentação"></a>
+  <a href="https://github.com/jvataidee/AutoHybTS/actions/workflows/ci.yml"><img src="https://github.com/jvataidee/AutoHybTS/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/jvataidee/AutoHybTS/blob/main/LICENSE"><img src="https://img.shields.io/badge/licen%C3%A7a-MIT-green.svg" alt="Licença MIT"></a>
+</p>
+
+# AutoHybTS
+
+**Automated Hybrid Time Series Forecasting.** Biblioteca Python que automatiza a comparação de modelos individuais de previsão e a descoberta de **sistemas híbridos residuais** (modelo-base + corretor do erro), aceitando complexidade adicional só quando critérios de validação temporal definidos pelo usuário são satisfeitos.
+
+A interface é inspirada no [PyCaret](https://pycaret.org) — um experimento, métodos curtos, resultados prontos para tabela e gráfico —, mas o foco é outro: reunir num só fluxo, com validação sem vazamento, os modelos híbridos residuais para previsão de séries temporais e as estratégias de montá-los (correção aditiva, vários estágios, decomposição, combinação).
+
+> **Status: candidata à v1 (`1.0.0rc1`).** A API funciona para uma série ou um painel de séries, nas variantes A (multipasso) e B (rolling de um passo com parâmetros congelados). Esta é uma pré-versão para validação; a `1.0.0` estável depende da conferência final e do estudo em séries reais. Veja as [notas e a política de compatibilidade](documentation/releasing.rst).
+
+## Instalação
+
+Requer Python 3.11 ou mais novo.
+
+Para testar o código antes da publicação da candidata, instale direto do repositório:
+
+```bash
+pip install "autohybts[stats,plot] @ git+https://github.com/jvataidee/AutoHybTS.git"
+```
+
+A publicação de `v1.0.0rc1` será feita primeiro no TestPyPI. As instruções para instalar
+a candidata pelo índice de testes estão nas [notas de release](documentation/releasing.rst).
+
+Para usar modelos próprios em PyTorch ou TensorFlow, acrescente os extras `torch` e/ou `tensorflow` (ex.: `autohybts[stats,plot,torch]`).
+
+## Início rápido
+
+```python
+from autohybts import AutoHybridExperiment, load_model, save_model
+from autohybts.datasets import get_data
+
+y = get_data("synthetic_daily")  # pd.Series diária
+exp = AutoHybridExperiment(fh=14, session_id=42).fit(y)  # sela os últimos 14 pontos
+
+result = exp.compare_models()  # busca em V_search + seleção incremental em V_select
+result.leaderboard  # todas as candidatas avaliadas na busca
+result.decisions  # cada desafiante (ex.: arima-mlp): aceito ou não, e por quê
+
+final = exp.finalize_model(result.best)  # reajuste no histórico anterior ao teste
+exp.predict_model(final).predictions  # previsões indexadas por data
+exp.evaluate_external(final).metrics  # teste selado, uma única vez
+
+path = save_model(final, "artifacts/champion")
+model = load_model(path, trusted=True)  # trusted=True: só para arquivos de confiança
+```
+
+Carregar um modelo executa código (pickle). Para artefatos que passam por outras mãos,
+assine com `save_model(..., signing_key=chave)` e confira com
+`load_model(..., signing_key=chave)`, ou fixe o hash com `load_model(..., sha256=...)`.
+
+### Estratégias de montar o sistema híbrido
+
+```python
+result = exp.compare_models(
+    include=("standalone", "residual", "multistage", "decomposition", "combination")
+)
+result.strategies  # melhor e mediana de cada estratégia
+result.plot("pareto")  # erro × custo; também x="complexity" e "strategies"
+
+exp.create_hybrid("arima", "mlp")  # ŷ = b + α·r̂
+exp.create_hybrid("arima", "mlp", extra_stages=["linear"])  # correção da correção
+exp.create_decomposition("linear", "mlp", method="ma")  # suave + volátil
+exp.create_combination(["arima", "knn"], weights="inverse_mse")
+exp.tune_model("knn", n_trials=20)  # só em V_search; Optuna se instalado
+```
+
+### Comparação e validação cruzada temporal
+
+```python
+cv = exp.cross_validate(folds=8, step=7)  # mesmas origens para todos os modelos
+cv.summary  # média, desvio, posto médio
+cv.tests()  # Wilcoxon e Diebold-Mariano com Holm (relatório)
+cv.plot("critical_difference")  # também: leaderboard, boxplot, win_rate, forecasts
+exp.nested_cross_validate(outer_folds=3)  # o procedimento inteiro, dobra a dobra
+```
+
+### Modelos próprios (PyTorch, TensorFlow, qualquer biblioteca)
+
+```python
+from autohybts.models import keras_model, keras_zoo, torch_model
+from autohybts.models.torch_zoo import LSTMNet, MambaNet
+
+exp.register_model(
+    "lstm",
+    torch_model(LSTMNet, hidden=32, lags=28, differencing=1),
+    family="deep",
+    requires={"torch": ">=2.2"},
+    version="1",
+)
+exp.register_model(
+    "mamba",
+    torch_model(MambaNet, d_model=32, lags=28, differencing=1),
+    family="deep",
+    requires={"torch": ">=2.2"},
+    version="1",
+)
+exp.register_model(
+    "keras_lstm",
+    keras_model(keras_zoo.lstm, units=32, lags=28),
+    family="deep",
+    requires={"tensorflow": ">=2.16"},
+    version="1",
+)
+# depois, os nomes valem em base_models, correctors, create_hybrid, tune_model ...
+```
+
+### Várias séries
+
+```python
+exp = AutoHybridExperiment(fh=14).fit({"loja_a": y_a, "loja_b": y_b})
+result = exp.compare_models()  # ranking pela média dos postos entre séries
+model = exp.finalize_model(result.best)  # PanelForecaster: um modelo por série
+exp.evaluate_external(model).metrics  # uma linha por série + média
+```
+
+## Datasets
+
+Copie o nome e passe para `get_data`; o resultado é uma `pd.Series` pronta para o `fit`.
+
+```python
+from autohybts.datasets import get_data
+
+y = get_data("ozone")
+```
+
+| Nome | O que é | Frequência | Pontos |
+|---|---|---|---|
+| `synthetic_daily` | sintética: tendência, sazonalidade semanal e ruído AR(1) (offline) | diária | 730 |
+| `white_noise_daily` | sintética: nível + ruído branco, controle negativo (offline) | diária | 730 |
+| `air_passengers` | passageiros aéreos, 1949–1960 | mensal | 144 |
+| `nottem` | temperatura em Nottingham, 1920–1939 | mensal | 240 |
+| `us_acc_deaths` | mortes acidentais nos EUA, 1973–1978 | mensal | 72 |
+| `sunspots_monthly` | manchas solares, 1749–1983 | mensal | 2820 |
+| `uk_gas` | consumo de gás no Reino Unido, 1960–1986 | trimestral | 108 |
+| `johnson_johnson` | lucro por ação da Johnson & Johnson, 1960–1980 | trimestral | 84 |
+| `ozone` | ozônio total em Halley Bay (Antártida), 1956–2000 | anual | 45 |
+| `nile` | vazão do rio Nilo, 1871–1970 | anual | 100 |
+| `lynx` | linces capturados no Canadá, 1821–1934 | anual | 114 |
+| `lake_huron` | nível do lago Huron, 1875–1972 | anual | 98 |
+| `sunspots` | manchas solares, 1700–1988 | anual | 289 |
+| `m4:D1` | M4: troque `D1` por `Y…`, `Q…`, `M…`, `W…`, `D…` ou `H…` (100 mil séries) | várias | — |
+| `m3:N1402` | M3: 3.003 séries; exige o extra `datasets` | várias | — |
+
+As sintéticas são geradas na hora. As outras são baixadas na primeira vez e ficam em cache
+(`~/.cache/autohybts/datasets`); as reais vêm do [Rdatasets](https://vincentarelbundock.github.io/Rdatasets/).
+
+Nas séries do M4 e do M3 o teste oficial da competição vem no fim; sele-o com `test_size`:
+
+```python
+from autohybts.datasets import load_benchmark
+
+series = load_benchmark("m4", subset="daily", series_id="D1")
+exp = AutoHybridExperiment(fh=series.descriptor.horizon, test_size=len(series.test)).fit(
+    series.full()
+)
+```
+
+Qualquer outra série do Rdatasets entra por `load_dataset`, dizendo qual coluna é o tempo,
+qual é o alvo e a frequência (veja a documentação, *Datasets*). A biblioteca não preenche
+valores ausentes: trate-os antes do `fit`.
+
+## Documentação e tutoriais
+
+- Documentação: <https://autohybts.readthedocs.io/>
+- Tutoriais em notebook, salvos com as saídas: [`notebooks/`](https://github.com/jvataidee/AutoHybTS/tree/main/notebooks)
+
+Para configurar a publicação no Read the Docs, veja
+[`Publicação no Read the Docs`](documentation/contributing.rst).
+O projeto em português (`/pt-br/latest/`) deve usar **Language: Portuguese (Brazil)**
+e **Build configuration file: `documentation/.readthedocs.yaml`**. O YAML da raiz
+(`.readthedocs.yaml`) compila a versão em inglês.
+
+## Princípios
+
+- Validade temporal antes de automação: nenhuma informação posterior à origem de previsão entra como feature, e o teste selado nunca alimenta busca ou seleção.
+- Seleção incremental guardada: um desafiante só substitui o campeão atual se superar critérios pareados de ganho e vitórias; caso contrário, a estrutura anterior (inclusive um modelo individual) é mantida.
+- Rastreabilidade: candidatas, tentativas e decisões têm identidade estável e ficam registradas, inclusive rejeições e falhas.
+
+## Limitações atuais
+
+- Decomposição, combinação fixa e estágios múltiplos só entram na busca quando pedidos em `compare_models(include=...)`; a CV aninhada é só para uma série; a seleção dinâmica (`dynamic`) só existe na variante B.
+- `compare_models` com o orçamento padrão (`small`), o espaço completo e 7 origens por camada leva alguns minutos numa série de ~700 pontos, sobretudo por causa do ARIMA com ordem automática; use `budget="smoke"`, `fold=3` ou `base_models=[...]` para explorar.
+- A regra de aceite (ganho mediano ≥ 5 %, vitórias ≥ 60 %, variabilidade ≥ 0,05, com 7 origens por camada quando a série comporta) foi calibrada em controles sintéticos: aceitou estruturas espúrias em 2–4 % das séries de ruído branco e ganhos reais em 54–56 % das séries com resíduo previsível. Não é controle de erro estatístico; em séries curtas, com menos origens, a taxa de falso aceite é maior (veja o guia de seleção).
+
+## Créditos
+
+Inspirada na ergonomia do [PyCaret](https://pycaret.org); o PyCaret não é dependência.
+
+## Licença
+
+[MIT](https://github.com/jvataidee/AutoHybTS/blob/main/LICENSE) © João Ataíde.

autohybts-1.0.0rc1/notebooks/README.md

@@ -0,0 +1,67 @@
+# Tutoriais da AutoHybTS
+
+Notebooks no estilo dos tutoriais do PyCaret 4: curtos, numerados, um tema por notebook, usando a API orientada a objetos (`AutoHybridExperiment`). As cópias em inglês, célula a célula, estão em [`en/`](en/README.md); uma mudança num tutorial entra nos dois idiomas.
+
+| Notebook | Conteúdo | Requer |
+|---|---|---|
+| [01_quickstart](01_quickstart.ipynb) | Carregar uma série, comparar modelos, prever e avaliar no teste selado | etapa I8 |
+| [02_hybrid_selection](02_hybrid_selection.ipynb) | Busca em estágios, híbrido montado à mão, decisões de seleção, auditoria de tentativas, diagnósticos e eventos | etapas I8 e I11 |
+| [03_finalize_and_persist](03_finalize_and_persist.ipynb) | Finalizar, avaliar uma vez, salvar e carregar com manifesto, previsão operacional sem teste selado | etapa I8 |
+| [04_rolling_one_step](04_rolling_one_step.ipynb) | Variante B: previsão de um passo com parâmetros congelados e streaming de observações | etapa I10 |
+| [06_compare_and_cross_validate](06_compare_and_cross_validate.ipynb) | Ranking das finalistas, validação cruzada temporal, gráficos de comparação, testes estatísticos, comparação no teste selado e CV aninhada | — |
+| [07_panel](07_panel.ipynb) | Várias séries no mesmo experimento: ranking entre séries, seleção sobre o conjunto, um modelo por série e avaliação externa por série | — |
+| [08_advanced_families_and_tuning](08_advanced_families_and_tuning.ipynb) | Estágios extras, decomposição, combinação fixa, busca com todas as famílias e `tune_model` | — |
+| [09_ablation](09_ablation.ipynb) | Ablação do procedimento de seleção (§30.5): 4 procedimentos, mesmo orçamento e mesmos testes externos, em 12 séries sintéticas × 3 sementes, orçamento `small` | pesado (≈55 min) |
+| [10_external_models](10_external_models.ipynb) | Modelos próprios: PyTorch (LSTM, Transformer, Mamba, GRU escrito na hora), TensorFlow/Keras (LSTM, Transformer, convolução), Holt-Winters do statsmodels e gradient boosting, como bases, corretores, na busca, no ajuste e na persistência | extras `torch` e `tensorflow`; pesado |
+| [11_calibration](11_calibration.ipynb) | Calibração da regra de aceite em controles com resposta conhecida (ruído branco e resíduo previsível): falsos aceites, ganhos recusados, efeito do número de origens e do teste de Wilcoxon, conjunto de confirmação | — |
+| [12_baselines_and_boosting](12_baselines_and_boosting.ipynb) | Baselines (média histórica, média em janela, média sazonal em janela, passeio aleatório com drift), boosting sobre lags (HistGradientBoosting, AdaBoost.R2, LightGBM) como bases e corretores, RMAE e contagem de ajustes | LightGBM no extra `boosting` |
+| [13_ensembles](13_ensembles.ipynb) | Ensembles de candidatas completas (média, mediana, média aparada, inverso do MSE, NNLS com encolhimento), ensemble de híbridos, ensemble corrigido e ensembles na busca com a regra de aceite | — |
+| [14_intermittent_demand](14_intermittent_demand.ipynb) | Demanda intermitente: Croston-SBA, TSB, ADIDA e IMAPA contra médias simples, por que a RMSSE em vez da MASE, mudança de taxa, demanda que para e a família `intermittent` na busca | — |
+| [15_statsforecast](15_statsforecast.ipynb) | AutoARIMA, AutoETS, AutoTheta e AutoCES do StatsForecast contra statsmodels e baselines, parâmetros congelados (`forward`), os híbridos estatístico-ANN da replicação e a busca com esses modelos | extra `nixtla-stats` (traz pandas 2.x) |
+| [05_benchmark_m4](05_benchmark_m4.ipynb) | M4 com o teste oficial selado, painel do M3 e Rdatasets (baixa os dados na primeira execução) | rede na 1ª vez; extra `datasets` para o M3 |
+
+## Como executar
+
+```bash
+.venv/Scripts/python -m pip install -e ".[dev,stats,notebook]"
+```
+
+No VS Code, abra o notebook e selecione o kernel do `.venv`.
+
+## Estado
+
+| Notebook | Situação |
+|---|---|
+| 01_quickstart | roda (≈1–2 min com o orçamento padrão) |
+| 03_finalize_and_persist | roda (≈3–6 min: dois `compare_models`) |
+| 02_hybrid_selection | roda (≈1,5 min) |
+| 04_rolling_one_step | roda (≈2,5–4,5 min) |
+| 07_panel | roda |
+| 08_advanced_families_and_tuning | roda (≈1 min) |
+| 09_ablation | roda (≈55 min com o orçamento `small`); nos testes só com `AUTOHYBTS_RUN_HEAVY=1` |
+| 05_benchmark_m4 | roda (≈25 s com cache; o primeiro download do M4 diário tem ~100 MB) |
+| 06_compare_and_cross_validate | roda (≈50 s) |
+| 10_external_models | roda (≈6 min); nos testes só com `AUTOHYBTS_RUN_HEAVY=1` |
+| 11_calibration | roda (≈8 min) |
+| 12_baselines_and_boosting | roda (≈1,5 min) |
+| 13_ensembles | roda (≈4–5 min) |
+| 14_intermittent_demand | roda (≈15 s) |
+| 15_statsforecast | roda no ambiente com o extra `nixtla-stats` (pandas 2.x) |
+
+O teste `tests/integration/test_notebooks.py` executa cada notebook assim que todos os nomes listados em `metadata.autohybts.requires` existem no pacote:
+
+```bash
+.venv/Scripts/python -m pytest tests/integration/test_notebooks.py -m slow -rs
+```
+
+Notebooks marcados `heavy` só rodam com `AUTOHYBTS_RUN_HEAVY=1`; um notebook cujos `extras` (declarados nos metadados) não estão instalados é pulado com o nome do que falta.
+
+## Novo tutorial
+
+O esqueleto no modelo de aula, com os metadados já no esquema, sai de:
+
+```bash
+.venv/Scripts/python notebooks/new_notebook.py 15_temporal_bagging "Bagging temporal" --guide user_guide/ensembles --requires autohybts.AutoHybridExperiment.compare_models
+```
+
+As regras (seções, metadados, execução e saídas) estão em `documentation/contributing.rst`.

autohybts-1.0.0rc1/notebooks/en/README.md

@@ -0,0 +1,31 @@
+# AutoHybTS tutorials (English)
+
+English copies of the tutorials in `notebooks/` (Portuguese), cell by cell, with the same code, metadata and outputs. Each notebook is PyCaret-4 style: short, numbered, one topic per notebook, using the object-oriented API (`AutoHybridExperiment`).
+
+| Notebook | Content | Requires |
+|---|---|---|
+| [01_quickstart](01_quickstart.ipynb) | Load a series, compare models, forecast and evaluate on the sealed test | — |
+| [02_hybrid_selection](02_hybrid_selection.ipynb) | Staged search, a hand-built hybrid, selection decisions, trial audit, diagnostics and events | — |
+| [03_finalize_and_persist](03_finalize_and_persist.ipynb) | Finalize, evaluate once, save and load with a manifest, operational forecasting without a sealed test | — |
+| [04_rolling_one_step](04_rolling_one_step.ipynb) | Variant B: one-step forecasting with frozen parameters and streaming observations | — |
+| [05_benchmark_m4](05_benchmark_m4.ipynb) | M4 with the official test sealed, an M3 panel and Rdatasets (downloads the data on the first run) | network the first time; `datasets` extra for M3 |
+| [06_compare_and_cross_validate](06_compare_and_cross_validate.ipynb) | Ranking of the finalists, temporal cross-validation, comparison plots, statistical tests, comparison on the sealed test and nested CV | — |
+| [07_panel](07_panel.ipynb) | Several series in the same experiment: ranking across series, selection over the whole set, one model per series and external evaluation per series | — |
+| [08_advanced_families_and_tuning](08_advanced_families_and_tuning.ipynb) | Extra stages, decomposition, fixed combination, search with every family and `tune_model` | — |
+| [09_ablation](09_ablation.ipynb) | Ablation of the selection procedure (§30.5): 4 procedures, same budget and same external tests, on 12 synthetic series × 3 seeds, `small` budget | heavy (≈55 min) |
+| [10_external_models](10_external_models.ipynb) | Your own models: PyTorch (LSTM, Transformer, Mamba, a GRU written on the spot), TensorFlow/Keras (LSTM, Transformer, convolution), statsmodels' Holt-Winters and gradient boosting, as bases, correctors, in the search, in tuning and in persistence | `torch` and `tensorflow` extras; heavy |
+| [11_calibration](11_calibration.ipynb) | Calibration of the acceptance rule on controls with a known answer (white noise and predictable residual): false acceptances, rejected gains, effect of the number of origins and of the Wilcoxon test, confirmation set | — |
+| [12_baselines_and_boosting](12_baselines_and_boosting.ipynb) | Baselines, boosting on lags (HistGradientBoosting, AdaBoost.R2, LightGBM, XGBoost, CatBoost) as bases and correctors, RMAE and fit counts | `boosting` extra |
+| [13_ensembles](13_ensembles.ipynb) | Ensembles of complete candidates (mean, median, trimmed mean, inverse MSE, NNLS with shrinkage), ensemble of hybrids, corrected ensemble and ensembles in the search with the acceptance rule | — |
+| [14_intermittent_demand](14_intermittent_demand.ipynb) | Intermittent demand: Croston-SBA, TSB, ADIDA and IMAPA against simple means, why RMSSE instead of MASE, rate changes, demand that stops and the `intermittent` family in the search | — |
+| [15_statsforecast](15_statsforecast.ipynb) | StatsForecast's AutoARIMA, AutoETS, AutoTheta and AutoCES against statsmodels and baselines, frozen parameters (`forward`), the statistical-ANN hybrids of the replication and the search with these models | `nixtla-stats` extra (brings pandas 2.x) |
+
+## How to run
+
+```bash
+.venv/Scripts/python -m pip install -e ".[dev,stats,notebook]"
+```
+
+In VS Code, open the notebook and select the `.venv` kernel. Run the notebooks from this folder (`notebooks/en`); notebook 15 needs the environment with the `nixtla-stats` extra.
+
+A change to a tutorial goes into both languages; `tests/contracts/test_docs_translation.py` checks that every Portuguese notebook has an English copy with the same metadata. The rules (sections, metadata, execution and outputs) are in `documentation/en/contributing.rst`.