ForecastingWorkflowConfig#

class openstef_models.presets.ForecastingWorkflowConfig(*, kind: ~typing.Literal['single'] = 'single', model_id: ~openstef_models.mixins.model_serializer.ModelIdentifier, run_name: str | None = None, model: ~typing.Literal['xgboost', 'gblinear', 'flatliner', 'median', 'constant_quantile', 'lgbm', 'lgbmlinear'], quantiles: list[~openstef_core.types.Quantile] = [0.5], sample_interval: ~datetime.timedelta = datetime.timedelta(seconds=900), horizons: list[~openstef_core.types.LeadTime] = [LeadTime('P2D')], xgboost_hyperparams: ~openstef_models.models.forecasting.xgboost_forecaster.XGBoostHyperParams = XGBoostHyperParams(n_estimators=100, learning_rate=0.3, max_depth=6, min_child_weight=1, gamma=0, objective='pinball_loss', evaluation_metric='mean_pinball_loss', reg_alpha=0, reg_lambda=1, max_delta_step=0, max_leaves=0, grow_policy='depthwise', max_bin=256, num_parallel_trees=1, subsample=1.0, colsample_bytree=1.0, colsample_bylevel=1.0, colsample_bynode=1.0, tree_method='auto', random_state=42, early_stopping_rounds=None, use_target_scaling=True), gblinear_hyperparams: ~openstef_models.models.forecasting.gblinear_forecaster.GBLinearHyperParams = GBLinearHyperParams(n_steps=500, updater='shotgun', learning_rate=0.15, objective='reg:quantileerror', evaluation_metric='mean_pinball_loss', reg_alpha=0.0001, reg_lambda=0.1, feature_selector='shuffle', top_k=0, random_state=None, early_stopping_rounds=10), lgbm_hyperparams: ~openstef_models.models.forecasting.lgbm_forecaster.LGBMHyperParams = LGBMHyperParams(n_estimators=100, learning_rate=0.49, max_depth=2, min_child_weight=1, min_data_in_leaf=10, min_data_in_bin=10, reg_alpha=0, reg_lambda=1, num_leaves=100, max_bin=256, colsample_bytree=1.0, early_stopping_rounds=None), lgbmlinear_hyperparams: ~openstef_models.models.forecasting.lgbmlinear_forecaster.LGBMLinearHyperParams = LGBMLinearHyperParams(n_estimators=100, learning_rate=0.07, max_depth=6, min_child_weight=0.06, min_data_in_leaf=500, min_data_in_bin=500, reg_alpha=0, reg_lambda=1, num_leaves=30, max_bin=256, colsample_bytree=1, early_stopping_rounds=None), location: ~openstef_models.presets.forecasting_workflow.LocationConfig = LocationConfig(name='test_location', description='', coordinate=Coordinate(latitude=52.132633, longitude=5.291266), country_code='NL'), school_holidays: ~openstef_models.transforms.time_domain.school_holiday_features_adder.SchoolHolidayConfig | None = None, target_column: str = 'load', energy_price_column: str = 'day_ahead_electricity_price', radiation_column: str = 'radiation', wind_speed_column: str = 'windspeed', pressure_column: str = 'pressure', temperature_column: str = 'temperature', relative_humidity_column: str = 'relative_humidity', selected_features: ~openstef_models.utils.feature_selection.FeatureSelection = FeatureSelection(include=None, include_regex=None, exclude=None, exclude_regex=None), predict_history: ~datetime.timedelta = datetime.timedelta(days=14), cutoff_history: ~datetime.timedelta = datetime.timedelta(0), completeness_threshold: float = 0.5, completeness_threshold_target_constant_quantile: float = 0.03, flatliner_threshold: ~datetime.timedelta = datetime.timedelta(days=1), detect_non_zero_flatliner: bool = False, predict_nonzero_flatliner: bool = False, shifters: list[~openstef_models.transforms.general.shifter.Shifter] = [], rolling_aggregate_features: list[~openstef_models.transforms.time_domain.rolling_aggregates_adder.AggregationFunction] = [], clip_features: ~openstef_models.utils.feature_selection.FeatureSelection = FeatureSelection(include=None, include_regex=None, exclude=None, exclude_regex=None), nan_on_outlier_features: ~openstef_models.utils.feature_selection.FeatureSelection = FeatureSelection(include=set(), include_regex=set(), exclude=None, exclude_regex=None), outlier_strictness_n_std: float = 2.0, max_day_lags: int = 14, sample_weight_config: ~openstef_models.transforms.general.sample_weighter.SampleWeightConfig = <factory>, data_splitter: ~openstef_models.utils.data_split.DataSplitter = DataSplitter(val_fraction=0.15, test_fraction=0.0, stratification_fraction=0.15, min_days_for_stratification=4, random_state=42), evaluation_metrics: list[~openstef_beam.evaluation.metric_providers.MetricProvider] = <factory>, mlflow_storage: ~openstef_models.integrations.mlflow.mlflow_storage.MLFlowStorage | None = <factory>, model_reuse_enable: bool = True, model_reuse_max_age: ~datetime.timedelta = datetime.timedelta(days=7), model_selection_enable: bool = True, model_selection_metric: tuple[~typing.Union[~openstef_core.types.Quantile, ~typing.Literal['global']], str, ~openstef_beam.evaluation.metric_providers.MetricDirection] = (0.5, 'R2', 'higher_is_better'), model_selection_old_model_penalty: float = 1.2, model_performance_callback_enabled: bool = False, model_performance_callback_metric_threshold: tuple[~typing.Union[~openstef_core.types.Quantile, ~typing.Literal['global']], str, ~openstef_beam.evaluation.metric_providers.MetricDirection, float] = (0.5, 'R2', 'higher_is_better', 0.0), verbosity: ~typing.Literal[0, 1, 2, 3, True] = 0, tags: dict[str, str] = <factory>, experiment_tags: dict[str, str] = <factory>)[source]#

Bases: BaseConfig

Configuration for forecasting workflows.

Defines all parameters needed to set up a forecasting model, including model type, hyperparameters, location information, data columns, and feature engineering settings.

Parameters:
  • kind (Literal['single'])

  • model_id (str)

  • run_name (str | None)

  • model (Literal['xgboost', 'gblinear', 'flatliner', 'median', 'constant_quantile', 'lgbm', 'lgbmlinear'])

  • quantiles (list[Quantile])

  • sample_interval (timedelta)

  • horizons (list[LeadTime])

  • xgboost_hyperparams (XGBoostHyperParams)

  • gblinear_hyperparams (GBLinearHyperParams)

  • lgbm_hyperparams (LGBMHyperParams)

  • lgbmlinear_hyperparams (LGBMLinearHyperParams)

  • location (LocationConfig)

  • school_holidays (SchoolHolidayConfig | None)

  • target_column (str)

  • energy_price_column (str)

  • radiation_column (str)

  • wind_speed_column (str)

  • pressure_column (str)

  • temperature_column (str)

  • relative_humidity_column (str)

  • selected_features (FeatureSelection)

  • predict_history (timedelta)

  • cutoff_history (timedelta)

  • completeness_threshold (float)

  • completeness_threshold_target_constant_quantile (float)

  • flatliner_threshold (timedelta)

  • detect_non_zero_flatliner (bool)

  • predict_nonzero_flatliner (bool)

  • shifters (list[Shifter])

  • rolling_aggregate_features (list[Literal['mean', 'median', 'max', 'min']])

  • clip_features (FeatureSelection)

  • nan_on_outlier_features (FeatureSelection)

  • outlier_strictness_n_std (float)

  • max_day_lags (int)

  • sample_weight_config (SampleWeightConfig)

  • data_splitter (DataSplitter)

  • evaluation_metrics (list[MetricProvider])

  • mlflow_storage (MLFlowStorage | None)

  • model_reuse_enable (bool)

  • model_reuse_max_age (timedelta)

  • model_selection_enable (bool)

  • model_selection_metric (tuple[Union[Quantile, Literal['global']], str, MetricDirection])

  • model_selection_old_model_penalty (float)

  • model_performance_callback_enabled (bool)

  • model_performance_callback_metric_threshold (tuple[Union[Quantile, Literal['global']], str, MetricDirection, float])

  • verbosity (Literal[0, 1, 2, 3, True])

  • tags (dict[str, str])

  • experiment_tags (dict[str, str])

kind: Literal['single']#

Discriminator tag for config type.

model_id: ModelIdentifier#

Unique identifier for the forecasting model.

run_name: str | None#

Optional name for this workflow run, can be used for versioning.

model: Literal['xgboost', 'gblinear', 'flatliner', 'median', 'constant_quantile', 'lgbm', 'lgbmlinear']#

Type of forecasting model to use.

quantiles: list[Quantile]#

List of quantiles to predict for probabilistic forecasting.

sample_interval: timedelta#

Time interval between consecutive data samples.

horizons: list[LeadTime]#

List of forecast horizons to predict.

xgboost_hyperparams: XGBoostHyperParams#

Hyperparameters for XGBoost forecaster.

gblinear_hyperparams: GBLinearHyperParams#

Hyperparameters for GBLinear forecaster.

lgbm_hyperparams: LGBMHyperParams#

Hyperparameters for LightGBM forecaster.

lgbmlinear_hyperparams: LGBMLinearHyperParams#

Hyperparameters for LightGBM forecaster.

location: LocationConfig#

Location information for the forecasting workflow.

school_holidays: SchoolHolidayConfig | None#

Opt-in school holiday features. None disables them.

target_column: str#

Name of the target variable column in datasets.

energy_price_column: str#

Name of the energy price column in datasets.

radiation_column: str#

Name of the radiation column in datasets.

wind_speed_column: str#

Name of the wind speed column in datasets.

pressure_column: str#

Name of the pressure column in datasets.

temperature_column: str#

Name of the temperature column in datasets.

relative_humidity_column: str#

Name of the relative humidity column in datasets.

selected_features: FeatureSelection#

Feature selection for which features to include/exclude.

predict_history: timedelta#

Amount of historical data available at prediction time.

cutoff_history: timedelta#

Amount of historical data to exclude from training and prediction due to incomplete features from lag-based preprocessing. When using lag transforms (e.g., lag-14), the first N days contain NaN values. Set this to match your maximum lag duration (e.g., timedelta(days=14)). Default of 0 assumes no invalid rows are created by preprocessing. Note: should be same as predict_history if you are using lags. We default to disabled to keep the same behaviour as openstef 3.0.

completeness_threshold: float#

Minimum fraction of data that should be available for making a regular forecast.

completeness_threshold_target_constant_quantile: float#

Minimum fraction of target data that should be available for making a constant quantile forecast.

flatliner_threshold: timedelta#

Number of minutes that the load has to be constant to detect a flatliner.

detect_non_zero_flatliner: bool#

If True, flatliners are also detected on non-zero values (median of the load).

predict_nonzero_flatliner: bool#

If True, predict the median of load measurements instead of zero (only for flatliner model).

shifters: list[Shifter]#

List of feature shifts to align aggregation intervals. Each Shifter can target different features with different aggregation periods.

rolling_aggregate_features: list[AggregationFunction]#

If not None, rolling aggregate(s) of load will be used as features in the model.

clip_features: FeatureSelection#

Feature selection for which features to clip to their learned range.

nan_on_outlier_features: FeatureSelection#

Feature selection for which features to replace out-of-range values with NaN. Defaults to no features (disabled).

outlier_strictness_n_std: float#

Number of standard deviations for outlier detection (lower = stricter bounds). Only used when nan_on_outlier_features is enabled.

max_day_lags: int#

Maximum number of days to look back for day-based lags. Default is 14 days (two weekly cycles). Set to 7 for a single weekly cycle.

sample_weight_config: SampleWeightConfig#

Sample weighting configuration. Controls how training samples are weighted. Defaults to weight_exponent=1.0 for gblinear, 0.0 (uniform) for other models.

data_splitter: DataSplitter#

Configuration for splitting data into training, validation, and test sets.

evaluation_metrics: list[MetricProvider]#

List of metric providers for evaluating model score.

mlflow_storage: MLFlowStorage | None#

Configuration for MLflow experiment tracking and model storage.

model_reuse_enable: bool#

Whether to enable reuse of previously trained models.

model_reuse_max_age: timedelta#

Maximum age of a model to be considered for reuse.

model_selection_enable: bool#

Whether to enable automatic model selection based on performance.

model_selection_metric: tuple[Union[Quantile, Literal['global']], str, MetricDirection]#

Metric to monitor for model performance when retraining.

model_selection_old_model_penalty: float#

Penalty to apply to the old model’s metric to bias selection towards newer models.

model_performance_callback_enabled: bool#

Whether to enable the ModelPerformanceCallback that evaluates model performance at the end of fitting.

model_performance_callback_metric_threshold: tuple[Union[Quantile, Literal['global']], str, MetricDirection, float]#

Metric to monitor for model performance threshold at the end of fitting.

verbosity: Literal[0, 1, 2, 3, True]#

Verbosity level. 0=silent, 1=warning, 2=info, 3=debug

tags: dict[str, str]#

Optional metadata tags for the model run.

experiment_tags: dict[str, str]#

Optional metadata tags for experiment tracking.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'protected_namespaces': ()}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].