multitask.search_spaces

multitask.search_spaces

Default hyperparameter search spaces and per-task constants.

A neutral module imported by spotforecast2.multitask.strategies, the user-facing shim modules spotforecast2.multitask.optuna / spotforecast2.multitask.spotoptim, and spotforecast2.models’s ForecasterRecursiveModelFull.tune. Keeping the defaults here means no shim has to import a strategy back, and no strategy class has to import a shim — eliminating the cyclic-import warning CodeQL raised against the lazy-import workaround.

This module is the single canonical home for:

Functions

Name Description
default_optuna_search_space Built-in Optuna search space for LightGBM.
default_spotoptim_search_space Built-in SpotOptim search space for LightGBM.
search_space_catboost Optuna search space for CatBoost hyperparameters.
search_space_lgbm Optuna search space for LightGBM hyperparameters.
search_space_xgb Optuna search space for XGBoost hyperparameters.

default_optuna_search_space

multitask.search_spaces.default_optuna_search_space(trial)

Built-in Optuna search space for LightGBM.

Estimator hyperparameters use the estimator__ prefix so that ForecasterRecursive.set_params(**sample) forwards them to the wrapped LGBMRegressor instead of silently setting attributes on the wrapper. lags is consumed separately via set_lags and therefore stays bare.

This is the space OptunaStrategy uses when no search_space is given. Consumers that tune a non-LightGBM estimator pass their own space instead.

Parameters

Name Type Description Default
trial Any An optuna.trial.Trial instance. required

Returns

Name Type Description
Dict[str, Any] Mapping of hyperparameter name to the value suggested for trial.

Examples

import optuna
from spotforecast2.multitask.search_spaces import default_optuna_search_space

optuna.logging.set_verbosity(optuna.logging.WARNING)
study = optuna.create_study(sampler=optuna.samplers.TPESampler(seed=0))
params = default_optuna_search_space(study.ask())
print(sorted(params))
['estimator__bagging_fraction', 'estimator__feature_fraction', 'estimator__learning_rate', 'estimator__max_depth', 'estimator__n_estimators', 'estimator__num_leaves', 'estimator__reg_alpha', 'estimator__reg_lambda', 'lags']
/Users/bartz/workspace/spotforecast2/src/spotforecast2/multitask/search_spaces.py:92: UserWarning: Choices for a categorical distribution should be a tuple of None, bool, int, float and str for persistent storage but contains [1, 2, 24] which is of type list.
  "lags": trial.suggest_categorical(
/Users/bartz/workspace/spotforecast2/src/spotforecast2/multitask/search_spaces.py:92: UserWarning: Choices for a categorical distribution should be a tuple of None, bool, int, float and str for persistent storage but contains [1, 2, 24, 48] which is of type list.
  "lags": trial.suggest_categorical(
/Users/bartz/workspace/spotforecast2/src/spotforecast2/multitask/search_spaces.py:92: UserWarning: Choices for a categorical distribution should be a tuple of None, bool, int, float and str for persistent storage but contains [1, 2, 23, 24, 47, 48] which is of type list.
  "lags": trial.suggest_categorical(

default_spotoptim_search_space

multitask.search_spaces.default_spotoptim_search_space()

Built-in SpotOptim search space for LightGBM.

Estimator hyperparameters carry the estimator__ prefix; see the docstring of default_optuna_search_space for the rationale. This is the space SpotOptimStrategy uses when no search_space is given; consumers that widen the bounds or tune another estimator start from a copy of it.

Returns

Name Type Description
Dict[str, Any] Mapping of hyperparameter name to a SpotOptim bound tuple
Dict[str, Any] (low, high) / (low, high, "log10") or, for lags, the list of
Dict[str, Any] categorical lag sets.

Examples

from spotforecast2.multitask.search_spaces import default_spotoptim_search_space

space = default_spotoptim_search_space()
print(space["estimator__learning_rate"])
widened = {**space, "estimator__max_depth": (3, 48)}
print(widened["estimator__max_depth"])
(0.0001, 0.1, 'log10')
(3, 48)

search_space_catboost

multitask.search_spaces.search_space_catboost(trial)

Optuna search space for CatBoost hyperparameters.

Consumed by ForecasterRecursiveModelFull.tune via the SEARCH_SPACES registry below. Estimator keys use the estimator__ prefix; see default_optuna_search_space for the rationale.

The space is deliberately bootstrap_type-agnostic: it omits subsample / colsample (valid only for specific CatBoost bootstrap types) to avoid invalid-combination errors, and instead tunes CatBoost’s native depth / l2_leaf_reg / random_strength / bagging_temperature levers.

Parameters

Name Type Description Default
trial Any An optuna.trial.Trial instance. required

Returns

Name Type Description
Dict[str, Any] Mapping of hyperparameter name to suggested value for the current
Dict[str, Any] trial.

Examples

import optuna
from spotforecast2.multitask.search_spaces import search_space_catboost

optuna.logging.set_verbosity(optuna.logging.WARNING)
study = optuna.create_study(
    direction="minimize",
    sampler=optuna.samplers.TPESampler(seed=42),
)
trial = study.ask()
params = search_space_catboost(trial)
print("Keys:", list(params.keys()))
assert "estimator__depth" in params
assert "lags" in params
assert isinstance(params["estimator__learning_rate"], float)
Keys: ['estimator__depth', 'estimator__learning_rate', 'estimator__l2_leaf_reg', 'estimator__n_estimators', 'estimator__random_strength', 'estimator__bagging_temperature', 'lags']

search_space_lgbm

multitask.search_spaces.search_space_lgbm(trial)

Optuna search space for LightGBM hyperparameters.

Consumed by ForecasterRecursiveModelFull.tune via the SEARCH_SPACES registry below. Estimator keys use the estimator__ prefix; see default_optuna_search_space for the rationale.

Parameters

Name Type Description Default
trial Any An optuna.trial.Trial instance. required

Returns

Name Type Description
Dict[str, Any] Mapping of hyperparameter name to suggested value for the current
Dict[str, Any] trial.

Examples

import optuna
from spotforecast2.multitask.search_spaces import search_space_lgbm

optuna.logging.set_verbosity(optuna.logging.WARNING)
study = optuna.create_study(
    direction="minimize",
    sampler=optuna.samplers.TPESampler(seed=42),
)
trial = study.ask()
params = search_space_lgbm(trial)
print("Keys:", list(params.keys()))
assert "estimator__num_leaves" in params
assert "lags" in params
assert isinstance(params["estimator__learning_rate"], float)
Keys: ['estimator__num_leaves', 'estimator__max_depth', 'estimator__learning_rate', 'estimator__n_estimators', 'estimator__bagging_fraction', 'estimator__feature_fraction', 'estimator__reg_alpha', 'estimator__reg_lambda', 'lags']

search_space_xgb

multitask.search_spaces.search_space_xgb(trial)

Optuna search space for XGBoost hyperparameters.

Consumed by ForecasterRecursiveModelFull.tune via the SEARCH_SPACES registry below. Estimator keys use the estimator__ prefix; see default_optuna_search_space for the rationale.

Parameters

Name Type Description Default
trial Any An optuna.trial.Trial instance. required

Returns

Name Type Description
Dict[str, Any] Mapping of hyperparameter name to suggested value for the current
Dict[str, Any] trial.

Examples

import optuna
from spotforecast2.multitask.search_spaces import search_space_xgb

optuna.logging.set_verbosity(optuna.logging.WARNING)
study = optuna.create_study(
    direction="minimize",
    sampler=optuna.samplers.TPESampler(seed=42),
)
trial = study.ask()
params = search_space_xgb(trial)
print("Keys:", list(params.keys()))
assert "estimator__max_depth" in params
assert "lags" in params
assert isinstance(params["estimator__learning_rate"], float)
Keys: ['estimator__max_depth', 'estimator__learning_rate', 'estimator__subsample', 'estimator__colsample_bytree', 'estimator__min_child_weight', 'estimator__n_estimators', 'estimator__alpha', 'estimator__lambda', 'lags']