energy_fault_detector.data_splitting.sequence_dataset

class SequenceDatasetBuilder(sequence_length, ts_freq, stride=1, pad_incomplete=False, pad_value=0.0)[source]

Bases: object

Build sequence datasets from a time-series DataFrame with a DatetimeIndex.

This class provides two main dataset builders:

  • build_sliding_dataset for seq2seq models (sequence → sequence),

  • build_seq2one_dataset for seq2one models (sequence → single timestep).

Timestamps are handled as datetime64[ns] (tz-naive, effectively UTC), and when mapping back we localize to the original tz.

Features:

  • Sliding windows with configurable overlap.

  • Data gaps handled via DataGapHandler (windows crossing gaps are dropped, so windows represent contiguous data).

  • Optional conditional_features split out as separate input sequences.

Parameters:

  • sequence_length (int) – Number of time steps in each sequence.

  • ts_freq (timedelta64) – Expected sampling frequency as np.timedelta64.

  • stride (int) – Stride between consecutive windows (sequence_length = disjoint).

  • pad_incomplete (bool) – If True, resample to a regular grid and pad missing values with pad_value before windowing.

  • pad_value (float) – Value to use when padding during resampling if pad_incomplete is True.

build_seq2one_dataset(df, batch_size, conditional_features=None, shuffle=True, predict_mode=False)[source]

Create a seq2one tf.data.Dataset from a time-series DataFrame.

Inputs are sequences of length sequence_length, targets are the main features at the last timestep of each sequence.

Supports a simple DatetimeIndex or a MultiIndex with exactly one datetime-like level. In the MultiIndex case, windows are built per group (first non-datetime level) and concatenated.

Parameters:

  • df (DataFrame) – Time-series data with DatetimeIndex, already preprocessed.

  • batch_size (int) – Batch size for the dataset.

  • conditional_features (Optional[List[str]]) – Optional list of column names to treat as conditional features.

  • shuffle (bool) – Whether to shuffle sequences (only relevant when training is True).

  • predict_mode (bool) – If True, the dataset is used for inference. To ensure we can predict all timestamps, we set stride to 1. TODO: consider stride = sequence_length.

Returns:

  • dataset is a tf.data.Dataset for training or inference,

  • window_timestamps is an array of shape (n_windows, sequence_length) with timestamps for each window.

Return type:

Tuple[DatasetV2, ndarray]

build_sliding_dataset(df, batch_size, conditional_features=None, shuffle=True, predict_mode=False)[source]

Create a seq2seq tf.data.Dataset from a time-series DataFrame.

Supports a simple DatetimeIndex or a MultiIndex with exactly one datetime-like level. In the MultiIndex case, windows are built per group (first non-datetime level) and concatenated.

Parameters:

  • df (DataFrame) – Time-series data with DatetimeIndex, already preprocessed.

  • batch_size (int) – Batch size for the dataset.

  • conditional_features (Optional[List[str]]) – Optional list of column names to treat as conditional features.

  • shuffle (bool) – Whether to shuffle sequences (only relevant when training is True).

  • predict_mode (bool) – If True, the dataset is used for inference. To ensure we can predict all timestamps, we set stride to 1. TODO: consider stride = sequence_length.

Returns:

  • dataset is a tf.data.Dataset for training or inference,

  • window_timestamps is an array of shape (n_windows, sequence_length)

    with timestamps for each window.

Return type:

Tuple[DatasetV2, ndarray]