notebooks/Custom-models.ipynb

{
 "cells": [
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "# Custom models\n",
    "\n",
    "Even though ``dtaianomaly`` already offers a lot of functionality, there is always room\n",
    "for more enhancements. ``dtaianomaly`` is designed with flexibility in mind: it is\n",
    "extremely easy to integrate a new component in ``dtaianomaly``. These new components\n",
    "can be either existing methods that haven't been implemented yet, or new state-of-the-art\n",
    "time series anomaly detection methods. By implementing your new component in ``dtaianomaly``, y\n",
    "ou can seamlessly use the existing tools - such as the ``Pipepline`` and ``Workflow`` - as if it were a native part of ``dtaianomaly``. \n",
    "\n",
    "Below, we illustrate how you can implement your own (1) anomaly detector, (2) dataloader, (3) preprocessor, (4) thresholding, and (5) evaluation metric."
   ],
   "id": "51368cba1da81e2"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-10-03T09:31:02.212253Z",
     "start_time": "2024-10-03T09:31:01.928054Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import numpy as np\n",
    "import pandas as pd\n",
    "from typing import Optional, Tuple"
   ],
   "id": "bdfe9c5ba7d9a287",
   "outputs": [],
   "execution_count": 1
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Custom anomaly detector\n",
    "\n",
    "The core functionality of ``dtaianomaly`` - time series anomaly detection - is extended by implementing the ``BaseDetector``. To achieve this, you need to implement the ``fit()`` and ``decision_function()`` methods. Below, we implement an anomaly detector that detects anomalies when the distance between an observation and the mean value exceeds a specified number of standard deviations (also known as the [3-$\\sigma$ rule](https://en.wikipedia.org/wiki/68%E2%80%9395%E2%80%9399.7_rule). The methods have the following functionality:\n",
    "\n",
    "1. ``fit()``: learn the mean and standard deviation of the training data. These values are stored in the attributes ``mean_`` and ``std_``. \n",
    "2. ``decision_function()``: compute the values that have distance larger than ``nb_sigmas`` times the learned standard deviation from the learned mean. These values are considered anomalies. "
   ],
   "id": "eb1336812ba74b30"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-10-03T09:31:03.954716Z",
     "start_time": "2024-10-03T09:31:02.212253Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from dtaianomaly.anomaly_detection import BaseDetector\n",
    "\n",
    "class NbSigmaAnomalyDetector(BaseDetector):\n",
    "    nb_sigmas: float \n",
    "    mean_: float\n",
    "    std_: float\n",
    "    \n",
    "    def __init__(self, nb_sigmas: float = 3.0):\n",
    "        self.nb_sigmas = nb_sigmas\n",
    "\n",
    "    def fit(self, X: np.ndarray, y: Optional[np.ndarray] = None) -> 'NbSigmaAnomalyDetector':\n",
    "        \"\"\" Compute the mean and standard deviation of the given time series. \"\"\"\n",
    "        self.mean_ = X.mean()\n",
    "        self.std_ = X.std()\n",
    "        return self\n",
    "\n",
    "    def decision_function(self, X: np.ndarray) -> np.ndarray:\n",
    "        \"\"\" Compute which values are too far from the mean. \"\"\"\n",
    "        return np.abs(X - self.mean_) > self.nb_sigmas * self.std_"
   ],
   "id": "2f08afbdaaae181c",
   "outputs": [],
   "execution_count": 2
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Custom data loader\n",
    "\n",
    "Some dataloaders are provided within ``dtaianomaly``, but often we want to detect anomalies in our own data. Typically, for such custom data, there is no dataloader available within ``dtaianomaly``. To address this, you can implement a new dataloader by extending the ``LazyDataLoader`` object, along with the ``_load`` method. Upon initialization of the custom data loader, a ``path`` parameter is required, which points to the location of the data. Optionally, you can pass a ``do_caching`` parameter to prevent reading big files multiple times. The ``_load`` function will effectively load this dataset and return a ``DataSet`` object, which combines the data ``X`` and ground truth labels ``y``. The ``load`` function will either load the data or return a cached version of the data, depending on the ``do_caching`` property.\n",
    "\n",
    "Implementing a custom dataloader is especially useful for quantitatively evaluating the anomaly detectors on your own data, as you can pass the loader to a ``Workflow`` and easily analyze multiple detectors simultaneously. "
   ],
   "id": "ff9ec6a88b2fd86f"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-10-03T09:31:03.964904Z",
     "start_time": "2024-10-03T09:31:03.955883Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from dtaianomaly.data import LazyDataLoader, DataSet\n",
    "\n",
    "class SimpleDataLoader(LazyDataLoader):\n",
    "        \n",
    "    def _load(self)-> DataSet:\n",
    "        \"\"\" Read a data frame with the data in column 'X' and the labels in column 'y'. \"\"\"\n",
    "        df = pd.read_csv(self.path)\n",
    "        return DataSet(df['X'].values, df['y'].values)"
   ],
   "id": "798a876f13a67410",
   "outputs": [],
   "execution_count": 3
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Custom preprocessor\n",
    "\n",
    "The preprocessors will perform some processing on the time series, after which the transformed time series can be used for anomaly detection. Below, we implement a custom preprocessor by extending the ``Preprocessor`` class. Our preprocessor replaces all missing values (i.e., the NaN values) with the mean of the training data. Specifically, we need to implement following methods:\n",
    "\n",
    "1. ``_fit()``: learns the mean value of the given time series and stores it as the ``fill_value_`` attribute. \n",
    "2. ``_transform()``: fills in all missing values with the given time series by the learned mean value. This method returns both a transformed ``X`` and ``y``, because some preprocessors also change the labels ``y`` (for example, the ``SamplingRateUnderSampler``).\n",
    "\n",
    "Notice that we implement the ``_fit()`` and ``_transform()`` methods (with a starting underscore), while we can call the ``fit()`` and ``transform()`` methods (without the underscore) on an instance of our ``Imputer``. This is because the public methods will first check if the input is valid using the ``check_preprocessing_inputs`` method, and only then call the protected methods with starting underscores, ensuring that valid data is passed to these methods."
   ],
   "id": "19c4e1df0eb8bec8"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-10-03T09:31:03.975053Z",
     "start_time": "2024-10-03T09:31:03.964904Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from dtaianomaly.preprocessing import Preprocessor\n",
    "\n",
    "class Imputer(Preprocessor):\n",
    "    fill_value_: float\n",
    "    \n",
    "    def _fit(self, X: np.ndarray, y: Optional[np.ndarray] = None) -> 'Preprocessor':\n",
    "        \"\"\" Learn the mean value of the given dataset. \"\"\"\n",
    "        self.fill_value_ = X.mean()\n",
    "        return self\n",
    "\n",
    "    def _transform(self, X: np.ndarray, y: Optional[np.ndarray] = None) -> Tuple[np.ndarray, Optional[np.ndarray]]:\n",
    "        \"\"\" Replace all nan-values with the learned value. \"\"\"\n",
    "        X[np.isnan(X)] = self.fill_value_\n",
    "        return X, y"
   ],
   "id": "ce8d45209573ce41",
   "outputs": [],
   "execution_count": 4
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Custom Thresholding\n",
    "\n",
    "Many anomaly detectors compute continuous anomaly scores (\"how *anomalous* is the sample?), while many practical applications prefer binary labels (\"is the sample *an anomaly*?\"). Converting the continuous scores to binary labels can be done via thresholding. The most common thresholding strategies have already been implemented in ``dtaianomaly``, but is possible to add a new thresholding technique, as we do below. For this, we extend the ``Thresholding`` object and implement the ``threshold`` method. Our custom thresholding technique sets a dynamic threshold, such that observations with an anomaly score larger than a specified number of standard deviations above the mean anomaly score are considered anomalous. "
   ],
   "id": "7655229d0eb5949a"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-10-03T09:31:03.984591Z",
     "start_time": "2024-10-03T09:31:03.975053Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from dtaianomaly.thresholding import Thresholding\n",
    "\n",
    "class DynamicThreshold(Thresholding):\n",
    "    nb_sigmas: float\n",
    "    \n",
    "    def __init__(self, nb_sigmas: float):\n",
    "        self.nb_sigmas = nb_sigmas\n",
    "        \n",
    "    def threshold(self, scores: np.ndarray) -> np.ndarray:\n",
    "        threshold = scores.mean() + self.nb_sigmas * scores.std()\n",
    "        return scores > threshold"
   ],
   "id": "6f24df09f19e7cbf",
   "outputs": [],
   "execution_count": 5
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Custom evaluation\n",
    "\n",
    "Various performance metrics exist to evaluate an anomaly detector. There are two types of metrics in ``dtaianomaly``:\n",
    "\n",
    "1. ``BinaryMetric``]: the provided anomaly scores must be binary anomaly labels. An example of such metric is the precision.\n",
    "2. ``ProbaMetric``: the provided anomaly scores are expected to be continuous scores. An example of such metric is the area under the ROC curve (AUC-ROC).\n",
    "\n",
    "Custom evaluation metrics can be implemented in ``dtaianomaly``. Below, we implement accuracy by extending the ``BinaryMetric`` class (since accuracy requires binary labels) and implementing the ``_compute()`` method. Similar to the custom preprocessor above, we implement the ``_compute()`` method with starting underscore, while we call the ``compute()`` method to measure the metric. This is because the public ``compute()`` method performs checks on the input, ensuring that valid data is passed to the ``_compute()`` method. \n",
    "\n",
    "> :warning: Anomaly detection is typically a highly unbalanced problem: anomalies are, by definition, rare. Therefore, it is not recommended to use accuracy for evaluation (time series) anomaly detection!"
   ],
   "id": "9ade228d8751752f"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-10-03T09:31:03.994702Z",
     "start_time": "2024-10-03T09:31:03.984591Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from dtaianomaly.evaluation import BinaryMetric\n",
    "\n",
    "class Accuracy(BinaryMetric):\n",
    "\n",
    "    def _compute(self, y_true: np.ndarray, y_pred: np.ndarray):\n",
    "        \"\"\" Compute the accuracy. \"\"\"\n",
    "        return np.nanmean(y_true == y_pred)"
   ],
   "id": "a6cc0b8ad760147f",
   "outputs": [],
   "execution_count": 6
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}