example_notebooks/0. Register And Save State.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "007bdd6f",
   "metadata": {},
   "source": [
    "# [Aligning Big Brains and Atlases](https://biop.github.io/ijp-imagetoatlas/) in Python\n",
    "\n",
    "This series of notebook demoes the use of [ABBA with python](https://github.com/BIOP/abba_python)\n",
    "\n",
    "For this notebook to work, you will as well need to:\n",
    "* set the elastix and transformix path for the elastix registration steps.\n",
    "* to have DeepSlice installed in a separate conda environment (pip installed deepslice) and set its path\n",
    "These path will be stored for any future abba instance created (stored in user Java prefs)\n",
    "\n",
    "By running this notebook, you will perform a fully automated registration of demo mouse brain sections to the Adult Mouse Allen Brain atlas.\n",
    "\n",
    "If this is the first, you will need an internet connection, as the atlas will be downloaded, as well as some sample dataset.\n",
    "\n",
    "The dataset is downloaded from https://zenodo.org/record/6592478\n",
    "\n",
    "Multichannel registration works reasonably well in this notebook because the first channel of the atlas (NISSL, indexed 0), is ressembling the DAPI channel of the slices (indexed 0), and the second channel of the atlas (ARA, indexed 1), is ressembling the autofluorescence channel of the slices (indexed 1)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5c4e9d2f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# core dependencies\n",
    "import os\n",
    "import time\n",
    "from pathlib import Path\n",
    "\n",
    "basePath = os.getcwd() + '/images/'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5c10bc71-99a0-44de-8c6a-f89e6e5e457b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# for testing in IDE - not required if you installed abba_python via pip!\n",
    "# os.chdir('../src')\n",
    "# os.getcwd()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "08a34e55-f2b5-402c-bdfe-305fd5bb9a87",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from abba_python import abba\n",
    "\n",
    "from bg_atlasapi import utils\n",
    "\n",
    "#from scijava_python_command.magic import cell_with_modal_ui"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3bd1e07a-a7c4-4a36-b095-c757de7024e8",
   "metadata": {},
   "source": [
    "## Download test sections if necessary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "86a102df",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Demo dataset for automated slices registration\n",
    "zenodo_demo_slices_url = 'https://zenodo.org/record/6592478/files/'\n",
    "\n",
    "\n",
    "# Only one section every five section is used for this demo\n",
    "demo_sections = [\n",
    "    'S00.tif',\n",
    "    'S05.tif',\n",
    "    'S10.tif',\n",
    "    'S15.tif',\n",
    "    'S20.tif',\n",
    "    'S25.tif',\n",
    "    'S30.tif',\n",
    "    'S35.tif',\n",
    "    'S40.tif',\n",
    "    'S45.tif',\n",
    "    'S50.tif',\n",
    "    'S55.tif',\n",
    "    'S60.tif',\n",
    "    'S65.tif',\n",
    "    'S70.tif',\n",
    "    'S75.tif',\n",
    "    'S80.tif']\n",
    "\n",
    "\n",
    "def download_if_necessary(base_path, section_name):\n",
    "    output_path = Path(base_path + section_name)\n",
    "    if not output_path.exists():\n",
    "        utils.check_internet_connection()\n",
    "        url = zenodo_demo_slices_url + section_name + '?download=1'\n",
    "        utils.retrieve_over_http(url, output_path)\n",
    "\n",
    "\n",
    "def download_test_images(base_path):\n",
    "    [download_if_necessary(base_path, section) for section in demo_sections]\n",
    "\n",
    "if not os.path.exists(basePath):\n",
    "    os.makedirs(basePath)\n",
    "    \n",
    "download_test_images(basePath)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "54979364",
   "metadata": {},
   "source": [
    "## ABBA initialization"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "98c03c88",
   "metadata": {
    "scrolled": true,
    "tags": []
   },
   "outputs": [],
   "source": [
    "headless = False\n",
    "from abba_python.abba import Abba\n",
    "\n",
    "# -- FOR DEBUGGING\n",
    "# import imagej.doctor\n",
    "# imagej.doctor.checkup()\n",
    "# imagej.doctor.debug_to_stderr()\n",
    "\n",
    "import logging\n",
    "# logging.basicConfig(level=logging.DEBUG)\n",
    "# logging.basicConfig(level=logging.WARN)\n",
    "\n",
    "if headless:\n",
    "    # -- HEADLESS\n",
    "    # create a thread: the jupyter UI will not be responsive is the cell is not finished. \n",
    "    # that's why it's needed to split the initialisation in two cells.\n",
    "    aligner = Abba('Adult Mouse Brain - Allen Brain Atlas V3p1', headless=True)\n",
    "    \n",
    "else:\n",
    "    # -- NOT HEADLESS\n",
    "    aligner = Abba('Adult Mouse Brain - Allen Brain Atlas V3p1')\n",
    "    aligner.show_bdv_ui()  # creates and show a bdv view\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "060995c5-48c1-403f-87c1-91d9ee7bfb6b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# (Optional cell) DO NOT MOVE THIS PIECE OF CODE HIGHER UP: Java needs to be initialised\n",
    "# Goal: make java less talkative\n",
    "from scyjava import jimport\n",
    "DebugTools = jimport('loci.common.DebugTools')\n",
    "DebugTools.enableLogging(\"DEBUG\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b1d5c61f-0d53-4c9b-abf4-31a5340ecacf",
   "metadata": {},
   "source": [
    "## Setup ABBA: elastix, transformix, and DeepSlice"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2f0ce139",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Optional: run this cell if you need to setup ABBA:\n",
    "# - set up elastix and transformix\n",
    "# - set up deepslice extra conda environment (required for this notebook)\n",
    "# - set up a different place to store the atlases\n",
    "if not headless:\n",
    "    # Maybe just run it once not in headless to set elastix and transformix path correctly. They will be remembered in headless mode (stored in java Prefs)\n",
    "    aligner.ij.command().run('ch.epfl.biop.wrappers.ij2command.BiopWrappersSet',True)\n",
    "    # Maybe just run it once not in headless to set the DeepSlice Conda env correctly\n",
    "    aligner.ij.command().run('ch.epfl.biop.wrappers.deepslice.ij2commands.DeepSlicePrefsSet',True)\n",
    "else:\n",
    "    pass\n",
    "    # If you want to set elastix and transformix Path without GUI, you can comment 'pass' and set the \n",
    "    # proper exe paths below:\n",
    "    aligner.set_deepslice_env('C:/Users/nico/.conda/envs/deep_slice', '1.1.5')\n",
    "    aligner.set_elastix_path('C:/elastix-5.0.1-win64/elastix.exe')\n",
    "    aligner.set_transformix_path('C:/elastix-5.0.1-win64/transformix.exe')\n",
    "    # aligner.set_atlas_cache_dir('path_to_cache_dir') # Uncomment if you want to change the default location for caching the atlases\n",
    "    \n",
    "aligner.print_config()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "358e4e2c",
   "metadata": {},
   "source": [
    "## 3. Import sections into ABBA"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5c444a91",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# NOTE! Remove the .bfmemo file in the images folder! (cf https://github.com/ome/bioformats/issues/3957)\n",
    "\n",
    "# import sections into ABBA\n",
    "files = [basePath + section for section in demo_sections]\n",
    "aligner.import_from_files(filepaths=files)\n",
    "\n",
    "# ALL REGISTRATIONS AND COMMANDS BELOW ARE PERFORMED ON THE SELECTED SLICES!!\n",
    "# since we want to register all of them, we select all of them\n",
    "# abba.select_all_slices()\n",
    "aligner.deselect_all_slices()\n",
    "# abba.select_slices([0]) # only one for testing\n",
    "# abba.select_all_slices()\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "96333598",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "aligner.select_all_slices()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "66f97d0a",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# we want to avoid saturation in the display. This does not matter for\n",
    "# all registration methods EXCEPT for DeepSlice, which takes in rgb images\n",
    "aligner.change_display_settings(0, 0, 500)\n",
    "aligner.change_display_settings(1, 0, 1200)\n",
    "\n",
    "if not headless:\n",
    "    # programmatic way to show (or hide) sections and channels\n",
    "    aligner.get_bdv_view().setSelectedSlicesVisibility(True)\n",
    "    aligner.get_bdv_view().setSelectedSlicesVisibility(0, True) # Channel 0\n",
    "    aligner.get_bdv_view().setSelectedSlicesVisibility(1, True) # Channel 1"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3964abcb",
   "metadata": {},
   "source": [
    "## 4. DeepSlice Registration(s)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e65db448",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# a first deepslice registration round : possible because it's the Allen CCF atlas, cut in coronal mode\n",
    "# what's assumed : the sections are already in the correct order\n",
    "aligner.register_slices_deepslice_local(channels='0,1',\n",
    "                                  ensemble=False,\n",
    "                                  model='mouse',\n",
    "                                  post_processing='Keep order + ensure regular spacing',\n",
    "                                  slices_spacing_micrometer=-1,      \n",
    "                                  allow_slicing_angle_change=True) # use run_mode='Web' if you are not headless and without a local deepslice env\n",
    "\n",
    "#allow_slicing_angle_change: bool,\n",
    "#                                        channels: str,\n",
    "#                                        ensemble: bool,\n",
    "#                                        model: str,\n",
    "#                                        post_processing: str,\n",
    "#                                        slices_spacing_micrometer: float\n",
    "\n",
    "# second deepslice registration: because the slices are resampled for the registration,\n",
    "# we usually get a slightly better positioning along z and cutting angle\n",
    "# also: it's fast, and the combination of two affine transforms is\n",
    "# an affine transform, so it's not like we are adding extra degrees of freedom\n",
    "# aligner.register_slices_deepslice(channels=[0, 1],\n",
    "#                                  maintain_slices_order = True, # the slices are already sorted: do not mess the order\n",
    "#                                  run_mode='local') # use run_mode='web' if you are not headless and without a local deepslice env"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "83b8f828",
   "metadata": {},
   "source": [
    "## 5. Elastix affine registration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4d364363",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "\n",
    "# a round of elastix registration, affine\n",
    "# the channel 0 of the dataset (DAPI) is registered with the Nissl Channel of the atlas (0)\n",
    "# and the channel 1 of the dataset (mainly autofluo) is registered with the autofluo channel of the atlas (1)\n",
    "# these two channels have equal weights in the registration process\n",
    "aligner.register_slices_elastix_affine(channels_slice_csv='0,1',\n",
    "                                    channels_atlas_csv='0,1',\n",
    "                                    pixel_size_micrometer=40)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee4cb12b",
   "metadata": {},
   "source": [
    "## 6. Elastix spline registration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f08093da",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# %%cell_with_modal_ui\n",
    "# optional: a round of elastix registration, spline\n",
    "# same channels as in the affine registration\n",
    "# 5 control points along x = very coarse spline (and thus maybe unnecessary)\n",
    "# abba.register_elastix_spline(\n",
    "#    nb_control_points=5,\n",
    "#    atlas_image_channels=[0, 1],\n",
    "#    slice_image_channels=[0, 1],\n",
    "#    pixel_size_micrometer=40).get()\n",
    "\n",
    "# a round of elastix registration, affine\n",
    "# same channels as in the affine registration \n",
    "# 16 control points = reasonable spline, which allows for local corrections, without deforming two much the section\n",
    "aligner.register_slices_elastix_spline(channels_slice_csv='0,1',\n",
    "                                    channels_atlas_csv='0,1',\n",
    "                                    nb_control_points_x=16,\n",
    "                                    pixel_size_micrometer=20)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "57c522c1",
   "metadata": {},
   "source": [
    "## 7. Wait for end of all registrations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9d4a3a3c",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# all tasks/registrations are enqueued and executed asynchronously\n",
    "# if you need to wait before saving, then wait for all tasks to be finished:\n",
    "aligner.wait_for_end_of_tasks()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b7508c96",
   "metadata": {},
   "source": [
    "## 8. Saving the result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "27e6a478",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# abba.set_slices_thickness_match_neighbors() # not critical, but for 3d reconstruction it will allow for each slice to occupy the place available between its neighbors\n",
    "\n",
    "save_dir = os.path.join(os.getcwd(), 'temp', 'notebook0', 'state')\n",
    "\n",
    "if not os.path.exists(save_dir):\n",
    "    os.makedirs(save_dir)\n",
    "\n",
    "\n",
    "aligner.state_save(save_dir+\"/state.abba\") # full absolute path needed, returns True if the process was successfull - it won't erase an existing file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bdb43d2f-6b9e-4eef-8700-72dd06111f0f",
   "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.8.17"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}