diff --git a/README.md b/README.md index 0a0042d5..00457c66 100644 --- a/README.md +++ b/README.md @@ -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") @@ -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) diff --git a/docs/conf.py b/docs/conf.py index ed69f7f7..b03e86c3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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) diff --git a/docs/configuration.rst b/docs/configuration.rst index 1bf2d481..e71d2dee 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -30,11 +30,19 @@ This setup: - Runs ARCANA with provided parameters when calling :py:obj:`FaultDetector.predict(..., root_cause_analysis=True) `. If not provided, default ARCANA parameters are used (see :py:obj:`ARCANA docs `). -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 `: .. code-block:: python @@ -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 ` 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 ^^^^^^^^^^^^^^^^^^^^^^ @@ -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 `: ``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 `: ``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 ` with a positive ``val_block_size``. @@ -202,6 +208,37 @@ returned by :meth:`FaultDetectionResult.criticality ` +(or :func:`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 ` +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 diff --git a/docs/criticality.rst b/docs/criticality.rst index 57cb0371..e606cb1a 100644 --- a/docs/criticality.rst +++ b/docs/criticality.rst @@ -1,20 +1,30 @@ .. _criticality: -Criticality -=========== +Criticality and alarms +====================== The criticality is a cumulative counter derived from the point-wise anomaly predictions of a model. It is used to convert raw per-timestamp anomaly decisions into a *persistence-aware* signal, so that alarms are raised only when -anomalous behaviour is sustained over time. This avoids raising alarms for isolated anomalies caused by noise or by -potential data-quality issues. +anomalous behaviour is sustained over time. This avoids raising unnecessary alarms for isolated anomalies caused by +noise or by potential data-quality issues. -The reference implementation is -:func:`calculate_criticality ` in -:mod:`energy_fault_detector.utils.analysis`. The same calculation is available directly on a prediction result via -:meth:`FaultDetectionResult.criticality `. +The package provides two building blocks in :mod:`energy_fault_detector.utils.analysis`: -How it works ------------- +- :func:`calculate_criticality ` computes the raw + criticality counter. +- :func:`calculate_alarms ` builds on it to derive + **alarm events** (start, end, duration) from the criticality. + +Both are exposed on a prediction result: + +- :meth:`FaultDetectionResult.criticality ` + returns only the criticality series (the basic counter, with an explicit ``max_criticality``). +- :meth:`FaultDetectionResult.criticality_alarms ` + returns both the alarm events and the criticality series, with the threshold and reset window derived from the + time frequency. + +How the criticality works +------------------------- For every timestamp the counter is updated by one of three rules, depending on the predicted anomaly and on the operating status (``normal_idx``): @@ -40,40 +50,68 @@ The counter is bounded below by ``0`` and above by ``max_criticality``. If ``nor timestamps are treated as normal operation. .. note:: - The status information (``normal_idx``) can be used to ignore alarms which otherwise inflate the - counter during periods in which anomalous behavior is not meaningful (e.g. during maintenance) + The status information (normal_idx) can be used to ignore alarms which otherwise inflate the counter during periods in which anomalous + behavior is not meaningful (e.g. during maintenance). -Parameters ----------- +Deriving alarms with ``calculate_alarms`` +----------------------------------------- + +:func:`calculate_alarms ` computes the criticality and turns +every timestamp at which the criticality reaches the threshold into an alarm. Contiguous alarm timestamps are +aggregated into alarm events. .. code-block:: python - from energy_fault_detector.utils.analysis import calculate_criticality + from energy_fault_detector.utils.analysis import calculate_alarms - criticality = calculate_criticality( - anomalies, # pd.Series[bool] over time - normal_idx=None, # optional pd.Series[bool], True = normal operation - init_criticality=0, # starting value of the counter - max_criticality=1000, # upper bound of the counter + alarm_events, criticality = calculate_alarms( + anomalies, # pd.Series[bool] over time + normal_idx=None, # optional pd.Series[bool], True = normal operation + init_criticality=0, # starting value of the counter + criticality_threshold=None, # None -> derived from the time frequency (see below) + alarm_reset_time_minutes=60, # reset window used to derive max_criticality ) -- ``anomalies``: boolean :class:`pandas.Series` of predicted anomalies, indexed by timestamp or by a ``MultiIndex`` - such as ``(asset_id, timestamp)``. -- ``normal_idx``: optional boolean :class:`pandas.Series` with normal-operation status. It is reindexed to - ``anomalies``; missing values are treated as normal (``True``). -- ``init_criticality``: initial value of the counter. Used if persistence is desired across multiple calls to the function (e.g. when processing a long time series in separatechunks). -- ``max_criticality``: maximum value the counter can reach. +``alarm_events`` is a :class:`pandas.DataFrame` with the columns ``start``, ``end`` and ``duration`` (and an +additional ``group`` column for a ``MultiIndex``). ``criticality`` is the :class:`pandas.Series` of the counter over +time. + +If ``criticality_threshold`` is not given, it is derived from the time frequency of the data: -The function returns a :class:`pandas.Series` with the criticality value per timestamp and the same index as the -input. For a ``MultiIndex``, the criticality is computed independently per group (e.g. per asset). +- ``criticality_threshold = int(1 hour / time_frequency)`` — the number of timestamps needed to accumulate one hour + of anomalous behaviour. +- If the time frequency is larger than one hour (or cannot be inferred, e.g. for a ``RangeIndex``), the threshold + defaults to ``1``. -On a prediction result you can call the method directly: +``max_criticality`` is derived from the threshold and ``alarm_reset_time_minutes``, which has a default value of ``60``: + +- ``max_criticality = criticality_threshold + int(alarm_reset_time_minutes / time_frequency)`` +- If the time frequency is larger than ``alarm_reset_time_minutes`` (or cannot be inferred), + ``max_criticality = criticality_threshold + 1``. + +The time frequency is inferred as the median difference between consecutive timestamps, using the datetime level of a +``MultiIndex`` when present. For MultiIndex data the criticality and the alarm events are computed independently per +group (e.g. per asset). + +On a prediction result you can call the method directly. It returns the same ``(alarm_events, criticality)`` tuple: .. code-block:: python results = fault_detector.predict(sensor_data=test_sensor_data) - criticality = results.criticality() # all timestamps treated as normal + alarm_events, criticality = results.criticality_alarms() # defaults derived from the data + alarm_events, criticality = results.criticality_alarms( + normal_idx=test_status, + criticality_threshold=6, + alarm_reset_time_minutes=60, + ) + +For the plain criticality counter (without alarm event detection) use the +:meth:`FaultDetectionResult.criticality ` +method, which returns only the ``criticality`` series: + +.. code-block:: python + criticality = results.criticality(normal_idx=test_status, max_criticality=144) Interpreting criticality: raising alarms @@ -84,9 +122,9 @@ Criticality is interpreted relative to an application-specific **criticality thr - as long as ``criticality < threshold``, no alarm is raised, - once ``criticality >= threshold``, an alarm is raised (the anomaly is treated as significant). -Because the counter rises by one per anomalous timestamp, the threshold can be read as the minimum number of consecutive -anomalous timestamps required to raise an alarm. With a fixed sampling frequency this corresponds directly to a time -window: +Because the counter rises by one per anomalous timestamp, the threshold can be read as the minimum number of +consecutive anomalous timestamps required to raise an alarm. With a fixed sampling frequency this corresponds directly +to a time window: .. code-block:: text @@ -114,10 +152,10 @@ Consider: - **Time frequency** of the data and the desired alarm latency. The same physical time window maps to different thresholds for different sampling rates. -- **Expected random anomalies** from noise or data-quality problems. These can be estimated from real anomalies used for validation - and or from validation data with normal status: run the model on validation data known to be normal, - observe how the criticality behaves, and choose a threshold that random fluctuations do not reach. - The more (expected) spurious anomalies per unit of time, the higher the threshold should be. +- **Expected random anomalies** from noise or data-quality problems. These can be estimated from real anomalies used + for validation and/or from validation data with normal status: run the model on validation data known to be normal, + observe how the criticality behaves, and choose a threshold that random fluctuations do not reach. The more + (expected) spurious anomalies per unit of time, the higher the threshold should be. - **Severity and cost** of a missed fault versus a false alarm. A simple procedure: @@ -126,29 +164,31 @@ A simple procedure: #. Observe the maximum criticality reached by random anomalies (noise / data quality). #. Set the threshold well above that level, and additionally require the desired minimum persistence time. -Choosing ``max_criticality`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Choosing ``alarm_reset_time_minutes`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``max_criticality`` caps the counter and therefore controls how long it takes for an active alarm to be reset -after the system returns to normal behaviour. Once the counter has saturated at ``max_criticality``, it must be -decremented back towards the threshold before the alarm is closed. Because the counter decreases by one per normal +``alarm_reset_time_minutes`` controls how long it takes for an active alarm to be reset after the system returns to +normal behaviour, by determining ``max_criticality``. Once the counter has saturated at ``max_criticality``, it must be +decremented back below the threshold before the alarm is closed. Because the counter decreases by one per normal timestamp, the time to reset from saturation is at most: .. code-block:: text max_reset_time = (max_criticality - criticality_threshold) * time_frequency + = alarm_reset_time_minutes -Continuing the example above (``10 minutes`` resolution) with a threshold of ``6`` and ``max_criticality = 12``: +Continuing the example above (``10 minutes`` resolution) with a threshold of ``6`` and +``alarm_reset_time_minutes = 60``, ``max_criticality`` becomes ``6 + int(60 / 10) = 12``: .. math:: (12 - 6) \times 10\,\text{min} = 60\,\text{min} -so at most **one hour** of consecutive normal behaviour is needed for the counter to fall from saturation back below the -threshold and for the alarm to close. +so at most **one hour** of consecutive normal behaviour is needed for the counter to fall from saturation back below +the threshold and for the alarm to close. -Choose ``max_criticality`` relative to your threshold so that the time to reset matches what the application can -tolerate. Setting it so that the reset time is at most **1 hour** or **1 day** is often a good default. +Setting the reset time to at most **1 hour** or **1 day** is often a good default, depending on the application +context and user preferences. .. list-table:: :header-rows: 1 @@ -176,30 +216,27 @@ tolerate. Setting it so that the reset time is at most **1 hour** or **1 day** i - ~1 day normal (from saturation) .. note:: - Both the threshold and ``max_criticality`` are expressed in *number of timestamps*, not in physical time. When you + The threshold and ``max_criticality`` are expressed in *number of timestamps*, not in physical time. When you change the time frequency of your data, recompute them so that the intended physical time windows are preserved. + ``calculate_alarms`` does this automatically for the defaults. -Configuration -------------- - -When using the :class:`FaultDetector ` framework, the maximum -criticality can be set in the YAML configuration: +Alarm event output +^^^^^^^^^^^^^^^^^^ -.. code-block:: yaml - - predict: - criticality: - max_criticality: 144 # default: one day at 10 min resolution - -The criticality *threshold* is not part of this configuration: it is an application decision that you apply to the -returned criticality series, e.g.: +Each alarm event contains the first and last timestamp at which the criticality was at or above the threshold: .. code-block:: python - criticality = results.criticality(normal_idx=test_status, max_criticality=config.max_criticality) - alarms = criticality >= 6 + alarm_events, criticality = calculate_alarms( + anomalies, criticality_threshold=6, alarm_reset_time_minutes=60 + ) + print(alarm_events) + + # start end duration + # 0 2024-01-01 01:10:00 2024-01-01 03:10:00 0 days 02:00:00 -See :ref:`configuration_guide` for the full configuration reference. +The ``duration`` is the difference between ``end`` and ``start``. For a ``MultiIndex`` input an additional +``group`` column identifies the asset or device. Visualisation ------------- @@ -216,7 +253,8 @@ Criticality can be plotted together with the anomaly score using data=test_sensor_data, normal_index=test_status, show_criticality=True, - max_criticality=144, + criticality_threshold=6, + alarm_reset_time_minutes=60, ) Relation to evaluation (CARE score) diff --git a/docs/examples/advanced_config.yaml b/docs/examples/advanced_config.yaml index 3ec6181c..792af351 100644 --- a/docs/examples/advanced_config.yaml +++ b/docs/examples/advanced_config.yaml @@ -120,7 +120,3 @@ root_cause_analysis: init_x_bias: recon num_iter: 1000 verbose: true - -predict: - criticality: - max_criticality: 144 diff --git a/docs/examples/old_config.yaml b/docs/examples/old_config.yaml deleted file mode 100644 index 4e0f454a..00000000 --- a/docs/examples/old_config.yaml +++ /dev/null @@ -1,26 +0,0 @@ -train: - # ... - - data_preprocessor: - # only imputation and scaling are done by default, other steps can be skipped. - params: - imputer_strategy: 'mean' - scale: 'standardize' # standard scaling or minmax scaling (minmax) - include_column_selector: true # whether to apply the ColumnSelector - max_nan_frac_per_col: 0.05 # ColumnSelector option - drop columns where >5% is NaN. - features_to_exclude: # ColumnSelector option - features to always exclude - - feature1 - - feature2 - angles: # list of angles to transform to sine/cosine values; skipped if none provided - - angle1 - - angle2 - include_low_unique_value_filter: true # whether to apply the LowVarianceFilter - min_unique_value_count: 2 # LowVarianceFilter option - drop columns with less than 3 unique values - max_col_zero_frac: 0.99 # LowVarianceFilter option - drop columns which are at least 90% zero - include_duplicate_value_to_nan: false # whether to apply the DuplicateValuesToNan - value_to_replace: 0 # DuplicateValuesToNan option - if duplicated, replace duplicates with NaN - n_max_duplicates: 6 # DuplicateValuesToNan option - if duplicated for n_max_duplicates, replace after 6th value with NaN - duplicate_features_to_exclude: # DuplicateValuesToNan option - list of feature to not transform with DuplicateValuesToNan - - do_not_replace_value_with_nan - - # ... diff --git a/docs/sequence_models.rst b/docs/sequence_models.rst index bcb9d726..6210c728 100644 --- a/docs/sequence_models.rst +++ b/docs/sequence_models.rst @@ -71,8 +71,8 @@ Important points: - ``stride``: - ``stride=1`` → heavily overlapping windows, - ``stride=sequence_length`` → disjoint windows. -- ``ts_freq``: expected sampling interval. The config parser converts - strings like ``"30s"``, ``"10m"`` into ``numpy.timedelta64``. +- ``ts_freq``: expected sampling interval. Strings like ``"30s"``, ``"10m"`` + are converted to ``numpy.timedelta64`` when the model is initialized. - ``pad_incomplete``: if ``true``, the data is resampled to a regular grid at ``ts_freq`` and missing timestamps are filled with ``pad_value``. diff --git a/docs/usage_examples.rst b/docs/usage_examples.rst index 1c80de25..924398ec 100644 --- a/docs/usage_examples.rst +++ b/docs/usage_examples.rst @@ -24,11 +24,11 @@ Throughout this documentation we use the following objects and conventions. predicted anomalies. * Configuration: :class:`FaultDetector ` behaviour - is controlled via a YAML configuration parsed by :class:`Config `. - For most users, the easiest entry point is - :func:`generate_quickstart_config `, - which returns a minimal, valid configuration. For more control, you can provide your own YAML file; see - :doc:`configuration` for examples. + is controlled via a :class:`Config ` object. + ``Config()`` with no arguments produces a ready-to-use default configuration; for custom + preprocessing (angle columns, scaler, etc.) use + :func:`generate_quickstart_config `. + See :doc:`configuration` for details. * ``sensor_data``: a :class:`pandas.DataFrame` in **wide format**. Each row is a timestamp (or index entry), each column a sensor or feature. @@ -61,7 +61,6 @@ create a configuration, train a model and predict. 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") @@ -73,9 +72,8 @@ create a configuration, train a model and predict. # This is optional; if omitted, all data is treated as normal normal_index = df["status"] == "normal" - # 2. Generate and load a base config - generate_quickstart_config(output_path="base_config.yaml") - config = Config("base_config.yaml") + # 2. Create a default configuration + config = Config() # MultilayerAutoencoder, RMSE score, quantile threshold, default preprocessing # 3. Train a normal-behavior model fault_detector = FaultDetector(config=config, model_directory="fault_detector_model") @@ -149,14 +147,20 @@ with the following information: * arcana_losses: pandas DataFrame containing recorded values for all losses in ARCANA. None if ARCANA was not run. * tracked_bias: List of pandas DataFrames. None if ARCANA was not run. -On top of the raw predictions, you can derive the *criticality* counter, which accumulates sustained anomalies and is -used to raise alarms only after anomalous behaviour persists over time. See :ref:`criticality` for the interpretation -and how to choose a threshold: +On top of the raw predictions you can derive the *criticality* counter and alarm events, which raise alarms only after +anomalous behaviour persists over time. See :ref:`criticality` for the interpretation and how to choose the settings: .. code-block:: python + 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 + ) + # alarm_events: DataFrame with columns start, end, duration (and group for MultiIndex data) + + # Alternatively, only the criticality counter, with an explicit maximum criticality = results.criticality(normal_idx=test_status, max_criticality=144) - alarms = criticality >= 6 # threshold chosen based on time frequency and application context You can also create a :py:obj:`FaultDetector ` object and load trained models using the :py:obj:`FaultDetector.load ` class method. @@ -195,7 +199,7 @@ Configuration ^^^^^^^^^^^^^ The behaviour of the :py:class:`FaultDetector ` -is controlled by a YAML configuration, parsed by :py:class:`Config `. +is controlled by a :py:class:`Config ` object (a Pydantic model). The config typically has: - a ``train`` section: @@ -206,21 +210,23 @@ The config typically has: - ``data_splitter``: how training/validation sets are split, - optional ``data_clipping``: outlier clipping on training data only. - an optional ``root_cause_analysis`` section for ARCANA. -- an optional ``predict`` section (e.g. criticality settings). -For most users, the easiest way to create a valid configuration is via :func:`generate_quickstart_config `: +``Config()`` with no arguments produces a ready-to-use default configuration. +For custom preprocessing (angle columns, scaler, etc.) or to generate a YAML file, use +:func:`generate_quickstart_config `: .. code-block:: python - from energy_fault_detector.config.quickstart_config import generate_quickstart_config + from energy_fault_detector import FaultDetector from energy_fault_detector.config import Config + from energy_fault_detector.config import generate_quickstart_config - # Create a minimal, valid config file - generate_quickstart_config(output_path="base_config.yaml") + # Simplest: use defaults + config = Config() + fd = FaultDetector(config=config) - # Load and use it - cfg = Config("base_config.yaml") - fd = FaultDetector(config=cfg) + # Or generate a config with custom preprocessing and save to YAML: + config = generate_quickstart_config(angle_columns=["wind_dir"], output_path="base_config.yaml") If you prefer to write the YAML yourself or need more control, see the :ref:`Configuration guide ` for a full reference and examples. @@ -250,8 +256,8 @@ walkthrough of the evaluation workflow (event creation, criticality, CARE-Score on benchmark datasets such as CARE2Compare and PreDist). A higher-level evaluation helper/script may be added in a future version. -See :ref:`criticality` for how criticality is computed and interpreted for both alarm raising and event-level -evaluation. +See :ref:`criticality` for how criticality and alarm events are computed and interpreted for both alarm raising and +event-level evaluation. MultiIndex and sequence models ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/energy_fault_detector/anomaly_scores/rmse_score.py b/energy_fault_detector/anomaly_scores/rmse_score.py index 9cd7d0a1..927d951a 100644 --- a/energy_fault_detector/anomaly_scores/rmse_score.py +++ b/energy_fault_detector/anomaly_scores/rmse_score.py @@ -67,6 +67,11 @@ def standardize(self, x: DataType): """Standardization of the reconstruction error in x""" check_is_fitted(self) + + if not hasattr(self, 'std_x_'): + # backward compat. + self.std_x_ = np.zeros(x.shape[1]) + x_ = x.copy() std_mask = self.std_x_ > 0 if np.all(std_mask): diff --git a/energy_fault_detector/config/__init__.py b/energy_fault_detector/config/__init__.py index a7b6bc61..328d7dfe 100644 --- a/energy_fault_detector/config/__init__.py +++ b/energy_fault_detector/config/__init__.py @@ -1,10 +1,10 @@ """Configuration of the fault-detection pipeline, loaded and validated from YAML.""" -from energy_fault_detector.config.config import Config -from energy_fault_detector.config.base_config import InvalidConfigFile +from energy_fault_detector.config.config import Config, InvalidConfigFile from energy_fault_detector.config.quickstart_config import generate_quickstart_config __all__ = [ "Config", - "generate_quickstart_config" + "InvalidConfigFile", + "generate_quickstart_config", ] diff --git a/energy_fault_detector/config/base_config.py b/energy_fault_detector/config/base_config.py deleted file mode 100644 index 46ab9f84..00000000 --- a/energy_fault_detector/config/base_config.py +++ /dev/null @@ -1,163 +0,0 @@ -"""Base config class template""" - -import os -import logging -from typing import Dict, Optional, List, Any, Callable -import datetime -from abc import ABC -from copy import deepcopy - -import yaml -import numpy as np -from cerberus import Validator - -logger = logging.getLogger('energy_fault_detector') - -SCHEMA = {'allow_unknown': True} - - -def _format_timedelta(value: np.timedelta64) -> str: - """Format np.timedelta64 as a compact string like '30s' for YAML.""" - # Store everything in seconds - total_seconds = int(value.astype('timedelta64[s]').astype(int)) - return f"{total_seconds}s" - - -class InvalidConfigFile(Exception): - """Raise when config file is not valid""" - - -class BaseConfig(ABC): - """Base configuration class. - either config_filename or config_dict must be provided. - """ - - def __init__(self, config_filename: str = None, config_dict: Dict[str, Any] = None): - - self.configuration_file: str = config_filename - self.config_dict: Optional[Dict] = config_dict - - # config schema - define in the subclasses - self._schema: Dict = None - self._extra_validation_checks = None - # call self.read_config() - - def __getitem__(self, item) -> Any: - return self.config_dict[item] - - def __contains__(self, item): - return item in self.config_dict.keys() - - def __repr__(self): - return self.config_dict.__repr__() - - def read_config(self, part: str = None) -> None: - """Read and validate the configuration.""" - - if self.configuration_file is not None: - with open(self.configuration_file, 'r', encoding='utf-8') as f: - self.config_dict = yaml.safe_load(f) - - if self.config_dict is None: - raise InvalidConfigFile('The configuration file is empty!') - - # backwards compatibility - if part is not None: - if part in self.config_dict: - self.config_dict = self.config_dict[part] - - if self._schema is None: - raise ValueError('The `_schema` attribute is missing...') - - self._validate_config(self.config_dict, schema=self._schema, extra_checks=self._extra_validation_checks) - - def update_config(self, new_config_dict: Dict[str, Any]) -> None: - """Update the configuration. Sets the configuration_file path to None. - - Args: - new_config_dict: dictionary with the new configuration. - """ - # TODO: consider returning a new instance - new_config = self.config_dict.copy() - new_config.update(new_config_dict) - self._validate_config(new_config, self._schema, extra_checks=self._extra_validation_checks) - self.configuration_file = None - - def write_config(self, file_name: Optional[str] = None, overwrite: bool = False) -> None: - """Write the configuration to a yaml file""" - - # make copy to not modify the original config - conf_dict_to_save = deepcopy(self.config_dict) - - if file_name is None and self.configuration_file is None: - raise ValueError('No file name given and no known configuration file to overwrite.') - - file_name = file_name if file_name is not None else self.configuration_file - if os.path.exists(file_name) and not overwrite: - raise FileExistsError(f'File {file_name} already exists and overwrite is set to False.') - - ae_params = conf_dict_to_save.get('train', {}).get('autoencoder', {}).get('params', {}) - seq_builder = ae_params.get('sequence_builder') - if isinstance(seq_builder, dict): - sb_ts_freq = seq_builder.get('ts_freq') - if isinstance(sb_ts_freq, np.timedelta64): - seq_builder['ts_freq'] = _format_timedelta(sb_ts_freq) - conf_dict_to_save['train']['autoencoder']['params']['sequence_builder'] = seq_builder - - with open(file_name, 'w', encoding='utf-8') as f: - yaml.safe_dump(conf_dict_to_save, f) - - def save(self, file_name: str, overwrite: bool = False) -> None: - """Save the configuration to a yaml file. - - Wrapper for write_config so API is similar to other objects. - """ - self.write_config(file_name, overwrite) - - @staticmethod - def _parse_dates(dates: List, dt_format: str = '%Y-%m-%d') -> List: - """Parse given string dates""" - - parsed = [] - for date in dates: - if isinstance(date, str): - date = datetime.datetime.strptime(date, dt_format).date() - elif isinstance(date, datetime.date): - pass - else: - raise ValueError('Given date %s of type %s cannot be parsed' % date, type(date)) - parsed.append(date) - - return parsed - - def _validate_config(self, config_dict: Dict[str, Any], schema: Dict[str, str], - extra_checks: List[Callable[[Dict], None]] = None) -> None: - """Check whether the provided configuraton has all expected keys. - If the given file is a valid configuration, the config_dict attribute is set. - - Args: - config_dict: dictionary containing the configuration - schema: Cerberus schema to validate against - extra_checks: list of extra validation checks to run. Should be functions that take the configuration - dictionary as input and return the (updated) config_dict or raise InvalidConfigFile - """ - - validator = Validator(allow_unknown=True) # allow_unknown for backwards compat - if not validator.validate(config_dict, schema): - raise InvalidConfigFile(f'Configuration is not valid: {validator.errors}') - - for key in list(config_dict.keys()): - if key not in schema: - logger.info('Key `%s` is an unknown field and will be ignored.', key) - config_dict.pop(key) - - if config_dict == {}: - raise InvalidConfigFile(f'The configuration file is empty for {self.__class__.__name__}.') - - config_dict = validator.normalized(config_dict) - - if extra_checks is not None: - for extra_check in extra_checks: - config_dict = extra_check(config_dict) - - self.config_dict = config_dict diff --git a/energy_fault_detector/config/config.py b/energy_fault_detector/config/config.py index 998099a4..59b6af7e 100644 --- a/energy_fault_detector/config/config.py +++ b/energy_fault_detector/config/config.py @@ -1,215 +1,104 @@ -"""Configuration object for anomaly detection""" +"""Configuration object for anomaly detection. -import logging -from pathlib import Path -from typing import Dict, Optional, List, Callable, Any -import warnings - -from energy_fault_detector.config.base_config import BaseConfig, InvalidConfigFile +The :class:`Config` class is a Pydantic ``BaseModel`` that validates YAML/dict +input. Top-level sections (``train``, ``root_cause_analysis``, ``dtype``) are +typed fields accessible via normal attribute access +(``config.train.autoencoder.params``). File I/O (``Config('file.yaml')``, +``write_config``) is built into the constructor and model methods. -logger = logging.getLogger('energy_fault_detector') - -# TODO: Clearer error/validation messages -# Consider pydantic or data classes instead of cerberus -TRAIN_SCHEMA = { - 'anomaly_score': { - 'type': 'dict', - 'required': True, - 'schema': { - 'name': {'type': 'string', 'required': True}, - 'params': {'type': 'dict', 'required': False}, - } - }, - 'autoencoder': { - 'type': 'dict', - 'required': True, - 'schema': { - 'name': {'type': 'string', 'required': True}, - 'params': {'type': ['dict', 'list'], 'required': True}, - 'verbose': {'type': 'integer', 'required': False}, - } - }, - 'data_preprocessor': { - 'type': 'dict', - 'required': True, - 'allow_unknown': False, - 'nullable': True, # if not specified, create default pipeline - 'schema': { - 'params': {'type': 'dict', 'required': False, 'nullable': True,}, - 'steps': { - 'type': 'list', - 'required': False, - 'nullable': True, - 'schema': { - 'type': 'dict', - 'allow_unknown': True - } - }, - } - }, - 'threshold_selector': { - 'type': 'dict', - 'required': True, - 'schema': { - 'name': {'type': 'string', 'required': True}, - 'fit_on_val': {'type': 'boolean', 'required': False, 'default': False}, - 'params': {'type': 'dict', 'required': False}, - } - }, - 'data_clipping': { - 'type': 'dict', - 'required': False, # no data clipping if not specified - 'schema': { - 'lower_percentile': {'type': 'float', 'required': False}, - 'upper_percentile': {'type': 'float', 'required': False}, - 'features_to_exclude': {'type': 'list', 'required': False, 'schema': {'type': 'string'}}, - 'features_to_clip': {'type': 'list', 'required': False, 'schema': {'type': 'string'}}, - } - }, - 'data_splitter': { - 'type': 'dict', - 'required': False, # defaults if not specified - 'schema': { - 'type': {'type': 'string', 'required': False, 'default': 'BlockDataSplitter', - 'allowed': ['DataSplitter', 'BlockDataSplitter', 'blocks', 'sklearn', 'train_test_split', 'train_val_split']}, - 'train_block_size': {'type': 'integer', 'required': False, 'dependencies': {'type': ['DataSplitter', 'BlockDataSplitter', 'blocks']}}, - 'val_block_size': {'type': 'integer', 'required': False, 'dependencies': {'type': ['DataSplitter', 'BlockDataSplitter', 'blocks']}}, - 'validation_split': {'type': 'float', 'required': False, 'dependencies': {'type': ['sklearn', 'train_test_split', 'train_val_split']}}, - 'shuffle': {'type': 'boolean', 'required': False, 'dependencies': {'type': ['sklearn', 'train_test_split']}}, - } - }, - 'protect_conditional_features': {'type': 'boolean', 'required': False, 'default': False}, -} +All sections have sensible defaults — ``Config()`` with no arguments produces a +ready-to-use configuration (MultilayerAutoencoder, RMSE anomaly score, quantile +threshold selector, default preprocessing pipeline, BlockDataSplitter). +""" -ROOT_CAUSE_ANALYSIS_SCHEMA = { - 'alpha': {'type': 'float', 'required': False}, - 'init_x_bias': {'type': 'string', 'required': False}, - 'num_iter': {'type': 'integer', 'required': False}, - 'epsilon': {'type': 'float', 'required': False}, - 'verbose': {'type': 'boolean', 'required': False}, - 'max_sample_threshold': {'type': 'integer', 'required': False}, -} +import logging +import warnings +from pathlib import Path +from typing import Any, Literal -PREDICT_SCHEMA = { - 'criticality': {'type': 'dict', 'required': False, 'schema': { - 'max_criticality': {'type': 'integer', 'required': False} - }} -} +import yaml +from pydantic import ( + BaseModel, + ConfigDict, + PrivateAttr, + ValidationError, + model_validator, +) -CONFIG_SCHEMA = { - 'train': {'type': 'dict', 'schema': TRAIN_SCHEMA, 'required': False, 'allow_unknown': True}, - 'predict': {'type': 'dict', 'schema': PREDICT_SCHEMA, 'required': False}, - 'root_cause_analysis': {'type': 'dict', 'schema': ROOT_CAUSE_ANALYSIS_SCHEMA, 'required': False}, - 'dtype': {'type': 'string', 'required': False, 'allowed': ['float32', 'float64']} -} +logger = logging.getLogger("energy_fault_detector") -def _validate_early_stopping(config_dict: Dict[str, Any]) -> Dict[str, Any]: - """Check whether early_stopping settings are ok.""" +class InvalidConfigFile(Exception): + """Raise when the configuration file is not valid.""" - train_config = config_dict.get('train', {}) - early_stopping = train_config.get('autoencoder', {}).get('params', {}).get('early_stopping', False) - data_splitter = train_config.get('data_splitter', {}) - validation_split = data_splitter.get('validation_split', 0.0) - val_block_size = data_splitter.get('val_block_size', 0) +def _format_validation_error(exc: ValidationError) -> InvalidConfigFile: + """Convert a Pydantic ``ValidationError`` into an :class:`InvalidConfigFile`.""" + lines = [] + for err in exc.errors(): + loc = ".".join(str(p) for p in err["loc"]) + lines.append(f"{loc}: {err['msg']}") + return InvalidConfigFile("Configuration is not valid: " + "; ".join(lines)) - if not isinstance(validation_split, float): - validation_split = 0.0 - validation = 0 < validation_split < 1 or val_block_size > 0 +class AnomalyScoreConfig(BaseModel): + """``train.anomaly_score`` section.""" - if early_stopping and not validation: - msg = f'Configuration is not valid: If early_stopping is enabled either validation_split or ' \ - f'val_block_size must be given. If validation_split is used, it must be a float >0 and <1.' - raise InvalidConfigFile(msg) + model_config = ConfigDict(extra="allow", validate_assignment=True) + name: str = "rmse" + params: dict[str, Any] = {} - return config_dict + @model_validator(mode="after") + def _none_params_to_empty(self) -> "AnomalyScoreConfig": + if self.params is None: + self.params = {} + return self -def _parse_timedelta(config_dict: Dict[str, Any]) -> Dict[str, Any]: - """Parse sequence_builder.ts_freq from a compact string (e.g. '10m') to np.timedelta64. +class AutoencoderConfig(BaseModel): + """``train.autoencoder`` section. - Expects `ts_freq` under: train.autoencoder.params.sequence_builder.ts_freq - and supports strings like '10m', '1h', '30s'. + ``params`` is an opaque dict consumed by the registry/model factory + (includes autoencoder-specific keys like ``sequence_builder``). """ - UNIT_MAP = {"min": "m", "sec": "s", "hr": "h", "hour": "h"} - - train_cfg = config_dict.get("train", {}) - ae_cfg = train_cfg.get("autoencoder", {}) or {} - params_cfg = ae_cfg.get("params", {}) or {} - seq_builder_cfg = params_cfg.get("sequence_builder", {}) or {} - ts_freq = seq_builder_cfg.get("ts_freq") - - if isinstance(ts_freq, str): - # Parse '10m', '1h', etc. - digits = "".join(ch for ch in ts_freq if ch.isdigit()) - unit = "".join(ch for ch in ts_freq if not ch.isdigit()) - unit = UNIT_MAP.get(unit, unit) - if not digits or not unit: - raise ValueError(f"Unexpected value for `ts_freq`: {ts_freq!r}. Expected format like '10m', '1h'.") - import numpy as np # noqa: F401 - value = int(digits) - seq_builder_cfg["ts_freq"] = np.timedelta64(value, unit) - params_cfg["sequence_builder"] = seq_builder_cfg - ae_cfg["params"] = params_cfg - train_cfg["autoencoder"] = ae_cfg - config_dict["train"] = train_cfg - - return config_dict - - -def _validate_sequence_fit_on_val(config_dict: Dict[str, Any]) -> Dict[str, Any]: - """Warn if fit_on_val=True with a sequence model and shuffle=True.""" - - train_cfg = config_dict.get("train", {}) - has_sequence_builder = "sequence_builder" in ( - train_cfg.get("autoencoder", {}).get("params", {}) or {} - ) - fit_on_val = train_cfg.get("threshold_selector", {}).get("fit_on_val", False) - shuffle = train_cfg.get("data_splitter", {}).get("shuffle", False) - if has_sequence_builder and fit_on_val and shuffle: - import warnings - warnings.warn( - "Using 'fit_on_val=True' with a sequence model and 'shuffle=True' may result in " - "non-contiguous validation timestamps. The sequence builder will drop windows that " - "cross data gaps, potentially leaving no valid windows for threshold fitting. " - "Consider setting 'shuffle: false' or 'fit_on_val: false'.", - UserWarning, - stacklevel=2, - ) + model_config = ConfigDict(extra="allow", validate_assignment=True) + name: str = "default" + params: dict[str, Any] = {} + verbose: int | None = None - return config_dict + @model_validator(mode="after") + def _none_params_to_empty(self) -> "AutoencoderConfig": + if self.params is None: + self.params = {} + return self -class Config(BaseConfig): - """Configuration class. Either config_filename or config_dict must be provided. - Reads a yaml file with the anomaly detection configuration and sets corresponding settings. - """ - - def __init__(self, config_filename: str | Path = None, config_dict: Dict[str, Any] = None): - super().__init__(config_filename=config_filename, config_dict=config_dict) - self._schema = CONFIG_SCHEMA - self._extra_validation_checks: List[Callable[[Dict], Dict]] = [_parse_timedelta, - _validate_early_stopping, - _validate_sequence_fit_on_val] - self.read_config() +class DataPreprocessorConfig(BaseModel): + """``train.data_preprocessor`` section (``extra='forbid'``). - def __getitem__(self, item) -> Any: - return self.config_dict[item] - - def __contains__(self, item): - return item in self.config_dict - - @property - def data_preprocessor_steps(self) -> List[Dict[str, Any]]: - """Get the data preprocessor steps.""" - data_prep = self.config_dict.get('train', {}).get('data_preprocessor', {}) or {} - params = data_prep.get('params') or {} - steps = data_prep.get('steps') or [] + After validation, ``steps`` is always a list (converted from legacy + ``params`` if needed, or defaulted to ``[]``). The ``params`` field is + cleared after conversion so that ``write_config`` produces the ``steps`` + format. An empty ``steps`` list means "use the DataPreprocessor's built-in + default pipeline". + """ - if steps and params: + model_config = ConfigDict(extra="forbid", validate_assignment=True) + params: dict[str, Any] | None = None + steps: list[dict[str, Any]] | None = [] + + @model_validator(mode="before") + @classmethod + def _none_to_empty(cls, data: Any) -> Any: + """Treat ``data_preprocessor: null`` (or missing) as an empty config.""" + if data is None: + return {} + return data + + @model_validator(mode="after") + def _convert_params_to_steps(self) -> "DataPreprocessorConfig": + if self.steps and self.params: warnings.warn( "Both 'data_preprocessor.steps' and 'data_preprocessor.params' provided in config; " "'data_preprocessor.steps' take precedence and 'data_preprocessor.params' are ignored. " @@ -217,133 +106,254 @@ def data_preprocessor_steps(self) -> List[Dict[str, Any]]: DeprecationWarning, stacklevel=2, ) - return steps - - if params and not steps: + self.params = None + elif self.params and not self.steps: warnings.warn( "Using deprecated 'data_preprocessor.params' to create a DataPreprocessor. " "Please update to 'steps'; 'data_preprocessor.params' will be removed in a future version.", DeprecationWarning, stacklevel=2, ) - steps = _data_preprocessor_params_to_steps(params) + self.steps = _data_preprocessor_params_to_steps(self.params) + self.params = None + if self.steps is None: + self.steps = [] + return self - return steps or [] - @property - def root_cause_analysis(self) -> bool: - """Whether to run ARCANA.""" - return 'root_cause_analysis' in self.config_dict +class ThresholdSelectorConfig(BaseModel): + """``train.threshold_selector`` section.""" - @property - def arcana_params(self) -> Dict[str, Any]: - """Get the ARCANA parameters.""" - return self.config_dict.get('root_cause_analysis', {}) + model_config = ConfigDict(extra="allow", validate_assignment=True) + name: str = "quantile" + fit_on_val: bool = False + params: dict[str, Any] = {} - @property - def data_split_params(self) -> Dict[str, Any]: - """DataSplitter or train_test_split parameters.""" - return self.config_dict.get('train', {}).get('data_splitter', {}) + @model_validator(mode="after") + def _none_params_to_empty(self) -> "ThresholdSelectorConfig": + if self.params is None: + self.params = {} + return self - @property - def data_clipping(self) -> bool: - """Whether to clip training data.""" - return 'data_clipping' in self.config_dict.get('train', {}) - @property - def data_clipping_params(self) -> Dict[str, Any]: - """Data clipping parameters.""" - return self.config_dict.get('train', {}).get('data_clipping', {}) +class DataClippingConfig(BaseModel): + """``train.data_clipping`` section.""" - @property - def max_criticality(self) -> Optional[int]: - """Max criticality value.""" - return self.config_dict.get('predict', {}).get('criticality', {}).get('max_criticality', 144) + model_config = ConfigDict(extra="allow", validate_assignment=True) + lower_percentile: float | None = None + upper_percentile: float | None = None + features_to_exclude: list[str] | None = None + features_to_clip: list[str] | None = None - @property - def fit_threshold_on_val(self) -> bool: - """Whether to fit threshold on validation data only.""" - return self.config_dict.get('train', {}).get('threshold_selector', {}).get('fit_on_val', False) - @property - def dtype(self): - """Data type, float32 by default.""" - return self.config_dict.get('dtype', 'float32') +class DataSplitterConfig(BaseModel): + """``train.data_splitter`` section. + + ``type`` selects block-style vs sklearn-style splitting. The remaining + fields are type-specific options; irrelevant ones are ignored by the + splitter implementation. + + Defaults to ``BlockDataSplitter`` with ``train_block_size``, ``val_block_size``, + ``validation_split`` and ``shuffle`` all ``None``; the + :py:obj:`BlockDataSplitter ` + then falls back to its own block-size defaults (5040 / 1680 samples). Early + stopping requires validation data to be configured explicitly: a positive + ``val_block_size`` for block splitters, or a ``validation_split`` in (0, 1) + for sklearn splitters. + """ + + model_config = ConfigDict(extra="allow", validate_assignment=True) + type: Literal[ + "DataSplitter", + "BlockDataSplitter", + "blocks", + "sklearn", + "train_test_split", + "train_val_split", + ] = "BlockDataSplitter" + train_block_size: int | None = None + val_block_size: int | None = None + validation_split: float | None = None + shuffle: bool | None = None + + +class TrainConfig(BaseModel): + """``train`` section. + + All sub-sections have defaults; ``TrainConfig()`` produces a ready-to-use + configuration. + """ + + model_config = ConfigDict(extra="allow", validate_assignment=True) + autoencoder: AutoencoderConfig = AutoencoderConfig() + anomaly_score: AnomalyScoreConfig = AnomalyScoreConfig() + data_preprocessor: DataPreprocessorConfig = DataPreprocessorConfig() + threshold_selector: ThresholdSelectorConfig = ThresholdSelectorConfig() + data_clipping: DataClippingConfig | None = None + data_splitter: DataSplitterConfig = DataSplitterConfig() + protect_conditional_features: bool = False + + +class RootCauseAnalysisConfig(BaseModel): + """``root_cause_analysis`` section. + + The YAML keeps all ARCANA parameters flat (``alpha``, ``num_iter``, …) at the + section level. The :attr:`params` property returns them as a dict for easy + unpacking (``Arcana(**config.root_cause_analysis.params)``). + """ + + model_config = ConfigDict(extra="allow", validate_assignment=True) + alpha: float | None = None + init_x_bias: str | None = None + num_iter: int | None = None + epsilon: float | None = None + verbose: bool | None = None + max_sample_threshold: int | None = None @property - def protect_conditional_features(self) -> bool: - """Whether to protect conditional features from being dropped by preprocessing.""" - return self.config_dict.get('train', {}).get('protect_conditional_features', False) + def params(self) -> dict[str, Any]: + """Return all non-None RCA parameters as a dict (including extras).""" + result = { + k: v + for k, v in self.__dict__.items() + if v is not None and not k.startswith("_") + } + extra = getattr(self, "__pydantic_extra__", None) + if extra: + result.update({k: v for k, v in extra.items() if v is not None}) + return result + +def _validate_early_stopping(model: "Config") -> None: + """Check whether early_stopping settings are consistent with the data splitter.""" + params = model.train.autoencoder.params + early_stopping = params.get("early_stopping", False) + + splitter = model.train.data_splitter + block_types = {"DataSplitter", "BlockDataSplitter", "blocks"} + + if splitter.type in block_types: + val_block_size = splitter.val_block_size or 0 + validation = val_block_size > 0 + else: + validation_split = splitter.validation_split or 0.0 + if not isinstance(validation_split, float): + validation_split = 0.0 + validation = 0 < validation_split < 1 + + if early_stopping and not validation: + msg = ( + "Configuration is not valid: If early_stopping is enabled either validation_split or " + "val_block_size must be given. If validation_split is used, it must be a float >0 and <1." + ) + raise InvalidConfigFile(msg) -def _data_preprocessor_params_to_steps(params: Dict[str, Any]) -> List[Dict[str, Any]]: - """Translate old data_preprocessor params into a 'steps' specification. + +def _validate_sequence_fit_on_val(model: "Config") -> None: + """Warn if ``fit_on_val=True`` with a sequence model and ``shuffle=True``. + + Sequence models need temporally contiguous validation data. Shuffling + breaks that contiguity, and the sequence builder will drop windows that cross + data gaps — potentially leaving no valid windows for threshold fitting. + """ + params = model.train.autoencoder.params + has_sequence_builder = "sequence_builder" in params + fit_on_val = model.train.threshold_selector.fit_on_val + shuffle = model.train.data_splitter.shuffle or False + + if has_sequence_builder and fit_on_val and shuffle: + warnings.warn( + "Using 'fit_on_val=True' with a sequence model and 'shuffle=True' may result in " + "non-contiguous validation timestamps. The sequence builder will drop windows that " + "cross data gaps, potentially leaving no valid windows for threshold fitting. " + "Consider setting 'shuffle: false' or 'fit_on_val: false'.", + UserWarning, + stacklevel=2, + ) + + +def _data_preprocessor_params_to_steps(params: dict[str, Any]) -> list[dict[str, Any]]: + """Translate old ``data_preprocessor.params`` into a ``steps`` specification. + + Args: + params: Legacy params dict. Returns: - List of step-spec dicts to be passed to the DataPreprocessor, e.g.: - [ - {"name": "duplicate_to_nan", "params": {...}}, - {"name": "counter_diff_transformer", "params": {...}}, - ... - ] + List of step-spec dicts to be passed to the DataPreprocessor, e.g.:: + + [ + {"name": "duplicate_to_nan", "params": {...}}, + {"name": "counter_diff_transformer", "params": {...}}, + ... + ] """ p = params or {} - steps: List[Dict[str, Any]] = [] + steps: list[dict[str, Any]] = [] # 0. DuplicateValuesToNan if p.get("include_duplicate_value_to_nan", False): - steps.append({ - "name": "duplicate_to_nan", - "params": { - "value_to_replace": p.get("value_to_replace", 0), - "n_max_duplicates": p.get("n_max_duplicates", 144), - "features_to_exclude": p.get("duplicate_features_to_exclude"), - }, - }) + steps.append( + { + "name": "duplicate_to_nan", + "params": { + "value_to_replace": p.get("value_to_replace", 0), + "n_max_duplicates": p.get("n_max_duplicates", 144), + "features_to_exclude": p.get("duplicate_features_to_exclude"), + }, + } + ) # 1. CounterDiffTransformer counter_cols = p.get("counter_columns_to_transform", []) or [] if counter_cols: - steps.append({ - "name": "counter_diff_transformer", - "params": { - "counters": counter_cols, - "compute_rate": False, - "reset_strategy": "zero", - }, - }) + steps.append( + { + "name": "counter_diff_transformer", + "params": { + "counters": counter_cols, + "compute_rate": False, + "reset_strategy": "zero", + }, + } + ) # 2. ColumnSelector if p.get("include_column_selector", True): - steps.append({ - "name": "column_selector", - "params": { - "max_nan_frac_per_col": p.get("max_nan_frac_per_col", 0.05), - "features_to_exclude": p.get("features_to_exclude"), - }, - }) + steps.append( + { + "name": "column_selector", + "params": { + "max_nan_frac_per_col": p.get("max_nan_frac_per_col", 0.05), + "features_to_exclude": p.get("features_to_exclude"), + }, + } + ) # 3. LowUniqueValueFilter if p.get("include_low_unique_value_filter", True): - steps.append({ - "name": "low_unique_value_filter", - "params": { - "min_unique_value_count": p.get("min_unique_value_count", 2), - "max_col_zero_frac": p.get("max_col_zero_frac", 1.0), - }, - }) + steps.append( + { + "name": "low_unique_value_filter", + "params": { + "min_unique_value_count": p.get("min_unique_value_count", 2), + "max_col_zero_frac": p.get("max_col_zero_frac", 1.0), + }, + } + ) # 4. AngleTransformer angles = p.get("angles", []) or [] if angles: - steps.append({ - "name": "angle_transformer", - "params": {"angles": angles}, - }) + steps.append( + { + "name": "angle_transformer", + "params": {"angles": angles}, + } + ) # 5. SimpleImputer - imputer_params: Dict[str, Any] = {"strategy": p.get("imputer_strategy", "mean")} + imputer_params: dict[str, Any] = {"strategy": p.get("imputer_strategy", "mean")} if imputer_params["strategy"] == "constant": imputer_params["fill_value"] = p.get("imputer_fill_value", None) steps.append({"name": "simple_imputer", "params": imputer_params}) @@ -351,8 +361,184 @@ def _data_preprocessor_params_to_steps(params: Dict[str, Any]) -> List[Dict[str, # 6. Scaler scale = p.get("scale", "standardize") if scale in ["standardize", "standard", "standardscaler"]: - steps.append({"name": "scaler", "step_name": "scaler", "params": {"scaler_type": "standard"}}) + steps.append( + { + "name": "scaler", + "step_name": "scaler", + "params": {"scaler_type": "standard"}, + } + ) else: - steps.append({"name": "scaler", "step_name": "scaler", "params": {"scaler_type": "minmax"}}) + steps.append( + { + "name": "scaler", + "step_name": "scaler", + "params": {"scaler_type": "minmax"}, + } + ) return steps + + +class Config(BaseModel): + """Configuration for the anomaly-detection pipeline. + + Loads and validates a YAML configuration file (or an inline dict) using + Pydantic models. Top-level sections (``train``, ``root_cause_analysis``, + ``dtype``) are accessible via normal attribute access + (e.g. ``config.train.autoencoder.params``). + + All sections have defaults — ``Config()`` with no arguments produces a + ready-to-use configuration. + + Example: + + .. code-block:: python + + from energy_fault_detector.config import Config + + # defaults + config = Config() + + # from YAML file + config = Config('config.yaml') + + # from dict + config = Config({'train': {...}}) + + Args: + config_filename: Path to a YAML configuration file, or an inline + configuration dictionary. + config_dict: Inline configuration dictionary (alternative to passing + a dict as the first positional argument). + """ + + model_config = ConfigDict( + extra="ignore", validate_default=True, validate_assignment=True + ) + train: TrainConfig = TrainConfig() + root_cause_analysis: RootCauseAnalysisConfig | None = None + dtype: Literal["float32", "float64"] = "float32" + + _configuration_file: str | None = PrivateAttr(default=None) + + @model_validator(mode="after") + def _run_extra_checks(self) -> "Config": + """Run post-validation checks.""" + _validate_early_stopping(self) + _validate_sequence_fit_on_val(self) + return self + + def __init__( + self, + config_filename: str | Path | dict[str, Any] | None = None, + config_dict: dict[str, Any] | None = None, + **kwargs: Any, + ) -> None: + if isinstance(config_filename, dict): + config_dict = config_filename + config_filename = None + + if config_filename is not None: + with open(config_filename, "r", encoding="utf-8") as f: + data = yaml.safe_load(f) + if data is None: + raise InvalidConfigFile("The configuration file is empty!") + self._log_unknown_keys(data) + try: + super().__init__(**data) + except ValidationError as exc: + raise _format_validation_error(exc) from exc + object.__setattr__(self, "_configuration_file", str(config_filename)) + elif config_dict is not None: + self._log_unknown_keys(config_dict) + try: + super().__init__(**config_dict) + except ValidationError as exc: + raise _format_validation_error(exc) from exc + else: + super().__init__(**kwargs) + + @staticmethod + def _log_unknown_keys(data: Any) -> None: + if isinstance(data, dict): + known_keys = set(Config.model_fields.keys()) + for key in list(data.keys()): + if key not in known_keys: + logger.info( + "Key `%s` is an unknown field and will be ignored.", key + ) + + def __repr__(self) -> str: + return repr(self.model_dump(exclude_none=True)) + + @property + def config_dict(self) -> dict[str, Any]: + """Return a plain dictionary representation of the config. + + .. deprecated:: + Use :meth:`model_dump` (Pydantic's built-in) or direct attribute + access instead. + """ + warnings.warn( + "Config.config_dict is deprecated; use Config.model_dump() or " + "direct attribute access instead.", + DeprecationWarning, + stacklevel=2, + ) + return self.model_dump(exclude_none=True) + + def write_config( + self, file_name: str | None = None, overwrite: bool = False + ) -> None: + """Write the configuration to a YAML file. + + Args: + file_name: Target path. If ``None``, uses the original configuration file. + overwrite: If ``False``, raises :class:`FileExistsError` when the file + already exists. + """ + if file_name is None and self._configuration_file is None: + raise ValueError( + "No file name given and no known configuration file to overwrite." + ) + + file_name = file_name if file_name is not None else self._configuration_file + if Path(file_name).exists() and not overwrite: + raise FileExistsError( + f"File {file_name} already exists and overwrite is set to False." + ) + + conf_dict = self.model_dump(exclude_none=True) + + with open(file_name, "w", encoding="utf-8") as f: + yaml.safe_dump(conf_dict, f) + + def save(self, file_name: str, overwrite: bool = False) -> None: + """Save the configuration to a YAML file. Wrapper for :meth:`write_config`.""" + self.write_config(file_name, overwrite) + + @property + def configuration_file(self) -> str | None: + """Original YAML file path, if this config was loaded from one.""" + return self._configuration_file + + def update_config(self, new_config_dict: dict[str, Any]) -> None: + """Update configuration from a top-level partial dictionary. + + Deprecated: prefer direct typed attribute access or a new Config instance. + """ + warnings.warn( + "Config.update_config() is deprecated; use typed attribute access instead.", + DeprecationWarning, + stacklevel=2, + ) + + merged = self.model_dump(exclude_none=True) + merged.update(new_config_dict) # preserves old shallow-merge semantics + updated = Config(config_dict=merged) + + for name in self.__class__.model_fields: + setattr(self, name, getattr(updated, name)) + + object.__setattr__(self, "_configuration_file", None) diff --git a/energy_fault_detector/core/fault_detection_model.py b/energy_fault_detector/core/fault_detection_model.py index d4b752b0..d18e9de1 100644 --- a/energy_fault_detector/core/fault_detection_model.py +++ b/energy_fault_detector/core/fault_detection_model.py @@ -195,27 +195,19 @@ def train_val_split(self, x: DataType) -> Tuple[DataType, DataType]: tuple: x_train, x_val """ - data_splitter_params = self.config.data_split_params + splitter = self.config.train.data_splitter - # Normalize aliases - data_splitter_type = data_splitter_params.get('type') - if data_splitter_type in ('sklearn', 'train_test_split', 'train_val_split'): - splitter_kind = 'sklearn' - else: - splitter_kind = 'blocks' - - if splitter_kind == 'blocks': - train_data, val_data = BlockDataSplitter( - train_block_size=data_splitter_params.get('train_block_size'), - val_block_size=data_splitter_params.get('val_block_size'), - ).split(x=x) - else: # 'sklearn' - shuffle = data_splitter_params.get('shuffle') + if splitter.type in ('sklearn', 'train_test_split', 'train_val_split'): train_data, val_data = train_test_split( x, - test_size=data_splitter_params['validation_split'], - shuffle=shuffle if shuffle is not None else False + test_size=splitter.validation_split, + shuffle=splitter.shuffle if splitter.shuffle is not None else False ) + else: + train_data, val_data = BlockDataSplitter( + train_block_size=splitter.train_block_size, + val_block_size=splitter.val_block_size, + ).split(x=x) return train_data, val_data diff --git a/energy_fault_detector/core/fault_detection_result.py b/energy_fault_detector/core/fault_detection_result.py index f9984da1..16fd6a35 100644 --- a/energy_fault_detector/core/fault_detection_result.py +++ b/energy_fault_detector/core/fault_detection_result.py @@ -1,5 +1,5 @@ -from typing import Optional, List +from typing import Optional, List, Tuple from dataclasses import dataclass from pathlib import Path import json @@ -7,7 +7,7 @@ import pandas as pd import numpy as np -from ..utils.analysis import calculate_criticality +from ..utils.analysis import calculate_alarms, calculate_criticality _INDEX_META_FILE = "_index_meta.json" @@ -52,6 +52,34 @@ def criticality(self, normal_idx: pd.Series | None = None, init_criticality: int """ return calculate_criticality(self.predicted_anomalies, normal_idx, init_criticality, max_criticality) + def criticality_alarms(self, normal_idx: pd.Series | None = None, init_criticality: int = 0, + criticality_threshold: int | None = None, alarm_reset_time_minutes: float = 60 + ) -> Tuple[pd.DataFrame, pd.Series]: + """Derive alarm events and the criticality counter from the predicted anomalies. + + The criticality increases for sustained anomalies during normal operation and decreases again during normal + behaviour. Timestamps at which the criticality reaches ``criticality_threshold`` are treated as alarms and + aggregated into contiguous alarm events. + + Args: + normal_idx (pd.Series, optional): A pandas Series with boolean values indicating normal operation, indexed + by timestamp. Ignored if None. + init_criticality (int, optional): The initial criticality value. Defaults to 0. + criticality_threshold (int, optional): Criticality value at which an alarm is raised. If None, it defaults + to one hour of anomalous behaviour (``int(1 hour / time_frequency)``); if the time frequency exceeds + one hour, it defaults to ``1``. + alarm_reset_time_minutes (float, optional): Time window in minutes after which an alarm is reset once the + system behaves normally again. Used to derive ``max_criticality``. Defaults to 60. + + Returns: + Tuple[pd.DataFrame, pd.Series]: A tuple containing: + - alarm_events (pd.DataFrame): Columns ``start``, ``end`` and ``duration`` and, for a MultiIndex, + an additional ``group`` column. + - criticality (pd.Series): The criticality over time. + """ + return calculate_alarms(self.predicted_anomalies, normal_idx, init_criticality, criticality_threshold, + alarm_reset_time_minutes) + def save(self, directory: str | Path, **kwargs) -> None: """Saves the results to CSV files in the specified directory. diff --git a/energy_fault_detector/core/model_factory.py b/energy_fault_detector/core/model_factory.py index 463bfb5c..841d390b 100644 --- a/energy_fault_detector/core/model_factory.py +++ b/energy_fault_detector/core/model_factory.py @@ -1,6 +1,8 @@ from typing import Union, Dict, TYPE_CHECKING +import numpy as np + from energy_fault_detector.registration import registry from energy_fault_detector.config import Config from energy_fault_detector.data_preprocessing import DataPreprocessor @@ -14,6 +16,19 @@ ModelType = Union["Autoencoder", AnomalyScore, ThresholdSelector, DataPreprocessor] +_TS_FREQ_UNIT_MAP = {"min": "m", "sec": "s", "hr": "h", "hour": "h"} + + +def _parse_ts_freq(ts_freq: str) -> np.timedelta64: + """Parse a compact frequency string like ``'30s'`` or ``'10m'`` to ``np.timedelta64``.""" + digits = "".join(ch for ch in ts_freq if ch.isdigit()) + unit = "".join(ch for ch in ts_freq if not ch.isdigit()) + unit = _TS_FREQ_UNIT_MAP.get(unit, unit) + if not digits or not unit: + raise ValueError( + f"Unexpected value for `ts_freq`: {ts_freq!r}. Expected format like '10m', '1h'.") + return np.timedelta64(int(digits), unit) + class ModelFactory: def __init__(self, config: Config) -> None: @@ -32,18 +47,18 @@ def _initialize_models(self) -> None: from energy_fault_detector.data_splitting.sequence_dataset import SequenceDatasetBuilder from energy_fault_detector.autoencoders.seq2one_autoencoder import SequenceAutoencoder - train_dict = self.config["train"] + train = self.config.train # Data preprocessor - self._models["data_preprocessor"] = DataPreprocessor(steps=self.config.data_preprocessor_steps) + self._models["data_preprocessor"] = DataPreprocessor(steps=train.data_preprocessor.steps) # autoencoder - ae_params = train_dict.get("autoencoder") - ae_class = registry.get("autoencoder", ae_params["name"]) - ae_kwargs = dict(ae_params.get("params", {})) + ae_config = train.autoencoder + ae_class = registry.get("autoencoder", ae_config.name) + ae_kwargs = dict(ae_config.params) # Add verbose from config (train.autoencoder.verbose), defaulting to 1 - ae_verbose = ae_params.get("verbose", 1) + ae_verbose = ae_config.verbose if ae_config.verbose is not None else 1 ae_kwargs.setdefault("verbose", ae_verbose) # If this is a sequence AE, build the SequenceDatasetBuilder from config @@ -54,7 +69,9 @@ def _initialize_models(self) -> None: f"sequence_builder config is required for sequence autoencoder {ae_class.__name__}" ) - ts_freq = builder_conf["ts_freq"] # already np.timedelta64 thanks to _parse_timedelta + ts_freq = builder_conf["ts_freq"] + if isinstance(ts_freq, str): + ts_freq = _parse_ts_freq(ts_freq) sequence_builder = SequenceDatasetBuilder( sequence_length=builder_conf["sequence_length"], ts_freq=ts_freq, @@ -68,14 +85,14 @@ def _initialize_models(self) -> None: self._models["autoencoder"] = ae_class(**ae_kwargs) # anomaly_score - score_params = train_dict.get("anomaly_score") - score_class = registry.get("anomaly_score", score_params["name"]) - self._models["anomaly_score"] = score_class(**score_params.get("params", {})) + score_config = train.anomaly_score + score_class = registry.get("anomaly_score", score_config.name) + self._models["anomaly_score"] = score_class(**score_config.params) # threshold_selector - thresh_params = train_dict.get("threshold_selector") - thresh_class = registry.get("threshold_selector", thresh_params["name"]) - self._models["threshold_selector"] = thresh_class(**thresh_params.get("params", {})) + thresh_config = train.threshold_selector + thresh_class = registry.get("threshold_selector", thresh_config.name) + self._models["threshold_selector"] = thresh_class(**thresh_config.params) @property def data_preprocessor(self) -> DataPreprocessor: diff --git a/energy_fault_detector/evaluation/care2compare.py b/energy_fault_detector/evaluation/care2compare.py index 37ebe18d..01baac68 100644 --- a/energy_fault_detector/evaluation/care2compare.py +++ b/energy_fault_detector/evaluation/care2compare.py @@ -291,30 +291,23 @@ def find_step(names: List[str]) -> dict | None: angle_columns = get_columns(angles) to_exclude_columns = get_columns(to_exclude) - # old: - dp = config['train'].setdefault('data_preprocessor', {}) - params = dp.get('params') - steps = dp.get('steps') - if params: - params['angles'] = merge_unique(params.get('angles', []), angle_columns) - params['features_to_exclude'] = merge_unique(params.get('features_to_exclude', []), to_exclude_columns) - # new - else: - angle_step = find_step(['angle_transformer', 'angle_transform']) - if angle_step is None: - steps.append({'name': 'angle_transformer', 'params': {'angles': angle_columns}}) - else: - angle_params = angle_step.setdefault('params', {}) - angle_params['angles'] = merge_unique(angle_params.get('angles', []), angle_columns) - colsel_step = find_step(['column_selector']) - if colsel_step is None: - steps.append({'name': 'column_selector', 'params': {'features_to_exclude': to_exclude_columns}}) - else: - colsel_params = colsel_step.setdefault('params', {}) - colsel_params['features_to_exclude'] = merge_unique( - colsel_params.get('features_to_exclude', []), to_exclude_columns) + train = config.train + dp = train.data_preprocessor - config.update_config(config.config_dict) + steps = dp.steps or [] + angle_step = find_step(['angle_transformer', 'angle_transform']) + if angle_step is None: + steps.append({'name': 'angle_transformer', 'params': {'angles': angle_columns}}) + else: + angle_params = angle_step.setdefault('params', {}) + angle_params['angles'] = merge_unique(angle_params.get('angles', []), angle_columns) + colsel_step = find_step(['column_selector']) + if colsel_step is None: + steps.append({'name': 'column_selector', 'params': {'features_to_exclude': to_exclude_columns}}) + else: + colsel_params = colsel_step.setdefault('params', {}) + colsel_params['features_to_exclude'] = merge_unique( + colsel_params.get('features_to_exclude', []), to_exclude_columns) def _get_column_map(self, wind_farm: str) -> Dict[str, str]: """Maps anonymized columns to human-readable format using feature descriptions""" diff --git a/energy_fault_detector/fault_detector.py b/energy_fault_detector/fault_detector.py index ca7f953f..f235052e 100644 --- a/energy_fault_detector/fault_detector.py +++ b/energy_fault_detector/fault_detector.py @@ -61,20 +61,25 @@ def preprocess_train_data(self, sensor_data: pd.DataFrame, normal_index: pd.Seri # TODO: add list of relevant features to config and protect relevant features (if present) as well. # Determine which features to protect based on config flag - protect = self.config.protect_conditional_features if self.config else True + protect = self.config.train.protect_conditional_features if self.config and self.config.train else True protected_features = ( self.autoencoder.conditional_features or [] ) if protect else [] # Data clipping (outlier clipping) - if self.config.data_clipping: + if self.config.train.data_clipping is not None: logger.debug('Clip data before scaling.') - clipper_params = self.config.data_clipping_params.copy() + clip = self.config.train.data_clipping + features_to_exclude = clip.features_to_exclude or [] if protected_features: - existing_exclusions = clipper_params.get('features_to_exclude', []) - clipper_params['features_to_exclude'] = list(set(existing_exclusions + protected_features)) + features_to_exclude = list(set(features_to_exclude + protected_features)) logger.debug(f'Excluding conditional features from clipping: {protected_features}') - data_clipper = DataClipper(**clipper_params) + data_clipper = DataClipper( + lower_percentile=clip.lower_percentile, + upper_percentile=clip.upper_percentile, + features_to_exclude=features_to_exclude or None, + features_to_clip=clip.features_to_clip, + ) data_clipper.fit(x=x) x = data_clipper.transform(x) @@ -144,7 +149,8 @@ def fit(self, sensor_data: pd.DataFrame, normal_index: pd.Series = None, save_mo val_recon_error = self.autoencoder.get_reconstruction_error(x_val) if not fit_autoencoder_only: - self._fit_threshold(x=x, y=y, x_val=x_val, fit_on_validation=self.config.fit_threshold_on_val) + fit_on_val = self.config.train.threshold_selector.fit_on_val + self._fit_threshold(x=x, y=y, x_val=x_val, fit_on_validation=fit_on_val) if save_models: model_path, model_date = self.save(overwrite=overwrite_models) @@ -201,7 +207,7 @@ def tune(self, sensor_data: pd.DataFrame, normal_index: Optional[pd.Series] = No if tune_method not in ['threshold', 'decoder', 'full']: raise ValueError(f'Unknown tune method {tune_method}.') - fit_on_val = self.config.fit_threshold_on_val + fit_on_val = self.config.train.threshold_selector.fit_on_val if tune_method == 'threshold' and fit_on_val: logger.warning('Fine-tuning using only validation data for threshold does not make sense if only the' ' threshold is tuned! Setting fit_threshold_on_val to False.') @@ -402,7 +408,8 @@ def run_root_cause_analysis(self, sensor_data: pd.DataFrame, track_losses: bool # backwards compatibility, old models did not save config, just use default parameters rca = Arcana(model=self.autoencoder) else: - rca = Arcana(model=self.autoencoder, **self.config.arcana_params) + rca = Arcana(model=self.autoencoder, + **(self.config.root_cause_analysis.params or {})) df_arcana_bias, arcana_losses, tracked_bias = rca.find_arcana_bias(x=x_prepped, track_losses=track_losses, @@ -486,7 +493,7 @@ def _resolve_conditional_features(self, prepped_sensor_data: pd.DataFrame) -> Li logger.warning(f"Declared conditions not found in sensor_data will be ignored: " f"{sorted(missing)}. Using: {available or 'none'}") - if not self.config.protect_conditional_features: + if not self.config.train.protect_conditional_features: # Uses nested for loop in case categorical cols have been encoded already and contain the original # conditional feature name as a substring. surviving = [declared_condition for declared_condition in available @@ -518,7 +525,7 @@ def _fallback_if_no_conditionals(self) -> None: elif isinstance(self.autoencoder, ConditionalAE): logger.warning("All conditional features are unavailable. " "Falling back from ConditionalAE to MultilayerAutoencoder.") - ae_params = dict(self.config['train']['autoencoder'].get('params', {})) + ae_params = dict(self.config.train.autoencoder.params) ae_params.pop('conditional_features', None) self.autoencoder = MultilayerAutoencoder(**ae_params) diff --git a/energy_fault_detector/quick_fault_detection/configuration.py b/energy_fault_detector/quick_fault_detection/configuration.py index d851ee66..2484af7b 100644 --- a/energy_fault_detector/quick_fault_detection/configuration.py +++ b/energy_fault_detector/quick_fault_detection/configuration.py @@ -72,36 +72,30 @@ def update_preprocessor_config(config: Config, features_to_exclude: Union[List[s Config: Updated config object. """ + dp = config.train.data_preprocessor + if features_to_exclude is not None: - if config['train']['data_preprocessor'].get('params'): - # old data preprocessing configuration style - config['train']['data_preprocessor']['params']['features_to_exclude'] = features_to_exclude - else: - # new configuration style - steps = config['train']['data_preprocessor'].setdefault('steps', []) - column_selector_found = False - for step in steps: - if step['name'] == 'column_selector': - step['params']['features_to_exclude'] = features_to_exclude - column_selector_found = True - break - if not column_selector_found: - steps.append({'name': 'column_selector', 'params': {'features_to_exclude': features_to_exclude}}) + if dp.steps is None: + dp.steps = [] + column_selector_found = False + for step in dp.steps: + if step['name'] == 'column_selector': + step['params']['features_to_exclude'] = features_to_exclude + column_selector_found = True + break + if not column_selector_found: + dp.steps.append({'name': 'column_selector', 'params': {'features_to_exclude': features_to_exclude}}) if angles is not None: - if config['train']['data_preprocessor'].get('params'): - # old data preprocessing configuration style - config['train']['data_preprocessor']['params']['angles'] = angles - else: - # new configuration style - steps = config['train']['data_preprocessor'].setdefault('steps', []) - angle_transformer_found = False - for step in steps: - if step['name'] == 'angle_transformer': - step['params']['angles'] = angles - angle_transformer_found = True - break - if not angle_transformer_found: - steps.append({'name': 'angle_transformer', 'params': {'angles': angles}}) + if dp.steps is None: + dp.steps = [] + angle_transformer_found = False + for step in dp.steps: + if step['name'] == 'angle_transformer': + step['params']['angles'] = angles + angle_transformer_found = True + break + if not angle_transformer_found: + dp.steps.append({'name': 'angle_transformer', 'params': {'angles': angles}}) return config @@ -115,7 +109,7 @@ def update_autoencoder_config(config: Config, autoencoder_params: dict) -> Confi Returns: Config: Updated config object. """ - config['train']['autoencoder']['params'].update(autoencoder_params) + config.train.autoencoder.params.update(autoencoder_params) return config @@ -137,5 +131,5 @@ def update_threshold_config(config: Config, quantile: float) -> Config: logger.warning(f'Quantile for reconstruction error threshold was specified as {quantile} which smaller than 0.' f'To avoid an exception quantile will be set to the default value 0.95') quantile = 0.95 - config['train']['threshold_selector']['params']['quantile'] = quantile + config.train.threshold_selector.params['quantile'] = quantile return config diff --git a/energy_fault_detector/quick_fault_detection/optimization.py b/energy_fault_detector/quick_fault_detection/optimization.py index b367a1d7..3119571f 100644 --- a/energy_fault_detector/quick_fault_detection/optimization.py +++ b/energy_fault_detector/quick_fault_detection/optimization.py @@ -87,7 +87,7 @@ def reconstruction_mse(trial: op.Trial) -> float: Returns: MSE of the reconstruction on validation data. """ - trial_config_dict = deepcopy(config.config_dict) # make a copy of the config object, so we do not mutate the original config + trial_config_dict = deepcopy(config.model_dump(exclude_none=True)) # make a copy of the config object, so we do not mutate the original config params = trial_config_dict['train']['autoencoder']['params'] # sample new parameters @@ -137,7 +137,7 @@ def reconstruction_mse(trial: op.Trial) -> float: study_name='autoencoder_optimization', direction='minimize') - autoencoder_params = config.config_dict['train']['autoencoder']['params'] + autoencoder_params = config.train.autoencoder.params study.enqueue_trial(params={ 'batch_size': autoencoder_params['batch_size'], 'learning_rate': autoencoder_params['learning_rate'], diff --git a/energy_fault_detector/utils/analysis.py b/energy_fault_detector/utils/analysis.py index a2970a0b..f3cfba04 100644 --- a/energy_fault_detector/utils/analysis.py +++ b/energy_fault_detector/utils/analysis.py @@ -4,6 +4,11 @@ import numpy as np import pandas as pd +import logging + +logger = logging.getLogger("energy_fault_detector") + +_ALARM_EVENT_COLUMNS = ["start", "end", "duration"] def create_events(sensor_data: pd.DataFrame, boolean_information: pd.Series, @@ -141,6 +146,12 @@ def calculate_criticality(anomalies: pd.Series, normal_idx: pd.Series = None, in Raises: ValueError: If the lengths of the given pandas Series for anomalies and normal_idx do not match. """ + if init_criticality < 0: + init_criticality = 0 + logger.warning(f'init_criticality < 0, was set to 0.') + elif init_criticality > max_criticality: + init_criticality = max_criticality + logger.warning(f'init_criticality > max_criticality, was set to max_criticality ({max_criticality}).') # Ensure aligned and sorted indices anomalies = anomalies.sort_index() @@ -175,6 +186,143 @@ def calculate_criticality(anomalies: pd.Series, normal_idx: pd.Series = None, in return _compute_criticality_array(anomalies, normal_idx, init_criticality, max_criticality) +def calculate_alarms(anomalies: pd.Series, normal_idx: pd.Series = None, init_criticality: int = 0, + criticality_threshold: Optional[int] = None, alarm_reset_time_minutes: float = 60 + ) -> Tuple[pd.DataFrame, pd.Series]: + """Derive alarm events from predicted anomalies using a criticality counter. + + The function computes the :func:`criticality ` and marks every timestamp at which the + criticality reaches or exceeds ``criticality_threshold`` as an alarm. Contiguous alarm timestamps are aggregated + into alarm events with ``start``, ``end`` and ``duration``. + + If ``criticality_threshold`` is not provided, it defaults to ``int(1 hour / time_frequency)``, i.e. the number of + timestamps needed for one hour of anomalous behaviour. If the time frequency is larger than one hour, the default + threshold is ``1``. The time frequency is inferred from the datetime index of ``anomalies``. + + ``max_criticality`` is derived from the threshold and ``alarm_reset_time_minutes`` so that an alarm is reset after + at most ``alarm_reset_time_minutes`` of normal behaviour: + ``max_criticality = criticality_threshold + int(alarm_reset_time_minutes / time_frequency)``. If the time frequency + is larger than ``alarm_reset_time_minutes`` (or cannot be inferred), ``max_criticality`` is + ``criticality_threshold + 1``. + + Args: + anomalies (pd.Series): A pandas Series with boolean values indicating whether an anomaly was detected, + indexed by timestamp, or MultiIndex (device_id, timestamp). + normal_idx (pd.Series, optional): A pandas Series with boolean values indicating normal operation, same index + as ``anomalies``. If not provided, all timestamps are assumed to be normal operation. Defaults to None. + init_criticality (int, optional): The initial criticality value. Defaults to 0. + criticality_threshold (int, optional): Criticality value at which an alarm is raised. If None, it is derived + from the time frequency (one hour of anomalous behaviour). Defaults to None. + alarm_reset_time_minutes (float, optional): Time window in minutes after which an alarm is reset once the + system behaves normally again. Used to derive ``max_criticality``. Defaults to 60. + + Returns: + Tuple[pd.DataFrame, pd.Series]: A tuple containing: + - alarm_events (pd.DataFrame): Columns ``start``, ``end`` and ``duration`` and, for a MultiIndex, + an additional ``group`` column. + - criticality (pd.Series): The criticality over time, indexed like ``anomalies``. + """ + anomalies = anomalies.sort_index() + + index = anomalies.index + if isinstance(index, pd.MultiIndex): + dt_level = _detect_datetime_level(index) + time_index = index.get_level_values(dt_level) if dt_level is not None else None + else: + time_index = index + + time_frequency_nano_seconds = None + if isinstance(time_index, pd.DatetimeIndex): + # In a MultiIndex the datetime level repeats each timestamp per group, which prevents frequency inference. + time_index = pd.DatetimeIndex(time_index.drop_duplicates()) + freq = time_index.freqstr or time_index.inferred_freq + if freq is not None: + try: + time_frequency_nano_seconds = pd.tseries.frequencies.to_offset(freq).nanos + except ValueError: # non-fixed frequency + time_frequency_nano_seconds = None + + nano_seconds_in_an_hour = 60 * 60 * 1e9 + nano_seconds_alarm_reset_time = alarm_reset_time_minutes * 60 * 1e9 + + if criticality_threshold is None: + if time_frequency_nano_seconds is None or time_frequency_nano_seconds > nano_seconds_in_an_hour: + criticality_threshold = 1 + else: + criticality_threshold = max(1, int(nano_seconds_in_an_hour / time_frequency_nano_seconds)) + criticality_threshold = int(criticality_threshold) + + if time_frequency_nano_seconds is None or time_frequency_nano_seconds > nano_seconds_alarm_reset_time: + max_criticality = criticality_threshold + 1 + else: + reset_steps = max(1, int(nano_seconds_alarm_reset_time / time_frequency_nano_seconds)) + max_criticality = criticality_threshold + reset_steps + + criticality = calculate_criticality(anomalies, normal_idx, init_criticality, max_criticality) + alarm_events = _create_alarm_events(criticality, criticality_threshold) + return alarm_events, criticality + + +def _detect_datetime_level(index: pd.MultiIndex) -> Optional[int]: + """Return the datetime level index of a MultiIndex, or None.""" + for i, level in enumerate(index.levels): + if isinstance(level, pd.DatetimeIndex): + return i + return None + + +def _create_alarm_events(criticality: pd.Series, criticality_threshold: int) -> pd.DataFrame: + """Aggregate contiguous timestamps above the criticality threshold into alarm events.""" + alarm_mask = criticality >= criticality_threshold + index = alarm_mask.index + + if isinstance(index, pd.MultiIndex): + group_level = _detect_group_level(index) + datetime_level = _detect_datetime_level(index) + if group_level is not None and datetime_level is not None: + group_values = index.get_level_values(group_level) + events = [] + for group in pd.unique(group_values): + group_mask = alarm_mask[group_values == group].copy() + group_mask.index = index[group_values == group].get_level_values(datetime_level) + events.append(_single_alarm_events(group_mask, group_label=group)) + columns = _ALARM_EVENT_COLUMNS + ["group"] + non_empty = [event for event in events if not event.empty] + if not non_empty: + return pd.DataFrame(columns=columns) + return pd.concat(non_empty, ignore_index=True) + if datetime_level is not None: + alarm_mask = alarm_mask.copy() + alarm_mask.index = index.get_level_values(datetime_level) + else: + alarm_mask = alarm_mask.reset_index(drop=True) + + return _single_alarm_events(alarm_mask) + + +def _single_alarm_events(alarm_mask: pd.Series, group_label=None) -> pd.DataFrame: + """Create alarm events for a single contiguous boolean series.""" + mask = np.asarray(alarm_mask, dtype=bool) + if not mask.any(): + columns = _ALARM_EVENT_COLUMNS + (["group"] if group_label is not None else []) + return pd.DataFrame(columns=columns) + + padded = np.concatenate(([False], mask, [False])) + edges = np.diff(padded.astype(np.int8)) + start_positions = np.flatnonzero(edges == 1) + end_positions = np.flatnonzero(edges == -1) - 1 + + index = alarm_mask.index + events = pd.DataFrame({ + "start": index[start_positions], + "end": index[end_positions], + }) + events["duration"] = events["end"] - events["start"] + if group_label is not None: + events["group"] = group_label + return events + + def _detect_group_level(index: pd.Index) -> Optional[int]: """Return the non-datetime grouping level index, or None.""" if not isinstance(index, pd.MultiIndex): diff --git a/notebooks/Example - Create new model classes.ipynb b/notebooks/Example - Create new model classes.ipynb index f8cfa9b3..0df49dd5 100644 --- a/notebooks/Example - Create new model classes.ipynb +++ b/notebooks/Example - Create new model classes.ipynb @@ -151,15 +151,12 @@ " 'upper_percentile': 0.999\n", " },\n", " 'data_preprocessor': {\n", - " 'params': {\n", - " 'include_column_selector': True,\n", - " 'include_low_unique_value_filter': True,\n", - " 'include_duplicate_value_to_nan': False,\n", - " 'max_col_zero_frac': 0.99,\n", - " 'max_nan_frac_per_col': 0.05,\n", - " 'min_unique_value_count': 10,\n", - " 'scale': 'minmax'\n", - " }\n", + " 'steps': [\n", + " {'name': 'column_selector', 'params': {'max_nan_frac_per_col': 0.05}},\n", + " {'name': 'low_unique_value_filter', 'params': {'min_unique_value_count': 10, 'max_col_zero_frac': 0.99}},\n", + " {'name': 'simple_imputer', 'params': {'strategy': 'mean'}},\n", + " {'name': 'scaler', 'params': {'scaler_type': 'minmax'}}\n", + " ]\n", " },\n", " 'data_splitter': {\n", " 'shuffle': True,\n", diff --git a/notebooks/PreDist/predist_utils.py b/notebooks/PreDist/predist_utils.py index d75fde3e..1cbf7ecf 100644 --- a/notebooks/PreDist/predist_utils.py +++ b/notebooks/PreDist/predist_utils.py @@ -59,7 +59,7 @@ def train_or_get_model(event_id: int, dataset: PreDistDataset, manufacturer: int # Add the code size to the AE configuration, based on the bottleneck ratio # code_size is part of the model configuration, so we overwrite the parameter of the underlying dictionary. bottleneck = calculate_bottleneck(train_data, local_conf, bottleneck_ratio) - local_conf['train']['autoencoder']['params']['code_size'] = bottleneck + local_conf.train.autoencoder.params['code_size'] = bottleneck # For the conditional autoencoders, add time features if ts_features: @@ -118,7 +118,7 @@ def calculate_bottleneck(df: pd.DataFrame, config: Config, ratio: float) -> int: """ # Get the conditional features from the config - ae_params = config['train']['autoencoder']['params'] + ae_params = config.train.autoencoder.params cond_features = ae_params.get('conditional_features', []) # Exclude conditions (not compressed) @@ -126,17 +126,11 @@ def calculate_bottleneck(df: pd.DataFrame, config: Config, ratio: float) -> int: # Check for feature exclusions in config excluded = [] - dp_config = config['train'].get('data_preprocessor', {}) - if dp_config.get('params'): - # params-based data prep config - excluded = dp_config.get('params').get('features_to_exclude', []) - else: - # steps-based data prep config - steps = config['train']['data_preprocessor'].get('steps', []) - for step in steps: - if step['name'] == 'column_selector': - excluded = step['params'].get('features_to_exclude', []) - break + steps = config.train.data_preprocessor.steps or [] + for step in steps: + if step['name'] == 'column_selector': + excluded = step.get('params', {}).get('features_to_exclude', []) + break # Remove the excluded features from the input dimension input_dim -= len([e for e in excluded if e in df.columns]) diff --git a/pyproject.toml b/pyproject.toml index 06273656..59157cf3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,7 +28,7 @@ dependencies = [ "pyyaml", "scikit-learn>=1.5.2,<=1.7.0", "pandas>=2.0,<3.0", - "cerberus", + "pydantic>=2.0", "matplotlib>=3.9.0", "optuna>=4.0", "chardet>=5.0", diff --git a/tests/config/test_config.py b/tests/config/test_config.py index 23b19735..852b55e4 100644 --- a/tests/config/test_config.py +++ b/tests/config/test_config.py @@ -3,8 +3,6 @@ import shutil import unittest -import numpy as np - from energy_fault_detector.config import Config, InvalidConfigFile PROJECT_ROOT = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), '..') @@ -20,10 +18,10 @@ def tearDown(self) -> None: def test_init(self): conf = Config(os.path.join(PROJECT_ROOT, './tests/test_data/test_config.yaml')) - self.assertDictEqual(conf.config_dict['train'], { + self.assertDictEqual(conf.model_dump(exclude_none=True)['train'], { 'anomaly_score': {'name': 'mahalanobis', 'params': {'pca': True, 'pca_min_var': 0.85}}, - 'data_preprocessor': None, # unspecified, default pipeline + 'data_preprocessor': {'steps': []}, 'autoencoder': {'name': 'MultilayerAutoencoder', 'verbose': 0, 'params': {'layers': [300], @@ -35,13 +33,14 @@ def test_init(self): 'epochs': 10, 'loss_name': 'mean_squared_error'}}, 'threshold_selector': {'name': 'FDR', - 'params': {'target_false_discovery_rate': 0.8}, - 'fit_on_val': False}, - 'data_splitter': {'train_block_size': 7, 'val_block_size': 3, 'type': 'BlockDataSplitter'}, + 'params': {'target_false_discovery_rate': 0.8}, + 'fit_on_val': False}, + 'data_splitter': {'type': 'BlockDataSplitter', + 'train_block_size': 7, 'val_block_size': 3}, 'data_clipping': {'lower_percentile': 0.01, 'upper_percentile': 0.99}, 'protect_conditional_features': False, }) - self.assertDictEqual(conf.config_dict['root_cause_analysis'], + self.assertDictEqual(conf.model_dump(exclude_none=True)['root_cause_analysis'], {'alpha': 0.8, 'init_x_bias': 'recon', 'num_iter': 200} @@ -51,22 +50,16 @@ def test_arcana_config(self): conf = Config(os.path.join(PROJECT_ROOT, './tests/test_data/test_config.yaml')) self.assertTrue(conf.root_cause_analysis) self.assertDictEqual( - conf.arcana_params, + conf.root_cause_analysis.params, {'alpha': 0.8, 'num_iter': 200, 'init_x_bias': 'recon'} ) conf = Config(os.path.join(PROJECT_ROOT, './tests/test_data/test_config_no_rca.yaml')) self.assertFalse(conf.root_cause_analysis) - def test_criticality_config(self): - conf = Config(os.path.join(PROJECT_ROOT, './tests/test_data/test_criticality_config.yaml')) - self.assertDictEqual(conf.config_dict['predict'], { - 'criticality': {'max_criticality': 144} - }) - def test_early_stopping_val_split_config(self): conf = Config(os.path.join(PROJECT_ROOT, './tests/test_data/test_early_stopping_val_split_config.yaml')) - self.assertDictEqual(conf.config_dict['train']['autoencoder']['params'], { + self.assertDictEqual(conf.model_dump(exclude_none=True)['train']['autoencoder']['params'], { 'layers': [300], 'code_size': 50, 'learning_rate': 0.001, @@ -79,7 +72,7 @@ def test_early_stopping_val_split_config(self): 'epochs': 100, 'loss_name': 'mean_squared_error' }) - self.assertDictEqual(conf.config_dict['train']['data_splitter'], { + self.assertDictEqual(conf.model_dump(exclude_none=True)['train']['data_splitter'], { 'type': 'sklearn', 'shuffle': True, 'validation_split': 0.25 @@ -87,7 +80,7 @@ def test_early_stopping_val_split_config(self): def test_early_stopping_val_block_config(self): conf = Config(os.path.join(PROJECT_ROOT, './tests/test_data/test_early_stopping_val_block_config.yaml')) - self.assertDictEqual(conf.config_dict['train']['autoencoder']['params'], { + self.assertDictEqual(conf.model_dump(exclude_none=True)['train']['autoencoder']['params'], { 'layers': [300], 'code_size': 50, 'learning_rate': 0.001, @@ -100,7 +93,7 @@ def test_early_stopping_val_block_config(self): 'epochs': 100, 'loss_name': 'mean_squared_error' }) - self.assertDictEqual(conf.config_dict['train']['data_splitter'], { + self.assertDictEqual(conf.model_dump(exclude_none=True)['train']['data_splitter'], { 'type': 'DataSplitter', 'train_block_size': 7, 'val_block_size': 3 @@ -115,12 +108,12 @@ def test_sequence_builder_conf(self): expected = { 'sequence_length': 36, 'stride': 1, - 'ts_freq': np.timedelta64(30, 's'), # parsed by _parse_timedelta into np.timedelta64(10, 'm') + 'ts_freq': '30s', 'pad_incomplete': False, 'pad_value': 0.0, } self.assertDictEqual( - conf['train']['autoencoder']['params']['sequence_builder'], expected + conf.train.autoencoder.params['sequence_builder'], expected ) def test_bidirectional_sequence_builder_conf(self): @@ -128,32 +121,38 @@ def test_bidirectional_sequence_builder_conf(self): expected = { 'sequence_length': 36, 'stride': 1, - 'ts_freq': np.timedelta64(30, 's'), + 'ts_freq': '30s', 'pad_incomplete': False, 'pad_value': 0.0, } self.assertEqual( - conf['train']['autoencoder']['name'], + conf.train.autoencoder.name, 'BidirectionalLSTMSeq2OneAutoencoder' ) self.assertEqual( - conf['train']['autoencoder']['params']['merge_mode'], + conf.train.autoencoder.params['merge_mode'], 'sum' ) self.assertDictEqual( - conf['train']['autoencoder']['params']['sequence_builder'], + conf.train.autoencoder.params['sequence_builder'], expected ) - def test_sequence_builder_conf(self): - conf = Config(os.path.join(PROJECT_ROOT, './tests/test_data/test_config_ts_freq.yaml')) - expected = { - 'sequence_length': 36, - 'stride': 1, - 'ts_freq': np.timedelta64(30, 's'), # parsed by _parse_timedelta into np.timedelta64(10, 'm') - 'pad_incomplete': False, - 'pad_value': 0.0, - } - self.assertDictEqual( - conf['train']['autoencoder']['params']['sequence_builder'], expected - ) + def test_defaults_only_autoencoder(self): + """Config with only autoencoder should get sensible defaults for everything else.""" + conf = Config(config_dict={'train': {'autoencoder': {'name': 'MultilayerAutoencoder', + 'params': {'layers': [10]}}}}) + self.assertEqual(conf.train.anomaly_score.name, 'rmse') + self.assertEqual(conf.train.threshold_selector.name, 'quantile') + self.assertIsNotNone(conf.train.data_preprocessor) + self.assertEqual(conf.train.data_splitter.type, 'BlockDataSplitter') + self.assertFalse(conf.train.protect_conditional_features) + + def test_empty_config_defaults(self): + """Config() with no arguments should produce a ready-to-use configuration.""" + conf = Config() + self.assertEqual(conf.train.autoencoder.name, 'default') + self.assertEqual(conf.train.anomaly_score.name, 'rmse') + self.assertEqual(conf.train.threshold_selector.name, 'quantile') + self.assertEqual(conf.train.data_splitter.type, 'BlockDataSplitter') + self.assertEqual(conf.dtype, 'float32') diff --git a/tests/config/test_quickstart_config.py b/tests/config/test_quickstart_config.py index 393c98a1..5fe8abef 100644 --- a/tests/config/test_quickstart_config.py +++ b/tests/config/test_quickstart_config.py @@ -27,17 +27,17 @@ def test_generate_quickstart_config_valid_dict(self) -> None: ) # Basic structure checks - self.assertIn("train", cfg) - train = cfg["train"] - self.assertIn("data_preprocessor", train) - self.assertIn("steps", train["data_preprocessor"]) - self.assertIn("autoencoder", train) - self.assertIn("params", train["autoencoder"]) - self.assertIn("threshold_selector", train) - self.assertIn("params", train["threshold_selector"]) + self.assertIsNotNone(cfg.train) + train = cfg.train + self.assertIsNotNone(train.data_preprocessor) + self.assertIsNotNone(train.data_preprocessor.steps) + self.assertIsNotNone(train.autoencoder) + self.assertIsNotNone(train.autoencoder.params) + self.assertIsNotNone(train.threshold_selector) + self.assertIsNotNone(train.threshold_selector.params) # Ensure certain steps exist - step_names = [s["name"] for s in train["data_preprocessor"]["steps"]] + step_names = [s["name"] for s in train.data_preprocessor.steps] self.assertIn("column_selector", step_names) self.assertIn("simple_imputer", step_names) self.assertIn("scaler", step_names) @@ -65,5 +65,5 @@ def test_save_load_quickstart_config(self) -> None: loaded_cfg = Config(config_path) # Compare dictionaries - self.assertEqual(cfg.config_dict, loaded_cfg.config_dict) - self.assertEqual(loaded_cfg["train"]["data_splitter"]["validation_split"], 0.25) + self.assertEqual(cfg.model_dump(exclude_none=True), loaded_cfg.model_dump(exclude_none=True)) + self.assertEqual(loaded_cfg.train.data_splitter.validation_split, 0.25) diff --git a/tests/core/test_fault_detection_result.py b/tests/core/test_fault_detection_result.py index f94994e6..f27a62b7 100644 --- a/tests/core/test_fault_detection_result.py +++ b/tests/core/test_fault_detection_result.py @@ -204,5 +204,67 @@ def test_multiindex_without_optional_fields(self): self.assertIsNone(loaded.tracked_bias) +class TestFaultDetectionResultCriticality(unittest.TestCase): + """Test the alarm/criticality derivation on FaultDetectionResult.""" + + def _make_result(self, anomalies): + return FaultDetectionResult( + predicted_anomalies=anomalies, + reconstruction=pd.DataFrame(index=anomalies.index), + recon_error=pd.DataFrame(index=anomalies.index), + anomaly_score=pd.Series(0.0, index=anomalies.index), + ) + + def test_criticality_returns_series(self): + """The legacy criticality method returns only the criticality series.""" + idx = pd.date_range("2024-01-01", periods=6, freq="10min") + anomalies = pd.Series([True, True, True, False, False, False], index=idx) + + result = self._make_result(anomalies) + criticality = result.criticality() + + self.assertIsInstance(criticality, pd.Series) + self.assertEqual(criticality.index.equals(idx), True) + self.assertEqual(list(criticality), [1, 2, 3, 2, 1, 0]) + + def test_criticality_supports_max_criticality(self): + """The legacy criticality method caps the counter at max_criticality.""" + idx = pd.date_range("2024-01-01", periods=5, freq="10min") + anomalies = pd.Series([True] * 5, index=idx) + + result = self._make_result(anomalies) + criticality = result.criticality(max_criticality=3) + + self.assertEqual(list(criticality), [1, 2, 3, 3, 3]) + + def test_criticality_alarms_returns_events_and_series(self): + idx = pd.date_range("2024-01-01", periods=20, freq="10min") + anomalies = pd.Series(False, index=idx) + anomalies.iloc[2:10] = True + + result = self._make_result(anomalies) + alarm_events, criticality = result.criticality_alarms() + + self.assertIsInstance(alarm_events, pd.DataFrame) + self.assertIsInstance(criticality, pd.Series) + self.assertEqual(list(alarm_events.columns), ["start", "end", "duration"]) + self.assertEqual(criticality.index.equals(idx), True) + self.assertEqual(alarm_events.iloc[0]["start"], idx[7]) + + def test_criticality_alarms_uses_normal_idx_and_threshold(self): + idx = pd.date_range("2024-01-01", periods=10, freq="10min") + anomalies = pd.Series(True, index=idx) + normal_idx = pd.Series([True] * 5 + [False] * 5, index=idx) + + result = self._make_result(anomalies) + alarm_events, criticality = result.criticality_alarms( + normal_idx=normal_idx, criticality_threshold=3, alarm_reset_time_minutes=20 + ) + + # max criticality = 3 + int(20 / 10) = 5; non-normal timestamps keep the value frozen + self.assertEqual(list(criticality), [1, 2, 3, 4, 5, 5, 5, 5, 5, 5]) + self.assertEqual(alarm_events.iloc[0]["start"], idx[2]) + + if __name__ == "__main__": unittest.main() diff --git a/tests/core/test_model_factory.py b/tests/core/test_model_factory.py index 28ffef5c..37c8683a 100644 --- a/tests/core/test_model_factory.py +++ b/tests/core/test_model_factory.py @@ -2,7 +2,9 @@ import os import unittest -from energy_fault_detector.core.model_factory import ModelFactory +import numpy as np + +from energy_fault_detector.core.model_factory import ModelFactory, _parse_ts_freq from energy_fault_detector.config import Config from energy_fault_detector.autoencoders import MultilayerAutoencoder from energy_fault_detector.anomaly_scores import MahalanobisScore @@ -36,3 +38,16 @@ def test_model_creation(self): # Test for anomaly score anomaly_score = model_factory.anomaly_score self.assertIsInstance(anomaly_score, MahalanobisScore) + + def test_parse_ts_freq_to_timedelta64(self): + """The model factory parses ts_freq strings into np.timedelta64 for the SequenceDatasetBuilder.""" + from energy_fault_detector.data_splitting.sequence_dataset import SequenceDatasetBuilder + + self.assertEqual(_parse_ts_freq('30s'), np.timedelta64(30, 's')) + self.assertEqual(_parse_ts_freq('10m'), np.timedelta64(10, 'm')) + + builder = SequenceDatasetBuilder( + sequence_length=36, ts_freq=_parse_ts_freq('30s'), stride=1 + ) + self.assertIsInstance(builder.ts_freq, np.timedelta64) + self.assertEqual(builder.ts_freq, np.timedelta64(30, 's')) diff --git a/tests/data_preprocessing/test_data_preprocessor.py b/tests/data_preprocessing/test_data_preprocessor.py index 18375762..8cdd22ec 100644 --- a/tests/data_preprocessing/test_data_preprocessor.py +++ b/tests/data_preprocessing/test_data_preprocessor.py @@ -541,6 +541,7 @@ def _create_config_dict(self, protect_conditional_features: bool = True): """Create configuration matching updated advanced_config.yaml structure.""" return { 'train': { + 'protect_conditional_features': protect_conditional_features, 'data_clipping': { 'lower_percentile': 0.001, 'upper_percentile': 0.999, @@ -571,7 +572,6 @@ def _create_config_dict(self, protect_conditional_features: bool = True): 'verbose': 0 } }, - 'protect_conditional_features': protect_conditional_features, 'anomaly_score': {'name': 'rmse'}, 'threshold_selector': {'name': 'quantile'}, } diff --git a/tests/quick_fault_detection/test_configuration.py b/tests/quick_fault_detection/test_configuration.py index 95ebcc00..a94cacea 100644 --- a/tests/quick_fault_detection/test_configuration.py +++ b/tests/quick_fault_detection/test_configuration.py @@ -24,16 +24,16 @@ def test_select_config_low_feature_number(self): angles=['angle'], automatic_optimization=False) - data_preprocessor_steps = config['train']['data_preprocessor']['steps'] + data_preprocessor_steps = config.train.data_preprocessor.steps for step in data_preprocessor_steps: if step['name'] == 'angle_transformer': self.assertListEqual(step['params']['angles'], ['angle']) if step['name'] == 'column_selector': self.assertListEqual(step['params']['features_to_exclude'], ['exclude_feature']) - self.assertEqual(config['train']['autoencoder']['params']['code_size'], expected_code_size) - self.assertListEqual(config['train']['autoencoder']['params']['layers'], expected_layers) - self.assertEqual(config['train']['threshold_selector']['params']['quantile'], 0.99) + self.assertEqual(config.train.autoencoder.params['code_size'], expected_code_size) + self.assertListEqual(config.train.autoencoder.params['layers'], expected_layers) + self.assertEqual(config.train.threshold_selector.params['quantile'], 0.99) def test_select_config_high_feature_number(self): num_features = 100 @@ -48,6 +48,6 @@ def test_select_config_high_feature_number(self): angles=None, automatic_optimization=False) - self.assertEqual(config['train']['autoencoder']['params']['code_size'], expected_code_size) - self.assertListEqual(config['train']['autoencoder']['params']['layers'], expected_layers) - self.assertEqual(config['train']['threshold_selector']['params']['quantile'], 0.99) + self.assertEqual(config.train.autoencoder.params['code_size'], expected_code_size) + self.assertListEqual(config.train.autoencoder.params['layers'], expected_layers) + self.assertEqual(config.train.threshold_selector.params['quantile'], 0.99) diff --git a/tests/quick_fault_detection/test_quick_fault_detector.py b/tests/quick_fault_detection/test_quick_fault_detector.py index c547e24d..1fb2e04e 100644 --- a/tests/quick_fault_detection/test_quick_fault_detector.py +++ b/tests/quick_fault_detection/test_quick_fault_detector.py @@ -148,7 +148,7 @@ def test_features_to_exclude_passed_to_config(self, MockFaultDetector, mock_plot call_kwargs = MockFaultDetector.call_args config = call_kwargs[1]["config"] if "config" in call_kwargs[1] else call_kwargs[0][0] # Check that column_selector step has sensor_0 excluded - steps = config["train"]["data_preprocessor"]["steps"] + steps = config.train.data_preprocessor.steps col_selector = next(s for s in steps if s["name"] == "column_selector") self.assertIn("sensor_0", col_selector["params"]["features_to_exclude"]) diff --git a/tests/test_data/old_models/create_legacy_model_fixtures.py b/tests/test_data/old_models/create_legacy_model_fixtures.py new file mode 100644 index 00000000..b82ff1c9 --- /dev/null +++ b/tests/test_data/old_models/create_legacy_model_fixtures.py @@ -0,0 +1,305 @@ +"""Create small saved-model fixtures for compatibility testing. + +1. Create a python environment with a previous version of energy-fault-detector. + Use the minimum supported Python version (3.10) so Keras is capped at 3.12.4; + newer Keras versions add config keys (e.g. ``quantization_config``) that older + Keras cannot deserialize, so fixtures created with newer Keras fail on 3.10. +2. Run this script: + python tests/test_data/old_models/create_legacy_model_fixtures.py \ + --output tests/test_data/old_models/py_efd \ + --purpose "Test compatibility for EFD models." + +It creates: + + old_models/ + ├── dense/ + ├── sequence/ + └── manifest.json + +""" + +from __future__ import annotations + +import argparse +import json +import platform +import shutil +import sys +from importlib.metadata import PackageNotFoundError, version +from pathlib import Path + +import numpy as np +import pandas as pd + +from energy_fault_detector import FaultDetector +from energy_fault_detector.config import Config + + +def make_dense_data(n_rows: int = 80) -> pd.DataFrame: + """Create deterministic tabular/time-series data for the dense model. + + Args: + n_rows: Number of samples to generate. + + Returns: + Numeric DataFrame with a 10-minute DatetimeIndex. + """ + rng = np.random.default_rng(42) + index = pd.date_range("2025-01-01", periods=n_rows, freq="10min") + phase = np.linspace(0, 4 * np.pi, n_rows) + + return pd.DataFrame( + { + "temperature": 50 + 3 * np.sin(phase) + rng.normal(0, 0.15, n_rows), + "pressure": 10 + 0.5 * np.cos(phase) + rng.normal(0, 0.05, n_rows), + "power": 100 + 8 * np.sin(phase / 2) + rng.normal(0, 0.3, n_rows), + }, + index=index, + ) + + +def make_sequence_data(n_rows: int = 120) -> pd.DataFrame: + """Create deterministic contiguous time-series data for a sequence model. + + Args: + n_rows: Number of samples to generate. + + Returns: + Numeric DataFrame with a regular 10-minute DatetimeIndex. + """ + rng = np.random.default_rng(123) + index = pd.date_range("2025-02-01", periods=n_rows, freq="10min") + phase = np.linspace(0, 6 * np.pi, n_rows) + + return pd.DataFrame( + { + "sensor_a": np.sin(phase) + rng.normal(0, 0.03, n_rows), + "sensor_b": np.cos(phase) + rng.normal(0, 0.03, n_rows), + "sensor_c": 0.3 * np.sin(phase / 2) + rng.normal(0, 0.02, n_rows), + }, + index=index, + ) + + +def dense_config() -> Config: + """Build a small dense-autoencoder configuration.""" + return Config( + config_dict={ + "train": { + "data_preprocessor": None, + "data_splitter": { + "type": "sklearn", + "validation_split": 0.2, + "shuffle": False, + }, + "autoencoder": { + "name": "default", + "verbose": 0, + "params": { + "layers": [8], + "code_size": 3, + "batch_size": 16, + "epochs": 1, + "learning_rate": 0.001, + "loss_name": "mean_squared_error", + "early_stopping": False, + }, + }, + "anomaly_score": { + "name": "rmse", + "params": {"scale": False}, + }, + "threshold_selector": { + "name": "quantile", + "fit_on_val": False, + "params": {"quantile": 0.95}, + }, + } + } + ) + + +def sequence_config() -> Config: + """Build a small LSTM seq2one configuration.""" + return Config( + config_dict={ + "train": { + "data_preprocessor": { + "steps": [ + {"name": "standard_scaler"}, + ] + }, + "data_splitter": { + "type": "sklearn", + "validation_split": 0.2, + "shuffle": False, + }, + "autoencoder": { + "name": "lstm_seq2one", + "verbose": 0, + "params": { + "sequence_builder": { + "sequence_length": 8, + "ts_freq": "10m", + "stride": 1, + "pad_incomplete": False, + "pad_value": 0.0, + }, + "layers": [8], + "decoder_layers": [8], + "code_size": 4, + "batch_size": 16, + "epochs": 1, + "learning_rate": 0.001, + "loss_name": "mean_squared_error", + "early_stopping": False, + }, + }, + "anomaly_score": { + "name": "rmse", + "params": {"scale": False}, + }, + "threshold_selector": { + "name": "quantile", + "fit_on_val": False, + "params": {"quantile": 0.95}, + }, + } + } + ) + + +def train_and_save( + name: str, + config: Config, + data: pd.DataFrame, + output_dir: Path, +) -> Path: + """Train, smoke-test, and save one model. + + Args: + name: Fixture name. + config: Model configuration. + data: Training and prediction data. + output_dir: Directory where the fixture should be saved. + + Returns: + Directory containing the saved model. + """ + fixture_dir = output_dir / name + detector = FaultDetector(config=config, model_directory=fixture_dir) + + normal_index = pd.Series(True, index=data.index) + metadata = detector.fit( + sensor_data=data, + normal_index=normal_index, + save_models=True, + overwrite_models=True, + ) + + result = detector.predict(data) + + if result.anomaly_score.empty: + raise RuntimeError(f"{name}: prediction unexpectedly produced no anomaly scores.") + + if not result.predicted_anomalies.index.equals(result.anomaly_score.index): + raise RuntimeError(f"{name}: anomaly predictions and scores have different indices.") + + saved_path = Path(metadata.model_path) + print(f"Created {name} fixture: {saved_path}") + print( + f" scores={len(result.anomaly_score)}, " + f"predicted_anomalies={int(result.predicted_anomalies.sum())}" + ) + + return saved_path + + +def installed_version(distribution: str) -> str | None: + """Return an installed package version if available.""" + try: + return version(distribution) + except PackageNotFoundError: + return None + + +def main() -> None: + """Create dense and sequence saved-model compatibility fixtures.""" + parser = argparse.ArgumentParser() + parser.add_argument( + "--purpose", + type=str, + default="test", + help="Purpose of the saved-model fixtures.", + ) + parser.add_argument( + "--output", + type=Path, + default=Path("tests/test_data/old_models"), + help="Output directory for saved fixtures.", + ) + parser.add_argument( + "--overwrite", + action="store_true", + help="Replace an existing output directory.", + ) + args = parser.parse_args() + + output_dir: Path = args.output.resolve() + + if output_dir.exists(): + if not args.overwrite: + raise FileExistsError( + f"{output_dir} already exists. Use --overwrite to replace it." + ) + shutil.rmtree(output_dir) + + output_dir.mkdir(parents=True) + + dense_path = train_and_save( + name="dense", + config=dense_config(), + data=make_dense_data(), + output_dir=output_dir, + ) + sequence_path = train_and_save( + name="sequence", + config=sequence_config(), + data=make_sequence_data(), + output_dir=output_dir, + ) + + manifest = { + "purpose": args.purpose, + "python": sys.version, + "platform": platform.platform(), + "package_versions": { + "energy-fault-detector": installed_version("energy-fault-detector"), + "tensorflow": installed_version("tensorflow"), + "keras": installed_version("keras"), + "pydantic": installed_version("pydantic"), + "scikit-learn": installed_version("scikit-learn"), + "pandas": installed_version("pandas"), + "numpy": installed_version("numpy"), + }, + "fixtures": { + "dense": str(dense_path.relative_to(output_dir)), + "sequence": str(sequence_path.relative_to(output_dir)), + }, + "data_generation": { + "dense": "make_dense_data(n_rows=80)", + "sequence": "make_sequence_data(n_rows=120)", + }, + } + + manifest_path = output_dir / "manifest.json" + manifest_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8") + + print(f"\nManifest written to: {manifest_path}") + print("\nLater compatibility smoke test:") + print(f' FaultDetector.load("{dense_path}")') + print(f' FaultDetector.load("{sequence_path}")') + + +if __name__ == "__main__": + main() diff --git a/tests/test_data/old_models/py310_efd071/dense/anomaly_score/RMSEScore.pkl b/tests/test_data/old_models/py310_efd071/dense/anomaly_score/RMSEScore.pkl new file mode 100644 index 00000000..efe89401 Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/dense/anomaly_score/RMSEScore.pkl differ diff --git a/tests/test_data/old_models/py310_efd071/dense/autoencoder/MultilayerAutoencoder.attrs b/tests/test_data/old_models/py310_efd071/dense/autoencoder/MultilayerAutoencoder.attrs new file mode 100644 index 00000000..7a07523d Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/dense/autoencoder/MultilayerAutoencoder.attrs differ diff --git a/tests/test_data/old_models/py310_efd071/dense/autoencoder/MultilayerAutoencoder.encoder.keras b/tests/test_data/old_models/py310_efd071/dense/autoencoder/MultilayerAutoencoder.encoder.keras new file mode 100644 index 00000000..97cec74a Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/dense/autoencoder/MultilayerAutoencoder.encoder.keras differ diff --git a/tests/test_data/old_models/py310_efd071/dense/autoencoder/MultilayerAutoencoder.model.keras b/tests/test_data/old_models/py310_efd071/dense/autoencoder/MultilayerAutoencoder.model.keras new file mode 100644 index 00000000..50baf5d9 Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/dense/autoencoder/MultilayerAutoencoder.model.keras differ diff --git a/tests/test_data/old_models/py310_efd071/dense/config.yaml b/tests/test_data/old_models/py310_efd071/dense/config.yaml new file mode 100644 index 00000000..420b9f3f --- /dev/null +++ b/tests/test_data/old_models/py310_efd071/dense/config.yaml @@ -0,0 +1,28 @@ +train: + anomaly_score: + name: rmse + params: + scale: false + autoencoder: + name: default + params: + batch_size: 16 + code_size: 3 + early_stopping: false + epochs: 1 + layers: + - 8 + learning_rate: 0.001 + loss_name: mean_squared_error + verbose: 0 + data_preprocessor: null + data_splitter: + shuffle: false + type: sklearn + validation_split: 0.2 + protect_conditional_features: false + threshold_selector: + fit_on_val: false + name: quantile + params: + quantile: 0.95 diff --git a/tests/test_data/old_models/py310_efd071/dense/data_preprocessor/DataPreprocessor.pkl b/tests/test_data/old_models/py310_efd071/dense/data_preprocessor/DataPreprocessor.pkl new file mode 100644 index 00000000..50d17636 Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/dense/data_preprocessor/DataPreprocessor.pkl differ diff --git a/tests/test_data/old_models/py310_efd071/dense/threshold_selector/QuantileThresholdSelector.pkl b/tests/test_data/old_models/py310_efd071/dense/threshold_selector/QuantileThresholdSelector.pkl new file mode 100644 index 00000000..76183c32 Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/dense/threshold_selector/QuantileThresholdSelector.pkl differ diff --git a/tests/test_data/old_models/py310_efd071/manifest.json b/tests/test_data/old_models/py310_efd071/manifest.json new file mode 100644 index 00000000..6f74d502 --- /dev/null +++ b/tests/test_data/old_models/py310_efd071/manifest.json @@ -0,0 +1,22 @@ +{ + "purpose": "Saved-model compatibility fixtures created before the Pydantic config migration.", + "python": "3.10.11 (tags/v3.10.11:7d4cc5a, Apr 5 2023, 00:38:17) [MSC v.1929 64 bit (AMD64)]", + "platform": "Windows-10-10.0.26100-SP0", + "package_versions": { + "energy-fault-detector": "0.7.1", + "tensorflow": "2.18.1", + "keras": "3.12.4", + "pydantic": null, + "scikit-learn": "1.7.0", + "pandas": "2.3.3", + "numpy": "1.26.4" + }, + "fixtures": { + "dense": "dense", + "sequence": "sequence" + }, + "data_generation": { + "dense": "make_dense_data(n_rows=80)", + "sequence": "make_sequence_data(n_rows=120)" + } +} \ No newline at end of file diff --git a/tests/test_data/old_models/py310_efd071/sequence/anomaly_score/RMSEScore.pkl b/tests/test_data/old_models/py310_efd071/sequence/anomaly_score/RMSEScore.pkl new file mode 100644 index 00000000..efe89401 Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/sequence/anomaly_score/RMSEScore.pkl differ diff --git a/tests/test_data/old_models/py310_efd071/sequence/autoencoder/LSTMSeq2OneAutoencoder.attrs b/tests/test_data/old_models/py310_efd071/sequence/autoencoder/LSTMSeq2OneAutoencoder.attrs new file mode 100644 index 00000000..3aa7b881 Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/sequence/autoencoder/LSTMSeq2OneAutoencoder.attrs differ diff --git a/tests/test_data/old_models/py310_efd071/sequence/autoencoder/LSTMSeq2OneAutoencoder.decoder.keras b/tests/test_data/old_models/py310_efd071/sequence/autoencoder/LSTMSeq2OneAutoencoder.decoder.keras new file mode 100644 index 00000000..7db3d4bb Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/sequence/autoencoder/LSTMSeq2OneAutoencoder.decoder.keras differ diff --git a/tests/test_data/old_models/py310_efd071/sequence/autoencoder/LSTMSeq2OneAutoencoder.encoder.keras b/tests/test_data/old_models/py310_efd071/sequence/autoencoder/LSTMSeq2OneAutoencoder.encoder.keras new file mode 100644 index 00000000..64a74026 Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/sequence/autoencoder/LSTMSeq2OneAutoencoder.encoder.keras differ diff --git a/tests/test_data/old_models/py310_efd071/sequence/autoencoder/LSTMSeq2OneAutoencoder.model.keras b/tests/test_data/old_models/py310_efd071/sequence/autoencoder/LSTMSeq2OneAutoencoder.model.keras new file mode 100644 index 00000000..bc87ceaa Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/sequence/autoencoder/LSTMSeq2OneAutoencoder.model.keras differ diff --git a/tests/test_data/old_models/py310_efd071/sequence/config.yaml b/tests/test_data/old_models/py310_efd071/sequence/config.yaml new file mode 100644 index 00000000..066a1302 --- /dev/null +++ b/tests/test_data/old_models/py310_efd071/sequence/config.yaml @@ -0,0 +1,38 @@ +train: + anomaly_score: + name: rmse + params: + scale: false + autoencoder: + name: lstm_seq2one + params: + batch_size: 16 + code_size: 4 + decoder_layers: + - 8 + early_stopping: false + epochs: 1 + layers: + - 8 + learning_rate: 0.001 + loss_name: mean_squared_error + sequence_builder: + pad_incomplete: false + pad_value: 0.0 + sequence_length: 8 + stride: 1 + ts_freq: 600s + verbose: 0 + data_preprocessor: + steps: + - name: standard_scaler + data_splitter: + shuffle: false + type: sklearn + validation_split: 0.2 + protect_conditional_features: false + threshold_selector: + fit_on_val: false + name: quantile + params: + quantile: 0.95 diff --git a/tests/test_data/old_models/py310_efd071/sequence/data_preprocessor/DataPreprocessor.pkl b/tests/test_data/old_models/py310_efd071/sequence/data_preprocessor/DataPreprocessor.pkl new file mode 100644 index 00000000..a84abcef Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/sequence/data_preprocessor/DataPreprocessor.pkl differ diff --git a/tests/test_data/old_models/py310_efd071/sequence/threshold_selector/QuantileThresholdSelector.pkl b/tests/test_data/old_models/py310_efd071/sequence/threshold_selector/QuantileThresholdSelector.pkl new file mode 100644 index 00000000..a252a318 Binary files /dev/null and b/tests/test_data/old_models/py310_efd071/sequence/threshold_selector/QuantileThresholdSelector.pkl differ diff --git a/tests/test_data/old_models/py311_efd060/dense/anomaly_score/RMSEScore.pkl b/tests/test_data/old_models/py311_efd060/dense/anomaly_score/RMSEScore.pkl new file mode 100644 index 00000000..efe89401 Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/dense/anomaly_score/RMSEScore.pkl differ diff --git a/tests/test_data/old_models/py311_efd060/dense/autoencoder/MultilayerAutoencoder.attrs b/tests/test_data/old_models/py311_efd060/dense/autoencoder/MultilayerAutoencoder.attrs new file mode 100644 index 00000000..96c55e0f Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/dense/autoencoder/MultilayerAutoencoder.attrs differ diff --git a/tests/test_data/old_models/py311_efd060/dense/autoencoder/MultilayerAutoencoder.encoder.keras b/tests/test_data/old_models/py311_efd060/dense/autoencoder/MultilayerAutoencoder.encoder.keras new file mode 100644 index 00000000..d0f9108e Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/dense/autoencoder/MultilayerAutoencoder.encoder.keras differ diff --git a/tests/test_data/old_models/py311_efd060/dense/autoencoder/MultilayerAutoencoder.model.keras b/tests/test_data/old_models/py311_efd060/dense/autoencoder/MultilayerAutoencoder.model.keras new file mode 100644 index 00000000..466f2729 Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/dense/autoencoder/MultilayerAutoencoder.model.keras differ diff --git a/tests/test_data/old_models/py311_efd060/dense/config.yaml b/tests/test_data/old_models/py311_efd060/dense/config.yaml new file mode 100644 index 00000000..420b9f3f --- /dev/null +++ b/tests/test_data/old_models/py311_efd060/dense/config.yaml @@ -0,0 +1,28 @@ +train: + anomaly_score: + name: rmse + params: + scale: false + autoencoder: + name: default + params: + batch_size: 16 + code_size: 3 + early_stopping: false + epochs: 1 + layers: + - 8 + learning_rate: 0.001 + loss_name: mean_squared_error + verbose: 0 + data_preprocessor: null + data_splitter: + shuffle: false + type: sklearn + validation_split: 0.2 + protect_conditional_features: false + threshold_selector: + fit_on_val: false + name: quantile + params: + quantile: 0.95 diff --git a/tests/test_data/old_models/py311_efd060/dense/data_preprocessor/DataPreprocessor.pkl b/tests/test_data/old_models/py311_efd060/dense/data_preprocessor/DataPreprocessor.pkl new file mode 100644 index 00000000..89e96022 Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/dense/data_preprocessor/DataPreprocessor.pkl differ diff --git a/tests/test_data/old_models/py311_efd060/dense/threshold_selector/QuantileThresholdSelector.pkl b/tests/test_data/old_models/py311_efd060/dense/threshold_selector/QuantileThresholdSelector.pkl new file mode 100644 index 00000000..1c2d2b20 Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/dense/threshold_selector/QuantileThresholdSelector.pkl differ diff --git a/tests/test_data/old_models/py311_efd060/manifest.json b/tests/test_data/old_models/py311_efd060/manifest.json new file mode 100644 index 00000000..e70c3646 --- /dev/null +++ b/tests/test_data/old_models/py311_efd060/manifest.json @@ -0,0 +1,22 @@ +{ + "purpose": "Saved-model compatibility fixtures created before the Pydantic config migration.", + "python": "3.11.8 (tags/v3.11.8:db85d51, Feb 6 2024, 22:03:32) [MSC v.1937 64 bit (AMD64)]", + "platform": "Windows-10-10.0.26100-SP0", + "package_versions": { + "energy-fault-detector": "0.6.0", + "tensorflow": "2.15.1", + "keras": "2.15.0", + "pydantic": "2.12.5", + "scikit-learn": "1.7.0", + "pandas": "2.2.3", + "numpy": "1.26.4" + }, + "fixtures": { + "dense": "dense", + "sequence": "sequence" + }, + "data_generation": { + "dense": "make_dense_data(seed=42, rows=80)", + "sequence": "make_sequence_data(seed=123, rows=120)" + } +} \ No newline at end of file diff --git a/tests/test_data/old_models/py311_efd060/sequence/anomaly_score/RMSEScore.pkl b/tests/test_data/old_models/py311_efd060/sequence/anomaly_score/RMSEScore.pkl new file mode 100644 index 00000000..efe89401 Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/sequence/anomaly_score/RMSEScore.pkl differ diff --git a/tests/test_data/old_models/py311_efd060/sequence/autoencoder/LSTMSeq2OneAutoencoder.attrs b/tests/test_data/old_models/py311_efd060/sequence/autoencoder/LSTMSeq2OneAutoencoder.attrs new file mode 100644 index 00000000..ce5b1d97 Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/sequence/autoencoder/LSTMSeq2OneAutoencoder.attrs differ diff --git a/tests/test_data/old_models/py311_efd060/sequence/autoencoder/LSTMSeq2OneAutoencoder.decoder.keras b/tests/test_data/old_models/py311_efd060/sequence/autoencoder/LSTMSeq2OneAutoencoder.decoder.keras new file mode 100644 index 00000000..84acbb00 Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/sequence/autoencoder/LSTMSeq2OneAutoencoder.decoder.keras differ diff --git a/tests/test_data/old_models/py311_efd060/sequence/autoencoder/LSTMSeq2OneAutoencoder.encoder.keras b/tests/test_data/old_models/py311_efd060/sequence/autoencoder/LSTMSeq2OneAutoencoder.encoder.keras new file mode 100644 index 00000000..7e598349 Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/sequence/autoencoder/LSTMSeq2OneAutoencoder.encoder.keras differ diff --git a/tests/test_data/old_models/py311_efd060/sequence/autoencoder/LSTMSeq2OneAutoencoder.model.keras b/tests/test_data/old_models/py311_efd060/sequence/autoencoder/LSTMSeq2OneAutoencoder.model.keras new file mode 100644 index 00000000..c075a507 Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/sequence/autoencoder/LSTMSeq2OneAutoencoder.model.keras differ diff --git a/tests/test_data/old_models/py311_efd060/sequence/config.yaml b/tests/test_data/old_models/py311_efd060/sequence/config.yaml new file mode 100644 index 00000000..1c68506f --- /dev/null +++ b/tests/test_data/old_models/py311_efd060/sequence/config.yaml @@ -0,0 +1,39 @@ +train: + anomaly_score: + name: rmse + params: + scale: false + autoencoder: + name: lstm_seq2one + params: + batch_size: 16 + code_size: 4 + decoder_layers: + - 8 + early_stopping: false + epochs: 1 + layers: + - 8 + learning_rate: 0.001 + loss_name: mean_squared_error + sequence_builder: + pad_incomplete: false + pad_value: 0.0 + sequence_length: 8 + stride: 1 + ts_freq: 600s + verbose: 0 + data_preprocessor: + steps: + - name: standard_scaler + step_name: standard_scaler + data_splitter: + shuffle: false + type: sklearn + validation_split: 0.2 + protect_conditional_features: false + threshold_selector: + fit_on_val: false + name: quantile + params: + quantile: 0.95 diff --git a/tests/test_data/old_models/py311_efd060/sequence/data_preprocessor/DataPreprocessor.pkl b/tests/test_data/old_models/py311_efd060/sequence/data_preprocessor/DataPreprocessor.pkl new file mode 100644 index 00000000..cfbf47e5 Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/sequence/data_preprocessor/DataPreprocessor.pkl differ diff --git a/tests/test_data/old_models/py311_efd060/sequence/threshold_selector/QuantileThresholdSelector.pkl b/tests/test_data/old_models/py311_efd060/sequence/threshold_selector/QuantileThresholdSelector.pkl new file mode 100644 index 00000000..d68c4bb5 Binary files /dev/null and b/tests/test_data/old_models/py311_efd060/sequence/threshold_selector/QuantileThresholdSelector.pkl differ diff --git a/tests/test_data/test_bad_early_stopping_config.yaml b/tests/test_data/test_bad_early_stopping_config.yaml index f6e92848..40684d82 100644 --- a/tests/test_data/test_bad_early_stopping_config.yaml +++ b/tests/test_data/test_bad_early_stopping_config.yaml @@ -35,7 +35,3 @@ root_cause_analysis: alpha: 0.8 init_x_bias: recon num_iter: 200 - -predict: - criticality: - max_criticality: 144 diff --git a/tests/test_data/test_criticality_config.yaml b/tests/test_data/test_criticality_config.yaml deleted file mode 100644 index f366d4c7..00000000 --- a/tests/test_data/test_criticality_config.yaml +++ /dev/null @@ -1,43 +0,0 @@ -train: - anomaly_score: - name: 'mahalanobis' - params: - pca: true - pca_min_var: 0.85 - data_preprocessor: - steps: - - name: column_selector - params: - features_to_exclude: - - feature1 - - feature2 - autoencoder: - name: 'MultilayerAutoencoder' - params: - layers: [300] - code_size: 50 - learning_rate: 0.001 - decay_rate: 0.001 - decay_steps: 100 - batch_size: 144 - epochs: 10 - loss_name: 'mean_squared_error' - threshold_selector: - name: 'FDR' - params: - target_false_discovery_rate: 0.8 - data_splitter: - train_block_size: 7 - val_block_size: 3 - data_clipping: - lower_percentile: 0.01 - upper_percentile: 0.99 - -root_cause_analysis: - alpha: 0.8 - init_x_bias: recon - num_iter: 200 - -predict: - criticality: - max_criticality: 144 diff --git a/tests/test_fault_detector.py b/tests/test_fault_detector.py index 8a259320..da20bce7 100644 --- a/tests/test_fault_detector.py +++ b/tests/test_fault_detector.py @@ -79,8 +79,8 @@ def test_save_load_models(self): self.assertEqual(original_threshold_params, loaded_threshold_params) # Check the configuration - self.assertDictEqual(self.fault_detector.config.config_dict, - loaded_fault_detector.config.config_dict) + self.assertDictEqual(self.fault_detector.config.model_dump(exclude_none=True), + loaded_fault_detector.config.model_dump(exclude_none=True)) # Check path when overwrite = True results = self.fault_detector.fit(sensor_data=self.sensor_data, normal_index=self.normal_index, @@ -159,7 +159,6 @@ def test_save_load_roundtrip_with_weighted_rmse(self): class TestFaultDetector(unittest.TestCase): def setUp(self) -> None: self.conf = Config(os.path.join(PROJECT_ROOT, './tests/test_data/test_config.yaml')) - self.conf.read_config() self.sensor_data = pd.DataFrame(data=[[1., 2., 3.], [4., 5., 6.], @@ -195,8 +194,8 @@ def test_init(self): self.assertEqual(fault_detector.model_directory, str(self.test_model_dir)) self.assertEqual(fault_detector.config, self.conf) - def test_save_models(self): - self.conf.write_config = MagicMock() + @patch.object(Config, 'write_config') + def test_save_models(self, mock_write_config): fault_detector = self._create_fault_detector(self.conf) asset_id = 1 @@ -209,20 +208,19 @@ def test_save_models(self): self.assertEqual(model_object.save.call_args[0][0], os.path.join(fault_detector.model_directory, str(asset_id), dt, name)) - fault_detector.config.write_config.assert_called_once() - self.assertEqual(fault_detector.config.write_config.call_args[0][0], + mock_write_config.assert_called_once() + self.assertEqual(mock_write_config.call_args[0][0], os.path.join(fault_detector.model_directory, str(asset_id), dt, 'config.yaml')) @patch("energy_fault_detector.core.fault_detection_model.FaultDetectionModel._load_pickled_model") - @patch("energy_fault_detector.config.Config.read_config") - def test_load_models(self, mock_load_pickled_model, mock_read_config): + @patch("energy_fault_detector.core.fault_detection_model.Config") + def test_load_models(self, mock_load_pickled_model, mock_config): mock_load_pickled_model.side_effect = [ mock_data_preprocessor, mock_autoencoder, mock_threshold, mock_score, ] - mock_read_config = MagicMock() fault_detector = FaultDetector.load("path_to_saved_models") @@ -233,8 +231,8 @@ def test_load_models(self, mock_load_pickled_model, mock_read_config): self.assertEqual(call_args[1]['model_type'], name) self.assertEqual(call_args[1]['model_directory'], os.path.join('path_to_saved_models', name)) - def test_train(self): - self.conf.write_config = MagicMock() + @patch.object(Config, 'write_config') + def test_train(self, mock_write_config): fault_detector = self._create_fault_detector(self.conf) mock_data_preprocessor.transform.side_effect = [self.sensor_data[self.normal_index], @@ -258,7 +256,7 @@ def test_train(self): mock_threshold.fit.assert_called_once() # saved models: mock_score.save.assert_called_once() - self.conf.write_config.assert_called_once() + mock_write_config.assert_called_once() model_dir = os.path.join(fault_detector.model_directory, fault_detector.save_timestamps[0]) model_date = results.model_date @@ -278,7 +276,7 @@ def test_train(self): save_models=False) mock_score.save.assert_not_called() - self.assertEqual(self.conf.write_config.call_count, 1) + self.assertEqual(mock_write_config.call_count, 1) def test_tune(self): mock_data_preprocessor.transform.side_effect = [self.sensor_data[self.normal_index], @@ -447,7 +445,7 @@ def test_sequence_model_save_and_load_roundtrip(self) -> None: np.testing.assert_allclose(a, b, atol=1e-6) # Config should round-trip as well - self.assertDictEqual(fd.config.config_dict, fd2.config.config_dict) + self.assertDictEqual(fd.config.model_dump(exclude_none=True), fd2.config.model_dump(exclude_none=True)) class TestFaultDetectorBidirectionalSequenceSaveLoad(unittest.TestCase): @@ -498,7 +496,7 @@ def test_sequence_model_save_and_load_roundtrip(self) -> None: for a, b in zip(w1, w2): np.testing.assert_allclose(a, b, atol=1e-6) - self.assertDictEqual(fd.config.config_dict, fd2.config.config_dict) + self.assertDictEqual(fd.config.model_dump(exclude_none=True), fd2.config.model_dump(exclude_none=True)) class TestAutoencoderGetReconstructionError(unittest.TestCase): @@ -616,7 +614,7 @@ def test_fallback_preserves_architecture_params(self): from energy_fault_detector.autoencoders import MultilayerAutoencoder fd = FaultDetector(config=self.conf, model_directory=self.test_dir) - ae_params = self.conf['train']['autoencoder'].get('params', {}) + ae_params = self.conf.train.autoencoder.params sensor_data_no_cond = self.sensor_data.drop(columns=['feature_a', 'feature_b']) fd._resolve_conditional_features(sensor_data_no_cond) @@ -694,7 +692,7 @@ def setUp(self) -> None: self.config_path = os.path.join(PROJECT_ROOT, 'tests/test_data/test_conditional_ae_config.yaml') self.conf = Config(self.config_path) # Set protect_conditional_features to False - self.conf.config_dict['train']['protect_conditional_features'] = False + self.conf.train.protect_conditional_features = False self.test_dir = tempfile.mkdtemp() np.random.seed(42) @@ -715,10 +713,10 @@ def tearDown(self) -> None: def test_conditional_features_can_be_dropped_when_unprotected(self): """When protect=False, pipeline can drop constant conditional features.""" from energy_fault_detector.autoencoders import MultilayerAutoencoder - self.conf.config_dict['train']['protect_conditional_features'] = False - self.conf.config_dict['train']['data_preprocessor']['steps'].append({'name': 'low_unique_value_filter', 'params': {'min_unique_value_count': 2}}) + self.conf.train.protect_conditional_features = False + self.conf.train.data_preprocessor.steps.append({'name': 'low_unique_value_filter', 'params': {'min_unique_value_count': 2}}) fd = FaultDetector(config=self.conf, model_directory=self.test_dir) - self.assertFalse(fd.config.protect_conditional_features) + self.assertFalse(fd.config.train.protect_conditional_features) result = fd.fit(sensor_data=self.sensor_data, normal_index=self.normal_index, save_models=False) # feature_a was constant, should have been dropped, triggering fallback @@ -733,7 +731,7 @@ def test_conditional_features_can_be_dropped_when_unprotected(self): def test_protect_true_keeps_constant_conditional(self): """When protect=True (default), constant conditional features are kept.""" - self.conf.config_dict['train']['protect_conditional_features'] = True + self.conf.train.protect_conditional_features = True fd = FaultDetector(config=self.conf, model_directory=self.test_dir) fd.fit(sensor_data=self.sensor_data, normal_index=self.normal_index, save_models=False) @@ -783,7 +781,7 @@ class TestProtectConditionalFeaturesConfigProperty(unittest.TestCase): def test_default_is_false(self): """Default value should be False when not specified.""" config = Config(os.path.join(PROJECT_ROOT, 'tests/test_data/test_config.yaml')) - self.assertFalse(config.protect_conditional_features) + self.assertFalse(config.train.protect_conditional_features) def test_explicit_false(self): """Explicit False in config should be respected.""" @@ -796,7 +794,7 @@ def test_explicit_false(self): 'threshold_selector': {'name': 'quantile', 'params': {'quantile': 0.95}}, } }) - self.assertFalse(config.protect_conditional_features) + self.assertFalse(config.train.protect_conditional_features) def test_explicit_true(self): """Explicit True in config should be respected.""" @@ -809,7 +807,7 @@ def test_explicit_true(self): 'threshold_selector': {'name': 'quantile', 'params': {'quantile': 0.95}}, } }) - self.assertTrue(config.protect_conditional_features) + self.assertTrue(config.train.protect_conditional_features) class TestHandleDuplicateIndex(unittest.TestCase): diff --git a/tests/test_model_compatibility.py b/tests/test_model_compatibility.py new file mode 100644 index 00000000..3123f737 --- /dev/null +++ b/tests/test_model_compatibility.py @@ -0,0 +1,202 @@ +"""Compatibility tests for loading and applying pre-Pydantic saved models. + +The fixtures under ``tests/test_data/old_models/`` were created with older +versions of ``energy-fault-detector`` (before the Pydantic config migration) +using the script ``tests/test_data/old_models/create_legacy_model_fixtures.py``. + +For Keras 3 fixtures (``py310_efd071``) the full pipeline is exercised: +``FaultDetector.load`` + ``predict``. These fixtures are created with the +minimum supported Python version (3.10), which caps Keras at 3.12.4, so they +load on every supported Python/Keras combination. For Keras 2 fixtures +(``py311_efd060``) the autoencoder cannot be loaded by Keras 3 +(``keras.src.engine.functional`` was renamed), so only the non-Keras components +(config, data preprocessor, threshold selector, anomaly score) are loaded and +applied individually. +""" + +import os +import unittest + +import numpy as np +import pandas as pd + +from energy_fault_detector.anomaly_scores import RMSEScore +from energy_fault_detector.autoencoders import LSTMSeq2OneAutoencoder, MultilayerAutoencoder +from energy_fault_detector.config import Config +from energy_fault_detector.core import FaultDetectionResult +from energy_fault_detector.data_preprocessing import DataPreprocessor +from energy_fault_detector.fault_detector import FaultDetector +from energy_fault_detector.threshold_selectors import QuantileThresholdSelector + +PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +OLD_MODELS_DIR = os.path.join(PROJECT_ROOT, 'tests', 'test_data', 'old_models') + + +def make_dense_data(n_rows: int = 80) -> pd.DataFrame: + """Create deterministic tabular data matching the dense fixture training data. + + Args: + n_rows: Number of samples to generate. + + Returns: + Numeric DataFrame with a 10-minute DatetimeIndex. + """ + rng = np.random.default_rng(42) + index = pd.date_range("2025-01-01", periods=n_rows, freq="10min") + phase = np.linspace(0, 4 * np.pi, n_rows) + return pd.DataFrame( + { + "temperature": 50 + 3 * np.sin(phase) + rng.normal(0, 0.15, n_rows), + "pressure": 10 + 0.5 * np.cos(phase) + rng.normal(0, 0.05, n_rows), + "power": 100 + 8 * np.sin(phase / 2) + rng.normal(0, 0.3, n_rows), + }, + index=index, + ) + + +def make_sequence_data(n_rows: int = 120) -> pd.DataFrame: + """Create deterministic time-series data matching the sequence fixture training data. + + Args: + n_rows: Number of samples to generate. + + Returns: + Numeric DataFrame with a regular 10-minute DatetimeIndex. + """ + rng = np.random.default_rng(123) + index = pd.date_range("2025-02-01", periods=n_rows, freq="10min") + phase = np.linspace(0, 6 * np.pi, n_rows) + return pd.DataFrame( + { + "sensor_a": np.sin(phase) + rng.normal(0, 0.03, n_rows), + "sensor_b": np.cos(phase) + rng.normal(0, 0.03, n_rows), + "sensor_c": 0.3 * np.sin(phase / 2) + rng.normal(0, 0.02, n_rows), + }, + index=index, + ) + + +class TestLegacyModelCompatibility(unittest.TestCase): + """Load and apply saved-model fixtures created before the Pydantic config migration.""" + + def _assert_loaded_components(self, detector: FaultDetector) -> None: + """Verify all model components and config were loaded.""" + self.assertIsNotNone(detector.autoencoder) + self.assertIsNotNone(detector.data_preprocessor) + self.assertIsNotNone(detector.threshold_selector) + self.assertIsNotNone(detector.anomaly_score) + self.assertIsNotNone(detector.config) + + def _assert_predict_results(self, result: FaultDetectionResult, expected_len: int) -> None: + """Verify prediction results are sane and internally consistent. + + Args: + result: Output of ``FaultDetector.predict``. + expected_len: Expected number of rows in the anomaly score / predictions. + """ + self.assertFalse(result.anomaly_score.empty) + self.assertTrue(np.all(np.isfinite(result.anomaly_score.values))) + self.assertEqual(len(result.anomaly_score), expected_len) + self.assertIsInstance(result.predicted_anomalies, pd.Series) + self.assertEqual(result.predicted_anomalies.dtype, bool) + self.assertTrue(result.predicted_anomalies.index.equals(result.anomaly_score.index)) + + @staticmethod + def _load_non_keras_components(model_path: str) -> tuple: + """Load config, data preprocessor, threshold selector, and anomaly score. + + Bypasses ``FaultDetector.load`` (which also loads the Keras autoencoder) + so the non-Keras pickled components can be tested independently. + + Args: + model_path: Directory containing the saved model (config.yaml + sub-dirs). + + Returns: + Tuple of (Config, DataPreprocessor, QuantileThresholdSelector, RMSEScore). + """ + config = Config(os.path.join(model_path, 'config.yaml')) + + data_preprocessor = DataPreprocessor() + data_preprocessor.load(os.path.join(model_path, 'data_preprocessor')) + + threshold_selector = QuantileThresholdSelector() + threshold_selector.load(os.path.join(model_path, 'threshold_selector')) + + anomaly_score = RMSEScore() + anomaly_score.load(os.path.join(model_path, 'anomaly_score')) + + return config, data_preprocessor, threshold_selector, anomaly_score + + def _assert_non_keras_pipeline(self, model_path: str, data: pd.DataFrame, + expected_ae_name: str) -> None: + """Load non-Keras components, run data through the partial pipeline. + + Args: + model_path: Directory containing the saved model. + data: Synthetic data matching the fixture's training data. + expected_ae_name: Expected ``config.train.autoencoder.name`` value. + """ + config, data_preprocessor, threshold_selector, anomaly_score = \ + self._load_non_keras_components(model_path) + + self.assertEqual(config.train.autoencoder.name, expected_ae_name) + self.assertIsInstance(data_preprocessor, DataPreprocessor) + self.assertIsInstance(threshold_selector, QuantileThresholdSelector) + self.assertIsInstance(anomaly_score, RMSEScore) + + prepped = data_preprocessor.transform(data) + self.assertFalse(prepped.empty) + + rng = np.random.default_rng(0) + recon_error = pd.DataFrame( + rng.standard_normal(prepped.shape), + index=prepped.index, columns=prepped.columns, + ) + scores = anomaly_score.transform(recon_error) + self.assertFalse(scores.empty) + self.assertTrue(np.all(np.isfinite(scores.values))) + + predicted = threshold_selector.predict(scores) + self.assertEqual(len(predicted), len(scores)) + + def test_dense_py310_efd071(self) -> None: + """Dense MultilayerAutoencoder saved with EFD 0.7.1 / Python 3.10 / Keras 3.""" + model_path = os.path.join(OLD_MODELS_DIR, 'py310_efd071', 'dense') + detector = FaultDetector.load(model_path=model_path) + self._assert_loaded_components(detector) + self.assertIsInstance(detector.autoencoder, MultilayerAutoencoder) + self.assertEqual(detector.config.train.autoencoder.name, 'default') + + result = detector.predict(make_dense_data()) + self._assert_predict_results(result, expected_len=80) + + def test_sequence_py310_efd071(self) -> None: + """LSTM seq2one autoencoder saved with EFD 0.7.1 / Python 3.10 / Keras 3.""" + model_path = os.path.join(OLD_MODELS_DIR, 'py310_efd071', 'sequence') + detector = FaultDetector.load(model_path=model_path) + self._assert_loaded_components(detector) + self.assertIsInstance(detector.autoencoder, LSTMSeq2OneAutoencoder) + self.assertEqual(detector.config.train.autoencoder.name, 'lstm_seq2one') + + result = detector.predict(make_sequence_data()) + self._assert_predict_results(result, expected_len=113) + + def test_dense_py311_efd060(self) -> None: + """Non-Keras components from EFD 0.6.0 / Python 3.11 / Keras 2 fixture (dense). + + The Keras 2 autoencoder cannot be loaded by Keras 3, but the config, + data preprocessor, threshold selector, and anomaly score are plain + pickle/YAML and should load and run. + """ + model_path = os.path.join(OLD_MODELS_DIR, 'py311_efd060', 'dense') + self._assert_non_keras_pipeline(model_path, make_dense_data(), 'default') + + def test_sequence_py311_efd060(self) -> None: + """Non-Keras components from EFD 0.6.0 / Python 3.11 / Keras 2 fixture (sequence). + + The Keras 2 autoencoder cannot be loaded by Keras 3, but the config, + data preprocessor, threshold selector, and anomaly score are plain + pickle/YAML and should load and run. + """ + model_path = os.path.join(OLD_MODELS_DIR, 'py311_efd060', 'sequence') + self._assert_non_keras_pipeline(model_path, make_sequence_data(), 'lstm_seq2one') diff --git a/tests/utils/test_analysis.py b/tests/utils/test_analysis.py index f8be1520..9dd9a89f 100644 --- a/tests/utils/test_analysis.py +++ b/tests/utils/test_analysis.py @@ -5,7 +5,7 @@ import pandas as pd from energy_fault_detector.utils import analysis -from energy_fault_detector.utils.analysis import calculate_criticality, create_events +from energy_fault_detector.utils.analysis import calculate_alarms, calculate_criticality, create_events # ────────────────────────────────────────────────────────────────────────────── @@ -107,6 +107,139 @@ def test_preserves_multiindex(self): assert crit.index.equals(idx) +# ────────────────────────────────────────────────────────────────────────────── +# calculate_alarms +# ────────────────────────────────────────────────────────────────────────────── + +class TestCalculateAlarmsSingleIndex: + """Alarm derivation with a simple DatetimeIndex.""" + + def test_no_anomalies_returns_empty_events(self): + idx = pd.date_range("2024-01-01", periods=10, freq="10min") + anomalies = pd.Series(False, index=idx) + events, crit = calculate_alarms(anomalies) + assert list(events.columns) == ["start", "end", "duration"] + assert events.empty + assert (crit == 0).all() + + def test_default_threshold_from_time_frequency(self): + """10 minute data -> default threshold of 6 (one hour), max = threshold + 6.""" + idx = pd.date_range("2024-01-01", periods=40, freq="10min") + anomalies = pd.Series(False, index=idx) + anomalies.iloc[2:14] = True + events, crit = calculate_alarms(anomalies) + + # 12 anomalies raise the criticality to 12 (threshold 6 + 6 reset steps) + assert crit.max() == 12 + # The alarm window starts when criticality reaches 6, i.e. the 6th anomaly (iloc 7) + assert events.iloc[0]["start"] == idx[7] + # Alarm ends when the criticality drops below the threshold again (6 normal steps after iloc 13) + assert events.iloc[0]["end"] == idx[19] + assert events.iloc[0]["duration"] == idx[19] - idx[7] + + def test_default_threshold_one_for_high_frequency_gap(self): + """Time frequency > 1 hour -> default threshold 1.""" + idx = pd.date_range("2024-01-01", periods=6, freq="2h") + anomalies = pd.Series([False, True, True, False, False, False], index=idx) + events, crit = calculate_alarms(anomalies) + + # threshold 1 and time frequency > reset window -> max_criticality = 2 + assert list(crit) == [0, 1, 2, 1, 0, 0] + assert events.iloc[0]["start"] == idx[1] + assert events.iloc[0]["end"] == idx[3] + + def test_explicit_threshold_and_reset_time(self): + idx = pd.date_range("2024-01-01", periods=10, freq="10min") + anomalies = pd.Series(True, index=idx) + events, crit = calculate_alarms(anomalies, criticality_threshold=3, alarm_reset_time_minutes=20) + + # max criticality = 3 + int(20 / 10) = 5 + assert crit.max() == 5 + assert events.iloc[0]["start"] == idx[2] + + def test_normal_idx_ignored_periods(self): + idx = pd.date_range("2024-01-01", periods=8, freq="10min") + anomalies = pd.Series(True, index=idx) + normal_idx = pd.Series([True, True, False, False, True, True, True, True], index=idx) + events, crit = calculate_alarms(anomalies, normal_idx=normal_idx, + criticality_threshold=2, alarm_reset_time_minutes=10) + + # max criticality = 2 + int(10 / 10) = 3, so t4..t7 stay at 3 + # t0,t1 -> 1,2 ; t2,t3 ignored ; t4..t7 -> 3,3,3,3 + assert list(crit) == [1, 2, 2, 2, 3, 3, 3, 3] + assert events.iloc[0]["start"] == idx[1] + + def test_init_criticality(self): + idx = pd.date_range("2024-01-01", periods=5, freq="10min") + anomalies = pd.Series(True, index=idx) + events, crit = calculate_alarms(anomalies, init_criticality=4, + criticality_threshold=5, alarm_reset_time_minutes=10) + + assert list(crit) == [5, 6, 6, 6, 6] + # Already at/above the threshold on the first timestamp + assert events.iloc[0]["start"] == idx[0] + + def test_no_time_frequency_uses_fallback(self): + """Without a datetime index the threshold falls back to 1 and max to threshold + 1.""" + idx = pd.RangeIndex(8) + anomalies = pd.Series([False, True, True, True, False, False, False, False], index=idx) + events, crit = calculate_alarms(anomalies) + + assert list(crit) == [0, 1, 2, 2, 1, 0, 0, 0] + assert events.iloc[0]["start"] == idx[1] + assert events.iloc[0]["end"] == idx[4] + + def test_multiple_disjoint_alarms(self): + idx = pd.date_range("2024-01-01", periods=30, freq="10min") + anomalies = pd.Series(False, index=idx) + anomalies.iloc[0:8] = True # criticality reaches 8, drops to 0 by iloc 16 + anomalies.iloc[20:30] = True # second alarm + events, _ = calculate_alarms(anomalies, alarm_reset_time_minutes=20) + + assert len(events) == 2 + assert events.iloc[0]["start"] == idx[5] + assert events.iloc[1]["start"] == idx[25] + + +class TestCalculateAlarmsMultiIndex(unittest.TestCase): + """Alarm derivation with a MultiIndex (asset_id, timestamp).""" + + def setUp(self): + self.times = pd.date_range("2024-01-01", periods=20, freq="10min") + self.idx = pd.MultiIndex.from_product([["asset_A", "asset_B"], self.times], + names=["asset_id", "timestamp"]) + + def test_alarms_are_grouped_per_asset(self): + anomalies = pd.Series(False, index=self.idx) + anomalies.loc["asset_A"] = [False] * 2 + [True] * 10 + [False] * 8 + anomalies.loc["asset_B"] = [False] * 5 + [True] * 7 + [False] * 8 + + events, crit = calculate_alarms(anomalies) + + assert set(events["group"]) == {"asset_A", "asset_B"} + assert "group" in events.columns + assert crit.groupby(level="asset_id").max().to_dict() == {"asset_A": 10, "asset_B": 7} + + def test_time_frequency_from_datetime_level(self): + """Time frequency is inferred from the datetime level of the MultiIndex.""" + anomalies = pd.Series(False, index=self.idx) + anomalies.loc["asset_A"] = [False] * 2 + [True] * 12 + [False] * 6 + + events, crit = calculate_alarms(anomalies) + + # default threshold 6, max 12 as for a single DatetimeIndex with 10 min frequency + assert crit.loc["asset_A"].max() == 12 + assert events.loc[events["group"] == "asset_A"].iloc[0]["start"] == self.times[7] + + def test_empty_events_keep_group_column(self): + anomalies = pd.Series(False, index=self.idx) + events, crit = calculate_alarms(anomalies) + + assert events.empty + assert list(events.columns) == ["start", "end", "duration", "group"] + assert (crit == 0).all() + + # ────────────────────────────────────────────────────────────────────────────── # create_events # ────────────────────────────────────────────────────────────────────────────── diff --git a/tests/utils/test_visualisation.py b/tests/utils/test_visualisation.py index 162b1bfc..43265ad4 100644 --- a/tests/utils/test_visualisation.py +++ b/tests/utils/test_visualisation.py @@ -88,6 +88,17 @@ def test_plot_reconstruction_with_model(self): self.assertEqual(len(axes), 2) plt.close(fig) + def test_plot_score_with_threshold_show_criticality(self): + idx = pd.date_range("2025-01-01", periods=10, freq="h") + data = pd.DataFrame({"a": np.arange(10, dtype=float)}, index=idx) + fd = DummyFDWithDP(data) + + fig, ax = viz.plot_score_with_threshold( + model=fd, data=data, show_threshold=False, show_criticality=True, max_criticality=144, + ) + self.assertIsInstance(fig, plt.Figure) + plt.close(fig) + def test_plot_arcana_mean_importances(self): importances = pd.Series( {