Tutorial_05_error_correction.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "4116b635",
   "metadata": {},
   "source": [
    "# Ermine Tutorial 05\n",
    "## Correct for static and dynamic errors\n",
    "\n",
    "by Sebastian Malkusch (c) 2021  \n",
    "malkusch@med.uni-frankfurt.de  \n",
    "Data Science| Klinische Pharmakologie  \n",
    "Institut für Klinische Pharmakologie  \n",
    "Goethe - Universität  \n",
    "Theodor-Stern-Kai 7  \n",
    "60590 Frankfurt am Main"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f6e94066",
   "metadata": {},
   "source": [
    "## Abstract\n",
    "In this tutorial, we cover static errors due to Endesfelder et al. (https://pubmed.ncbi.nlm.nih.gov/24522395/) and dynamic errors due to Savin and Doyle (https://pubmed.ncbi.nlm.nih.gov/15533928/) that occur when measuring molecular jumps in single-particle tracking experiments."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "89ac89dc",
   "metadata": {},
   "source": [
    "## Prerequisite\n",
    "Nothing"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0f5e3d9d",
   "metadata": {},
   "source": [
    "## Import libraries\n",
    "You need to install Ermine prior to usage.  \n",
    "Run  \n",
    "python -m pip install pyErmine  \n",
    "from the command line "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "827c7ddf",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pandas as pd\n",
    "import seaborn as sns\n",
    "import ermine as em"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d8732eed",
   "metadata": {},
   "source": [
    "## Define experimental parameters\n",
    "* define mobility modes for the model: priorModel_components  \n",
    "* define time interval between two measurements : $\\tau$\n",
    "* define the time interval of a single measurement: $\\sigma$\n",
    "* define degrees of freedom for translational movement: dof\n",
    "* define apparent extected mean squared displacements: $\\mu_\\text{apparent}$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "0ab0ccf7",
   "metadata": {},
   "outputs": [],
   "source": [
    "model_components = 3\n",
    "tau = 0.02\n",
    "sigma = tau \n",
    "dof = 4\n",
    "mu_apparent = np.array([[1306.66666667], [3866.66666667], [9466.66666667]])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a3adfe1",
   "metadata": {},
   "source": [
    "## Apparent diffusion coefficient\n",
    "According to Einstein, the diffusion coefficient for an error-free measurement is calculated as follows: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "5c70ae8d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 16333.33333337],\n",
       "       [ 48333.33333337],\n",
       "       [118333.33333338]])"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "D_apparent = mu_apparent / (dof * tau)\n",
    "D_apparent"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84e04bb9",
   "metadata": {},
   "source": [
    "## Static error\n",
    "Let's assume, that the first mobile mode with $\\mu_\\text{apparent} = 1307 \\mu m^{2}$ is immobile. In this case, the measured displacement results from the fact that the position of a fixed molecule was repeatedly measured with errors. The measured displacement in this case is therefore the static measurement error or, more precisely, the localization accuracy $\\epsilon$. It can be accessed by analysing the apparent extected mean squared displacement measured for the immobile mode using NeNA (https://pubmed.ncbi.nlm.nih.gov/24522395/):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "0bfb59ce",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The localization precision by NeNa is 18.07 nm.\n"
     ]
    }
   ],
   "source": [
    "epsilon = em.postprocessing.static_error(apparent_msd_d0 = mu_apparent[0], dof = dof)\n",
    "print(str(\"The localization precision by NeNa is %.2f nm.\" %(epsilon)))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8aa7f87d",
   "metadata": {},
   "source": [
    "## Dynamic error\n",
    "The position of a molecule is determined by the measured photon distribution. The photons are measured over a period of time $\\sigma$. Within this period of time, however, the molecule does not stand still, but moves. Accordingly, the determined position of a molecule is an averaged position of all positions that the molecule has taken over the period of $\\sigma$. Dies führt zu einem zusätzlichen Fehler für den korrigiert werden muss (https://pubmed.ncbi.nlm.nih.gov/15533928/):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "475cf7c9",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[     0.],\n",
       "       [ 48000.],\n",
       "       [153000.]])"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "D_corrected = em.postprocessing.calculate_diffusion_coefficient(expected_value = mu_apparent,\n",
    "                                                                tau = tau,\n",
    "                                                                dof =dof ,\n",
    "                                                                sigma = tau,\n",
    "                                                                epsilon = epsilon)\n",
    "D_corrected"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e94ab75f",
   "metadata": {},
   "source": [
    "## Re-estimating apparent ecpected values for the MSD\n",
    "Conversely, ermine also allows the determination of the expected apparent MSD values for a given diffuson coefficient:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "8da25262",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[1306.66666667],\n",
       "       [3866.66666667],\n",
       "       [9466.66666667]])"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mu_apparent_estimated = em.postprocessing.calculate_expectation_value(diff_coeff = D_corrected,\n",
    "                                                                      tau = tau,\n",
    "                                                                      dof = dof, \n",
    "                                                                      sigma = tau,\n",
    "                                                                      epsilon = epsilon)\n",
    "mu_apparent_estimated"
   ]
  }
 ],
 "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.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}