autots.evaluator.feature_detector.loss package

Submodules

autots.evaluator.feature_detector.loss.base module

FeatureDetectionLoss - Core loss calculation for feature detection.

class autots.evaluator.feature_detector.loss.base.FeatureDetectionLoss(changepoint_tolerance_days=7, level_shift_tolerance_days=7, anomaly_tolerance_days=1, holiday_tolerance_days=1, seasonality_window=14, weights=None, holiday_over_anomaly_bonus=0.4, trend_component_penalty='component', trend_complexity_window=7, trend_complexity_weight=0.0, focus_component_weights=False, validation_strictness=1.0, invalid_loss_mode='penalty', invalid_loss_penalty=1000000.0)

Bases: LossMetricsMixin, LossEvaluatorsMixin

Comprehensive loss calculator for feature detection optimization.

Each synthetic label family contributes to the total loss: - Trend changepoints and slopes - Level shifts - Anomalies (including shared events and post patterns) - Holiday timing, direct impacts, and splash/bridge days - Seasonality strength, patterns, and changepoints - Noise regimes and noise-to-signal characteristics - Low-frequency noise structure consistency (drift/shift leakage) - Series-level metadata consistency (scale, type) - Regressor impacts when present

DEFAULT_WEIGHTS = {'anomaly_loss': 1.3, 'holiday_event_loss': 1.2, 'holiday_impact_loss': 0.9, 'holiday_recall_loss': 0.9, 'holiday_splash_loss': 0.03, 'level_shift_loss': 1.3, 'metadata_loss': 0.05, 'noise_level_loss': 0.5, 'noise_regime_loss': 0.4, 'noise_structure_loss': 0.2, 'regressor_loss': 0.3, 'seasonality_changepoint_loss': 0.01, 'seasonality_pattern_loss': 2.0, 'seasonality_strength_loss': 2.0, 'trend_loss': 1.0}

INVALID_LOSS_PENALTY = 1000000.0

calculate_loss(detected_features, true_labels, series_name=None, true_components=None, date_index=None)

Calculate overall loss comparing detected features to true labels.

Parameters:

• detected_features (dict) – Output from TimeSeriesFeatureDetector.get_detected_features(…)

• true_labels (dict) – Labels from SyntheticDailyGenerator.get_all_labels(…)

• series_name (str, optional) – If provided, only evaluate the named series.

• true_components (dict, optional) – Mapping of series -> component arrays from SyntheticDailyGenerator.get_components()

• date_index (pd.DatetimeIndex, optional) – Index used for the time series. Required for seasonality changepoint evaluation.

Returns:

Loss breakdown with per-component metrics and total weighted loss.

Return type:

dict

autots.evaluator.feature_detector.loss.evaluators module

Component-specific loss evaluators.

class autots.evaluator.feature_detector.loss.evaluators.LossEvaluatorsMixin

Bases: object

Mixin providing component-specific loss evaluation methods.

autots.evaluator.feature_detector.loss.metrics module

Distance and penalty metrics for feature detection loss.

class autots.evaluator.feature_detector.loss.metrics.LossMetricsMixin

Bases: object

Mixin providing distance/penalty metric methods for loss calculation.

autots.evaluator.feature_detector.loss.reconstruction module

ReconstructionLoss for real-world datasets without component-level labels.

class autots.evaluator.feature_detector.loss.reconstruction.ReconstructionLoss(trend_complexity_window=7, trend_complexity_weight=1.0, metric_weights=None, trend_dominance_target=0.65, trend_min_other_variance=0.0001, seasonality_lags=(7, 365), seasonality_min_autocorr=0.1, seasonality_improvement_target=0.35, anomaly_improvement_target=0.25, anomaly_min_pre_std=0.001)

Bases: FeatureDetectionLoss

Loss function tailored for real-world datasets lacking component-level labels.

Focuses on reconstruction quality while discouraging overly complex trend fits and encouraging variance to be attributed to seasonality, holidays, anomalies, and level shifts.

DEFAULT_METRIC_WEIGHTS = {'anomaly_capture_loss': 0.7, 'noise_whiteness_loss': 0.5, 'reconstruction_loss': 0.5, 'seasonality_capture_loss': 0.8, 'seasonality_shape_loss': 0.6, 'structural_loss': 1.0, 'trend_dominance_loss': 0.9, 'trend_smoothness_loss': 1.2}

calculate_loss(observed_df, detected_features, components=None, series_name=None)

Calculate reconstruction-oriented loss for unlabeled datasets.

Parameters:

• observed_df (pd.DataFrame) – Original time series data used for detection.

• detected_features (dict) – Output from TimeSeriesFeatureDetector.get_detected_features(…, include_components=True).

• components (dict, optional) – Explicit component container matching get_detected_features()[‘components’].

• series_name (str, optional) – Restrict evaluation to a single series.

Returns:

Loss metrics per series and aggregate total weighted loss.

Return type:

dict

Module contents

class autots.evaluator.feature_detector.loss.FeatureDetectionLoss(changepoint_tolerance_days=7, level_shift_tolerance_days=7, anomaly_tolerance_days=1, holiday_tolerance_days=1, seasonality_window=14, weights=None, holiday_over_anomaly_bonus=0.4, trend_component_penalty='component', trend_complexity_window=7, trend_complexity_weight=0.0, focus_component_weights=False, validation_strictness=1.0, invalid_loss_mode='penalty', invalid_loss_penalty=1000000.0)

Bases: LossMetricsMixin, LossEvaluatorsMixin

Comprehensive loss calculator for feature detection optimization.

Each synthetic label family contributes to the total loss: - Trend changepoints and slopes - Level shifts - Anomalies (including shared events and post patterns) - Holiday timing, direct impacts, and splash/bridge days - Seasonality strength, patterns, and changepoints - Noise regimes and noise-to-signal characteristics - Low-frequency noise structure consistency (drift/shift leakage) - Series-level metadata consistency (scale, type) - Regressor impacts when present

DEFAULT_WEIGHTS = {'anomaly_loss': 1.3, 'holiday_event_loss': 1.2, 'holiday_impact_loss': 0.9, 'holiday_recall_loss': 0.9, 'holiday_splash_loss': 0.03, 'level_shift_loss': 1.3, 'metadata_loss': 0.05, 'noise_level_loss': 0.5, 'noise_regime_loss': 0.4, 'noise_structure_loss': 0.2, 'regressor_loss': 0.3, 'seasonality_changepoint_loss': 0.01, 'seasonality_pattern_loss': 2.0, 'seasonality_strength_loss': 2.0, 'trend_loss': 1.0}

INVALID_LOSS_PENALTY = 1000000.0

calculate_loss(detected_features, true_labels, series_name=None, true_components=None, date_index=None)

Calculate overall loss comparing detected features to true labels.

Parameters:

• detected_features (dict) – Output from TimeSeriesFeatureDetector.get_detected_features(…)

• true_labels (dict) – Labels from SyntheticDailyGenerator.get_all_labels(…)

• series_name (str, optional) – If provided, only evaluate the named series.

• true_components (dict, optional) – Mapping of series -> component arrays from SyntheticDailyGenerator.get_components()

• date_index (pd.DatetimeIndex, optional) – Index used for the time series. Required for seasonality changepoint evaluation.

Returns:

Loss breakdown with per-component metrics and total weighted loss.

Return type:

dict

class autots.evaluator.feature_detector.loss.ReconstructionLoss(trend_complexity_window=7, trend_complexity_weight=1.0, metric_weights=None, trend_dominance_target=0.65, trend_min_other_variance=0.0001, seasonality_lags=(7, 365), seasonality_min_autocorr=0.1, seasonality_improvement_target=0.35, anomaly_improvement_target=0.25, anomaly_min_pre_std=0.001)

Bases: FeatureDetectionLoss

Loss function tailored for real-world datasets lacking component-level labels.

Focuses on reconstruction quality while discouraging overly complex trend fits and encouraging variance to be attributed to seasonality, holidays, anomalies, and level shifts.

DEFAULT_METRIC_WEIGHTS = {'anomaly_capture_loss': 0.7, 'noise_whiteness_loss': 0.5, 'reconstruction_loss': 0.5, 'seasonality_capture_loss': 0.8, 'seasonality_shape_loss': 0.6, 'structural_loss': 1.0, 'trend_dominance_loss': 0.9, 'trend_smoothness_loss': 1.2}

calculate_loss(observed_df, detected_features, components=None, series_name=None)

Calculate reconstruction-oriented loss for unlabeled datasets.

Parameters:

• observed_df (pd.DataFrame) – Original time series data used for detection.

• detected_features (dict) – Output from TimeSeriesFeatureDetector.get_detected_features(…, include_components=True).

• components (dict, optional) – Explicit component container matching get_detected_features()[‘components’].

• series_name (str, optional) – Restrict evaluation to a single series.

Returns:

Loss metrics per series and aggregate total weighted loss.

Return type:

dict