templates/2_create_tiled_mibi_run.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Generate tiled region run file"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## NOTE: the functionality of this notebook has been ported over to TSAI (https://tsai.stanford.edu/research/mibi_tsai). $^1$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**NOTE**: Before running this notebook for the first time, make sure you've coregistered your instrument using the *update coregistration parameters* section of  `1_set_up_toffy.ipynb`. This will ensure your FOVs display correctly on the slide.\n",
    "\n",
    "### Background\n",
    "\n",
    "This notebook allows you to automatically set up large tiled runs of contiguous FOVs. You can specify the dimensions of the tiled image, for example 5x5, and select specific FOVs you wish to exclude from the final tile. To stitch these FOV images back into their tiled shape later, use the [Image Stitching notebook](https://github.com/angelolab/ark-analysis/blob/main/templates/Image_Stitching.ipynb) in the ark-analysis repo.\n",
    "\n",
    "The script expects that you have already generated and moved the necessary files into the appropriate directory before starting.\n",
    "\n",
    "- A JSON file defining the top-left corner of each region to tile. You can create this file by exporting the FOVs from the MIBIControl software. **Give each top-left corner FOV a descriptive name of the tiled region it defines.**\n",
    "- The optical image of your slide. This is automatically created when you load your slide, and is saved to the `D:\\\\Data\\\\optical-image` subfolder."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "from skimage.io import imread\n",
    "\n",
    "from toffy import json_utils, tiling_utils\n",
    "\n",
    "# suppress mpl deprecation\n",
    "import warnings\n",
    "from matplotlib.cbook import mplDeprecation\n",
    "warnings.filterwarnings(\"ignore\", category=mplDeprecation)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Define the data paths"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You will first need to define the prefix `tiled_region_prefix` to use for all of the files associated with this specific sample. The default is `'example_tiled_region'`, but you should change it to something relevant to your study, such as `'BRCA_SLIDE_1'`.\n",
    "\n",
    "Once you have picked your prefix for this specific sample, you'll need to ensure that all of the necessary files are in the appropriate directory with the correct names\n",
    "\n",
    "* `region_corners_path`: this file, which contains the top-left corner FOV of each tiled region, should be named `{tiled_region_prefix}_region_corners.json`.\n",
    "* `slide_path`: this file, which contains the image of your slide, should be named `{tiled_region_prefix}.bmp` or `{tiled_region_prefix}.jpg`. **This file can be found on the CAC at: <i>D:\\\\\\\\Data\\\\\\\\optical-image\\\\\\\\</i>**.\n",
    "\n",
    "Each of these files should be copied over to `C:\\\\Users\\\\Customer.ION\\\\Documents\\\\tiled_run_jsons`. More information on the uses and locations of the directories in toffy can be found in the <a href=\"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/angelolab/toffy#directory-structure\">README</a>."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# define the prefix for each file\n",
    "tiled_region_prefix = 'example_tiled_region'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# user created files\n",
    "tiled_regions_dir = os.path.join('C:\\\\Users\\\\Customer.ION\\\\Documents\\\\tiled_run_jsons')\n",
    "region_corners_path = os.path.join(tiled_regions_dir, '%s_region_corners.json' % tiled_region_prefix)\n",
    "\n",
    "# change slide_path_ext to '.jpg' if needed\n",
    "slide_path_ext = '.bmp'\n",
    "slide_path = os.path.join(tiled_regions_dir, tiled_region_prefix + slide_path_ext)\n",
    "\n",
    "# the final run file the notebook will generate\n",
    "tiled_region_path = os.path.join(tiled_regions_dir, \"%s_tiled_region_mapping.json\" % tiled_region_prefix)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "## 2. Generate the FOVs for each region"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This cell will prompt you to set the dimensions and randomization parameters of each tiled region. The parameters will be used to generate the FOVs over each tiled region."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# set the tiling parameters\n",
    "tiling_params = tiling_utils.set_tiled_region_params(region_corners_path)\n",
    "\n",
    "# generate the FOVs in each region using tiling_params\n",
    "tiled_region_fovs = tiling_utils.generate_tiled_region_fov_list(tiling_params)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Interactive FOV deselection"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The grid defining an ROI may cover more area than you wish to tile. This GUI allows you to interactively delete FOVs from *tiled_region_fovs* prior to saving:\n",
    "\n",
    "**NOTE: if you run the widget and do not need to run deselection, click <i>Save mapping</i> immediately to generate the final run file with all the FOVs generated.**\n",
    "\n",
    "1: Inspect using Zoom feature.\n",
    "\n",
    "<div>\n",
    "    <img src=\"img/tiled_region_zoom.gif\" width=\"300\" height=\"274\"/>\n",
    "</div>\n",
    "\n",
    "2: Propose/unpropose FOVs for removal by clicking. Click *Delete selected FOVs* to remove proposed FOVs. <b>This action cannot be undone!</b>\n",
    "\n",
    "<div>\n",
    "    <img src=\"img/tiled_region_selection.gif\" width=\"300\" height=\"274\"/>\n",
    "</div>\n",
    "\n",
    "3: You can always remove more FOVs even after saving. Just remember to re-save.\n",
    "\n",
    "4: After you're done, click *Save mapping*. The final run file will be saved to *tiled_region_path*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# read the slide image in\n",
    "slide_data = imread(slide_path)\n",
    "\n",
    "%matplotlib widget\n",
    "_ = tiling_utils.tiled_region_interactive_remap(\n",
    "    tiled_region_fovs,\n",
    "    tiling_params,\n",
    "    slide_data,\n",
    "    tiled_region_path,\n",
    "    figsize=(7, 7)\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Run JSON adjustment\n",
    "\n",
    "If you would like to break up your tiled file into smaller JSONs containing a specified amount of FOVs in each, you can do that using the code below. \n",
    "\n",
    "`file_split` is a list of values detailing how many FOVs to included in each new file, and must sum to the total number of FOVs in the run file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "file_split = []\n",
    "\n",
    "json_utils.split_run_file(tiled_regions_dir, os.path.basename(tiled_region_path), file_split)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$^1$ Piyadasa H, Oberlton B, and Kong A, et al. (2023). Rapid Setup of Tissue Microarray and Tiled Area Imaging on the Multiplexed Ion Beam Imaging Microscope using the Tile/SED/Array Interface. <i>J Vis Exp</i>, [OnlineFirst], https://www.jove.com/t/65615/rapid-setup-tissue-microarray-tiled-area-imaging-on-multiplexed-ion"
   ]
  }
 ],
 "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.8.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}