Referência da API

Nota

Os docstrings abaixo estão em inglês: são a fonte única, escrita no código. As mensagens de erro e os avisos da biblioteca estão em português.

Experimento

class autohybts.AutoHybridExperiment(fh=14, session_id=42, fold='auto', fold_strategy='expanding', window_size=None, seasonal_period=None, test_size=None, profile='standard', variant='A', budget='small', max_trials=None, max_wall_time_s=None, base_models=None, correctors=None, residual_windows=None, alphas=None, residual_sources=None, base_params=None, corrector_params=None, max_stages=2, decomposition_methods=None, combination_weights=('equal', 'inverse_mse'), ensemble_methods=('equal', 'median', 'inverse_mse', 'nnls'), stage_params='shared', significance_alpha=None, differencing=None, differencing_test='kpss', seasonality_test='friedman', transform=None, outliers=None, missing='reject', exog_future=(), exog_lags=None, exog_selection=None, progress=False, metrics=('MASE', 'MAE', 'RMSE', 'sMAPE'), n_jobs=1, registry=None, median_gain_threshold=0.05, win_rate_threshold=0.6, variability_threshold=None, min_coverage=1.0, epsilon=1e-12)

Base: Parametrized

Automated comparison of standalone and residual hybrid forecasters.

Parâmetros:

• fh (int) – forecast horizon (steps per origin, and default horizon of predictions).

• session_id (int) – seed of the whole experiment.

• fold (int | str) – origins in each validation layer (V_search and V_select). "auto" (default) uses 7 when the history allows and otherwise the largest number that fits, with a warning: the acceptance rule is calibrated for 7 units on one series; with fewer it accepts spurious structures more often. An integer is used as given.

• fold_strategy (str) – "expanding" or "rolling" (needs window_size).

• window_size (int | None) – training window length of each origin with fold_strategy="rolling".

• seasonal_period (int | str | None) – None infers it from the frequency (daily: 7, monthly: 12 …). "auto" keeps that period for the metrics but tests the seasonality on the training vector of the earliest validation origin (data every origin has seen): when that vector has at least 6 cycles and shows no evidence of one, the search uses period 1, so seasonal models and the STL are skipped; with fewer cycles the period stays. seasonality_ holds the test.

• test_size (int | None) – points sealed at the end of the series; None means fh, 0 disables the sealed test (operational forecasting).

• profile (Profile) – "quickstart" (variability criterion off by default), "standard", "research_strict" or "exploratory".

• variant (ProtocolVariant) – forecasting protocol. "A" (default): each origin forecasts fh steps at once, and a corrector’s window is fed with its own predicted residuals. "B": rolling one-step forecasts with frozen parameters; each observation is revealed only after its forecast and its residual then enters the corrector window. Bases that cannot take new observations without refitting are skipped in B; "dynamic" selection exists only in B.

• budget (BudgetPreset) – search preset ("smoke", "small", "medium", "large").

• max_trials (int | None) – overrides the preset’s total number of candidates.

• max_wall_time_s (float | None) – optional search deadline in seconds (None: none, the default). Cooperative: no candidate starts after it, a running one finishes; candidates kept out are STOPPED in the ledger. With a deadline the searched set can change between machines; budgets by count are the reproducible ones.

• base_models (Sequence[str] | None) – search space (None keeps the default search space).

• correctors (Sequence[str] | None) – search space (None keeps the default search space).

• residual_windows (Sequence[int] | None) – search space (None keeps the default search space).

• alphas (Sequence[float] | None) – search space (None keeps the default search space).

• residual_sources (Sequence[str] | None) – search space (None keeps the default search space).

• base_params (Mapping[str, Sequence[Mapping[str, Any]]] | None) – grid of each base in stage S0, by model name: a list of parameter dicts, one candidate each (e.g. {"knn": [{"lags": 7}, {"lags": 14}]}). A base without a grid uses its search defaults.

• corrector_params (Mapping[str, Sequence[Mapping[str, Any]]] | None) – alternative settings of each corrector, tried in stage S3 (refinement) around the best residual structures; S2 uses each corrector’s defaults.

• max_stages (int) – most correction stages tried when compare_models includes "multistage" (2 or 3).

• decomposition_methods (Sequence[str] | None) – decompositions tried when compare_models includes "decomposition"; None means ("ma", "stl") in variant A and ("ma",) in variant B.

• combination_weights (Sequence[str]) – weightings tried when compare_models includes "combination".

• ensemble_methods (Sequence[str]) – aggregations tried when compare_models includes "ensemble" ("equal", "median", "trimmed_mean", "inverse_mse", "nnls"): ensembles of the best base of each family, of the two best residual structures and residual corrections of the equal-weight ensemble. Off the default include: see the calibration gate.

• stage_params (str) – "shared" (extra stages reuse window, alpha and source) or "per_stage" (the search also varies the extra stage’s window and alpha).

• significance_alpha (float | None) – optional extra acceptance predicate: a one-sided paired Wilcoxon test on V_select must give p < significance_alpha (off by default). It needs at least 5 paired units with different errors, all series together, for 0.05: with 3 origins on one series it can never pass. It controls each comparison, not the whole chain (see SelectionPolicy).

• differencing (str | None) – "auto" makes every built-in lag model of the search choose its differences on each origin’s training vector: one seasonal difference when the seasonality test finds a strong cycle (period search_period_), then d up to 2 by differencing_test. None (default) keeps each model’s own setting (no differencing), so candidate IDs do not change.

• differencing_test (str) – "kpss" (KPSS does not reject stationarity, as auto.arima) or "adf" (ADF rejects a unit root, as the replication project).

• seasonality_test (str) – rule of seasonal_period="auto": "friedman" (test by position in the cycle, at least 6 cycles to drop the period) or "strength" (the replication project: a series that ADF finds stationary has no seasonality; otherwise STL strength on the Box-Cox series above 0.5).

• transform (str | None) – "boxcox" or "log" makes every built-in lag model of the search fit the transform on each origin’s training data and invert its forecasts; None (default) leaves the target as observed (ADR-0009).

• outliers (str | None) – "winsorize" or "interpolate" treats points with robust z > 4 (against a rolling median) in each origin’s training data only; forecast contexts and metric targets stay as observed. None (default) keeps them.

• missing (str) – "reject" (default) refuses a series with missing values; "ffill" fills each gap with the last observed value (causal: only the past is used) and drops leading gaps. Filled points are scored as observed.

• exog_future (Sequence[str]) – exogenous columns of X known in advance (calendar, holidays, planned prices): used at the forecast date itself. Every other column is past and enters lagged by at least the steps forecast from one origin (max(fh, test_size) in variant A, 1 in variant B), so no value unknown at the origin reaches a forecast (ADR-0011). Declaring an observed value, such as the day’s temperature, as future makes the evaluation an oracle.

• exog_lags (Mapping[str, Sequence[int]] | None) – extra lags per exogenous column, e.g. {"temperature": [7, 14]} (past columns need lags >= the minimum above).

• exog_selection (str | Sequence[str] | None) – how the exogenous features are chosen. None (default): every column at its smallest causal lag. A method of autohybts.data.exog_selection ("ccf", "granger", "lasso", "stepwise_bic", "mutual_info", "vote") or a list of them: each chosen set is a candidate feature set. "auto": every method and the set with all columns; the search tries them and the selection decides, under the acceptance rule, whether any covariate enters. Methods run on the data before the first V_select origin, as tuning does on V_search; V_select and the sealed test never reach them (exog_report()).

• progress (bool) – True shows tqdm progress bars for each search stage, the finalists on V_select, the choice of exogenous features and the outer folds of the nested cross-validation (extra progress). Reporting only: nothing evaluated changes. Events also go to the logging logger "autohybts" either way.

• metrics (Sequence[str]) – evaluation metrics; the first one ranks and selects.

• n_jobs (int) – threads used to evaluate candidates in parallel.

• registry (ModelRegistry | None) – custom model registry (built-ins by default).

• median_gain_threshold (float) – minimum paired median gain, finite and nonnegative (default 0.05). A protocol threshold, not a significance level.

• win_rate_threshold (float) – minimum share of strict wins, in [0, 1] (default 0.60).

• variability_threshold (float | None) – finite nonnegative correction variability threshold. None inherits the profile: 0.05, or disabled in quickstart. An explicit number enables the criterion, including in quickstart.

• min_coverage (float) – required valid-unit coverage in (0, 1]; research_strict requires 1.0. Lower coverage can change which units are compared.

• epsilon (float) – finite positive floor in the relative-gain denominator (default 1e-12).

fit(y, X=None, *, series_col=None, date_col=None, target=None)

Validate y, seal the test segment and freeze the temporal plan.

y is one series (pd.Series or SeriesFrame) or a panel: a PanelFrame, a mapping series_id -> pd.Series or a long DataFrame with series_col, date_col and target named explicitly. In a panel every series keeps its own sealed test, origins and MASE scale; candidates are compared on all of them.

X (optional) holds exogenous covariates indexed by date: every date of y (sealed test included) and, for future columns, later dates to forecast beyond the data. In a panel, X is a mapping series_id -> DataFrame or a long DataFrame with the same series_col and date_col as y; every series needs the same columns. Their kinds and lags follow exog_future and exog_lags.

Parâmetros:

• y (Series | SeriesFrame | PanelFrame | Mapping[str, Series] | DataFrame)

• X (DataFrame | None)

• series_col (str | None)

• date_col (str | None)

• target (str | None)

Tipo de retorno:

AutoHybridExperiment

property is_panel: bool

property splits: DataFrame

Origins of V_search and V_select (the sealed test is not listed).

property events: tuple[Event, ...]

models()

Catalog of base models and correctors, with families and capabilities.

Tipo de retorno:

DataFrame

register_model(name, factory, *, kind='base', family='deep', requires=None, version='1', capabilities=None, description='', default_params=None, tuning_space=None, replace=False)

Add a model built outside AutoHybTS (PyTorch, TensorFlow, any library).

factory receives a parameter mapping and returns a fresh, unfitted model: torch_model(...)/keras_model(...) from autohybts.models, or any callable returning a BaseForecaster (kind="base") or a ResidualCorrector (kind="corrector"). A model instance is also accepted and cloned for every trial. Afterwards the name works everywhere: create_model, base_models/correctors of the search, hybrids, tune_model.

requires (e.g. {"torch": ">=2.2"}) is checked when the model is built; a missing or older library makes the trial SKIPPED. version names the registration and enters every trial key: change it when the model code changes. Can be called before or after fit; returns the experiment for chaining.

Parâmetros:

• name (str)

• factory (Callable[[Mapping[str, Any]], Any] | Any)

• kind (str)

• family (str)

• requires (Mapping[str, str] | None)

• version (str)

• capabilities (Capabilities | None)

• description (str)

• default_params (Mapping[str, Any] | None)

• tuning_space (Mapping[str, Any] | None)

• replace (bool)

Tipo de retorno:

AutoHybridExperiment

create_model(name, exog=False, **params)

Evaluate one standalone model on every origin of both layers.

exog=True gives the model the experiment’s exogenous features (needs X in fit and a model that accepts covariates).

Parâmetros:

• name (str)

• exog (bool)

• params (Any)

Tipo de retorno:

ModelResult

create_ensemble(models, method='equal', **options)

Evaluate one ensemble of complete forecasters on every origin.

models are names (default parameters of this experiment), specs or ModelResult — standalone models, hybrids or other ensembles. method is "equal", "median", "trimmed_mean" (trim=), "inverse_mse" or "nnls" (shrinkage= towards equal weights); learned weights come from out-of-fold forecasts inside each origin’s training vector.

Parâmetros:

• models (Sequence[str | CandidateSpec | ModelResult])

• method (str)

• options (Any)

Tipo de retorno:

ModelResult

create_hybrid(base, corrector, window=7, alpha=1.0, residual_source='historical_oof_1step', base_params=None, corrector_params=None, extra_stages=(), stage_params=None, combine_correctors=(), combination_weights='inverse_mse')

Evaluate one residual hybrid base + alpha * corrector on every origin.

extra_stages names correctors of further stages: each one corrects the residuals of the model before it (residual_multistage). By default the extra stages share window, alpha and residual_source; stage_params gives one dict per extra stage to change them (e.g. [{"window_size": 28}]).

combine_correctors instead averages corrector and these correctors with fixed combination_weights ("equal" or "inverse_mse") as one correction.

base may also be a composed candidate (e.g. create_ensemble(...)): the corrector then learns the out-of-fold residuals of that composition (residual_composite); stages and corrector combinations are for named bases.

Parâmetros:

• base (str | CandidateSpec | ModelResult)

• corrector (str)

• window (int)

• alpha (float)

• residual_source (str)

• base_params (dict[str, Any] | None)

• corrector_params (dict[str, Any] | None)

• extra_stages (Sequence[str])

• stage_params (Sequence[Mapping[str, Any]] | None)

• combine_correctors (Sequence[str])

• combination_weights (str)

Tipo de retorno:

ModelResult

create_decomposition(base, corrector, method='ma', window=7, ma_window=None, base_params=None, corrector_params=None)

Evaluate base on the smooth part plus corrector on the volatile part.

method="ma" is a causal moving average (window by kurtosis on each training vector when ma_window is None); "stl" is variant A only.

Parâmetros:

• base (str)

• corrector (str)

• method (str)

• window (int)

• ma_window (int | None)

• base_params (dict[str, Any] | None)

• corrector_params (dict[str, Any] | None)

Tipo de retorno:

ModelResult

create_combination(models, weights='inverse_mse')

Evaluate a fixed combination of base models (weights from the training only).

Parâmetros:

• models (Sequence[str])

• weights (str)

Tipo de retorno:

ModelResult

tune_model(model: str | CandidateSpec | ModelResult, n_trials: int = 20, search_space: Mapping[str, Distribution | Sequence[Any]] | None = None, sampler: str = 'auto', return_tuner: Literal[False] = False) → ModelResult

tune_model(model: str | CandidateSpec | ModelResult, n_trials: int = 20, search_space: Mapping[str, Distribution | Sequence[Any]] | None = None, sampler: str = 'auto', *, return_tuner: Literal[True]) → tuple[ModelResult, TuningResult]

Tune the parameters of the model’s base on V_search only.

search_space maps parameter names (dotted for nested ones, e.g. "estimator_params.C") to a Distribution, a (low, high) pair (integers give an integer range) or a list of choices; None uses the built-in space of the base. sampler is "auto" (Optuna if installed, else seeded random search), "optuna" or "random". The tuned candidate is then evaluated on both layers like create_model: its V_select score was never seen by the tuner. return_tuner=True also returns every trial.

Parâmetros:

• model (str | CandidateSpec | ModelResult)

• n_trials (int)

• search_space (Mapping[str, Distribution | Sequence[Any]] | None)

• sampler (str)

• return_tuner (bool)

Tipo de retorno:

ModelResult | tuple[ModelResult, TuningResult]

compare_models(include=None, sort=None)

Budgeted search on V_search, then incremental selection on V_select.

include picks the families: "standalone" (required: the initial champion is a single model), "residual", "multistage" (extra correction stages on the best residual structures; needs "residual"), "decomposition" and "combination", "ensemble" (ensembles of bases, of residual structures and corrected ensembles; ensemble_methods) and, in variant B, "dynamic" (dynamic selection of the corrector, dref and local). "exogenous" (models with the covariates of X, and their residual corrections) challenges the univariate champion under the same acceptance rule. None means ("standalone", "residual"), plus "exogenous" when fit got X.

Parâmetros:

• include (Sequence[str] | None)

• sort (str | None)

Tipo de retorno:

CompareResult

get_standalone_reference(rule='initial_champion')

Return a standalone reference from the last comparison, without accessing test data.

Parâmetros:

rule (str) – initial_champion returns the chain’s initial standalone, ranked on search with sufficient selection coverage. lowest_select_error chooses the non-exogenous standalone finalist with the lowest finite selection error and sufficient coverage; candidate ID breaks ties.

Tipo de retorno:

CandidateSpec

The returned candidate can be finalized. In a panel its per-series configurations are preserved, as for the final champion.

finalize_model(candidate)

Refit the frozen candidate on the history before the sealed test.

In a panel each series is refitted with the configuration the selection chose for it for a selected finalist, including a standalone reference, and a PanelForecaster is returned.

Parâmetros:

candidate (CandidateSpec | ModelResult)

Tipo de retorno:

FinalizedForecaster | PanelForecaster

predict_model(model, fh=None, X_future=None)

Forecast from the end of the model’s training history; never refits.

A model with exogenous future columns takes their values for the horizon from X_future or, when omitted, from the X given to fit.

Parâmetros:

• model (FinalizedForecaster | PanelForecaster)

• fh (int | None)

• X_future (DataFrame | None)

Tipo de retorno:

PredictResult

evaluate_external(model, y_test=None)

Terminal evaluation, once per finalized model; the result never reaches the search.

Without y_test the sealed test of this experiment is used. An explicit y_test (e.g. an official benchmark test) must start right after the model’s training cutoff.

Parâmetros:

• model (FinalizedForecaster | PanelForecaster)

• y_test (Series | SeriesFrame | None)

Tipo de retorno:

ExternalResult

data_profile()

Data quality report of the development history (the sealed test is excluded).

One column per series in a panel.

Tipo de retorno:

DataFrame

outlier_report(series_id=None, *, types=('AO', 'LS', 'TC'), threshold=4.0, decay=0.7, max_events=10)

Optional exploratory AO/LS/TC screening, excluding the sealed test.

Returns candidate events and recommendations for review. Calling this method never modifies data or enables treatment in model search. Scores use OLS trend/seasonal controls, not ARIMA-adjusted significance tests. For model selection, detection and any chosen treatment must be fitted per training fold.

Parâmetros:

• series_id (str | None)

• types (tuple[str, ...])

• threshold (float)

• decay (float)

• max_events (int)

Tipo de retorno:

DataFrame

seasonality_report(series_id=None, periods=None)

Seasonality evidence on the development history (never the sealed test).

One row per candidate period (default: the experiment’s period): number of cycles, strength F_s of the classical decomposition, autocorrelation of the detrended series at the period, Kruskal-Wallis p-value by position in the cycle, the rule’s decision and the suggested number of seasonal differences. Exploratory: the search decides inside the training data (see seasonal_period="auto").

Parâmetros:

• series_id (str | None)

• periods (Sequence[int] | None)

Tipo de retorno:

DataFrame

characterize(series_id=None, periods=None)

The replication project’s characterization of the development history.

Per series: ADF and KPSS at d = 0, 1, 2, the stationarity decision and d (ADF: p <= 0.05 and statistic below the 5 % critical value), and, for non-stationary series, the strength of a robust STL on the Box-Cox series for each period in periods (default: the experiment’s period), the dominant period and the category (stationary, nonseasonal, seasonal when the strength exceeds 0.5). Exploratory: never reads the sealed test.

Parâmetros:

• series_id (str | None)

• periods (Sequence[int] | None)

Tipo de retorno:

DataFrame

stationarity_report(series_id=None, max_d=2)

ADF and KPSS at d = 0..max_d on the development history, with their consensus.

One row per series and order: statistics, p-values, each rule’s decision and consensus (both say stationary). The smallest passing order of each rule is in the table’s attrs (d_adf, d_kpss, d_consensus) for one series, and in the columns of the same name for a panel. Exploratory: never reads the sealed test.

Parâmetros:

• series_id (str | None)

• max_d (int)

Tipo de retorno:

DataFrame

decompose(method='stl', series_id=None, period=None)

Trend, seasonal and remainder of the development history, indexed by date.

method="stl" is a robust STL (statsmodels); "classical" the centred moving average with mean seasonal indices (numpy; the trend is NaN at the edges). Exploratory: the decomposition strategy recomputes its own decomposition on each origin’s training data.

Parâmetros:

• method (str)

• series_id (str | None)

• period (int | None)

Tipo de retorno:

DataFrame

residual_diagnostics(base, series_id=None, lags=None, **params)

Ljung-Box test of a base model’s one-step out-of-sample residuals.

The base is fitted on the first part of the development history and forecasts the rest one step at a time with frozen parameters, as the historical_oof_1step residuals that correctors learn from. Autocorrelation left in these residuals (small p-values) is room for a residual corrector. Default lags: min(10, n/5) and twice the seasonal period. Never reads the sealed test.

Parâmetros:

• base (str)

• series_id (str | None)

• lags (Sequence[int] | None)

• params (Any)

Tipo de retorno:

DataFrame

plot_characterization(periods=None)

ADF statistic against seasonal strength for every series (see characterize).

Parâmetros:

periods (Sequence[int] | None)

Tipo de retorno:

PlotArtifact

plot_data(plot='series', series_id=None)

A plot of the development history (never the sealed test).

series, acf, seasonality (mean by position), distribution, stationarity (the series at d = 0, 1, 2 with ADF/KPSS p-values and the ADF choice), acf_pacf (at that order) or decomposition (robust STL of the Box-Cox series at the experiment’s period).

Parâmetros:

• plot (str)

• series_id (str | None)

Tipo de retorno:

PlotArtifact

plot_model(candidate, plot='cv_forecasts', series_id=None)

Validation diagnostics of a candidate; never uses the sealed test.

In a panel the forecast plots show one series (series_id, default the first).

Parâmetros:

• candidate (CandidateSpec | ModelResult)

• plot (str)

• series_id (str | None)

Tipo de retorno:

PlotArtifact

get_metrics(candidate=None)

Per-origin metrics of candidate, or a per-layer summary of everything evaluated.

Parâmetros:

candidate (CandidateSpec | ModelResult | None)

Tipo de retorno:

DataFrame

export_evidence(path, plots=(), *, external=(), nested=None, figure_formats=('png',), include_predictions=False)

Tables, decisions, splits and manifest of the last compare_models.

external and nested are caller-supplied, already computed results; exporting never evaluates or refits a model. External predictions and actuals require include_predictions=True. figure_formats accepts png/pdf/svg.

Parâmetros:

• path (str | Path)

• plots (Sequence[str])

• external (Sequence[ExternalResult])

• nested (NestedCVResult | None)

• figure_formats (Sequence[str])

• include_predictions (bool)

Tipo de retorno:

EvidenceBundle

cross_validate(models=None, folds=5, fold_strategy=None, step=None, window_size=None, horizon=None, reference=0)

Rolling-origin temporal cross-validation of several models on the same folds.

Runs on the development history only (never the sealed test) with its own folds, independent of V_search/V_select. models accepts names (default parameters of this experiment), specs or ModelResult; by default the finalists of compare_models (champion first) or every configured base model. Use the result for reporting; selection keeps its own protocol.

Parâmetros:

• models (Sequence[str | CandidateSpec | ModelResult] | None)

• folds (int)

• fold_strategy (str | None)

• step (int | None)

• window_size (int | None)

• horizon (int | None)

• reference (int | str)

Tipo de retorno:

ComparisonResult

compare_external(models=None, reference=0)

Terminal comparison on the sealed test, at most one evaluation per model.

Each model is finalized (refit on the pre-test history) and evaluated once; a model already evaluated reuses its result. Report it; do not go back and change the configuration because of it, or the test becomes validation.

Parâmetros:

• models (Sequence[str | CandidateSpec | ModelResult] | None)

• reference (int | str)

Tipo de retorno:

ExternalComparison

nested_cross_validate(outer_folds=3, baselines=('naive', 'seasonal_naive'), budget=None, include=None, standalone_reference='initial_champion')

Estimate how the whole automated procedure generalizes.

For each outer origin (the last outer_folds blocks of fh points of the development history), a fresh experiment with these parameters searches and selects using only the history before that origin; its champion is refitted there and scored on the next block, side by side with fixed baselines and with best_standalone: an inner standalone reference chosen without the outer block. standalone_reference="initial_champion" keeps the chain’s initial champion (the compatible default); "lowest_select_error" chooses the non-exogenous standalone finalist with the lowest valid inner selection error. The folds table records standalone_reference_rule and candidate IDs.

Variant A forecasts the outer block at once. Variant B reveals each observation only after its one-step forecast; all fitted parameters stay frozen. The same information protocol applies to the champion, standalone reference and baselines.

include are the families of the inner compare_models; None repeats the ones of this experiment’s last compare_models (the procedure being estimated), or its default when it has not run. result.cost has the work done per outer fold (candidates, units, seconds), so the procedure’s cost can be reconstructed.

In a panel every series is cut at its own outer origin, the inner experiment runs on the whole truncated panel and the folds table has one row per fold and series; the summary averages over all of them. Each finalist’s per-series configuration is preserved when refitting the inner standalone reference.

Parâmetros:

• outer_folds (int)

• baselines (Sequence[str])

• budget (Literal['smoke', 'small', 'medium', 'large'] | None)

• include (Sequence[str] | None)

• standalone_reference (str)

Tipo de retorno:

NestedCVResult

classmethod from_snapshot(snapshot)

Rebuild an experiment with the parameters recorded in a CompareResult snapshot.

Parâmetros:

snapshot (dict[str, Any])

Tipo de retorno:

AutoHybridExperiment

exog_report()

How the exogenous features were chosen: one row per method and candidate feature.

Columns: method, column, lag, feature, score, p_value (when the method has one) and selected. Computed in fit on the training vector before the first V_select origin.

Tipo de retorno:

DataFrame

compare_exog()

Best finalist with covariates against the best without, on the same V_select units.

Reporting only (Wilcoxon and Diebold-Mariano in .tests(), Holm-adjusted); the decision is the acceptance rule’s, in compare_models().decisions. For the sealed test, finalize both and use compare_external.

Tipo de retorno:

ComparisonResult

class autohybts.AutoHybridForecaster(**params)

Base: Parametrized

Experiment, selection and finalization in one call, for operational forecasting.

Parâmetros:

**params (Any) – any parameter of AutoHybridExperiment (fh, budget, variant …); test_size defaults to 0 here, so the whole series is used and nothing is sealed. The fitted experiment, the comparison and the finalized model stay in experiment_, compare_ and model_.

get_params()

Tipo de retorno:

dict[str, Any]

fit(y)

Parâmetros:

y (Series | SeriesFrame | PanelFrame | Mapping[str, Series])

Tipo de retorno:

AutoHybridForecaster

predict(fh=None)

Parâmetros:

fh (int | None)

Tipo de retorno:

DataFrame

leaderboard()

Tipo de retorno:

DataFrame

property selection_history_: DataFrame

get_best_model()

Tipo de retorno:

FinalizedForecaster | PanelForecaster

Dados

class autohybts.PanelFrame(series)

Base: object

Ordered collection of SeriesFrame with unique ids and one frequency.

Parâmetros:

series (Mapping[str, SeriesFrame])

series: Mapping[str, SeriesFrame]

fingerprint: str

classmethod single(frame)

Parâmetros:

frame (SeriesFrame)

Tipo de retorno:

PanelFrame

classmethod from_dict(data, frequency=None)

One pd.Series (indexed by date) per series id.

Parâmetros:

• data (Mapping[str, Series])

• frequency (str | None)

Tipo de retorno:

PanelFrame

classmethod from_long(data, *, series_col, date_col, target, frequency=None)

Long table with one row per (series, date); columns are named explicitly.

Parâmetros:

• data (DataFrame)

• series_col (str)

• date_col (str)

• target (str)

• frequency (str | None)

Tipo de retorno:

PanelFrame

property series_ids: tuple[str, ...]

property frequency: str

property is_single: bool

to_long()

Tipo de retorno:

DataFrame

autohybts.datasets.get_data(name, **kwargs)

A named series as pd.Series with a regular DatetimeIndex.

• Offline examples: "synthetic_daily", "white_noise_daily", "intermittent_daily", "commodity_price_daily"; keyword arguments go to the generator (n, seed …).

• Benchmark series: "m4:D1" or "m3:N1402" — downloaded once to the cache (keywords offline, cache_dir). The official test is at the end; seal it with test_size equal to the benchmark horizon.

• Well-known Rdatasets series by short name ("ozone", "air_passengers" …, see NAMED_SERIES; case is ignored), downloaded the same way.

Parâmetros:

• name (str)

• kwargs (Any)

Tipo de retorno:

Series

autohybts.datasets.list_datasets(provider=None, *, subset=None, search=None, offline=False, cache_dir=None, cache=None)

Catalogue of a provider (m4, m3, rdatasets), or of providers if None.

Without a provider nothing is downloaded. subset filters M3/M4 by frequency; search filters Rdatasets by package, name and title.

Parâmetros:

• provider (str | None)

• subset (str | None)

• search (str | None)

• offline (bool)

• cache_dir (str | Path | None)

• cache (CacheManager | None)

Tipo de retorno:

DataFrame

autohybts.datasets.load_benchmark(name, subset, *, split='official', series_id=None, offline=False, cache_dir=None, cache=None)

M4 or M3 with the official split; one BenchmarkSeries when series_id is given.

The official test stays apart (.test); seal it with AutoHybridExperiment(test_size=len(series.test)).fit(series.full()) so it never reaches the search or the selection.

Parâmetros:

• name (str)

• subset (str)

• split (str)

• series_id (str | None)

• offline (bool)

• cache_dir (str | Path | None)

• cache (CacheManager | None)

Tipo de retorno:

BenchmarkDataset | BenchmarkSeries

autohybts.datasets.load_dataset(provider, *, package=None, name=None, target=None, time_col=None, frequency=None, offline=False, cache_dir=None, cache=None, **options)

One dataset of any provider; Rdatasets needs target, time_col and frequency.

Parâmetros:

• provider (str)

• package (str | None)

• name (str | None)

• target (str | None)

• time_col (str | None)

• frequency (str | None)

• offline (bool)

• cache_dir (str | Path | None)

• cache (CacheManager | None)

• options (Any)

Tipo de retorno:

BenchmarkDataset | BenchmarkSeries

autohybts.datasets.raw_dataset(provider, *, package, name, offline=False, cache_dir=None, cache=None)

A Rdatasets table exactly as published, to choose its columns.

Parâmetros:

• provider (str)

• package (str)

• name (str)

• offline (bool)

• cache_dir (str | Path | None)

• cache (CacheManager | None)

Tipo de retorno:

DataFrame

autohybts.datasets.describe_dataset(provider, subset=None, *, offline=False, cache_dir=None, cache=None)

Descriptor of a benchmark subset (downloads only the catalogue files).

Parâmetros:

• provider (str)

• subset (str | None)

• offline (bool)

• cache_dir (str | Path | None)

• cache (CacheManager | None)

Tipo de retorno:

DatasetDescriptor

autohybts.datasets.list_exog_datasets()

The series with covariates: target, columns, frequency and which columns are future.

Tipo de retorno:

DataFrame

autohybts.datasets.load_exog_dataset(name, **kwargs)

(y, X) of a series with covariates; downloaded once to the cache.

Keywords go to the download (offline, cache_dir, cache). Use the dataset’s future columns (list_exog_datasets()) as exog_future.

Parâmetros:

• name (str)

• kwargs (Any)

Tipo de retorno:

tuple[Series, DataFrame]

class autohybts.data.exog.ExogFrame(timestamps, values, columns, kinds)

Base: object

Validated covariates of one series, with the kind of each column.

Build it with ExogFrame.from_frame(X, future=[...]). The index may extend past the series (values of future columns for the forecast horizon).

Parâmetros:

• timestamps (DatetimeIndex)

• values (NDArray[float64])

• columns (tuple[str, ...])

• kinds (tuple[str, ...])

timestamps: DatetimeIndex

values: NDArray[float64]

columns: tuple[str, ...]

kinds: tuple[str, ...]

fingerprint: str

classmethod from_frame(frame, future=())

Covariates from a DataFrame indexed by date; future names known columns.

Parâmetros:

• frame (DataFrame | Series)

• future (Iterable[str])

Tipo de retorno:

ExogFrame

kind(column)

Parâmetros:

column (str)

Tipo de retorno:

str

default_features(step, columns=None)

Each column at its smallest causal lag: 0 for future, step for past.

Parâmetros:

• step (int)

• columns (Sequence[str] | None)

Tipo de retorno:

tuple[ExogFeature, …]

check(features, step)

Refuse a past feature lagged by less than step (it would leak).

Parâmetros:

• features (Sequence[ExogFeature])

• step (int)

Tipo de retorno:

None

design(features, timeline, step)

Feature matrix on timeline (the series dates, optionally extended).

Parâmetros:

• features (Sequence[ExogFeature])

• timeline (DatetimeIndex)

• step (int)

Tipo de retorno:

ExogDesign

to_frame()

The covariates as a DataFrame indexed by date (a copy).

Tipo de retorno:

DataFrame

describe()

Tipo de retorno:

dict[str, object]

autohybts.data.exog_selection.select_exog(y, covariates, kinds, step, method, *, max_lag=None, seed=0)

Features of covariates chosen by method on the training values y.

covariates has one row per value of y (same dates). past lags go from step to max_lag (default step + 6).

Parâmetros:

• y (ArrayLike)

• covariates (DataFrame)

• kinds (Mapping[str, str])

• step (int)

• method (str)

• max_lag (int | None)

• seed (int)

Tipo de retorno:

ExogSelection

class autohybts.datasets.BenchmarkSeries(train, test, descriptor)

Base: object

One series with its official split: train for the search, test sealed.

full() gives train and test back to back, so AutoHybridExperiment(fh=h, test_size=len(test)).fit(series.full()) seals exactly the official test.

Parâmetros:

• train (Series)

• test (Series | None)

• descriptor (DatasetDescriptor)

train: Series

test: Series | None

descriptor: DatasetDescriptor

property series_id: str

full()

Tipo de retorno:

Series

class autohybts.datasets.BenchmarkDataset(train, test, metadata, descriptor)

Base: object

Many series in long format (series_id, timestamp, value).

Parâmetros:

• train (DataFrame)

• test (DataFrame | None)

• metadata (DataFrame | None)

• descriptor (DatasetDescriptor)

train: DataFrame

test: DataFrame | None

metadata: DataFrame | None

descriptor: DatasetDescriptor

property series_ids: tuple[str, ...]

series(series_id)

Parâmetros:

series_id (str)

Tipo de retorno:

BenchmarkSeries

panel(series_ids=None, *, with_test=True)

Series as a panel; with_test appends each official test (to be sealed).

Parâmetros:

• series_ids (Sequence[str] | None)

• with_test (bool)

Tipo de retorno:

PanelFrame

class autohybts.datasets.DatasetDescriptor(provider, dataset_id, source_url, version, license, frequency, horizon, target_name, time_col, series_id_col, split_kind, extra=<factory>)

Base: object

Where a dataset came from and how it is split; kept in manifests.

Parâmetros:

• provider (str)

• dataset_id (str)

• source_url (str)

• version (str | None)

• license (str | None)

• frequency (str | None)

• horizon (int | None)

• target_name (str)

• time_col (str | None)

• series_id_col (str | None)

• split_kind (Literal['official', 'chronological', 'custom', 'none'])

• extra (Mapping[str, Any])

provider: str

dataset_id: str

source_url: str

version: str | None

license: str | None

frequency: str | None

horizon: int | None

target_name: str

time_col: str | None

series_id_col: str | None

split_kind: Literal['official', 'chronological', 'custom', 'none']

extra: Mapping[str, Any]

to_dict()

Tipo de retorno:

dict[str, Any]

class autohybts.datasets.CacheManager(root=None, *, offline=False, timeout=60.0, retries=2, opener=None)

Base: object

Parâmetros:

• root (str | Path | None)

• offline (bool)

• timeout (float)

• retries (int)

• opener (Opener | None)

path(provider, filename)

Parâmetros:

• provider (str)

• filename (str)

Tipo de retorno:

Path

manifest_path(provider, filename)

Parâmetros:

• provider (str)

• filename (str)

Tipo de retorno:

Path

read_manifest(provider, filename)

Parâmetros:

• provider (str)

• filename (str)

Tipo de retorno:

dict[str, Any] | None

fetch(provider, remote, *, allowed_domains, license=None, version=None, refresh=False)

Path of remote in the cache, downloading it first if needed and allowed.

Parâmetros:

• provider (str)

• remote (RemoteFile)

• allowed_domains (Collection[str])

• license (str | None)

• version (str | None)

• refresh (bool)

Tipo de retorno:

Path

verify(provider, remote)

Refuse a cached file whose bytes differ from its manifest or pinned checksum.

Parâmetros:

• provider (str)

• remote (RemoteFile)

Tipo de retorno:

None

Modelos finalizados e persistência

class autohybts.FinalizedForecaster(spec, model, history, seed, manifest=<factory>, n_trained=None, exog=None)

Base: object

Structure and hyper-parameters frozen at selection; coefficients refitted on history.

Holds the history it was fitted on because forecasting needs it (lags, filter state, residual windows). Forecasts start right after training_cutoff.

With exogenous features (ADR-0011) exog keeps the covariates up to the last observation; predict takes the values of future columns for the horizon (X_future) and update_state the covariates of the new dates (X_new).

Parâmetros:

• spec (CandidateSpec)

• model (BaseForecaster)

• history (SeriesFrame)

• seed (int | None)

• manifest (Mapping[str, Any])

• n_trained (int | None)

• exog (ExogState | None)

spec: CandidateSpec

model: BaseForecaster

history: SeriesFrame

seed: int | None

manifest: Mapping[str, Any]

n_trained: int | None = None

exog: ExogState | None = None

property training_cutoff: Timestamp

Last observation the parameters were fitted on.

property last_observation: Timestamp

Last observation known to the model (fit or later updates); forecasts start after it.

property variant: str

update_state(observations, *, refit=False, X_new=None)

Same fitted model, longer history: new observations change the state, not the fit.

Returns a new object; refit=True is refused because re-estimating parameters is a separate, explicit operation (finalize_model on the longer series). A model with exogenous features takes the covariates of the new dates in X_new.

Parâmetros:

• observations (Series | SeriesFrame)

• refit (bool)

• X_new (DataFrame | None)

Tipo de retorno:

FinalizedForecaster

stream()

Rolling one-step forecasting with observations arriving one at a time (variant B).

Tipo de retorno:

ForecastStream

property model_id: str

spec, data and seed.

Type:

Identity of this fitted artifact

context(horizon=0, X_future=None)

What the model sees at its last observation; with exogenous features, their rows up to horizon dates ahead (future columns from X_future).

Parâmetros:

• horizon (int)

• X_future (DataFrame | None)

Tipo de retorno:

TemporalContext

predict(fh, X_future=None)

fh steps after the last observation, indexed by date; no refit happens here.

A model with exogenous future columns needs their values for the fh dates in X_future; past columns come from the history.

Parâmetros:

• fh (int)

• X_future (DataFrame | None)

Tipo de retorno:

DataFrame

class autohybts.PanelForecaster(models, spec, manifest=<factory>)

Base: object

One finalized model per series; each series keeps its own configuration and cutoff.

Parâmetros:

• models (Mapping[str, FinalizedForecaster])

• spec (CandidateSpec)

• manifest (Mapping[str, Any])

models: Mapping[str, FinalizedForecaster]

spec: CandidateSpec

manifest: Mapping[str, Any]

property model_id: str

property variant: str

property series_ids: tuple[str, ...]

property training_cutoff: dict[str, Timestamp]

predict(fh, X_future=None)

fh steps after each series’ last observation, stacked by series.

X_future maps each series to the covariates of its horizon, for members with exogenous future columns.

Parâmetros:

• fh (int)

• X_future (Mapping[str, DataFrame] | None)

Tipo de retorno:

DataFrame

class autohybts.forecasting.finalized.ForecastStream(model)

Base: object

predict_next then observe, in strict alternation; parameters stay frozen.

Parâmetros:

model (FinalizedForecaster)

property model: FinalizedForecaster

The forecaster with every observation received so far.

predict_next(exog=None)

Forecast the next step; observe must reveal its value before the next call.

exog holds the covariates of the date being forecast (a mapping or Series by column, or a one-row DataFrame), needed for future columns.

Parâmetros:

exog (Any)

Tipo de retorno:

ForecastTicket

observe(value, exog=None)

Reveal the value forecast by the pending ticket; the model is not refitted.

exog adds covariates observed with the value (past columns of that date).

Parâmetros:

• value (float)

• exog (Any)

Tipo de retorno:

None

log()

Every ticket with the value that was later observed.

Tipo de retorno:

DataFrame

class autohybts.forecasting.finalized.ForecastTicket(origin, timestamp, prediction, base_prediction, correction)

Base: object

A one-step forecast issued before the value it forecasts is observed.

Variáveis:

• origin (pandas.Timestamp) – last observation the forecast used.

• timestamp (pandas.Timestamp) – date being forecast.

• prediction (float) – the forecast (base_prediction + correction).

• base_prediction (float) – the base model’s part.

• correction (float) – the residual corrector’s part (0 without a corrector).

Parâmetros:

• origin (Timestamp)

• timestamp (Timestamp)

• prediction (float)

• base_prediction (float)

• correction (float)

origin: Timestamp

timestamp: Timestamp

prediction: float

base_prediction: float

correction: float

autohybts.save_model(model, path, *, signing_key=None)

Write model to the directory path (created if needed); returns the directory.

With signing_key (a secret kept outside the artifact), the manifest also records an HMAC-SHA256 of the payload that load_model(..., signing_key=...) requires.

Parâmetros:

• model (FinalizedForecaster | PanelForecaster)

• path (str | Path)

• signing_key (bytes | None)

Tipo de retorno:

Path

autohybts.load_model(path, *, trusted=False, sha256=None, signing_key=None)

Load a finalized model; requires trusted=True because unpickling runs code.

sha256 pins the payload hash and signing_key requires the HMAC written by save_model; both are checked before anything is unpickled.

Parâmetros:

• path (str | Path)

• trusted (bool)

• sha256 (str | None)

• signing_key (bytes | None)

Tipo de retorno:

FinalizedForecaster | PanelForecaster

autohybts.read_manifest(path)

Inspect an artifact without executing anything.

Parâmetros:

path (str | Path)

Tipo de retorno:

dict[str, Any]

class autohybts.ExperimentStore(path)

Base: object

Experiments, evaluations and finalized models in one SQLite file.

The file and its tables are created on the first write. log records an experiment as a run; query runs SQL on a read-only connection and returns a DataFrame.

Parâmetros:

path (str | Path) – SQLite file (created if needed on the first log).

log(experiment, *, name='run', tags=None, models=(), values=False)

Record experiment as a run and return its run_id.

Everything the experiment has computed so far is written: series identity (no values), splits, evaluated candidates with per-layer and per-origin metrics and, after compare_models, the search ledger, the selection decisions and the champion. models adds finalized models; external evaluations already made are written as metrics and, with values=True, as predictions with observations.

The run_id depends on the experiment’s settings, data, temporal plan and name: logging the same experiment again replaces its rows (for instance after evaluate_external) instead of duplicating them.

Parâmetros:

• experiment (AutoHybridExperiment)

• name (str)

• tags (Mapping[str, Any] | None)

• models (Sequence[FinalizedForecaster | PanelForecaster])

• values (bool)

Tipo de retorno:

str

delete_run(run_id)

Remove every row of run_id.

Parâmetros:

run_id (str)

Tipo de retorno:

None

query(sql, params=())

Run sql on a read-only connection and return the result as a DataFrame.

Pass values through params (? or :name placeholders), never by formatting them into the SQL text.

Parâmetros:

• sql (str)

• params (Sequence[Any] | Mapping[str, Any])

Tipo de retorno:

DataFrame

runs()

One row per run, newest first, without the JSON columns.

Tipo de retorno:

DataFrame

tables()

Names of the tables of the store’s schema.

Tipo de retorno:

list[str]

register_model(model, path, *, name, run_id=None, reference_mae=None)

Register a model saved with save_model under name, as a candidate.

The registry keeps the artifact’s path and the payload SHA-256 read from its manifest, never the model itself. reference_mae is the error the model is expected to keep in production (for instance the MAE of evaluate_external); monitor compares the live error with it. Registering again keeps the stage.

Parâmetros:

• model (FinalizedForecaster)

• path (str | Path)

• name (str)

• run_id (str | None)

• reference_mae (float | None)

Tipo de retorno:

str

promote(model_id, stage='production', reason='')

Move a registered model to stage; a new production model archives the old one.

Every change is kept in stage_history with its reason.

Parâmetros:

• model_id (str)

• stage (str)

• reason (str)

Tipo de retorno:

None

registry(name=None)

Registered models (all, or those of name), newest first.

Parâmetros:

name (str | None)

Tipo de retorno:

DataFrame

load(name, stage='production', *, trusted=False, signing_key=None)

Load the model of name in stage with load_model.

The payload must match the SHA-256 recorded at registration. Like that hash, the database sits next to the artifacts, so it catches corruption, not tampering: pass signing_key for artifacts saved with one.

Parâmetros:

• name (str)

• stage (str)

• trusted (bool)

• signing_key (bytes | None)

Tipo de retorno:

FinalizedForecaster

log_forecasts(model_id, forecasts)

Record forecasts of a registered model made in production; returns the row count.

forecasts has y_pred and a timestamp column or index; origin, horizon (default 1) and series_id (default: the model’s series) are optional, as in the tables of predict_model and ForecastStream.log().

Parâmetros:

• model_id (str)

• forecasts (DataFrame)

Tipo de retorno:

int

log_actuals(series_id, actuals)

Record observed values of series_id (indexed by timestamp); returns the count.

A value logged again for the same timestamp replaces the previous one.

Parâmetros:

• series_id (str)

• actuals (Series)

Tipo de retorno:

int

log_covariates(series_id, covariates)

Record exogenous values of series_id by date and column; returns the count.

covariates is indexed by date with one column per covariate (missing cells are skipped). A value logged again for the same date and column replaces the previous one, e.g. a weather forecast later replaced by the observed value.

Parâmetros:

• series_id (str)

• covariates (DataFrame)

Tipo de retorno:

int

covariates(series_id, start=None, end=None)

Recorded covariates of series_id as a DataFrame (dates × columns).

start and end bound the dates (inclusive); the result is ready for update_state(..., X_new=...) or predict(..., X_future=...).

Parâmetros:

• series_id (str)

• start (str | Timestamp | None)

• end (str | Timestamp | None)

Tipo de retorno:

DataFrame

monitor(model_id, *, window=30, threshold=1.5, horizon=1)

Live error of a registered model: rolling MAE against its reference_mae.

One row per forecast (of horizon) whose observation has arrived, with the absolute error, the MAE over the last window such forecasts, the ratio to the reference and alert: a full window whose MAE exceeds threshold times the reference. Without a reference, ratio is empty and alert is false.

Parâmetros:

• model_id (str)

• window (int)

• threshold (float)

• horizon (int)

Tipo de retorno:

DataFrame

Resultados

class autohybts.results.CompareResult(best, leaderboard, selection_leaderboard, decisions, audit, search, selection, snapshot, comparison=None, events=<factory>)

Base: object

Search on V_search and incremental selection on V_select.

Variáveis:

• best (autohybts.domain.specs.CandidateSpec) – the champion (a CandidateSpec), ready for finalize_model.

• leaderboard (pandas.DataFrame) – one row per evaluated candidate of the search (V_search), sorted by the first metric, with mean_rank, metric means, coverage, n_units, failures and fit/predict seconds; is_champion marks the champion.

• selection_leaderboard (pandas.DataFrame) – the same columns for the finalists on V_select.

• decisions (pandas.DataFrame) – one row per challenge of the incremental chain: family, champion_before, challenger, accepted, reason_codes, median_gain, win_rate, variability_status, variability_value and p_value (with significance_alpha).

• audit (autohybts.selection.incremental.SelectionAudit) – how adaptive the selection was (SelectionAudit).

• search (autohybts.search.ledger.SearchResult) – everything the search tried (SearchResult; ledger_frame()).

• selection (autohybts.selection.incremental.SelectionResult) – the selection itself (SelectionResult; decision_units_frame() and, in a panel, champion_per_series and finalist_per_series).

• snapshot (dict[str, Any]) – what must stay fixed to reproduce the selection (settings, splits, space, budget, policy, protocol hash, champion).

• comparison (autohybts.reporting.comparison.ComparisonResult | None) – statistical comparison of the finalists on V_select (ComparisonResult), or None.

• events (tuple[autohybts.results.Event, ...]) – timed log of the experiment verbs.

Parâmetros:

• best (CandidateSpec)

• leaderboard (DataFrame)

• selection_leaderboard (DataFrame)

• decisions (DataFrame)

• audit (SelectionAudit)

• search (SearchResult)

• selection (SelectionResult)

• snapshot (dict[str, Any])

• comparison (ComparisonResult | None)

• events (tuple[Event, ...])

best: CandidateSpec

leaderboard: DataFrame

selection_leaderboard: DataFrame

decisions: DataFrame

audit: SelectionAudit

search: SearchResult

selection: SelectionResult

snapshot: dict[str, Any]

comparison: ComparisonResult | None = None

events: tuple[Event, ...]

strategy_table()

Every candidate of the search: score on V_search, cost, complexity, Pareto.

Tipo de retorno:

DataFrame

property strategies: DataFrame

best and median score, cost.

Type:

Per strategy (standalone, residual, multistage …)

plot(kind='pareto', x='cost')

pareto (error × cost, or × complexity with x="complexity") and strategies over every searched candidate; the comparison plots (leaderboard, boxplot, win_rate …) over the finalists on V_select.

Parâmetros:

• kind (str)

• x (str)

Tipo de retorno:

PlotArtifact

class autohybts.results.ModelResult(candidate, evaluation)

Base: object

One candidate evaluated on every origin (search and select layers).

Parâmetros:

• candidate (CandidateSpec)

• evaluation (EvaluationResult)

candidate: CandidateSpec

evaluation: EvaluationResult

property cv_results: DataFrame

One row per origin, plus Mean and Std rows (like PyCaret).

property metrics: dict[str, float]

class autohybts.results.ExternalResult(metrics, predictions, model_label)

Base: object

Terminal evaluation on the sealed (or an external) test; never fed back to the search.

Variáveis:

• metrics (pandas.DataFrame) – one row per model (and per series, plus the mean, in a panel).

• predictions (pandas.DataFrame) – y_pred and y_true over the test, indexed by date.

• model_label (str) – label of the evaluated structure.

Parâmetros:

• metrics (DataFrame)

• predictions (DataFrame)

• model_label (str)

metrics: DataFrame

predictions: DataFrame

model_label: str

class autohybts.results.PredictResult(predictions, model_label)

Base: object

Forecasts of a finalized model.

Variáveis:

• predictions (pandas.DataFrame) – y_pred indexed by date (stacked by series in a panel).

• model_label (str) – label of the forecasting structure.

Parâmetros:

• predictions (DataFrame)

• model_label (str)

predictions: DataFrame

model_label: str

class autohybts.results.ExternalComparison(table, steps, tests, reference)

Base: object

Terminal comparison on the sealed test: reporting only, never fed back.

tests compares each model with the reference on per-step absolute errors of the single test block (Diebold-Mariano with fh - 1 Newey-West lags, Holm-adjusted).

Parâmetros:

• table (DataFrame)

• steps (DataFrame)

• tests (DataFrame)

• reference (str)

table: DataFrame

steps: DataFrame

tests: DataFrame

reference: str

class autohybts.results.NestedCVResult(folds, summary, metric, include=(), cost=<factory>, snapshots=())

Base: object

Outer rolling-origin evaluation of the whole automated procedure.

In each outer fold the search and the selection ran again on the history before the outer origin only; the outer block was never seen by them. include are the families of the inner searches; cost has one row per outer fold with the work done there: candidates and units (origin x series) of the inner search and selection, configured budget, stop reason and seconds (search, selection, refit, total). snapshots records the resolved inner comparison configuration by fold.

Parâmetros:

• folds (DataFrame)

• summary (DataFrame)

• metric (str)

• include (tuple[str, ...])

• cost (DataFrame)

• snapshots (tuple[dict[str, Any], ...])

folds: DataFrame

summary: DataFrame

metric: str

include: tuple[str, ...] = ()

cost: DataFrame

snapshots: tuple[dict[str, Any], ...] = ()

property total_candidates: int

Candidates evaluated by every inner search together.

property total_fits: int

Leaf model fits of every inner search and selection together.

property total_seconds: float

class autohybts.search.ledger.SearchResult(metric, plan_fingerprint, ledger, results, retained, residual_structures, stop_reason, protocol, elapsed_s=0.0)

Base: object

Everything the search tried and what it found, on V_search only.

Variáveis:

• metric (str) – metric that ranked the candidates.

• plan_fingerprint (str) – fingerprint of the temporal plan the search used.

• ledger (tuple[autohybts.search.ledger.LedgerEntry, ...]) – every proposal, evaluated or not, with stage, status (EVALUATED, PRUNED_BUDGET, SKIPPED_CAPABILITY, DUPLICATE, STOPPED) and reason; ledger_frame() gives it as a table.

• results (tuple[autohybts.domain.results.EvaluationResult, ...]) – evaluation of every evaluated candidate.

• retained (tuple[str, ...]) – bases retained for the hybrids (stage S1).

• residual_structures (tuple[str, ...]) – residual structures carried to refinement.

• stop_reason (str) – "completed", a budget limit or "max_wall_time".

• protocol (dict[str, object]) – pre-registered settings of the search and their hash.

• elapsed_s (float) – wall time of the search.

Parâmetros:

• metric (str)

• plan_fingerprint (str)

• ledger (tuple[LedgerEntry, ...])

• results (tuple[EvaluationResult, ...])

• retained (tuple[str, ...])

• residual_structures (tuple[str, ...])

• stop_reason (str)

• protocol (dict[str, object])

• elapsed_s (float)

metric: str

plan_fingerprint: str

ledger: tuple[LedgerEntry, ...]

results: tuple[EvaluationResult, ...]

retained: tuple[str, ...]

residual_structures: tuple[str, ...]

stop_reason: str

protocol: dict[str, object]

elapsed_s: float

property trial_count: int

property cached_count: int

Evaluated candidates whose result came from the trial cache (nothing refitted).

property unit_count: int

Units (origin x series) actually evaluated, cache hits excluded.

Each unit is one fresh model trained at one origin; how many model fits a unit needs depends on the strategy, see fit_count.

property fit_count: int

Leaf model fits behind the evaluated candidates, cache hits excluded.

A residual hybrid at one origin counts its base, the extra base fit that produces the out-of-fold residuals and its corrector (domain.fit_count).

property trials_by_family: dict[str, int]

counts()

Tipo de retorno:

dict[str, int]

result(candidate_id)

Parâmetros:

candidate_id (str)

Tipo de retorno:

EvaluationResult

ledger_frame()

Tipo de retorno:

DataFrame

class autohybts.selection.incremental.SelectionResult(champion, champion_result, finalists, decisions, audit, champion_per_series=<factory>, finalist_per_series=<factory>)

Base: object

Outcome of the incremental selection on V_select.

champion is the final champion and champion_result its evaluation; finalists holds the best structure of each family, evaluated on V_select; decisions records every challenge, accepted or not, with per-unit errors and gains (decisions_frame() and decision_units_frame() give them as tables); audit is the SelectionAudit; in a panel, champion_per_series holds the configuration chosen for each series. finalist_per_series preserves these configurations for every finalist, keyed by its representative candidate ID.

Parâmetros:

• champion (CandidateSpec)

• champion_result (EvaluationResult)

• finalists (tuple[EvaluationResult, ...])

• decisions (tuple[SelectionDecision, ...])

• audit (SelectionAudit)

• champion_per_series (Mapping[str, CandidateSpec])

• finalist_per_series (Mapping[str, Mapping[str, CandidateSpec]])

champion: CandidateSpec

champion_result: EvaluationResult

finalists: tuple[EvaluationResult, ...]

decisions: tuple[SelectionDecision, ...]

audit: SelectionAudit

champion_per_series: Mapping[str, CandidateSpec]

finalist_per_series: Mapping[str, Mapping[str, CandidateSpec]]

decisions_frame()

One row per decision; models by short name, full label and ids at the end.

Tipo de retorno:

DataFrame

decision_units_frame()

One row per decision and compared unit: both errors, the gain and the win.

Everything a decision used is here, so median gain and win rate can be recomputed (and resampled by unit or series) outside the library.

Tipo de retorno:

DataFrame

class autohybts.selection.incremental.SelectionAudit(protocol_hash, search_protocol_hash, total_trials, tried_by_family, pruned_trials, failed_trials, finalist_ids, winner_id, comparison_origin_ids, decision_reasons, exploratory, search_best_score, winner_search_score, winner_select_score)

Base: object

Evidence of how adaptive the selection was: trials, pruning, finalists, reasons.

selection_gap() compares the winner’s score on V_search with its score on V_select: a large gap signals optimism from choosing where it was searched.

Parâmetros:

• protocol_hash (str)

• search_protocol_hash (str)

• total_trials (int)

• tried_by_family (dict[str, int])

• pruned_trials (int)

• failed_trials (int)

• finalist_ids (tuple[str, ...])

• winner_id (str)

• comparison_origin_ids (tuple[str, ...])

• decision_reasons (tuple[str, ...])

• exploratory (bool)

• search_best_score (float)

• winner_search_score (float)

• winner_select_score (float)

protocol_hash: str

search_protocol_hash: str

total_trials: int

tried_by_family: dict[str, int]

pruned_trials: int

failed_trials: int

finalist_ids: tuple[str, ...]

winner_id: str

comparison_origin_ids: tuple[str, ...]

decision_reasons: tuple[str, ...]

exploratory: bool

search_best_score: float

winner_search_score: float

winner_select_score: float

property selection_gap: float

Select-layer minus search-layer score of the winner (positive = optimism).

class autohybts.reporting.plots.PlotArtifact(kind, figure, source_split, candidate_id=None, origin_range=None, provenance=<factory>, backend='matplotlib')

Base: object

A matplotlib figure plus where its numbers come from.

figure is the matplotlib.figure.Figure (Jupyter displays it; save writes it). kind is the plot requested, source_split the data it used ("development", "validation" …, never the sealed test), candidate_id the candidate drawn, origin_range the first and last date covered and provenance the counts and settings behind the figure.

Parâmetros:

• kind (str)

• figure (Any)

• source_split (str)

• candidate_id (str | None)

• origin_range (tuple[Timestamp, Timestamp] | None)

• provenance (dict[str, Any])

• backend (str)

kind: str

figure: Any

source_split: str

candidate_id: str | None = None

origin_range: tuple[Timestamp, Timestamp] | None = None

provenance: dict[str, Any]

backend: str = 'matplotlib'

save(path)

Write the figure (format from the extension, e.g. .png or .svg).

Parâmetros:

path (str | Path)

Tipo de retorno:

Path

class autohybts.reporting.comparison.ComparisonResult(results, metric, history, source, reference=0, max_lag=0, splits=None)

Base: object

Several models scored on the same units, with tables, tests and plots.

Parâmetros:

• results (tuple[EvaluationResult, ...])

• metric (str)

• history (SeriesFrame)

• source (str)

• reference (int)

• max_lag (int)

• splits (DataFrame | None)

results: tuple[EvaluationResult, ...]

metric: str

history: SeriesFrame

source: str

reference: int = 0

max_lag: int = 0

splits: DataFrame | None = None

property labels: list[str]

property units: DataFrame

property summary: DataFrame

property win_rates: DataFrame

tests(reference=None)

Parâmetros:

reference (int | None)

Tipo de retorno:

DataFrame

friedman(alpha=0.05)

Parâmetros:

alpha (float)

Tipo de retorno:

dict[str, Any]

kruskal()

Kruskal-Wallis and Dunn (Holm); they ignore the pairing, prefer friedman.

Tipo de retorno:

dict[str, Any]

plot(kind='leaderboard')

Parâmetros:

kind (str)

Tipo de retorno:

Any

Especificações

class autohybts.domain.specs.CandidateSpec(family, strategy, base, corrector=None, window_size=None, alpha=None, residual_source=None, variant='A', members=(), options_json='{}', components=(), exog=())

Base: object

One configuration to evaluate: strategy, base, optional corrector, variant.

Strategies and the fields they use:

• standalone: base only.

• residual_additive: base + alpha * corrector on residual windows.

• residual_multistage: as above, then each corrector in members corrects the residuals of the previous stage; at most MAX_STAGES stages. Extra stages share window, alpha and source unless options["stages"] gives, per extra stage, a dict with any of window_size, alpha and residual_source.

• decomposition: base forecasts the smooth part and corrector the volatile part on windows of window_size; options holds method ("ma" or "stl", the latter only in variant A), ma_window (None: chosen by kurtosis on the training vector) and period (seasonal period, required by STL).

• fixed_combination: base and members combined with fixed weights; options["weights"] is "equal" or "inverse_mse" (estimated on the training vector only).

• residual_combination: base + alpha * Σ w_j r̂_j, the corrector and the correctors in members combined with fixed weights (options["weights"]).

• ensemble: components (2 to MAX_COMPONENTS candidates of any strategy, including other compositions) combined by options["method"] in ENSEMBLE_METHODS; trim (trimmed_mean) and shrinkage (nnls, towards equal weights) are filled with their defaults. The order of components is canonical (by candidate_id): the combination is commutative. base is COMPOSITE_BASE.

• residual_composite: component + alpha * corrector on the residual windows of one composed candidate (components holds it), e.g. a residual correction of an ensemble; residual fields as in residual_additive. base is COMPOSITE_BASE.

members, options and components enter candidate_id only when non-empty, so identities of the other strategies do not change. Compositions nest up to MAX_DEPTH levels.

exog (ADR-0011) lists the exogenous features the base receives; it applies to standalone, residual_additive and residual_multistage and, like the fields above, enters candidate_id only when non-empty.

Parâmetros:

• family (str)

• strategy (str)

• base (ModelSpec)

• corrector (ModelSpec | None)

• window_size (int | None)

• alpha (float | None)

• residual_source (str | None)

• variant (Literal['A', 'B'])

• members (tuple[ModelSpec, ...])

• options_json (str)

• components (tuple[CandidateSpec, ...])

• exog (tuple[ExogFeature, ...])

family: str

strategy: str

base: ModelSpec

corrector: ModelSpec | None

window_size: int | None

alpha: float | None

residual_source: str | None

variant: Literal['A', 'B']

members: tuple[ModelSpec, ...]

options_json: str

components: tuple[CandidateSpec, ...]

exog: tuple[ExogFeature, ...]

candidate_id: str

property depth: int

0 for a single structure (a base, a hybrid …), 1 + the deepest component for an ensemble or a residual composition.

Type:

Levels of composition

model_names()

Every registered model this candidate uses, as (kind, name), in order.

Tipo de retorno:

tuple[tuple[Literal[‘base’, ‘corrector’], str], …]

property options: dict[str, Any]

A fresh copy of the strategy options.

property stages: int

Number of correction stages (0 for strategies without a residual corrector).

classmethod ensemble(components, *, method='equal', family='ensemble', **options)

Ensemble of components (variant taken from them; they must agree).

Parâmetros:

• components (Sequence[CandidateSpec])

• method (str)

• family (str)

• options (Any)

Tipo de retorno:

CandidateSpec

classmethod corrected(component, corrector, window_size, alpha, residual_source, *, family='ensemble')

Residual correction of a composed component (e.g. of an ensemble).

Parâmetros:

• component (CandidateSpec)

• corrector (ModelSpec)

• window_size (int)

• alpha (float)

• residual_source (str)

• family (str)

Tipo de retorno:

CandidateSpec

classmethod standalone(name, params=None, *, family, variant='A')

Parâmetros:

• name (str)

• params (Mapping[str, Any] | None)

• family (str)

• variant (Literal['A', 'B'])

Tipo de retorno:

CandidateSpec

describe()

Canonical content of the spec; the source of candidate_id.

Tipo de retorno:

dict[str, Any]

property name: str

Short readable name of the structure, e.g. arima-mlp (parameters omitted).

label keeps the full configuration; several configurations share a name.

property label: str

class autohybts.domain.specs.ModelSpec(name, params_json='{}')

Base: object

A registered model name plus its parameters, stored in canonical form.

Parameters are kept as canonical JSON, so the spec is deeply immutable and two specs with equal parameters (in any key order, tuples or lists) are equal.

Parâmetros:

• name (str)

• params_json (str)

name: str

params_json: str

classmethod of(name, params=None)

Parâmetros:

• name (str)

• params (Mapping[str, Any] | None)

Tipo de retorno:

ModelSpec

property params: dict[str, Any]

A fresh copy of the parameters.

describe()

Tipo de retorno:

dict[str, Any]

property label: str

Busca, seleção e ajuste

class autohybts.search.spaces.SearchSpace(base_models=('naive', 'seasonal_naive', 'linear', 'knn', 'svm', 'tree', 'random_forest', 'arima', 'mlp'), base_params=<factory>, correctors=('linear', 'knn', 'mlp'), corrector_params=<factory>, residual_windows=(7, 28), alphas=(0.5, 1.0), residual_sources=('historical_oof_1step', ), refine_sources=('historical_oof_multistep', 'in_sample'), seasonal_period=1, variant='A', max_stages=1, decomposition_methods=(), combination_weights=(), dynamic_methods=(), stage_params='shared', ensemble_methods=(), differencing=None, differencing_test='kpss', transform=None, outliers=None, exog_sets=())

Base: object

What the search may try; the default search space by default.

base_params and corrector_params map a model name to a grid (sequence of parameter dicts); a missing entry means the model’s defaults. refine_sources are the residual sources tried in S3 around the best residual structures.

Advanced families are off by default: max_stages > 1 adds correction stages in S3; decomposition_methods, combination_weights and ensemble_methods open stage S4.

exog_sets (ADR-0011) are sets of exogenous features; each one is tried in stage SX with every base that accepts covariates and then with residual correctors on the best of them, all in the exogenous family.

Parâmetros:

• base_models (tuple[str, ...])

• base_params (Mapping[str, Sequence[Mapping[str, Any]]])

• correctors (tuple[str, ...])

• corrector_params (Mapping[str, Sequence[Mapping[str, Any]]])

• residual_windows (tuple[int, ...])

• alphas (tuple[float, ...])

• residual_sources (tuple[str, ...])

• refine_sources (tuple[str, ...])

• seasonal_period (int)

• variant (Literal['A', 'B'])

• max_stages (int)

• decomposition_methods (tuple[str, ...])

• combination_weights (tuple[str, ...])

• dynamic_methods (tuple[str, ...])

• stage_params (str)

• ensemble_methods (tuple[str, ...])

• differencing (str | None)

• differencing_test (str)

• transform (str | None)

• outliers (str | None)

• exog_sets (tuple[tuple[ExogFeature, ...], ...])

base_models: tuple[str, ...]

base_params: Mapping[str, Sequence[Mapping[str, Any]]]

correctors: tuple[str, ...]

corrector_params: Mapping[str, Sequence[Mapping[str, Any]]]

residual_windows: tuple[int, ...]

alphas: tuple[float, ...]

residual_sources: tuple[str, ...]

refine_sources: tuple[str, ...]

seasonal_period: int

variant: Literal['A', 'B']

max_stages: int

decomposition_methods: tuple[str, ...]

combination_weights: tuple[str, ...]

dynamic_methods: tuple[str, ...]

stage_params: str

ensemble_methods: tuple[str, ...]

differencing: str | None

differencing_test: str

transform: str | None

outliers: str | None

exog_sets: tuple[tuple[ExogFeature, ...], ...]

describe()

Tipo de retorno:

dict[str, Any]

base_proposals(registry)

S0: every configured base, in the configured order.

Parâmetros:

registry (ModelRegistry)

Tipo de retorno:

list[Proposal]

exog_proposals(registry)

SX: every base that accepts covariates, with each exogenous feature set.

Parâmetros:

registry (ModelRegistry)

Tipo de retorno:

list[Proposal]

exog_residual_proposals(bases, registry)

SX: residual correctors on the best bases with covariates (one-step residuals).

Multi-step residual sources would read past features further ahead than their lag inside the training vector, so only historical_oof_1step is proposed.

Parâmetros:

• bases (Sequence[CandidateSpec])

• registry (ModelRegistry)

Tipo de retorno:

list[Proposal]

residual_proposals(bases, registry)

S2: residual grid, breadth-first over the retained bases.

Each (source, corrector, window, alpha) combination is proposed for every retained base (best first) before the next combination, so a budget cut keeps the bases diverse instead of exhausting the grid of the first one.

Parâmetros:

• bases (Sequence[CandidateSpec])

• registry (ModelRegistry)

Tipo de retorno:

list[Proposal]

refinement_proposals(structures, registry, max_refinements)

S3: around each best residual structure, change one axis at a time.

Axes: residual source, corrector hyper-parameters and, when max_stages > 1, extra correction stages. At most max_refinements variants per axis and structure.

Parâmetros:

• structures (Sequence[CandidateSpec])

• registry (ModelRegistry)

• max_refinements (int)

Tipo de retorno:

list[Proposal]

advanced_proposals(bases, registry)

S4: decompositions over the retained bases and fixed combinations of the best.

Decompositions go breadth-first over the bases, like the residual grid. A combination joins the two best retained bases of different families. The two lists are interleaved, so a budget cut keeps both families represented.

Parâmetros:

• bases (Sequence[CandidateSpec])

• registry (ModelRegistry)

Tipo de retorno:

list[Proposal]

dynamic_proposals(structures, registry)

S4 (variant B): dynamic selection around the best residual structures.

dref chooses, at each step, among the structure’s corrector, the other configured correctors and no correction; local combines the base and the structure’s corrector locally. Grid of the legacy project (Silva et al., 2020): neighbours k in DYNAMIC_NEIGHBORS, lag size in DYNAMIC_LAGS and, for local, the kernel ridge alpha in LOCAL_ALPHAS. The first value of each axis is the default; defaults of every method come first, so a budget cut keeps them.

Parâmetros:

• structures (Sequence[CandidateSpec])

• registry (ModelRegistry)

Tipo de retorno:

list[Proposal]

corrector_combination_proposals(structures, registry)

S4: around each best residual structure, its corrector combined with the others.

Parâmetros:

• structures (Sequence[CandidateSpec])

• registry (ModelRegistry)

Tipo de retorno:

list[Proposal]

ensemble_proposals(bases, structures, registry)

S4: ensembles (family ensemble), all from candidates already searched.

• Ensembles of bases: the best retained base of each family, up to ENSEMBLE_SIZE (diversity of families before more members), with every configured method; median needs 3 members and trimmed_mean is left to explicit use (with 3 members it equals the median).

• Ensemble of hybrids: the two best residual structures, weighted methods only.

• Corrected ensemble: the equal-weight ensemble of bases corrected by each configured corrector (first window, alpha and source of the space).

The equal-weight version of each kind comes first, so a budget cut keeps the simplest control of every kind.

Parâmetros:

• bases (Sequence[CandidateSpec])

• structures (Sequence[CandidateSpec])

• registry (ModelRegistry)

Tipo de retorno:

list[Proposal]

default_params(name)

Parameters a base gets when no grid is given (seasonality and lags of this space).

Parâmetros:

name (str)

Tipo de retorno:

dict[str, Any]

class autohybts.search.budgets.SearchGuardConfig(mode: 'GuardMode' = 'standard', max_trials_total: 'int' = 200, max_trials_per_family: 'int' = 40, max_candidates_per_stage: 'int' = 60, max_refinements: 'int' = 2, max_wall_time_s: 'float | None' = None, top_k_per_family: 'int' = 2, top_k_residual_structures: 'int' = 2, require_full_pairing: 'bool' = True, prefer_simpler_on_tie: 'bool' = True, allow_test_feedback_to_search: 'bool' = False)

Base: object

Parâmetros:

• mode (Literal['research_strict', 'standard', 'exploratory'])

• max_trials_total (int)

• max_trials_per_family (int)

• max_candidates_per_stage (int)

• max_refinements (int)

• max_wall_time_s (float | None)

• top_k_per_family (int)

• top_k_residual_structures (int)

• require_full_pairing (bool)

• prefer_simpler_on_tie (bool)

• allow_test_feedback_to_search (bool)

mode: Literal['research_strict', 'standard', 'exploratory']

max_trials_total: int

max_trials_per_family: int

max_candidates_per_stage: int

max_refinements: int

max_wall_time_s: float | None

top_k_per_family: int

top_k_residual_structures: int

require_full_pairing: bool

prefer_simpler_on_tie: bool

allow_test_feedback_to_search: bool

classmethod preset(name, **overrides)

Parâmetros:

• name (Literal['smoke', 'small', 'medium', 'large'])

• overrides (Any)

Tipo de retorno:

SearchGuardConfig

describe()

Tipo de retorno:

dict[str, Any]

class autohybts.selection.policy.SelectionPolicy(profile='standard', median_gain_threshold=0.05, win_rate_threshold=0.6, variability=<factory>, min_coverage=1.0, epsilon=1e-12, family_order=('statistical', 'linear', 'kernel', 'tree', 'neural', 'residual', 'decomposition', 'combination', 'dynamic'), significance_alpha=None)

Base: object

Profile and thresholds of the incremental guarded selection.

Profiles:

• quickstart: variability off by default, declared in every decision.

• standard: protocol thresholds with the variability criterion on.

• research_strict: like standard; refuses to run without a variability criterion or with min_coverage < 1.

• exploratory: decisions are flagged as exploratory, never as unbiased.

significance_alpha (off by default) adds a statistical predicate: the challenger must also beat the champion in a one-sided paired Wilcoxon signed-rank test on the same units, p < significance_alpha. The protocol rule alone is not error control. The test bounds the false acceptance of one comparison at alpha, under its assumptions (independent, symmetric paired differences); it does not control the whole chain, where several families challenge a champion that changes with the earlier decisions, nor the dependence between overlapping origins. Measure the chain’s behaviour with autohybts.benchmarks.calibration.

Units with equal errors are dropped before the test, so n is the number of non-zero paired differences (all series of a panel together). With the exact null distribution the smallest one-sided p-value is 1 / 2**n: at least 5 such units for alpha = 0.05; with fold=3 on one series the predicate can never pass. The p-value comes from SciPy’s default method, which depends on the SciPy version (exact for small n in recent versions, a normal approximation in some cases), so it can move slightly between environments.

Parâmetros:

• profile (Literal['quickstart', 'standard', 'research_strict', 'exploratory'])

• median_gain_threshold (float)

• win_rate_threshold (float)

• variability (VariabilityCriterion | None)

• min_coverage (float)

• epsilon (float)

• family_order (tuple[str, ...])

• significance_alpha (float | None)

profile: Literal['quickstart', 'standard', 'research_strict', 'exploratory']

median_gain_threshold: float

win_rate_threshold: float

variability: VariabilityCriterion | None

min_coverage: float

epsilon: float

family_order: tuple[str, ...]

significance_alpha: float | None

classmethod quickstart(**overrides)

Parâmetros:

overrides (object)

Tipo de retorno:

SelectionPolicy

property exploratory: bool

describe()

Tipo de retorno:

dict[str, object]

class autohybts.search.tuning.Distribution(kind, low=0.0, high=0.0, choices=())

Base: object

One tunable parameter. Dotted names (estimator_params.C) set nested keys.

Parâmetros:

• kind (Literal['int', 'float', 'log_float', 'categorical'])

• low (float)

• high (float)

• choices (tuple[Any, ...])

kind: Literal['int', 'float', 'log_float', 'categorical']

low: float

high: float

choices: tuple[Any, ...]

sample(rng)

Parâmetros:

rng (Generator)

Tipo de retorno:

Any

suggest(trial, name)

Parâmetros:

• trial (Any)

• name (str)

Tipo de retorno:

Any

class autohybts.search.tuning.TuningResult(original, best, trials, sampler, metric)

Base: object

Every trial of a tuning run, the best candidate and how it was searched.

Parâmetros:

• original (CandidateSpec)

• best (CandidateSpec)

• trials (DataFrame)

• sampler (str)

• metric (str)

original: CandidateSpec

best: CandidateSpec

trials: DataFrame

sampler: str

metric: str

property improvement: float

Relative gain of the best over the original on V_search (0 if unchanged).

Estratégias

Decomposition hybrid: one model for the smooth part, another for the volatile part.

y = s + v. The base forecasts s; a corrector forecasts v from windows of its past values, recursively in variant A (only its own predictions enter the window). The forecast is the sum of the two paths.

• ma: causal moving average, s[t] uses y up to t only (the window expands at the start). A centred average would use future values and is not offered. The window comes from the training vector alone: the one whose volatile part has kurtosis closest to 3 (Babu and Reddy, 2014, as in the legacy project). Being causal, it is recomputed on any context, so new observations reach the frozen models (variant B).

• stl: robust STL fitted on the training vector only. It is not recomputed on later observations, so it serves variant A only (forecasting from the end of the training).

class autohybts.strategies.decomposition.DecompositionForecaster(smooth, volatile, window_size=7, method='ma', ma_window=None, max_window=365, period=7, min_corrector_rows=10)

Base: ForecasterBase

Parâmetros:

• smooth (BaseForecaster)

• volatile (ResidualCorrector)

• window_size (int)

• method (str)

• ma_window (int | None)

• max_window (int)

• period (int)

• min_corrector_rows (int)

composite: ClassVar[bool] = True

property min_train_size: int

Smallest training vector fit accepts.

property min_history: int

Smallest context.observed that predict accepts.

diagnostics()

Numbers about the last fit that selection may use (empty by default).

Tipo de retorno:

dict[str, float]

parts(history)

Smooth and volatile parts of history as known at its last observation.

Parâmetros:

history (NDArray[float64])

Tipo de retorno:

tuple[NDArray[float64], NDArray[float64]]

predict_components(horizon, history)

Paths of the smooth and the volatile part; the forecast is their sum.

Parâmetros:

• horizon (int)

• history (NDArray[float64])

Tipo de retorno:

tuple[NDArray[float64], NDArray[float64]]

autohybts.strategies.decomposition.causal_moving_average(y, window)

out[t] = mean(y[max(0, t - window + 1) : t + 1]): no value after t is used.

Parâmetros:

• y (NDArray[float64])

• window (int)

Tipo de retorno:

NDArray[float64]

autohybts.strategies.decomposition.kurtosis_window(y, max_window)

Window in 2..min(max_window, len(y) // 2) whose y - ma has kurtosis closest to 3.

Parâmetros:

• y (NDArray[float64])

• max_window (int)

Tipo de retorno:

int

autohybts.strategies.decomposition.stl_smooth(y, period)

Trend plus seasonal part of a robust STL fitted on y only.

Parâmetros:

• y (NDArray[float64])

• period (int)

Tipo de retorno:

NDArray[float64]

Fixed combinations: of base forecasters, and of residual correctors.

ŷ = Σ w_i · b_i with weights fixed at fit time:

• equal: w_i = 1 / k.

• inverse_mse: w_i ∝ 1 / MSE_i, where MSE_i is the mean squared one-step out-of-fold error of member i on the tail of the training vector (a separate fit on the prefix, as in historical_oof_1step). Weights never see data after the origin.

Every member is then fitted on the whole training vector and forecasts from the same context, so a frozen combination takes new observations like any base (variant B).

class autohybts.strategies.combination.CorrectorCombination(members, weights='equal', holdout=0.3)

Base: Parametrized

Several residual correctors averaged with fixed weights; itself a ResidualCorrector.

Used inside a residual hybrid, ŷ = b + α · Σ w_j · r̂_j, so it inherits every causality rule of the residual pipeline. inverse_mse weights come from the last holdout share of the corrector’s own training rows (in time order): each member is fitted on the rows before them and scored on them; then every member is refitted on all rows.

Parâmetros:

• members (Sequence[ResidualCorrector])

• weights (str)

• holdout (float)

fit(windows, targets)

Parâmetros:

• windows (ArrayLike)

• targets (ArrayLike)

Tipo de retorno:

CorrectorCombination

predict_next(window)

Parâmetros:

window (ArrayLike)

Tipo de retorno:

float

class autohybts.strategies.combination.FixedCombinationForecaster(members, weights='equal', settings=None)

Base: ForecasterBase

Parâmetros:

• members (Sequence[BaseForecaster])

• weights (str)

• settings (ResidualSettings | None)

composite: ClassVar[bool] = True

property min_train_size: int

Smallest training vector fit accepts.

property min_history: int

Smallest context.observed that predict accepts.

diagnostics()

Numbers about the last fit that selection may use (empty by default).

Tipo de retorno:

dict[str, float]

Ensembles of complete forecasters.

ŷ = agg(ŷ_1, ..., ŷ_K) over components that may themselves be hybrids or other compositions:

• equal: mean, weights 1/K.

• median: per-step median of the component forecasts.

• trimmed_mean: per step, drop the max(1, round(trim · K)) lowest and highest forecasts and average the rest.

• inverse_mse: w_k ∝ 1 / MSE_k of one-step out-of-fold errors.

• nnls: non-negative least squares of the target on the out-of-fold forecasts, normalized to sum 1 and shrunk towards equal weights, w = (1 − shrinkage) · w_nnls + shrinkage / K (few out-of-fold rows make free weights unstable: the forecast combination puzzle).

Out-of-fold forecasts come from historical_oof_1step inside the training vector: each component is refitted on the prefix before the tail and forecasts the tail one step at a time, so the weights never see data after the origin. Every component is then fitted on the whole training vector; a frozen ensemble takes new observations like any base (variant B).

class autohybts.strategies.ensemble.EnsembleForecaster(components, method='equal', trim=0.2, shrinkage=0.5, settings=None)

Base: ForecasterBase

Parâmetros:

• components (Sequence[BaseForecaster])

• method (str)

• trim (float)

• shrinkage (float)

• settings (ResidualSettings | None)

composite: ClassVar[bool] = True

property needs_oof: bool

property min_train_size: int

Smallest training vector fit accepts.

property min_history: int

Smallest context.observed that predict accepts.

diagnostics()

Numbers about the last fit that selection may use (empty by default).

Tipo de retorno:

dict[str, float]

class autohybts.registry.capabilities.Capabilities(multi_step=True, online_state_update=True, in_sample_fitted=False, deterministic=True, requires_extra=None, training_scope='local', output_type='point', horizon_strategy='recursive', max_horizon=None, target_mode='univariate', accepts_exog=False)

Base: object

Declared capabilities of a registered model.

Variáveis:

• multi_step (bool) – forecasts several steps from one origin (needed by variant A).

• online_state_update (bool) – forecasts from a later context with frozen parameters, i.e. new observations update its state without refitting (needed by variant B and by out-of-fold residuals).

• in_sample_fitted (bool) – exposes fitted_values() (allows the in_sample residual source).

• deterministic (bool) – same data and parameters give the same forecast whatever the seed; False means the output depends on random_state.

• requires_extra (str | None) – optional dependency group needed to fit, e.g. "stats".

• training_scope (str) – "local" (one series), "global" (trained on a panel; not evaluated by the univariate search) or "pretrained" (a foundation model used as is on each series).

• output_type (str) – "point"; "quantile", "samples" and "distribution" need a probabilistic contract and are skipped by the search.

• horizon_strategy (str) – how multi-step forecasts are produced: "recursive", "direct", "mimo", "dirrec" or "fixed" (a network trained for one horizon). It describes the model, not the A/B protocol.

• max_horizon (int | None) – longest horizon the model forecasts from one origin (None: any); longer requests are skipped, not truncated.

• target_mode (str) – "univariate" (one series from its own history), "multivariate" (several targets forecast jointly) or "exogenous" (needs covariates, past or known in advance). The search is univariate: the other two are skipped until they get their own contract.

• accepts_exog (bool) – takes exogenous features when the experiment has them (ADR-0011); it still forecasts without them.

Parâmetros:

• multi_step (bool)

• online_state_update (bool)

• in_sample_fitted (bool)

• deterministic (bool)

• requires_extra (str | None)

• training_scope (str)

• output_type (str)

• horizon_strategy (str)

• max_horizon (int | None)

• target_mode (str)

• accepts_exog (bool)

Count model fits per trial (cost accounting of the search).

A fit is the training of one leaf model: a base forecaster that is not a composition (naive, ARIMA, a lag regressor, a user model), a residual corrector or a fitted decomposition. Compositions (hybrids, combinations, ensembles) do not count themselves: their members do, so a residual hybrid at one origin counts the base, the extra fit of the base that produces its out-of-fold residuals and the corrector.

The counter lives in a context variable: each trial opens its own (count_fits), so parallel trials in threads never mix their counts. Outside a counting context record_fit does nothing. A user corrector that does not inherit from the library’s classes can call record_fit() in its fit to be counted.

class autohybts.domain.fit_count.FitCounter(total: 'int' = 0)

Base: object

Parâmetros:

total (int)

total: int = 0

autohybts.domain.fit_count.count_fits()

Count the fits made inside the block (nested blocks count only their own).

Tipo de retorno:

Iterator[FitCounter]

autohybts.domain.fit_count.record_fit(n=1)

Add n fits to the current counter, if any.

Parâmetros:

n (int)

Tipo de retorno:

None

Residual multistage: corrections of corrections, up to MAX_STAGES.

Formal targets. Stage 0 is the base b. For k >= 1 the stage-k model is ŷ_k = ŷ_{k-1} + α · r̂_k and its corrector learns e_k(t) = y(t) - ŷ_{k-1}(t), the error of the whole stage k - 1 model, produced inside the training vector by the configured residual source (out-of-fold by default). Because a residual hybrid is itself a base forecaster, stage k is a residual hybrid whose base is stage k - 1: every stage inherits the provenance rules of the residual pipeline (available_at equal to the target, windows ending at the origin, variant A recursion fed only with predicted residuals), so no observation error acts as a feature before it exists.

autohybts.strategies.multistage.stack_stages(base, correctors, *, window_size, alpha, residual_source, settings=None, stage_params=None)

Nest one residual hybrid per corrector, the first corrector closest to the base.

stage_params overrides window_size, alpha or residual_source of the stages after the first (one mapping per extra stage); missing keys are shared.

Parâmetros:

• base (BaseForecaster)

• correctors (Sequence[ResidualCorrector])

• window_size (int)

• alpha (float)

• residual_source (str)

• settings (ResidualSettings | None)

• stage_params (Sequence[Mapping[str, Any]] | None)

Tipo de retorno:

ResidualHybridForecaster

How the strategies of building a forecaster compare: error against cost (Pareto).

Every candidate the search evaluated is a point: error on V_search against fit time or structural complexity. A point is on the Pareto front when no other point is at least as good on both axes and better on one. The front shows what each extra unit of complexity bought; it is a report, never an input of the selection rule.

autohybts.reporting.strategies.complexity(candidate)

Number of fitted models in the structure (a base is 1, each corrector adds 1).

Parâmetros:

candidate (CandidateSpec)

Tipo de retorno:

int

autohybts.reporting.strategies.pareto_front(x, y)

Mask of points not dominated when both x and y are minimized.

Parâmetros:

• x (ArrayLike)

• y (ArrayLike)

Tipo de retorno:

NDArray[bool]

autohybts.reporting.strategies.strategy_plot(kind, table, metric, x='cost', source='V_search')

pareto (error vs cost or complexity, front highlighted) or strategies.

Parâmetros:

• kind (str)

• table (DataFrame)

• metric (str)

• x (Literal['cost', 'complexity'])

• source (str)

Tipo de retorno:

PlotArtifact

autohybts.reporting.strategies.strategy_table(results, metric)

One row per evaluated candidate: score, coverage, cost, complexity, Pareto flags.

Parâmetros:

• results (Sequence[EvaluationResult])

• metric (str)

Tipo de retorno:

DataFrame

Modelos próprios

AutoHybridExperiment.register_model (acima) registra o modelo no experimento.

autohybts.models.torch_model(module, kind='base', requires=None, **defaults)

Registry factory: wrapper settings go to the wrapper, everything else to module.

exp.register_model("lstm", torch_model(LSTMNet, hidden=32, lags=28)) makes hidden a module argument and lags a wrapper argument; both can be changed per candidate (create_model("lstm", hidden=64)) and tuned.

Parâmetros:

• module (Callable[[...], Any])

• kind (str)

• requires (Mapping[str, str] | None)

• defaults (Any)

Tipo de retorno:

Callable[[Mapping[str, Any]], Any]

class autohybts.models.TorchForecaster(module, module_params=None, lags=14, differencing=0, scale=True, epochs=100, batch_size=32, learning_rate=0.001, validation_fraction=0.2, patience=10, random_state=0, device='cpu', requires=None, seasonal_differencing=0, season_length=1, differencing_test='kpss', transform=None, outliers=None)

Base: _TorchState, LaggedModelForecaster

Base forecaster from a PyTorch module (see the module docstring for the contract).

Parâmetros:

• module (Callable[[...], Any])

• module_params (Mapping[str, Any] | None)

• lags (int | tuple[int, ...])

• differencing (int | str)

• scale (bool)

• epochs (int)

• batch_size (int)

• learning_rate (float)

• validation_fraction (float)

• patience (int)

• random_state (int | None)

• device (str)

• requires (Mapping[str, str] | None)

• seasonal_differencing (int)

• season_length (int)

• differencing_test (str)

• transform (str | None)

• outliers (str | None)

class autohybts.models.TorchCorrector(module, module_params=None, epochs=100, batch_size=32, learning_rate=0.001, validation_fraction=0.2, patience=10, random_state=0, device='cpu', requires=None)

Base: _TorchState, WindowCorrector

Residual corrector from a PyTorch module (input: residual window, oldest first).

Parâmetros:

• module (Callable[[...], Any])

• module_params (Mapping[str, Any] | None)

• epochs (int)

• batch_size (int)

• learning_rate (float)

• validation_fraction (float)

• patience (int)

• random_state (int | None)

• device (str)

• requires (Mapping[str, str] | None)

autohybts.models.keras_model(builder, kind='base', requires=None, **defaults)

Registry factory: wrapper settings go to the wrapper, everything else to builder.

Parâmetros:

• builder (Callable[[...], Any])

• kind (str)

• requires (Mapping[str, str] | None)

• defaults (Any)

Tipo de retorno:

Callable[[Mapping[str, Any]], Any]

class autohybts.models.KerasForecaster(builder, builder_params=None, lags=14, differencing=0, scale=True, epochs=100, batch_size=32, learning_rate=0.001, validation_fraction=0.2, patience=10, random_state=0, requires=None, seasonal_differencing=0, season_length=1, differencing_test='kpss', transform=None, outliers=None)

Base: _KerasState, LaggedModelForecaster

Base forecaster from a Keras model builder (see the module docstring).

Parâmetros:

• builder (Callable[[...], Any])

• builder_params (Mapping[str, Any] | None)

• lags (int | tuple[int, ...])

• differencing (int | str)

• scale (bool)

• epochs (int)

• batch_size (int)

• learning_rate (float)

• validation_fraction (float)

• patience (int)

• random_state (int | None)

• requires (Mapping[str, str] | None)

• seasonal_differencing (int)

• season_length (int)

• differencing_test (str)

• transform (str | None)

• outliers (str | None)

class autohybts.models.KerasCorrector(builder, builder_params=None, epochs=100, batch_size=32, learning_rate=0.001, validation_fraction=0.2, patience=10, random_state=0, requires=None)

Base: _KerasState, WindowCorrector

Residual corrector from a Keras model builder (input: residual window, oldest first).

Parâmetros:

• builder (Callable[[...], Any])

• builder_params (Mapping[str, Any] | None)

• epochs (int)

• batch_size (int)

• learning_rate (float)

• validation_fraction (float)

• patience (int)

• random_state (int | None)

• requires (Mapping[str, str] | None)

class autohybts.models.CustomForecaster(fit_fn, predict_fn, params=None, min_train_size=2, min_history=1, requires=None)

Base: ForecasterBase

Parâmetros:

• fit_fn (Callable[..., Any])

• predict_fn (Callable[..., Any])

• params (Mapping[str, Any] | None)

• min_train_size (int)

• min_history (int)

• requires (Mapping[str, str] | None)

property min_train_size: int

Smallest training vector fit accepts.

property min_history: int

Smallest context.observed that predict accepts.

class autohybts.models.RegressorForecaster(estimator, lags=14, differencing=0, scale=True, requires=None, seasonal_differencing=0, season_length=1, differencing_test='kpss', transform=None, outliers=None)

Base: LaggedModelForecaster

Any regressor with fit(X, y)/predict(X) on lag windows (oldest lag first).

Parâmetros:

• estimator (Any)

• lags (int | tuple[int, ...])

• differencing (int | str)

• scale (bool)

• requires (Mapping[str, str] | None)

• seasonal_differencing (int)

• season_length (int)

• differencing_test (str)

• transform (str | None)

• outliers (str | None)

autohybts.models.require(requirements)

Raise UnsupportedCapabilityError unless every requirement is installed.

Parâmetros:

requirements (Mapping[str, str] | None)

Tipo de retorno:

None

autohybts.models.check_specifier(version, specifier)

True if the installed version satisfies a PEP 440 specifier like ">=2.2,<3".

An invalid specifier raises ConfigurationError; a version that does not follow PEP 440 raises UnsupportedCapabilityError (it cannot be checked, so the model is skipped with the reason).

Parâmetros:

• version (str)

• specifier (str)

Tipo de retorno:

bool

autohybts.models.validate_requirements(requirements)

Refuse malformed requirements at registration (ConfigurationError).

Without packaging installed the syntax cannot be checked here; require will then skip the model with the installation hint.

Parâmetros:

requirements (Mapping[str, str] | None)

Tipo de retorno:

None

autohybts.models.framework_versions(packages)

Installed versions, for manifests and reports.

Parâmetros:

packages (Iterable[str])

Tipo de retorno:

dict[str, str | None]

Ablação

Ablation of the selection procedure.

Four procedures, the same search budget and the same external origins (each series’ sealed test):

• lowest_error: the finalist with the lowest mean error on V_select;

• incremental: the guarded incremental chain with the protocol thresholds, all families;

• incremental_simple: as above, only structures with at most two fitted models (standalone and additive residual hybrids);

• guarded_nested: as incremental, but if nested cross-validation on the development history says the procedure (all families, as in incremental) does not beat the procedure “best standalone model of the inner selection”, the best standalone model of V_select is kept. Both sides of that comparison are chosen inside each outer fold, without its block.

Each row (series x seed x procedure) records the external score of the chosen model, those of the best standalone model of V_select and of the naive and seasonal_naive references, and the full cost of the procedure: candidates and units (origin x series) of every search, selection and nested inner search, the configured budget, the stop reason, the proposals cut by each budget limit and the seconds of each phase. lowest_error, incremental and guarded_nested share one search (column search): their search cost is the same work, not three measurements. Budgets limit by count only (no wall clock), so a run is reproducible on another machine. Refitting the chosen model on the pre-test history (seconds_refit) and reading the external test (seconds_external) are reporting, not part of the procedure’s cost.

ablation_report gives, per procedure: median gain against the best standalone model on the test, wins/ties/losses against it, share of hybrids and mean complexity, validation–test gap, mean rank, spread of the median gain across seeds, coverage and cost. The external test only reports: never pick the “winning” procedure on it.

From Python:

from autohybts.benchmarks import ablation_report, run_ablation, synthetic_cases

table = run_ablation(synthetic_cases(12), seeds=(0, 1, 2))
ablation_report(table)

From the command line (--out also writes the resolved protocol next to the CSV):

python -m autohybts.benchmarks.ablation --dataset synthetic --series 12 --seeds 0 1 2
python -m autohybts.benchmarks.ablation --dataset m4-daily --series 20 --out ablation.csv

class autohybts.benchmarks.ablation.AblationCase(series_id, values, horizon, test_size, seasonal_period=None, stratum='', source=<factory>)

Base: object

One series: development history with the external test at the end.

Parâmetros:

• series_id (str)

• values (Series)

• horizon (int)

• test_size (int)

• seasonal_period (int | None)

• stratum (str)

• source (dict[str, Any])

series_id: str

values: Series

horizon: int

test_size: int

seasonal_period: int | None = None

stratum: str = ''

source: dict[str, Any]

autohybts.benchmarks.ablation.ablation_protocol(cases, seeds, budget='smoke', space=None, outer_folds=2)

Configured settings of a run, to save next to its table.

Metrics, initial selection policy and budget overrides follow the experiment’s configuration. Per-series resolved folds and family order remain in the comparison snapshots; this metadata does not perform a search or read the external test.

Local changes not committed cannot be detected without running git; record them by hand when the working tree is not clean.

Parâmetros:

• cases (Sequence[AblationCase])

• seeds (Sequence[int])

• budget (Literal['smoke', 'small', 'medium', 'large'])

• space (dict[str, Any] | None)

• outer_folds (int)

Tipo de retorno:

dict[str, Any]

autohybts.benchmarks.ablation.ablation_report(table, by=None)

Per procedure: gain vs best base, wins/ties/losses, hybrids, gap, rank, seed spread, cost.

Gain statistics use finite paired gains only. n_rows counts supplied case/seed rows, not the study’s planned cases; n_paired and paired_coverage identify the denominator of wins, ties and losses. Without valid gains their shares are NaN.

by (e.g. "stratum") adds an outer level: one block per group.

Parâmetros:

• table (DataFrame)

• by (str | None)

Tipo de retorno:

DataFrame

autohybts.benchmarks.ablation.ablation_uncertainty(table, n_boot=2000, seed=0, level=0.95)

Median gain vs the best base per procedure, with a series-level bootstrap interval.

Seeds of one series are not independent: each series’ gain is first summarized (median over its seeds), then series are resampled with replacement. Also reports the share of series where the procedure is better/worse than the base. Non-finite gains are excluded before aggregation; series without any finite gain remain in n_series but not in n_paired_series or the bootstrap. Their absence is reported explicitly.

Parâmetros:

• table (DataFrame)

• n_boot (int)

• seed (int)

• level (float)

Tipo de retorno:

DataFrame

autohybts.benchmarks.ablation.benchmark_cases(name, subset, n_series, seed=0, *, series_ids=None, development_only=False, development_tail=None)

A random sample of an official benchmark (downloads on first use).

The sample is reproducible: seed draws n_series ids without replacement from the benchmark’s id list; the official test of each series is its sealed test.

Parâmetros:

• name (str)

• subset (str)

• n_series (int)

• seed (int)

• series_ids (Sequence[str] | None)

• development_only (bool)

• development_tail (int | None)

Tipo de retorno:

Iterator[AblationCase]

autohybts.benchmarks.ablation.run_ablation(cases, seeds=(0,), budget='smoke', space=None, progress=None, outer_folds=2, *, checkpoint=None, resume=False, retry_failed=False, on_error='raise', configuration=None)

Run a fixed case/seed plan, optionally checkpointing complete cases atomically.

resume requires the same protocol, data hashes, environment and source code. Successful cases are never rerun. Interrupted cases resume automatically; failed or skipped cases require retry_failed=True. on_error="record" continues after case failures, but configuration and temporal leakage errors always stop. The returned table’s attrs contain protocol, cases and study coverage.

Parâmetros:

• cases (Iterable[AblationCase])

• seeds (Sequence[int])

• budget (Literal['smoke', 'small', 'medium', 'large'])

• space (dict[str, Any] | None)

• progress (Callable[[str], None] | None)

• outer_folds (int)

• checkpoint (str | Path | None)

• resume (bool)

• retry_failed (bool)

• on_error (Literal['raise', 'record'])

• configuration (Mapping[str, Any] | None)

Tipo de retorno:

DataFrame

autohybts.benchmarks.ablation.run_case(case, seed, budget='smoke', space=None, outer_folds=2, *, snapshot_callback=None)

The four procedures on one series and seed; one row per procedure.

Parâmetros:

• case (AblationCase)

• seed (int)

• budget (Literal['smoke', 'small', 'medium', 'large'])

• space (dict[str, Any] | None)

• outer_folds (int)

• snapshot_callback (Callable[[dict[str, Any]], None] | None)

Tipo de retorno:

list[dict[str, object]]

autohybts.benchmarks.ablation.synthetic_cases(n_series, n=400, horizon=14)

Daily series whose residual predictability cycles through AR(0), AR(0.5), AR(0.8).

Parâmetros:

• n_series (int)

• n (int)

• horizon (int)

Tipo de retorno:

Iterator[AblationCase]

Calibração da regra de aceite

Calibration of the acceptance rule on controls with a known answer.

Two controls, both daily, with the sealed test held out and never read:

• white_noise (negative control): level plus white noise. Nothing beyond the mean is predictable, so a hybrid champion is a false acceptance of complexity.

• ar_residual (positive control): trend, weekly seasonality and AR(0.8) noise, with bases that cannot model the AR part (naive, seasonal_naive) and a linear corrector. The residuals are predictable at short horizons, so a standalone champion is a rejected useful gain.

For each series and each number of select origins (fold), one experiment runs the search and the selection once; every policy is then applied to the same finalists with the pure run_chain, so policies differ only in the decision rule. Rates are reported per chain (the final champion: what a user gets) and per comparison (each hybrid challenger), with percentile bootstrap intervals that resample series, the independent units (origins of one series are not independent). Calibration and confirmation sets use disjoint seeds: tune a policy on the first, check it once on the second.

From Python:

from autohybts.benchmarks.calibration import (
    calibration_report, control_cases, run_calibration,
)

table = run_calibration(control_cases(20), folds=(2, 3, 5))
calibration_report(table)

From the command line (--out also writes the resolved protocol):

python -m autohybts.benchmarks.calibration --series 20 --folds 2 3 5 --out cal.csv

class autohybts.benchmarks.calibration.ControlCase(series_id: 'str', control: 'str', values: 'pd.Series')

Base: object

Parâmetros:

• series_id (str)

• control (str)

• values (Series)

series_id: str

control: str

values: Series

autohybts.benchmarks.calibration.calibration_protocol(n_series, split, folds, policies={'rule': {}, 'rule+wilcoxon_0.05': {'significance_alpha': 0.05}}, fh=7, budget='smoke', seed=0, include=('standalone', 'residual'))

Resolved settings of a calibration run, to save next to its table.

Parâmetros:

• n_series (int)

• split (str)

• folds (Sequence[int])

• policies (Mapping[str, Mapping[str, Any]])

• fh (int)

• budget (Literal['smoke', 'small', 'medium', 'large'])

• seed (int)

• include (Sequence[str])

Tipo de retorno:

dict[str, Any]

autohybts.benchmarks.calibration.calibration_report(table, n_boot=2000, seed=0)

Per control, number of select origins and policy: rates with 95 % intervals.

hybrid_champion_rate is the share of series whose final champion is a hybrid: on the negative control the false acceptance per chain, on the positive control one minus the rejected-gain rate (rejected_gain_rate). comparison_accept_rate is the share of hybrid challengers accepted. Intervals resample series.

Parâmetros:

• table (DataFrame)

• n_boot (int)

• seed (int)

Tipo de retorno:

DataFrame

autohybts.benchmarks.calibration.control_cases(n_series, split='calibration', n=300)

n_series series of each control; split picks disjoint seeds.

Parâmetros:

• n_series (int)

• split (str)

• n (int)

Tipo de retorno:

Iterator[ControlCase]

autohybts.benchmarks.calibration.run_calibration(cases, folds=(2, 3, 5), policies={'rule': {}, 'rule+wilcoxon_0.05': {'significance_alpha': 0.05}}, fh=7, budget='smoke', seed=0, progress=None, include=('standalone', 'residual'))

One row per series, number of select origins and policy (see the module docstring).

include are the families of the search; with "ensemble" the rates measure the calibration gate of the composed families: any champion that is not a single model counts as a composed champion.

Parâmetros:

• cases (Iterable[ControlCase])

• folds (Sequence[int])

• policies (Mapping[str, Mapping[str, Any]])

• fh (int)

• budget (Literal['smoke', 'small', 'medium', 'large'])

• seed (int)

• progress (Callable[[str], None] | None)

• include (Sequence[str])

Tipo de retorno:

DataFrame

Exceções

Exception hierarchy.

Configuration errors stop a run. Errors raised while fitting or predicting a single candidate are caught by the search and recorded as auditable FAILED trials.

exception autohybts.exceptions.ArtifactCompatibilityError

Base: AutoHybTSError

A persisted artifact is incompatible, corrupted or untrusted.

exception autohybts.exceptions.AutoHybTSError

Base: Exception

Base class for every error raised by autohybts.

exception autohybts.exceptions.CandidateFitError

Base: AutoHybTSError

A single candidate failed to fit or predict.

exception autohybts.exceptions.ConfigurationError

Base: AutoHybTSError, ValueError

Invalid or inconsistent configuration; stops the run.

exception autohybts.exceptions.CoverageError

Base: AutoHybTSError

A candidate lacks valid forecasts for some required evaluation unit.

exception autohybts.exceptions.DataValidationError

Base: ConfigurationError

Input series is invalid (unordered, duplicated, irregular, non-numeric or missing values).

Never fixed silently: the library does not reorder, resample, deduplicate or impute.

exception autohybts.exceptions.DatasetIntegrityError

Base: AutoHybTSError

A dataset failed a safety check: checksum, unapproved URL or unsafe archive.

exception autohybts.exceptions.DatasetUnavailableError

Base: AutoHybTSError

A dataset is not in the local cache and cannot be downloaded (offline or network).

exception autohybts.exceptions.InsufficientHistoryError

Base: AutoHybTSError, ValueError

Not enough observations for the requested split, window or horizon.

exception autohybts.exceptions.ProtocolConfigurationError

Base: ConfigurationError

Configuration cannot honour the declared scientific protocol.

Example: the research_strict profile without an explicitly defined variability criterion (open question A01).

exception autohybts.exceptions.SealedTestAccessError

Base: TemporalLeakageError

Search, selection or tuning tried to read the sealed test segment.

exception autohybts.exceptions.TemporalLeakageError

Base: AutoHybTSError

Information not available at the forecast origin would be used.

exception autohybts.exceptions.UnsupportedCapabilityError

Base: AutoHybTSError, NotImplementedError

Model, strategy or API path not supported by this adapter or version.