energy_fault_detector.autoencoders

Autoencoder model classes.

class BidirectionalLSTMSeq2OneAutoencoder(sequence_builder=None, layers=None, dropout_rate=0.0, regularization=0.01, stateful=False, merge_mode='sum', **ae_kwargs)

Bases: Seq2OneAutoencoder

Bidirectional LSTM-based seq2one autoencoder.

This model consumes a fixed-length time window and reconstructs the main features of the last timestep in that window. Conditional features can be provided per timestep and are concatenated to the encoder inputs without being reconstructed.

Input:

(batch_size, sequence_length, n_main_features) [+ conditional features]

Output:

(batch_size, n_main_features) (last timestep reconstruction)

Parameters:

• sequence_builder (Optional[SequenceDatasetBuilder]) – SequenceDatasetBuilder instance used to create the sequence datasets.

• layers (Optional[List[int]]) – List with the number of LSTM units per encoder layer. Defaults to [128, 64, 32] if None.

• dropout_rate (float) – Dropout rate applied after each LSTM layer.

• regularization (float) – L2 regularization strength for the first encoder LSTM layer.

• stateful (bool) – Whether to use stateful LSTMs.

• merge_mode (str) – String describing the method for combining the forward and backward layer in bidirectional layers. Possible options are [‘concat’, ‘sum’, ‘ave’, ‘mul’]. Defaults to ‘sum’.

• ae_kwargs – Training-related parameters (learning_rate, batch_size, epochs, loss_name, early_stopping, etc.) are accepted as keyword arguments and forwarded to Autoencoder.__init__.

Warning

When stateful=True, the dataset must not be shuffled during training, as shuffling breaks inter-batch state propagation. The current implementation does not enforce this constraint — the caller is responsible for setting shuffle=False in the data splitter / sequence builder when using stateful mode.

Configuration example:

train:
  autoencoder:
    name: BidirectionalLSTMSeq2OneAutoencoder
    params:
      layers: [100, 50, 25]
      regularization: 0.01
      sequence_builder:
        sequence_length: 10
        ts_freq: "10m"
        overlap: 9
      merge_mode: "sum"

Initialize a bidirectional LSTM-based seq2one autoencoder.

create_model(input_dimension, condition_dimension=None, **kwargs)

Create the underlying bidirectional LSTM seq2one autoencoder model.

Return type:

Model

class CNNAutoencoder(sequence_builder=None, layers=None, kernel_size=3, strides=1, dropout_rate=0.0, **ae_kwargs)

Bases: Seq2SeqAutoencoder

CNN-based Seq2Seq autoencoder

Parameters:

• sequence_builder (SequenceDatasetBuilder) – SequenceDatasetBuilder instance used to create the sequence datasets.

• layers (Optional[List[int]]) – List of integers indicating the number of filters of the convolutional layers in the encoder. Defaults to [128, 64, 32] if None. The last number of filters is effectively the code size / latent dimension of the autoencoder.

• kernel_size (int) – Specifies the length of the 1D convolution window. Default: 3.

• strides (int) – Stride length of the 1D convolution window. Default: 1.

• dropout_rate (float) – Dropout rate applied after each convolutional layer. Default: 0.

• conditional_features – Optional list of column names treated as conditional features. This will concatenate the conditions to the main inputs before feeding them to the encoder.

• ae_kwargs – Training-related parameters (learning_rate, batch_size, epochs, loss_name, early_stopping, etc.) are accepted as keyword arguments and forwarded to Autoencoder.__init__.

model

keras Model object.

history

dictionary with the losses for each epoch.

Configuration example:

train:
  autoencoder:
    name: CNNAutoencoder
    sequence_builder:
      sequence_length: 36
      ts_freq: "5m"
      stride: 6
    params:
      sequence_length: 12
      dropout_rate: 0.0
      filters: [128, 64, 32]
      learning_rate: 0.001
      batch_size: 128,
      epochs: 15
      loss_name: mse

create_model(input_dimension, condition_dimension=None, **kwargs)

Create ConvAE Model.

Parameters:

• input_dimension (Tuple[int, int]) – Tuple (sequence_length, n_main_features).

• condition_dimension (Optional[int]) – Number of conditional features per timestep, or None.

Return type:

Model

class CNNSeq2OneAutoencoder(sequence_builder=None, layers=None, decoder_layers=None, code_size=32, kernel_size=3, strides=1, dropout_rate=0.0, max_encoding_size=1000, **ae_kwargs)

Bases: Seq2OneAutoencoder

CNN-based seq2one autoencoder.

This model takes a sequence of length sequence_length and predicts/reconstructs the main features of the last timestep in that sequence. Optionally, per-timestep conditional features can be used as inputs.

It is designed as a short-context model: the Conv1D stack captures local temporal dynamics, while global seasonality (e.g. daily/weekly patterns) is expected to be provided via conditional features such as time-of-day and day-of-week encodings.

How this Seq2One Architecture works: The model will first use a stack of 1D-Convolutional layers to encode sequence data with dimensional reduction. After that, a series of MaxPooling-Layers followed by 1D convolutions is used to summarize the encoded sequences while subsequently reducing the number of timestamps per sequence. Once the encoded data is compact enough, the sample will be flattened and the prediction of the last timestamp of the original input series is done by applying a stack of Dense layers.

Input:

(batch_size, sequence_length, n_main_features) [+ conditional features]

Output:

(batch_size, n_main_features) (last timestep reconstruction)

Parameters:

• sequence_builder (SequenceDatasetBuilder) – SequenceDatasetBuilder instance used to create the sequence datasets.

• layers (Optional[List[int]]) – List of integers indicating the number of filters of the convolutional layers in the encoder. Defaults to [128, 64, 32] if None.

• decoder_layers (Optional[List[int]]) – List of integers indicating the number of units in the layers of the decoder. If not provided, defaults to [32, 64].

• code_size (int) – Size of the latent representation (encoded vector).

• kernel_size (int) – Specifies the length of the 1D convolution window. Default: 3.

• strides (int) – Stride length of the 1D convolution window. Default: 1.

• dropout_rate (float) – Dropout rate applied after each convolutional layer. Default: 0.

• conditional_features – Optional list of column names treated as conditional features. This will concatenate the conditions to the main inputs before feeding them to the encoder.

• max_encoding_size (int) – Maximum size of the encoded vector. If the encoded vector is larger, it will be reduced by a factor of 2 (using max pooling) until it reaches this size. Default: 1000.

• ae_kwargs – Training-related parameters (learning_rate, batch_size, epochs, loss_name, early_stopping, etc.) are accepted as keyword arguments and forwarded to Autoencoder.__init__.

Configuration example:

train:
  autoencoder:
    name: CNNSeq2OneAutoencoder
    params:
      layers: [64, 64, 32]
      code_size: 8
      kernel_size: 3
      max_encoding_size: 1000
      sequence_builder:
        sequence_length: 36
        ts_freq: "5m"
        stride: 6
      conditional_features:
        - hour_of_day_sine
        - hour_of_day_cosine
        - day_of_week_sine
        - day_of_week_cosine

Initialize a CNN-based seq2one autoencoder.

create_model(input_dimension, condition_dimension=None, **kwargs)

Create the underlying CNN seq2one autoencoder model.

Parameters:

• input_dimension (Tuple[int, int]) – Tuple (sequence_length, n_main_features) for the main inputs.

• condition_dimension (Optional[int]) – Number of conditional features per timestep, or None.

• **kwargs – Additional keyword arguments (unused, for extensibility).

Return type:

Model

Returns:

The created Keras model.

class ConditionalAE(conditional_features=None, layers=None, code_size=10, kernel_initializer='he_normal', act='prelu', last_act='linear', **ae_kwargs)

Bases: Autoencoder

Conditional symmetric autoencoder. Same as the MultilayerAutoencoder, where we use certain features in the input as conditions. These are concatenated to the input of both the encoder and decoder.

NOTE: If the input of the fit, tune or predict method is a numpy array or a tensorflow tensor, we assume that the

first couple of columns are the conditions.

Parameters:

• conditional_features (Optional[List[str]]) – list of feature names that are used as conditions. The conditional feature vector is concatenated to the input of both the encoder and decoder.

• layers (Optional[List[int]]) – list of integers indicating the size (# units) of the layers in both the encoder and in the decoder (reversed order in this case). Default [200]

• code_size (int) – number of units of the encoded layer (bottleneck layer). (number of features to compress the input features to). Default 10.

• kernel_initializer (str) – initializer to use in each layer. Default he_normal.

• act (str) – activation function to use, prelu, relu, … Defaults to prelu.

• last_act (str) – activation function for last layer, prelu, relu, sigmoid, linear… Defaults to linear.

• ae_kwargs – Training-related parameters (learning_rate, batch_size, epochs, loss_name, early_stopping, etc.) are accepted as keyword arguments and forwarded to Autoencoder.__init__.

model

keras Model object - the autoencoder network.

encoder

keras Model object - encoder network of the autoencoder.

history

dictionary with the losses and metrics for each epoch.

Configuration example:

train:
  autoencoder:
    name: ConditionalAutoencoder
    params:
      layers: [200]
      code_size: 40
      learning_rate: 0.001
      batch_size: 128,
      epochs: 15
      loss_name: mse
      conditional_features:
       - condition1
       - condition2

create_model(input_dimension, condition_dimension, **kwargs)

Compile a symmetric dense autoencoder.

Parameters:

• input_dimension (int) – number of features in input data.

• condition_dimension (int) – number of features in conditional data.

Return type:

Model

Returns:

A Keras model.

class LSTMSeq2OneAutoencoder(sequence_builder=None, layers=None, decoder_layers=None, code_size=32, dropout_rate=0.0, regularization=0.01, **ae_kwargs)

Bases: Seq2OneAutoencoder

LSTM-based seq2one autoencoder.

This model takes a sequence of length sequence_length and predicts/reconstructs the main features of the last timestep in that sequence. Optionally, per-timestep conditional features can be used as inputs.

The encoder uses a stack of LSTM layers, while the decoder is an MLP with dense layers. The last encoder layer reduces the sequences to the last timestep, which is the fed to the MLP decoder.

Input:

(batch_size, sequence_length, n_main_features) [+ conditional features]

Output:

(batch_size, n_main_features) (last timestep reconstruction)

Parameters:

• sequence_builder (Optional[SequenceDatasetBuilder]) – SequenceDatasetBuilder instance used to create the sequence datasets.

• layers (Optional[List[int]]) – List with the number of LSTM units per encoder layer. Defaults to [128, 64, 32] if None.

• code_size (int) – Size of the latent representation (encoded vector). Default: 32.

• decoder_layers (Optional[List[int]]) – List of integers indicating the number of units in the layers of the decoder. If not provided, defaults to [32, 64].

• dropout_rate (float) – Dropout rate applied after each LSTM layer.

• regularization (float) – L2 regularization strength for the first encoder LSTM layer.

• conditional_features – Optional list of column names treated as conditional features. This will concatenate the conditions to the main inputs before feeding them to the encoder.

• ae_kwargs – Training-related parameters (learning_rate, batch_size, epochs, loss_name, early_stopping, etc.) are accepted as keyword arguments and forwarded to Autoencoder.__init__.

Configuration example:

train:
  autoencoder:
    name: LSTMSeq2OneAutoencoder
    params:
      layers: [100, 50, 25]
      code_size: 10
      regularization: 0.01
      sequence_builder:
        sequence_length: 10
        ts_freq: "10m"
        overlap: 9

Initialize an LSTM-based seq2one autoencoder.

create_model(input_dimension, condition_dimension=None, **kwargs)

Create the underlying LSTM seq2one autoencoder model.

Parameters:

• input_dimension (Tuple[int, int]) – Tuple (sequence_length, n_main_features) for the main inputs.

• condition_dimension (Optional[int]) – Number of conditional features per timestep, or None.

• **kwargs – Additional keyword arguments (unused, for extensibility).

Return type:

Model

Returns:

The created Keras model.

class LSTMSeqAutoencoder(sequence_builder=None, layers=None, dropout_rate=0.0, regularization=0.01, **ae_kwargs)

Bases: Seq2SeqAutoencoder

LSTM-based sequence autoencoder.

This model reconstructs only the main features (all columns that are not listed in conditional_features). It can optionally use per-timestep conditional features as additional inputs to the encoder/decoder.

The input to the model is a sequence of length sequence_length with shape (batch_size, sequence_length, n_main_features) (plus conditional features if used). The output is a sequence of the same length and feature dimension for the main features.

Parameters:

• sequence_builder (Optional[SequenceDatasetBuilder]) – SequenceDatasetBuilder instance used to create the sequence datasets.

• layers (Optional[List[int]]) – List with the number of LSTM units per encoder layer. Defaults to [128, 64, 32] if None.

• dropout_rate (float) – Dropout rate applied after each LSTM layer.

• regularization (float) – L2 regularization strength for the first encoder LSTM layer.

• conditional_features – Optional list of column names treated as conditional features. This will concatenate the conditions to the main inputs before feeding them to the encoder.

• ae_kwargs – Training-related parameters (learning_rate, batch_size, epochs, loss_name, early_stopping, etc.) are accepted as keyword arguments and forwarded to Autoencoder.__init__.

Configuration example:

train:
  autoencoder:
    name: LSTMSeq2OneAutoencoder
    params:
      layers: [100, 50, 25]
      regularization: 0.01
      sequence_builder:
        sequence_length: 10
        ts_freq: "10m"
        overlap: 9

create_model(input_dimension, condition_dimension=None, **kwargs)

Create the underlying LSTM autoencoder model.

Parameters:

• input_dimension (Tuple[int, int]) – Tuple (sequence_length, n_main_features) describing the main-feature input shape.

• condition_dimension (Optional[int]) – Number of conditional features (per timestep) to use as additional inputs, or None if no conditions are used.

• **kwargs – Additional keyword arguments (currently unused, kept for extensibility).

Return type:

Model

Returns:

The created Keras model.

class MultilayerAutoencoder(layers=None, code_size=10, kernel_initializer='he_normal', act='prelu', last_act='linear', **ae_kwargs)

Bases: Autoencoder

Multilayer symmetric autoencoder with Dense layers.

Parameters:

• layers (Optional[List[int]]) – list of integers indicating the size (# units) of the layers in both the encoder and in the decoder (reversed order in this case). Default [200]

• code_size (int) – number of units of the encoded layer (bottleneck layer). (number of features to compress the input features to). Default 10.

• kernel_initializer (str) – initializer to use in each layer. Default he_normal.

• act (str) – activation function to use, prelu, relu, … Defaults to prelu.

• last_act (str) – activation function for last layer, prelu, relu, sigmoid, linear… Defaults to linear.

• ae_kwargs – Training-related parameters (learning_rate, batch_size, epochs, loss_name, early_stopping, etc.) are accepted as keyword arguments and forwarded to Autoencoder.__init__.

model

keras Model object - the autoencoder network.

encoder

keras Model object - encoder network of the autoencoder.

history

dictionary with the losses and metrics for each epoch.

Configuration example:

train:
  autoencoder:
    name: MultilayerAutoencoder
    params:
      layers: [200]
      code_size: 40
      learning_rate: 0.001
      batch_size: 128,
      epochs: 15
      loss_name: mse

create_model(input_dimension, **kwargs)

Compile a symmetric autoencoder model in Keras.

Parameters:

input_dimension (int) – number of features in input data.

Return type:

Model

Returns:

A Keras model.

• energy_fault_detector.autoencoders.seq2one_autoencoder
  • Seq2OneAutoencoder
• energy_fault_detector.autoencoders.seq2seq_autoencoder
  • Seq2SeqAutoencoder
• energy_fault_detector.autoencoders.sequence_autoencoder
  • SequenceAutoencoder
    • SequenceAutoencoder.encode()
    • SequenceAutoencoder.fit()
    • SequenceAutoencoder.get_reconstruction_error()
    • SequenceAutoencoder.predict()
    • SequenceAutoencoder.tune()
    • SequenceAutoencoder.tune_decoder()