doc/source/od/methods/llr.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[source](../../api/alibi_detect.od.llr.rst)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Likelihood Ratios for Outlier Detection"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview\n",
    "\n",
    "The outlier detector described by [Ren et al. (2019)](https://arxiv.org/abs/1906.02845) in [Likelihood Ratios for Out-of-Distribution Detection](https://arxiv.org/abs/1906.02845) uses the likelihood ratio (LLR) between 2 generative models as the outlier score. One model is trained on the original data while the other is trained on a perturbed version of the dataset. This is based on the observation that the log likelihood for an instance under a generative model can be heavily affected by population level background statistics. The second generative model is therefore trained to capture the background statistics still present in the perturbed data while the semantic features have been erased by the perturbations.\n",
    "\n",
    "The perturbations are added using an independent and identical Bernoulli distribution with rate $\\mu$ which substitutes a feature with one of the other possible feature values with equal probability. For images, this means for instance changing a pixel with a different pixel value randomly sampled within the $0$ to $255$ pixel range. The package also contains a [PixelCNN++](https://arxiv.org/abs/1701.05517) implementation adapted from the official TensorFlow Probability [version](https://www.tensorflow.org/probability/api_docs/python/tfp/distributions/PixelCNN), and available as a standalone model in `alibi_detect.models.tensorflow.pixelcnn`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Usage\n",
    "\n",
    "### Initialize\n",
    "\n",
    "Parameters:\n",
    "\n",
    "* `threshold`: outlier threshold value used for the negative likelihood ratio. Scores above the threshold are flagged as outliers.\n",
    "\n",
    "* `model`: a generative model, either as a `tf.keras.Model`, TensorFlow Probability distribution or built-in PixelCNN++ model.\n",
    "\n",
    "* `model_background`: optional separate model fit on the perturbed background data. If this is not specified, a copy of `model` will be used.\n",
    "\n",
    "* `log_prob`: if the model does not have a `log_prob` function like e.g. a TensorFlow Probability distribution, a function needs to be passed that evaluates the log likelihood.\n",
    "\n",
    "* `sequential`: flag whether the data is sequential or not. Used to create targets during training. Defaults to *False*.\n",
    "\n",
    "* `data_type`: can specify data type added to metadata. E.g. *'tabular'* or *'image'*.\n",
    "\n",
    "Initialized outlier detector example:\n",
    "\n",
    "```python\n",
    "from alibi_detect.od import LLR\n",
    "from alibi_detect.models.tensorflow import PixelCNN\n",
    "\n",
    "image_shape = (28, 28, 1)\n",
    "model = PixelCNN(image_shape)\n",
    "od = LLR(threshold=-100, model=model)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Fit\n",
    "\n",
    "We then need to train the 2 generative models in sequence. The following parameters can be specified:\n",
    "\n",
    "* `X`: training batch as a numpy array of preferably normal data.\n",
    "\n",
    "* `mutate_fn`: function used to create the perturbations. Defaults to an independent and identical Bernoulli distribution with rate $\\mu$ \n",
    "\n",
    "* `mutate_fn_kwargs`: kwargs for `mutate_fn`. For the default function, the mutation rate and feature range needs to be specified, e.g. *dict(rate=.2, feature_range=(0,255))*.\n",
    "\n",
    "* `loss_fn`: loss function used for the generative models.\n",
    "\n",
    "* `loss_fn_kwargs`: kwargs for the loss function.\n",
    "\n",
    "* `optimizer`: optimizer used for training. Defaults to [Adam](https://arxiv.org/abs/1412.6980) with learning rate 1e-3.\n",
    "\n",
    "* `epochs`: number of training epochs.\n",
    "\n",
    "* `batch_size`: batch size used during training.\n",
    "\n",
    "* `log_metric`: additional metrics whose progress will be displayed if verbose equals True.\n",
    "\n",
    "```python\n",
    "od.fit(X_train, epochs=10, batch_size=32)\n",
    "```\n",
    "\n",
    "It is often hard to find a good threshold value. If we have a batch of normal and outlier data and we know approximately the percentage of normal data in the batch, we can infer a suitable threshold:\n",
    "\n",
    "```python\n",
    "od.infer_threshold(X, threshold_perc=95, batch_size=32)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Detect\n",
    "\n",
    "We detect outliers by simply calling `predict` on a batch of instances `X`. Detection can be customized via the following parameters:\n",
    "\n",
    "* `outlier_type`: either *'instance'* or *'feature'*. If the outlier type equals *'instance'*, the outlier score at the instance level will be used to classify the instance as an outlier or not. If *'feature'* is selected, outlier detection happens at the feature level (e.g. by pixel in images).\n",
    "\n",
    "* `batch_size`: batch size used for model prediction calls.\n",
    "\n",
    "* `return_feature_score`: boolean whether to return the feature level outlier scores.\n",
    "\n",
    "* `return_instance_score`: boolean whether to return the instance level outlier scores.\n",
    "\n",
    "The prediction takes the form of a dictionary with `meta` and `data` keys. `meta` contains the detector's metadata while `data` is also a dictionary which contains the actual predictions stored in the following keys:\n",
    "\n",
    "* `is_outlier`: boolean whether instances or features are above the threshold and therefore outliers. If `outlier_type` equals *'instance'*, then the array is of shape *(batch size,)*. If it equals *'feature'*, then the array is of shape *(batch size, instance shape)*.\n",
    "\n",
    "* `feature_score`: contains feature level scores if `return_feature_score` equals True.\n",
    "\n",
    "* `instance_score`: contains instance level scores if `return_instance_score` equals True.\n",
    "\n",
    "\n",
    "```python\n",
    "preds = od.predict(X, outlier_type='instance', batch_size=32)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Examples\n",
    "\n",
    "### Image\n",
    "\n",
    "[Likelihood Ratio Outlier Detection with PixelCNN++](../../examples/od_llr_mnist.ipynb)\n",
    "\n",
    "### Sequential Data\n",
    "\n",
    "[Likelihood Ratio Outlier Detection on Genomic Sequences](../../examples/od_llr_genome.ipynb)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}