GPyTool.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "be7b45ae-6bc8-44eb-b3e0-1e0e64507149",
   "metadata": {},
   "source": [
    "GPyTool is the Python implementation of GP-FBM (Gaussian Process - Fractionnal Brownian Motion), a Bayesian framework developed to estimate the diffusive properties of a stochastic time trajectory.\n",
    "By estimating the correlation between two trajectories, it can also correct each individual trajectory for the substrate motion, inducing effective correlations between these two trajectories.\n",
    "GP-FBM was originally implemented through a C++ user-friendly interface, called GPTool, which also incorporates image processing tools (channels alignment, spot localization enhancement).\n",
    "This Python version incorporates the GP-FBM framework alone (no image processing tool); but 3D time trajectories (TXYZ) are now handled.\n",
    "GPyTool can be used to process single trajectories individually or with the substrate correction.\n",
    "\n",
    "Original GP-FBM study: Oliveira, G.M., Oravecz, A., Kobi, D. et al. Precise measurements of chromatin diffusion dynamics by modeling using Gaussian processes. Nat Commun 12, 6184 (2021).\n",
    "                       https://doi.org/10.1038/s41467-021-26466-7"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1d1e332-2154-448a-9b61-6f4fc2c31113",
   "metadata": {},
   "source": [
    "Start by loading the following modules."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "b2cf253a-a418-4018-bb19-3f93c4bf7a96",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pandas as pd\n",
    "import matplotlib.pyplot as plt\n",
    "from scipy.optimize import minimize\n",
    "from pathlib import Path\n",
    "import tkinter\n",
    "from tkinter.filedialog import asksaveasfile, askopenfilenames\n",
    "import re\n",
    "import ntpath\n",
    "import os.path\n",
    "from matplotlib import colors\n",
    "import time\n",
    "import json\n",
    "from GPyTool_functions import *"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "05ddfeb6-86ac-47c2-964a-830958daf1ef",
   "metadata": {},
   "source": [
    "The file GPyTool_functions.py needs to be located in the same folder as the current file GPyTool.ipynb"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "37db1b59-7ebd-4ee0-846b-31b656517dfb",
   "metadata": {},
   "source": [
    "Set the time and spatial calibrations (physical size of a pixel in µm - calib_px) and (delay between two consecutive frames in seconds - calib_fr). The diffusion coefficient is directly linked to these calibrations (not the alpha anomalous exponent)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "87cf174f-fe60-4080-94c7-a9c7da3c8a0e",
   "metadata": {},
   "outputs": [],
   "source": [
    "calib_px = 0.11 #1 px = 0.11 µm\n",
    "calib_fr = 0.5 #1 frame = 0.5 s"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6163214d-28c9-4c55-9a6e-2f91f3611568",
   "metadata": {},
   "source": [
    "The following part is used to process couple trajectories, with subtrate correction. Skip it if you want to process individually the trajectories (no substrate correction).\n",
    "The script first asks you to select a CSV file containing the names of the trajectory files (for example '260523_C36_tracer_1_SCR_CH1.xml'), two columns format; the header of this CSV file is 'traj_1,traj_2'.\n",
    "Each row corresponds to a run of GPyTool between the two trajectories mentionned in the two columns. For example, the row '260523_C36_tracer_1_SCR_CH1.xml' and '260523_C36_tracer_1_Sox2_CH1.xml' will analyze these two trajectories together, with substrate correction. the trajectories are expected to be CSV files (TXY or TXYZ formats) or XML (parsing from Icy software after tracking analysis) and they need to be located in the same folder as the CSV list file. After selecting the CSV file containing all the couples trajectories, the analysis starts. After each iteration of the script, a json file with the processed trajectories is saved in the same folder as the previous CSV file, with name 'results_XXXXXXXXX.json', where 'XXXXXXX' is a random number (used to avoid erasing previous results from previous analysis). At the end of the script, you get 'Done!'. During the process, some error message 'RuntimeWarning' can appear, but they do not perturb the analysis: they come from the minimization of a cost function. The final json file contains all the couple trajectories results: for each couple, the names of the two trajectories are saved, their anomalous exponents and diffusion coefficients with susbtrate correction, the alpha and D from the substrate itself and the estimated trajectory of the substrate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "54805627-1fa3-4d45-a5fc-6e5d38a3e8d1",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1/3\n",
      "2/3\n",
      "3/3\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "C:\\Users\\Bastien\\Documents\\postdoc_IGBMC\\GitHub_GPyTool\\GPyTool_v290923\\GPyTool_functions.py:159: RuntimeWarning: divide by zero encountered in power\n",
      "  fbm_kernel = D*(mat_t**alpha+mat_t.T**alpha-np.abs(mat_t-mat_t.T)**alpha)\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Done!\n"
     ]
    }
   ],
   "source": [
    "results_json = gpytool_couple(calib_px, calib_fr)\n",
    "print('Done!')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ab5752de-2f41-466e-90d0-d7f1bed63e9a",
   "metadata": {
    "tags": []
   },
   "source": [
    "The following part should be used to process each trajectory individually (no substrate correction). The output is a CSV file with the following structure:\n",
    "\n",
    "trajectory name (traj_ID), alpha exponent, diffusion coefficient (in µm²/s**alpha)\n",
    "\n",
    "Just select the trajectories (csv or xml; xml parsing from Icy software after tracking analysis) and fill the name of the CSV results file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "1cbed9b6-10e2-40ba-b29a-65c172dde2cb",
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1 / 5\n",
      "2 / 5\n",
      "3 / 5\n",
      "4 / 5\n",
      "5 / 5\n",
      "Done!\n"
     ]
    }
   ],
   "source": [
    "results_csv = gpytool(calib_px, calib_fr)\n",
    "print('Done!')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "892e4b12-f47a-443d-8638-695e170dcbe4",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.11.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}