MibiImage_Tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<h2>Introduction</h2>\n",
    "\n",
    "This notebook provides examples for working with MIBI data in the form of a MibiImage instance, which is a class in the `mibidata` module of the [mibilib](https://github.com/ionpath/mibilib/tree/master/mibidata) library. Complete documentation for the module is available [here](https://ionpath.github.io/mibilib/mibidata.html#module-mibidata)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib notebook\n",
    "%load_ext autoreload\n",
    "%autoreload 2\n",
    "\n",
    "import os\n",
    "\n",
    "import matplotlib\n",
    "import matplotlib.pyplot as plt\n",
    "from mpl_toolkits.axes_grid1 import make_axes_locatable\n",
    "import numpy as np\n",
    "from skimage import filters\n",
    "\n",
    "from mibidata.mibi_image import MibiImage\n",
    "from mibidata import color, tiff\n",
    "from mibitracker import request_helpers\n",
    "\n",
    "matplotlib.rcParams.update({\n",
    "    'font.size': 8,\n",
    "    'axes.grid': False,\n",
    "})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<h2>Creating a MibiImage Instance</h2>\n",
    "\n",
    "A MibiImage instance can be created with as little as a numpy array of count data and a list of channel names. Additional args in the constructor allow you to add relevant metadata, including run name and point name. For a full list of metadata args, see the [class documentation](https://ionpath.github.io/mibilib/mibidata.html#module-mibidata.mibi_image). Note that channels can be specified as either a list of integer masses, a list of string channel names, or a list of tuples of (integer mass, string channel name)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### From a numpy array"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create some random channel data. MIBI data is typically 16-bit uint, so\n",
    "# limit range to (0, 65535). Image size here is 128 x 128 pixels with 3\n",
    "# channels.\n",
    "random_channel_data = np.random.randint(0, 65535, (128, 128, 3), dtype=np.uint16)\n",
    "channels = ['Channel 1', 'Channel 2', 'Channel 3']\n",
    "random_mibi_image = MibiImage(\n",
    "    random_channel_data, channels,\n",
    "    run='Random Run', fov_name='Random Point Name')\n",
    "print(random_mibi_image)\n",
    "for key, val in random_mibi_image.metadata().items():\n",
    "    print(f'{key}: {val}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The most common and easiest way to import data into a MibiImage instance is to use the [mibidata.tiff.read](https://ionpath.github.io/mibilib/mibidata.html#module-mibidata.tiff) method. This method loads a Multiplexed MIBITIFF file that has been saved in the MIBITIFF format, which is the output of the IONpath TIFF Generator. In this case, all of the metadata is already saved with the image, and so the filename is the only parameter necessary."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### From a local file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "image = tiff.read('/path/to/mibi_tiff.tiff')\n",
    "image"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### From MIBItracker"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "# Load MIBItracker credentials from file.\n",
    "# For details about credentials, please review the 'MIBItracker_API_Tutorial.ipynb' notebook.\n",
    "from dotenv import load_dotenv\n",
    "fname_login = '/path/to/MIBItracker_login.dat'\n",
    "load_dotenv(fname_login)\n",
    "\n",
    "# This assumes your MIBItracker credentials are saved as environment variables.\n",
    "mr = request_helpers.MibiRequests(\n",
    "    os.getenv('MIBITRACKER_PUBLIC_URL'),\n",
    "    os.getenv('MIBITRACKER_PUBLIC_EMAIL'),\n",
    "    os.getenv('MIBITRACKER_PUBLIC_PASSWORD')\n",
    ")\n",
    "image_ids = (17, 26)\n",
    "images = []\n",
    "for image_id in image_ids:\n",
    "    im = mr.get_mibi_image(image_id)\n",
    "    images.append(im)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<h2>MibiImage Slicing</h2>\n",
    "\n",
    "Once loaded or created, the MibiImage class provides convenience methods for slicing, copying, and saving MIBI data. For example, we can select out certain channels of interest from the entire multiplexed image. An image can be sliced using a list of channel names either with the `slice_data` method or indexing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "image = images[0]\n",
    "image.channels"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data_of_interest = image['dsDNA', 'beta-tubulin', 'HLA class 1 A, B, and C', 'Na-K-ATPase alpha1']\n",
    "print(type(data_of_interest), np.shape(data_of_interest))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the channel masses are provided, they can also be used to slice the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "data_of_interest = image[89, 166, 160, 176]\n",
    "print(type(data_of_interest), np.shape(data_of_interest))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above commands that slice the data by index are equivalent to `MibiImage.slice_data()`.\n",
    "\n",
    "To create a new MibiImage instance from a subset of the channel, use `MibiImage.slice_image()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sub_image = image.slice_image(['dsDNA', 'beta-tubulin', 'HLA class 1 A, B, and C', 'Na-K-ATPase alpha1'])\n",
    "print(type(sub_image), np.shape(sub_image.data))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<h2>Image Visualization</h2>\n",
    "\n",
    "We can\n",
    "- slice out three channels for a simple RGB view\n",
    "- rotate that to CYM\n",
    "- use the `mibidata.color.composite` method to select a hue\n",
    "- use the `mibidata.color.composite` with up to 8 different colors"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(2, 2, figsize=(9.5, 8))\n",
    "\n",
    "rgb = image[['Keratin', 'dsDNA', 'CD45']]\n",
    "rgb = np.power(rgb / rgb.max(axis=(0, 1)), 1/2)\n",
    "ax[0, 0].imshow(rgb)\n",
    "ax[0, 0].set_title('Red: Keratin, Green: dsDNA, Blue: CD45')\n",
    "\n",
    "cym = color.rgb2cym(rgb)\n",
    "ax[0, 1].imshow(cym)\n",
    "ax[0, 1].set_title('Cyan: Keratin, Yellow: dsDNA, Magenta: CD45')\n",
    "\n",
    "ax[1, 0].imshow(color.composite(image, {'Orange': 'Lamin A/C'}))\n",
    "ax[1, 0].set_title('Orange: Lamin A/C')\n",
    "\n",
    "overlay = color.composite(\n",
    "    image,\n",
    "    {\n",
    "        'Green': 'CD3',\n",
    "        'Cyan': 'CD4',\n",
    "        'Yellow': 'CD8',\n",
    "        'Magenta': 'CD68'\n",
    "    })\n",
    "ax[1, 1].imshow(overlay)\n",
    "ax[1, 1].set_title('Cyan: CD4, Yellow: CD8\\n'\n",
    "                'Magenta: CD68, Green: CD3')\n",
    "\n",
    "fig.tight_layout()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<h2>Image Manipluation</h2>\n",
    "\n",
    "A deep copy of MibiImage instances can be made using the `copy` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_image = image.copy()\n",
    "new_image.channels"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To alter channel data in the image, you can access the `.data` property with the indices of the channels of interest."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_image.data[:, :, new_image.channel_inds('CD45')] = filters.median(image['CD45'])\n",
    "\n",
    "def show_image(data, axis, title):\n",
    "    cb = axis.imshow(data)\n",
    "    divider = make_axes_locatable(axis)\n",
    "    cax = divider.append_axes('right', size='5%', pad=0.05)\n",
    "    plt.colorbar(cb, cax=cax)\n",
    "    axis.set_title(title)\n",
    "\n",
    "fig, ax = plt.subplots(2, 2, figsize=(9.5, 8))\n",
    "show_image(image['CD45'], ax[0, 0], 'Raw CD45: gamma = 1')\n",
    "show_image(new_image['CD45'], ax[0, 1], 'Median-Filtered CD45: gamma = 1')\n",
    "show_image(np.power(image['CD45'], 1/2), ax[1, 0],\n",
    "            'Raw CD45: gamma = 1/2')\n",
    "show_image(np.power(new_image['CD45'], 1/2), ax[1, 1],\n",
    "            'Median-Filtered CD45: gamma = 1/2')\n",
    "fig.tight_layout()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Rather than scaling a single channel, we can also apply a default scaling to all channels, and then display an RGB overlay of a 3-D slice."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def scale(image, gamma=1/2):\n",
    "    \"\"\"Scales each 2-D slice of an N-D image to a brightened version in the [0, 1] range.\"\"\"\n",
    "    \n",
    "    scaled = np.divide(\n",
    "        image.data.astype(float),\n",
    "        image.data.max(axis=(0, 1)))\n",
    "    scaled = np.power(scaled, gamma)\n",
    "    image.data = scaled"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scaled_image = image.copy()\n",
    "scale(scaled_image, 1/3)\n",
    "\n",
    "fig, ax = plt.subplots(1, 2, figsize=(9.5, 4), sharex=True, sharey=True)\n",
    "\n",
    "ax[0].imshow(scaled_image[['CD68', 'Lamin A/C', 'dsDNA']])\n",
    "ax[0].set_title('CD68 - Lamin A/C - dsDNA')\n",
    "ax[1].imshow(scaled_image[['CD31', 'CD8', 'Keratin']])\n",
    "ax[1].set_title('CD31 - CD8 - Keratin')\n",
    "\n",
    "ax[0].set_xlim((0, 512))\n",
    "ax[0].set_ylim((1024, 512))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<h2>Saving MibiImages</h2>\n",
    "\n",
    "A MibiImage object can be saved as either a multiplexed MIBITIFF or a series of individual channel PNGs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When saving a series of channel PNGs, the folder to save to must be specified. The filenames of each PNG will be generated from the channel names of the MibiImage object, either the string label or the target only if they the channels are (mass, target) tuples."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tiff.write('/path/to/file.tiff', new_image)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_image.export_pngs('/path/to/folder')\n",
    "outputs = [png_name for png_name in os.listdir('/path/to/folder/') if os.path.splitext(png_name)[-1] == '.png']\n",
    "outputs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The exported TIFF or PNGs can then be uploaded to MIBItracker using the `mibitracker` module. See the Python section of the [MIBItracker Tutorial](https://github.com/ionpath/mibilib/blob/master/MIBItracker_API_Tutorial.ipynb) for more information on uploading TIFF or PNG files."
   ]
  }
 ],
 "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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}