Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
80dc641
Migrate config from Cerberus to Pydantic with Config wrapper
roelofsc Sep 9, 2026
6e48662
Remove backward-compat dict-style access, migrate consumers to attrib…
roelofsc Sep 9, 2026
c5dfae1
Simplify Config: add defaults for all sections, use flat DataSplitter…
roelofsc Sep 10, 2026
8f07064
Fix notebook API usage: migrate dict-style config access to attribute…
roelofsc Sep 10, 2026
2be16b0
Update docs for config refactor: remove update_config reference and p…
roelofsc Sep 10, 2026
db7f2fe
Simplify Config constructor and make early-stopping validation type-a…
roelofsc Sep 10, 2026
11c0798
Deprecate config_dict, use model_dump instead
roelofsc Sep 11, 2026
3c33b82
Docs: mention Config() as primary entry point, keep generate_quicksta…
roelofsc Sep 11, 2026
6fa1218
Format config modules with black+ruff
roelofsc Sep 11, 2026
04b7d9d
Restore BlockDataSplitter as default data splitter
roelofsc Sep 29, 2026
e8e3db7
Add legacy model compatibility tests and fixture generator
roelofsc Sep 30, 2026
7a8844c
Implemented criticality based alarm event identification
Nov 6, 2026
abc5ccb
Added checks for initial criticality
Nov 6, 2026
270f735
Reintroduced raw criticality calculation and refactored criticality-b…
Nov 6, 2026
9047f7f
Fix test for old RMSEScore object.
roelofsc Nov 6, 2026
94c2949
fixed wording in documentation
Nov 6, 2026
49eeaac
Fixed unit tests (protect_conditional_features)
Nov 9, 2026
bb08d20
Regenerate Keras 3 model fixtures with Keras 3.12.4 for py3.10 compat…
roelofsc Nov 9, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,15 +49,14 @@ pip install energy-fault-detector[dev]
```python
import pandas as pd
from energy_fault_detector import FaultDetector, Config
from energy_fault_detector.config import generate_quickstart_config

### 1. Load your data
df = pd.read_csv("my_data.csv", parse_dates=["timestamp"], index_col="timestamp")
sensor_data = df[["power", "wind_speed", "pitch"]]
normal_index = df["status"] == "normal" # optional boolean mask

### 2. Generate a default configuration
config = generate_quickstart_config()
### 2. Create a default configuration
config = Config() # MultilayerAutoencoder, RMSE score, quantile threshold, default preprocessing

### 3. Train a normal-behaviour model
fault_detector = FaultDetector(config=config, model_directory="my_model")
Expand All @@ -69,6 +68,9 @@ results = fault_detector.predict(sensor_data=sensor_data)
print(results.predicted_anomalies.sum(), "anomalies detected")
```

To generate a config YAML with custom preprocessing (angle columns, scaler, etc.), see
[`generate_quickstart_config`](https://aefdi.github.io/EnergyFaultDetector/configuration.html).

More examples: [Usage examples](https://aefdi.github.io/EnergyFaultDetector/usage_examples.html).

## Quick Fault Detection (CLI)
Expand Down
1 change: 0 additions & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,6 @@ def run_apidoc(app):
# internal utilities
str(pkg_dir / "utils" / "index_utils.py"),
# config internals
str(pkg_dir / "config" / "base_config.py"),
str(pkg_dir / "config" / "config.py"),
str(pkg_dir / "config" / "quickstart_config.py"),
# Class specific files (documented directly under the top module)
Expand Down
63 changes: 50 additions & 13 deletions docs/configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,19 @@ This setup:
- Runs ARCANA with provided parameters when calling :py:obj:`FaultDetector.predict(..., root_cause_analysis=True) <energy_fault_detector.fault_detector.FaultDetector.predict>`.
If not provided, default ARCANA parameters are used (see :py:obj:`ARCANA docs <energy_fault_detector.root_cause_analysis.arcana.Arcana>`).

If you leave out the data_preprocessor configuration (i.e., ``data_preprocessor: {}``), a default preprocessing pipeline
If you leave out the ``data_preprocessor`` section entirely (or set it to ``null``), a default preprocessing pipeline
is generated, which drops constant and binary features, features where >5% of the data is missing, imputes remaining
missing values with the mean value and scales the data to zero mean and unit standard deviation.

You can also generate this kind of configuration programmatically using
The simplest way to get started is ``Config()`` with no arguments, which uses all defaults:

.. code-block:: python

from energy_fault_detector.config import Config

config = Config() # ready-to-use defaults

For custom preprocessing (angle columns, scaler, etc.) or to generate a YAML file, use
:func:`generate_quickstart_config <energy_fault_detector.config.quickstart_config.generate_quickstart_config>`:

.. code-block:: python
Expand All @@ -54,23 +62,21 @@ You can look up the names for the available model classes in the class registry:
Configuration updates
^^^^^^^^^^^^^^^^^^^^^

To update the configuration 'on the fly' (for example for hyperparameter optimization), you provide a new
configuration dictionary via the :py:obj:`Config.update_config <energy_fault_detector.config.config.Config.update_config>` method:
To update the configuration 'on the fly' (for example for hyperparameter optimization), modify the
attributes directly and create a new :class:`~energy_fault_detector.FaultDetector`:

.. code-block:: python

from energy_fault_detector.config import Config
from copy import deepcopy
from energy_fault_detector import FaultDetector

config = Config('configs/base_config.yaml')

# update some parameters:
new_config_dict = deepcopy(config.config_dict)
new_config_dict['train']['anomaly_score']['name'] = 'mahalanobis'
config = Config(new_config_dict)
config.train.anomaly_score.name = 'mahalanobis'

# or create a new configuration object and model
new_model = FaultDetector(Config(config_dict=new_config_dict))
# create a new model with the updated config
new_model = FaultDetector(config)

Detailed configuration
^^^^^^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -150,9 +156,9 @@ Other training configuration sections

- Data splitter (``train.data_splitter``):

- ``type``: one of ``BlockDataSplitter`` (aliases: ``blocks``, ``DataSplitter``), or ``sklearn`` (alias ``train_test_split``).
- For sklearn: ``validation_split`` (float in (0, 1)) and ``shuffle`` (bool).
- For :py:obj:`BlockDataSplitter <energy_fault_detector.data_splitting.data_splitter.BlockDataSplitter>`: ``train_block_size`` and ``val_block_size``.
- ``type``: one of ``BlockDataSplitter`` (aliases: ``blocks``, ``DataSplitter``) or ``sklearn`` (alias ``train_test_split``). Default: ``BlockDataSplitter``.
- For :py:obj:`BlockDataSplitter <energy_fault_detector.data_splitting.data_splitter.BlockDataSplitter>`: ``train_block_size`` and ``val_block_size`` (both optional; the splitter falls back to 5040 / 1680 samples when left unset).
- For sklearn: ``validation_split`` (float in (0, 1)) and ``shuffle`` (bool). With ``shuffle`` false or unset, the last fraction of the data (in original order) is taken as the validation set.
- Early stopping guard: if ``train.autoencoder.params.early_stopping`` is true, you must either set a
valid ``validation_split`` in (0, 1), or use :py:obj:`BlockDataSplitter <energy_fault_detector.data_splitting.data_splitter.BlockDataSplitter>`
with a positive ``val_block_size``.
Expand Down Expand Up @@ -202,6 +208,37 @@ returned by :meth:`FaultDetectionResult.criticality <energy_fault_detector.core.
see :ref:`criticality`.


Criticality and alarms
^^^^^^^^^^^^^^^^^^^^^^
The criticality counter and the derived alarm events are computed from the prediction result rather than configured
in the YAML file. Call
:meth:`FaultDetectionResult.criticality_alarms <energy_fault_detector.core.fault_detection_result.FaultDetectionResult.criticality_alarms>`
(or :func:`calculate_alarms <energy_fault_detector.utils.analysis.calculate_alarms>`) with the desired settings:

.. code-block:: python

results = fault_detector.predict(sensor_data=test_data)

alarm_events, criticality = results.criticality_alarms(
normal_idx=test_status, # optional: True = normal operation
criticality_threshold=None, # None -> one hour of anomalous behaviour
alarm_reset_time_minutes=60, # reset window used to derive max_criticality
)

If ``criticality_threshold`` is omitted it defaults to ``int(1 hour / time_frequency)`` (or ``1`` if the time
frequency exceeds one hour). ``max_criticality`` is derived as
``criticality_threshold + int(alarm_reset_time_minutes / time_frequency)``. See :ref:`criticality` for the full
interpretation and guidance on choosing these values.

For the plain criticality counter without alarm event detection, use the legacy
:meth:`FaultDetectionResult.criticality <energy_fault_detector.core.fault_detection_result.FaultDetectionResult.criticality>`
method, which returns only the criticality series and accepts an explicit ``max_criticality``:

.. code-block:: python

criticality = results.criticality(normal_idx=test_status, max_criticality=144)


Root cause analysis (ARCANA)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If ``root_cause_analysis`` is provided, ARCANA will attempt to attribute anomalies to specific features using the
Expand Down
Loading
Loading