epyt-flow 0.1.0__py3-none-any.whl

epyt_flow/gym/control_gyms.py

@@ -0,0 +1,47 @@
+"""
+Module provides functions for registering and creating control environments.
+"""
+from .scenario_control_env import ScenarioControlEnv
+
+
+environments = {}
+
+
+def register(env_name: str, env: ScenarioControlEnv) -> None:
+    """
+    Registers a new environment under a given name.
+
+    Parameters
+    ----------
+    env_name : `str`
+        Name of the environment -- must be unique among all environments.
+    env : :class:`epyt_flow.gym.scenario_control_env.ScenarioControlEnv`
+        Environment.
+    """
+    if env_name in environments:
+        raise ValueError(f"Environment '{env_name}' already exists.")
+    if not issubclass(env, ScenarioControlEnv):
+        raise TypeError("'env' must be a subclass of " +
+                        "'epyt_flow.gym.ScenarioControlEnv'")
+
+    environments[env_name] = env
+
+
+def make(env_name: str, **kwds) -> ScenarioControlEnv:
+    """
+    Creates an instance of a registered environment.
+
+    Parameters
+    ----------
+    env_name : `str`
+        Name of the environment.
+
+    Returns
+    -------
+    :class:`epyt_flow.gym.scenario_control_env.ScenarioControlEnv`
+        Environment.
+    """
+    if env_name not in environments:
+        raise ValueError(f"Unknown environment '{env_name}'.")
+
+    return environments[env_name](**kwds)

epyt_flow/gym/scenario_control_env.py

@@ -0,0 +1,101 @@
+"""
+Module provides a base class for control environments.
+"""
+from abc import abstractmethod, ABC
+from copy import deepcopy
+
+from ..simulation import ScenarioSimulator, ScenarioConfig, ScadaData
+
+
+class ScenarioControlEnv(ABC):
+    """
+    Base class for a control environment challenge.
+
+    Parameters
+    ----------
+    scenario_config : :class:`~epyt_flow.simulation.scenario_config.ScenarioConfig`
+        Scenario configuration.
+    autoreset : `bool`, optional
+        If True, environment is automatically reset if terminated.
+
+        The default is False.
+    """
+    def __init__(self, scenario_config: ScenarioConfig, autoreset: bool = False, **kwds):
+        self.__scenario_config = scenario_config
+        self._scenario_sim = None
+        self._sim_generator = None
+        self.__autoreset = autoreset
+
+        super().__init__(**kwds)
+
+    @property
+    def autoreset(self) -> bool:
+        """
+        True, if environment automatically resets after it terminated.
+        """
+        return deepcopy(self.__autoreset)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def close(self) -> None:
+        """
+        Frees all resources.
+        """
+        try:
+            if self._sim_generator is not None:
+                self._sim_generator.send(True)
+                next(self._sim_generator)
+        except StopIteration:
+            pass
+
+        if self._scenario_sim is not None:
+            self._scenario_sim.close()
+
+    def reset(self) -> ScadaData:
+        """
+        Resets the environment (i.e. simulation).
+        """
+        if self._scenario_sim is not None:
+            self._scenario_sim.close()
+
+        self._scenario_sim = ScenarioSimulator(
+            scenario_config=self.__scenario_config)
+        self._sim_generator = self._scenario_sim.run_simulation_as_generator(support_abort=True)
+
+        return self._next_sim_itr()
+
+    def _next_sim_itr(self) -> ScadaData:
+        try:
+            next(self._sim_generator)
+            r = self._sim_generator.send(False)
+
+            if self.autoreset is True:
+                return r
+            else:
+                return r, False
+        except StopIteration:
+            if self.__autoreset is True:
+                return self.reset()
+            else:
+                return None, True
+
+    @abstractmethod
+    def step(self) -> tuple[ScadaData, float, bool]:
+        """
+        Performs the next step by applying an action and observing
+        the consequences (SCADA data, reward, terminated).
+
+        Note that `terminated` is only returned if `autoreset=False` otherwise
+        only SCADA data and reward are returned.
+
+        Returns
+        -------
+        `(ScadaData, float, bool)`
+            Triple of observations (:class:`~epyt_flow.simuation.scada.scada_data.ScadaData`),
+            reward (`float`), and terminated (`bool`).
+        """
+        raise NotImplementedError()

epyt_flow/metrics.py

@@ -0,0 +1,404 @@
+"""
+This module provides different metrics for evaluation.
+"""
+import numpy as np
+from sklearn.metrics import roc_auc_score as skelarn_roc_auc_score, f1_score as skelarn_f1_scpre, \
+    mean_absolute_error
+
+
+def running_mse(y_pred: np.ndarray, y: np.ndarray):
+    """
+    Computes the running Mean Squared Error (MSE).
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted outputs.
+    y : `numpy.ndarray`
+        Ground truth outputs.
+
+    Returns
+    -------
+    `float`
+        Running MSE.
+    """
+    if not isinstance(y_pred, np.ndarray):
+        raise TypeError("'y_pred' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y_pred)}'")
+    if not isinstance(y, np.ndarray):
+        raise TypeError("'y' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y)}'")
+    if y_pred.shape != y.shape:
+        raise ValueError(f"Shape mismatch: {y_pred.shape} vs. {y.shape}")
+    if len(y_pred.shape) != 1:
+        raise ValueError("'y_pred' must be a 1d array")
+    if len(y.shape) != 1:
+        raise ValueError("'y' must be a 1d array")
+
+    e_sq = np.square(y - y_pred)
+    r_mse = list(esq for esq in e_sq)
+
+    for i in range(1, len(y)):
+        r_mse[i] = ((i * r_mse[i - 1]) / (i + 1)) + (r_mse[i] / (i + 1))
+
+    return r_mse
+
+
+def mape(y_pred: np.ndarray, y: np.ndarray, epsilon: float = .05) -> float:
+    """
+    Computes the Mean Absolute Percentage Error (MAPE).
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted outputs.
+    y : `numpy.ndarray`
+        Ground truth outputs.
+    epsilon : `float`, optional
+        Small number added to predictions and ground truth to avoid division-by-zero.
+
+        The default is 0.05
+
+    Returns
+    -------
+    `float`
+        MAPE score.
+    """
+    if not isinstance(y_pred, np.ndarray):
+        raise TypeError("'y_pred' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y_pred)}'")
+    if not isinstance(y, np.ndarray):
+        raise TypeError("'y' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y)}'")
+    if not isinstance(epsilon, float):
+        raise TypeError("'epsilon' must be an instance of 'float' " +
+                        f"but not of '{type(epsilon)}'")
+    if y_pred.shape != y.shape:
+        raise ValueError(f"Shape mismatch: {y_pred.shape} vs. {y.shape}")
+    if len(y_pred.shape) != 1:
+        raise ValueError("'y_pred' must be a 1d array")
+    if len(y.shape) != 1:
+        raise ValueError("'y' must be a 1d array")
+
+    y_ = y + epsilon
+    y_pred_ = y_pred + epsilon
+    return np.mean(np.abs((y_ - y_pred_) / y_))
+
+
+def smape(y_pred: np.ndarray, y: np.ndarray, epsilon: float = .05) -> float:
+    """
+    Computes the Symmetric Mean Absolute Percentage Error (SMAPE).
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted outputs.
+    y : `numpy.ndarray`
+        Ground truth outputs.
+    epsilon : `float`, optional
+        Small number added to predictions and ground truth to avoid division-by-zero.
+
+        The default is 0.05
+
+    Returns
+    -------
+    `float`
+        SMAPE score.
+    """
+    if not isinstance(y_pred, np.ndarray):
+        raise TypeError("'y_pred' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y_pred)}'")
+    if not isinstance(y, np.ndarray):
+        raise TypeError("'y' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y)}'")
+    if not isinstance(epsilon, float):
+        raise TypeError("'epsilon' must be an instance of 'float' " +
+                        f"but not of '{type(epsilon)}'")
+    if y_pred.shape != y.shape:
+        raise ValueError(f"Shape mismatch: {y_pred.shape} vs. {y.shape}")
+    if len(y_pred.shape) != 1:
+        raise ValueError("'y_pred' must be a 1d array")
+    if len(y.shape) != 1:
+        raise ValueError("'y' must be a 1d array")
+
+    y_ = y + epsilon
+    y_pred_ = y_pred + epsilon
+    return 2. * np.mean(np.abs(y_ - y_pred_) / (np.abs(y_) + np.abs(y_pred_)))
+
+
+def mase(y_pred: np.ndarray, y: np.ndarray, epsilon: float = .05) -> float:
+    """
+    Computes the Mean Absolute Scaled Error (MASE).
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted outputs.
+    y : `numpy.ndarray`
+        Ground truth outputs.
+    epsilon : `float`, optional
+        Small number added to predictions and ground truth to avoid division-by-zero.
+
+        The default is 0.05
+
+    Returns
+    -------
+    `float`
+        MASE score.
+    """
+    if not isinstance(y_pred, np.ndarray):
+        raise TypeError("'y_pred' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y_pred)}'")
+    if not isinstance(y, np.ndarray):
+        raise TypeError("'y' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y)}'")
+    if not isinstance(epsilon, float):
+        raise TypeError("'epsilon' must be an instance of 'float' " +
+                        f"but not of '{type(epsilon)}'")
+    if y_pred.shape != y.shape:
+        raise ValueError(f"Shape mismatch: {y_pred.shape} vs. {y.shape}")
+    if len(y_pred.shape) != 1:
+        raise ValueError("'y_pred' must be a 1d array")
+    if len(y.shape) != 1:
+        raise ValueError("'y' must be a 1d array")
+
+    try:
+        y_ = y + epsilon
+        y_pred_ = y_pred + epsilon
+
+        mae = mean_absolute_error(y_, y_pred_)
+        naive_error = np.mean(np.abs(y_[1:] - y_pred_[:-1]))
+        return mae / naive_error
+    except Exception:
+        return None
+
+
+def f1_micro_score(y_pred: np.ndarray, y: np.ndarray) -> float:
+    """
+    Computes the F1 score using for a multi-class classification by
+    counting the total true positives, false negatives and false positives.
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted labels.
+    y : `numpy.ndarray`
+        Ground truth labels.
+
+    Returns
+    -------
+    `float`
+        F1 score.
+    """
+    if not isinstance(y_pred, np.ndarray):
+        raise TypeError("'y_pred' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y_pred)}'")
+    if not isinstance(y, np.ndarray):
+        raise TypeError("'y' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y)}'")
+    if y_pred.shape != y.shape:
+        raise ValueError(f"Shape mismatch: {y_pred.shape} vs. {y.shape}")
+
+    return skelarn_f1_scpre(y, y_pred, average="micro")
+
+
+def roc_auc_score(y_pred: np.ndarray, y: np.ndarray) -> float:
+    """
+    Computes the Area Under the Curve (AUC) of a classification.
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted labels.
+    y : `numpy.ndarray`
+        Ground truth labels.
+
+    Returns
+    -------
+    `float`
+        ROC AUC score.
+    """
+    if not isinstance(y_pred, np.ndarray):
+        raise TypeError("'y_pred' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y_pred)}'")
+    if not isinstance(y, np.ndarray):
+        raise TypeError("'y' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y)}'")
+    if y_pred.shape != y.shape:
+        raise ValueError(f"Shape mismatch: {y_pred.shape} vs. {y.shape}")
+
+    return skelarn_roc_auc_score(y, y_pred)
+
+
+def true_positive_rate(y_pred: np.ndarray, y: np.ndarray) -> float:
+    """
+    Computes the true positive rate (also called sensitivity).
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted labels.
+    y : `numpy.ndarray`
+        Ground truth labels.
+
+    Returns
+    -------
+    `float`
+        True positive rate.
+    """
+    if not isinstance(y_pred, np.ndarray):
+        raise TypeError("'y_pred' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y_pred)}'")
+    if not isinstance(y, np.ndarray):
+        raise TypeError("'y' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y)}'")
+    if y_pred.shape != y.shape:
+        raise ValueError(f"Shape mismatch: {y_pred.shape} vs. {y.shape}")
+    if len(y_pred.shape) != 1:
+        raise ValueError("'y_pred' must be a 1d array")
+    if len(y.shape) != 1:
+        raise ValueError("'y' must be a 1d array")
+    if set(np.unique(y_pred)) != set([0, 1]):
+        raise ValueError("Labels must be either '0' or '1'")
+
+    tp = np.sum((y == 1) & (y_pred == 1))
+    fn = np.sum((y == 1) & (y_pred == 0))
+
+    return tp / (tp + fn)
+
+
+def true_negative_rate(y_pred: np.ndarray, y: np.ndarray) -> float:
+    """
+    Computes the true negative rate (also called specificity).
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted labels.
+    y : `numpy.ndarray`
+        Ground truth labels.
+
+    Returns
+    -------
+    `float`
+        True negative rate.
+    """
+    if not isinstance(y_pred, np.ndarray):
+        raise TypeError("'y_pred' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y_pred)}'")
+    if not isinstance(y, np.ndarray):
+        raise TypeError("'y' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y)}'")
+    if y_pred.shape != y.shape:
+        raise ValueError(f"Shape mismatch: {y_pred.shape} vs. {y.shape}")
+    if len(y_pred.shape) > 1:
+        raise ValueError("'y_pred' must be a 1d array")
+    if len(y.shape) > 1:
+        raise ValueError("'y' must be a 1d array")
+    if set(np.unique(y_pred)) != set([0, 1]):
+        raise ValueError("Labels must be either '0' or '1'")
+
+    tn = np.sum((y == 0) & (y_pred == 0))
+    fp = np.sum((y == 0) & (y_pred == 1))
+
+    return tn / (tn + fp)
+
+
+def precision_score(y_pred: np.ndarray, y: np.ndarray) -> float:
+    """
+    Computes the precision of a classification.
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted labels.
+    y : `numpy.ndarray`
+        Ground truth labels.
+
+    Returns
+    -------
+    `float`
+        Precision score.
+    """
+    if not isinstance(y_pred, np.ndarray):
+        raise TypeError("'y_pred' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y_pred)}'")
+    if not isinstance(y, np.ndarray):
+        raise TypeError("'y' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y)}'")
+    if y_pred.shape != y.shape:
+        raise ValueError(f"Shape mismatch: {y_pred.shape} vs. {y.shape}")
+    if set(np.unique(y_pred)) != set([0, 1]):
+        raise ValueError("Labels must be either '0' or '1'")
+
+    tp = np.sum([np.all((y[i] == 1) & (y_pred[i] == 1)) for i in range(len(y))])
+    fp = np.sum([np.any((y[i] == 0) & (y_pred[i] == 1)) for i in range(len(y))])
+
+    return tp / (tp + fp)
+
+
+def accuracy_score(y_pred: np.ndarray, y: np.ndarray) -> float:
+    """
+    Computes the accuracy of a classification.
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted labels.
+    y : `numpy.ndarray`
+        Ground truth labels.
+
+    Returns
+    -------
+    `float`
+        Accuracy score.
+    """
+    if not isinstance(y_pred, np.ndarray):
+        raise TypeError("'y_pred' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y_pred)}'")
+    if not isinstance(y, np.ndarray):
+        raise TypeError("'y' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y)}'")
+    if y_pred.shape != y.shape:
+        raise ValueError(f"Shape mismatch: {y_pred.shape} vs. {y.shape}")
+
+    tp = np.sum([np.all(y[i] == y_pred[i]) for i in range(len(y))])
+    return tp / len(y)
+
+
+def f1_score(y_pred: np.ndarray, y: np.ndarray) -> float:
+    """
+    Computes the F1-score for a binary classification.
+
+    Parameters
+    ----------
+    y_pred : `numpy.ndarray`
+        Predicted labels.
+    y : `numpy.ndarray`
+        Ground truth labels.
+
+    Returns
+    -------
+    `float`
+        F1-score.
+    """
+    if not isinstance(y_pred, np.ndarray):
+        raise TypeError("'y_pred' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y_pred)}'")
+    if not isinstance(y, np.ndarray):
+        raise TypeError("'y' must be an instance of 'numpy.ndarray' " +
+                        f"but not of '{type(y)}'")
+    if y_pred.shape != y.shape:
+        raise ValueError(f"Shape mismatch: {y_pred.shape} vs. {y.shape}")
+    if len(y_pred.shape) != 1:
+        raise ValueError("'y_pred' must be a 1d array")
+    if len(y.shape) != 1:
+        raise ValueError("'y' must be a 1d array")
+    if set(np.unique(y_pred)) != set([0, 1]):
+        raise ValueError("Labels must be either '0' or '1'")
+
+    tp = np.sum((y == 1) & (y_pred == 1))
+    fp = np.sum((y == 0) & (y_pred == 1))
+    fn = np.sum((y == 1) & (y_pred == 0))
+
+    return (2. * tp) / (2. * tp + fp + fn)

epyt_flow/models/__init__.py

@@ -0,0 +1,2 @@
+from .event_detector import *
+from .sensor_interpolation_detector import *

epyt_flow/models/event_detector.py

@@ -0,0 +1,31 @@
+"""
+Module provides a base class for event detectors.
+"""
+from abc import abstractmethod, ABC
+
+from ..simulation.scada import ScadaData
+
+
+class EventDetector(ABC):
+    """
+    Base class for event detectors.
+    """
+    def __init__(self, **kwds):
+        super().__init__(**kwds)
+
+    @abstractmethod
+    def apply(self, scada_data: ScadaData) -> list[int]:
+        """
+        Applies this detector to given SCADA data and returns suspicious time points.
+
+        Parameters
+        ----------
+        scada_data : :class:`~epyt_flow.simulation.scada.scada_data.ScadaData`
+            SCADA data in which to look for events (i.e. anomalies).
+
+        Returns
+        -------
+        `list[int]`
+            List of suspicious time points.
+        """
+        raise NotImplementedError()

epyt_flow/models/sensor_interpolation_detector.py

@@ -0,0 +1,118 @@
+"""
+Module provides a simple residual-based event detector that performs sensor interpolation.
+"""
+from typing import Any, Union
+from copy import deepcopy
+import numpy as np
+from sklearn.linear_model import LinearRegression
+
+from .event_detector import EventDetector
+from ..simulation.scada import ScadaData
+
+
+class SensorInterpolationDetector(EventDetector):
+    """
+    Class implementing a residual-based event detector based on sensor interpolation.
+
+    Parameters
+    ----------
+    regressor_type : `Any`, optional
+        Regressor class that will be used for the sensor interpolation.
+        Must implement the usual `fit` and `predict` functions.
+
+        The default is `sklearn.linear_model.LinearRegression`
+    """
+    def __init__(self, regressor_type: Any = LinearRegression, **kwds):
+        self.__regressor_type = regressor_type
+        self.__regressors = []
+
+        super().__init__(**kwds)
+
+    @property
+    def regressor_type(self) -> Any:
+        """
+        Gets the class used for building the regressors in the sensor interpolation.
+
+        Returns
+        -------
+        `Any`
+            Regressor class.
+        """
+        return self.__regressor_type
+
+    @property
+    def regressors(self) -> list[Any]:
+        """
+        Gets the fitted sensor interpolation regressors.
+
+        Returns
+        -------
+        `list[Any]`
+            Fitted regressors.
+        """
+        return deepcopy(self.__regressors)
+
+    def __eq__(self, other) -> bool:
+        return self.__regressor_type == other.regressor_type and \
+            all(self.__regressors == other.regressors)
+
+    def fit(self, scada_data: Union[ScadaData, np.ndarray]) -> None:
+        """
+        Fit detector to given SCADA data -- assuming the given data represents
+        the normal operating state.
+
+        Parameters
+        ----------
+        scada_data : :class:`~epyt_flow.simulation.scada.scada_data.ScadaData` or `numpy.ndarray`
+            SCADA data to fit this detector.
+        """
+        if isinstance(scada_data, ScadaData):
+            data = scada_data.get_data()
+        else:
+            data = scada_data
+
+        self.__regressors = []
+        for output_idx in range(data.shape[1]):
+            input_idx = list(range(data.shape[1]))
+            input_idx.remove(output_idx)
+
+            X = data[:, input_idx]
+            y = data[:, output_idx]
+
+            model = self.__regressor_type()
+            model.fit(X, y)
+
+            y_pred = model.predict(X)
+            threshold = 1.2 * np.max(np.abs(y_pred - y))
+
+            self.__regressors.append((input_idx, output_idx, model, threshold))
+
+    def apply(self, scada_data: Union[ScadaData, np.ndarray]) -> list[int]:
+        """
+        Applies this detector to given SCADA data and returns suspicious time points.
+
+        Parameters
+        ----------
+        scada_data : :class:`~epyt_flow.simulation.scada.scada_data.ScadaData` or `numpy.ndarray`
+            SCADA data in which to look for events/anomalies.
+
+        Returns
+        -------
+        `list[int]`
+            List of suspicious time points.
+        """
+        suspicious_time_points = []
+
+        if isinstance(scada_data, ScadaData):
+            X = scada_data.get_data()
+        else:
+            X = scada_data
+
+        for input_idx, output_idx, model, threshold in self.__regressors:
+            y_pred = model.predict(X[:, input_idx])
+            y = X[:, output_idx]
+
+            suspicious_time_points += list(np.argwhere(np.abs(y_pred - y) > threshold).
+                                           flatten())
+
+        return list(set(suspicious_time_points))