updated example notebooks

Author: njl-02

notebooks/01_prediction_demo.ipynb

@@ -0,0 +1,129 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "825a7d90",
+   "metadata": {},
+   "source": [
+    "## CellCycleNet Example - Fine tune pretrained model and predict cell cycle stage on 3D DAPI images WITH ground truth labels.\n",
+    "This notebook demonstrates how to use CellCycleNet to fine tune the pretrained model and predict cell cycle stage from images of DAPI-stained nuclei that have associated ground truth labels for cell cycle stage.\n",
+    "\n",
+    "CellCycleNet requires the following data:\n",
+    " - A directory of 3D DAPI-stained fields of view named as `tile_<tile_num>.tiff`\n",
+    " - A directory of 3D segmentation masks named as `mask_<tile_num>.tiff`\n",
+    " - A directory of 3D ground truth label arrays named as `label_<tile_num>.npy` (pixel values must be 0, 1, or 2 where 0 = background, 1 = G1 nucleus, 2 = S/G2 nucleus)\n",
+    " - Where `<tile_num>` is an integer that uniquely identifies each field of view and its corresponding segmentation mask and label array\n",
+    "\n",
+    "### Step 1: Create single-nucleus images from segmented FOVs."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "001a1733-cda4-49db-833b-278f3c4a2099",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from cellcyclenet import utils\n",
+    "\n",
+    "IMAGE_DIR = '../data/test_tiles/' # path to DAPI-stained FOVs\n",
+    "MASK_DIR = '../data/test_masks/' # path to segmentation masks of FOVs \n",
+    "LABEL_DIR = '../data/test_labels/' # path to label arrays of FOVs\n",
+    "OUTPUT_DIR = '../data/test_SNI_label/' # path where labeled single-nucleus images will be saved\n",
+    "\n",
+    "# generate labeled SNIs #\n",
+    "'''\n",
+    "Optional Arguments for utils.generate_images_labeled():\n",
+    " - return_df: boolean, if True, returns a pandas dataframe with the tile numbers, object numbers, and labels of the labeled SNIs\n",
+    " - num_cores: integer, number of cores to use for parallel processing; if 'None', no parallel processing will be used\n",
+    " - is_3d: boolean, set to True if your data is 3D; set to False if your data is 2D\n",
+    "'''\n",
+    "df = utils.generate_images_labeled(IMAGE_DIR, MASK_DIR, LABEL_DIR, OUTPUT_DIR, return_df=True, num_cores=None, is_3d=True)\n",
+    "display(df)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "63f4651f-d75b-4d53-8f78-464fd8145a55",
+   "metadata": {},
+   "source": [
+    "### Step 2: Load pretrained model and finetune with labeled data."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dd2f8298-c077-436e-827b-89a3d7d2486b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from cellcyclenet import CellCycleNet\n",
+    "\n",
+    "# create 3D model instance (pretrained weights are loaded by default) #\n",
+    "model = CellCycleNet(is_3d=True)\n",
+    "\n",
+    "# convert dataframe to CellCycleNet dataset; split_data=True --> 70% training, 20% validation, 10% test #\n",
+    "train, val, test = model.create_dataset(dataframe=df, split_data=True)\n",
+    "\n",
+    "# train model on your labeled data #\n",
+    "'''\n",
+    "Optional Arguments for CellCycleNet.train():\n",
+    " - transform: callable, a function that takes an image and returns a transformed image; if None, no transformation will be applied\n",
+    " - lazy_load: boolean, if True, the dataset will be loaded lazily in each epoch (slower, but uses less memory); if False, the dataset will be loaded into memory (faster, but uses more memory) \n",
+    " - verbose: boolean, if True, training progress will be printed to the console\n",
+    "'''\n",
+    "model.train(train, val, n_epochs=10, batch_size=4, initial_LR=1e-5, transform=None, lazy_load=True, verbose=True)\n",
+    "\n",
+    "# save finetuned model weights #\n",
+    "model.save_model('fine_tuned_model.pt')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1577521d-4aaa-49c0-96de-91e3ea26ad97",
+   "metadata": {},
+   "source": [
+    "### Step 3: Predict cell cycle stage for each single-nucleus image in the test set."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "49b5b1a2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# generate cell cycle stage predictions (0 = G1, 1 = S/G2); with_labels=True --> predicting on labeled data #\n",
+    "test_predictions = model.predict(test, with_labels=True)\n",
+    "\n",
+    "# display predictions #\n",
+    "test_predictions.sort_values(['tile_num', 'obj_num'])\n",
+    "display(predictions)\n",
+    "\n",
+    "# plot an ROC curve to evaluate model peformance #\n",
+    "model.plot_ROC(test_predictions['label'], test_predictions['pred'], test_predictions['prob']"
+   ]
+  }
+ ],
+ "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.12.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}