Skip to content

Latest commit

 

History

History
126 lines (94 loc) · 2.84 KB

preprocessor.md

File metadata and controls

126 lines (94 loc) · 2.84 KB

TimeSeriesHandler Guide

TimeSeriesHandler provides a configurable preprocessing pipeline for multivariate time series, including optional auto-configuration (self_tune=True).

Related docs:

Import

from foreblocks import TimeSeriesHandler

Quick start

import numpy as np
import pandas as pd
from foreblocks import TimeSeriesHandler

data = np.random.randn(1200, 4)  # [T, F]
timestamps = pd.date_range("2025-01-01", periods=len(data), freq="h")

pre = TimeSeriesHandler(
    self_tune=True,
    window_size=96,
    horizon=24,
    generate_time_features=True,
)

X, y, processed, time_feats = pre.fit_transform(data, time_stamps=timestamps)

Return values from fit_transform(...):

  • X: input windows
  • y: forecast targets
  • processed: transformed full series
  • time_feats: optional time features (or None)

Core constructor options

Windowing

  • window_size (default 24)
  • horizon (default 10)

Main transforms

  • normalize (True)
  • differencing (False)
  • detrend (False)
  • log_transform (False)
  • apply_filter (False)
  • apply_ewt (False)

Outliers and imputation

  • remove_outliers (False)
  • outlier_method (default "iqr")
  • outlier_threshold (default 0.05)
  • apply_imputation (False)
  • impute_method (default "auto")

Auto-configuration / UX

  • self_tune (False)
  • generate_time_features (False)
  • plot (False)
  • verbose (False)

Typical workflow

# Fit on train data only
X_train, y_train, train_processed, tf_train = pre.fit_transform(train_data, time_stamps=train_ts)

# Transform validation/test using fitted state
X_val = pre.transform(val_data, time_stamps=val_ts)
X_test = pre.transform(test_data, time_stamps=test_ts)

# Invert model outputs back to data scale
pred_real = pre.inverse_transform(pred_scaled)

Manual configuration example

pre = TimeSeriesHandler(
    normalize=True,
    scaling_method="robust",   # when heavy tails are expected
    remove_outliers=True,
    outlier_method="ecod",
    apply_imputation=True,
    impute_method="knn",
    apply_filter=True,
    filter_method="savgol",
    detrend=True,
    generate_time_features=True,
)

Operational notes

  • Input must be 2D: [T, F].
  • Call fit_transform before transform; otherwise transform raises.
  • transform returns windows X (not (X, y, processed)).
  • inverse_transform accepts shape [N, D] or [N, H, D].
  • Auto-configuration prints detected settings when enabled.

When to enable self_tune

  • Use self_tune=True for heterogeneous datasets or quick baselines.
  • Use manual configuration for controlled ablations/reproducibility studies.