tutorials/3-advanced-topics/DTAT385_statistics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# deeptrack.statistics\n",
    "\n",
    "<a href=\"https://colab.research.google.com/github/DeepTrackAI/DeepTrack2/blob/develop/tutorials/3-advanced-topics/DTAT385_statistics.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# !pip install deeptrack  # Uncomment if running on Colab/Kaggle."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This advanced tutorial introduces the module deeptrack.statistics."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from deeptrack import statistics"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. What is the `statistics` module?\n",
    "\n",
    "The `statistics` module provides a set of features that perform statistical operations on input data to reduce its dimensionality. These operations include common tasks like summing, averaging, and calculating standard deviations along specified axes. The module is built around NumPy functions, so it offers familiar syntax and behavior for users. Additionally, it supports a `distributed` option, which determines whether each image in\n",
    "the input list should be handled individually or not."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. The `Reducer` class\n",
    "\n",
    "The `Reducer` class is the base class for features that reduce the input dimensionality using a statistical function. This class handles most of the core logic for the operations in the statistics module, including specifying the function (e.g., sum, mean) and the axis along which to reduce. Users typically won't interact with `Reducer` directly but will instead use its subclasses (e.g., `Sum`, `Mean`, `Std`) that provide the specific statistical function to apply."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Statistical Operations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "###  Sum\n",
    "\n",
    "The `Sum` operation calculates the sum of the input values along the specified axis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[array([1., 1.]), array([0., 0.])]\n"
     ]
    }
   ],
   "source": [
    "# Example data.\n",
    "\n",
    "input_values = [np.ones((2,)), np.zeros((2,))]\n",
    "\n",
    "print(input_values)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[2.0, 0.0]\n"
     ]
    }
   ],
   "source": [
    "sum_operation = statistics.Sum(axis=0, distributed=True)\n",
    "\n",
    "sum_result = sum_operation(input_values)\n",
    "\n",
    "print(sum_result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Above, the sum operation is performed along axis 0, with `distributed`=True, meaning the input arrays are processed individually. \n",
    "By setting `distributed`=False, the inputs are handled together, instead of individually:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1. 1.]\n"
     ]
    }
   ],
   "source": [
    "sum_operation = statistics.Sum(axis=0, distributed=False)\n",
    "\n",
    "sum_result = sum_operation(input_values)\n",
    "\n",
    "print(sum_result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "###  Product\n",
    "\n",
    "The `Prod` operation calculates the product of the input values along the specified axis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1.0, 0.0]\n"
     ]
    }
   ],
   "source": [
    "prod_operation = statistics.Prod(axis=0, distributed=True)\n",
    "\n",
    "prod_result = prod_operation(input_values)\n",
    "\n",
    "print(prod_result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Other operations\n",
    "\n",
    "Other statistical operations in the module include:\n",
    "\n",
    "`Mean`: Computes the arithmetic mean along the specified axis.\n",
    "\n",
    "`Median`: Computes the median along the specified axis.\n",
    "\n",
    "`Std`: Computes the standard deviation along the specified axis.\n",
    "\n",
    "`Variance`: Computes the variance along the specified axis.\n",
    "\n",
    "`Cumsum`: Computes the cumulative sum along the specified axis.\n",
    "\n",
    "`Min/Max`: Computes the minimum/maximum values along the specified axis.\n",
    "\n",
    "`PeakToPeak`: Computes the range (max - min) along the specified axis.\n",
    "\n",
    "`Quantile`: Computes the q-th quantile along the specified axis.\n",
    "\n",
    "`Percentile`: Computes the q-th percentile along the specified axis."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Adding Reducers to the Pipeline\n",
    "\n",
    "Reducers, such as `Sum`, can be added to a pipeline in two different ways. Both methods allow the reducer to be applied to the output of a preceding feature or sequence of features.\n",
    "\n",
    "`summed_pipeline = some_pipeline_of_features >> Sum(axis=0)`\n",
    "\n",
    "`summed_pipeline = Sum(some_pipeline_of_features, axis=0)`\n",
    "\n",
    "However, combining these two methods is not supported and may lead to unpredictable behavior."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "py_env_book",
   "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.10.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}