{ "cells": [ { "cell_type": "markdown", "id": "0604edb3", "metadata": {}, "source": [ "# HNE2Cell tutorial 1 — Installation and environment\n", "\n", "HNE2Cell detects and classifies 15 cell types (16 output classes including background) in H&E whole-slide images.\n", "This tutorial sets up the software environment, downloads the model and example data, and checks that the model runs.\n", "\n", "| Tutorial | Content |\n", "|---|---|\n", "| **1. Installation and environment** (this notebook) | conda environment, model download, test run |\n", "| 2. Patch-level inference | one tissue region: normalization, model outputs, post-processing, cell overlay |\n", "| 3. Whole-slide inference | full pipeline on an example slide, ending in a per-cell table |\n", "\n", "**Requirements**\n", "\n", "* Linux with an NVIDIA GPU (≥ 12 GB memory) and CUDA 12 driver. The TorchScript model runs on GPU only.\n", "* ≥ 32 GB RAM (64 GB recommended); the normalization step loads the full-resolution slide.\n", "* ~8 GB of disk space for the model and the example slide.\n", "\n", "The outputs shown in these notebooks were produced with model version 2.0 on one NVIDIA H200 GPU." ] }, { "cell_type": "markdown", "id": "e281f44b", "metadata": {}, "source": [ "## Step 1. Create the conda environment\n", "\n", "Run in a terminal (≈10–15 min, dominated by the PyTorch and CUDA download):\n", "\n", "```bash\n", "wget https://huggingface.co/roobee79/HNE2Cell/resolve/main/environment.yml\n", "conda env create -f environment.yml\n", "conda activate hne2cell\n", "python -m ipykernel install --user --name hne2cell --display-name \"Python 3 (hne2cell)\"\n", "```\n", "\n", "Then open this notebook with the **Python 3 (hne2cell)** kernel." ] }, { "cell_type": "markdown", "id": "ec0e64f5", "metadata": {}, "source": [ "## Step 2. Check the environment\n", "\n", "The cell below prints the versions of the key packages and the GPU that will be used." ] }, { "cell_type": "code", "execution_count": 1, "id": "b45e8808", "metadata": { "execution": { "iopub.execute_input": "2026-10-28T08:35:46.888479Z", "iopub.status.busy": "2026-10-28T08:35:46.887095Z", "iopub.status.idle": "2026-10-28T08:35:51.386518Z", "shell.execute_reply": "2026-10-28T08:35:51.385785Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "python 3.10.6\n", "torch 2.5.1\n", "torchvision 0.20.1+cu124\n", "tifffile 2024.7.24\n", "skimage 0.19.3\n", "cv2 4.5.4-dev\n", "pandas 1.5.3\n", "huggingface_hub 0.24.5\n", "openslide 3.4.1\n", "CUDA available: True\n", "GPU: NVIDIA H200\n" ] } ], "source": [ "import platform\n", "import torch, torchvision, openslide, tifffile, skimage, cv2, pandas, huggingface_hub\n", "\n", "print(\"python \", platform.python_version())\n", "for m in (torch, torchvision, tifffile, skimage, cv2, pandas, huggingface_hub):\n", " print(f\"{m.__name__:<12}\", m.__version__)\n", "print(\"openslide \", getattr(openslide, \"__library_version__\", \"?\"))\n", "print(\"CUDA available:\", torch.cuda.is_available())\n", "assert torch.cuda.is_available(), \"HNE2Cell needs an NVIDIA GPU\"\n", "print(\"GPU:\", torch.cuda.get_device_name(0))" ] }, { "cell_type": "markdown", "id": "4ca427cf", "metadata": {}, "source": [ "**Expected:** `CUDA available: True` and the name of your GPU. If CUDA is not available, check the NVIDIA driver\n", "(`nvidia-smi`) and that the notebook runs in the `hne2cell` kernel.\n", "\n", "## Step 3. Download the model, scripts and example data\n", "\n", "All files are taken from the version-pinned release `v2.0` of the Hugging Face repository\n", "(the model weights are 5.1 GB; the example slide, TCGA-56-8628 lung squamous cell carcinoma, is 36 MB)." ] }, { "cell_type": "code", "execution_count": 2, "id": "519ef4c7", "metadata": { "execution": { "iopub.execute_input": "2026-10-28T08:35:51.392390Z", "iopub.status.busy": "2026-10-28T08:35:51.392128Z", "iopub.status.idle": "2026-10-28T08:35:51.911342Z", "shell.execute_reply": "2026-10-28T08:35:51.910796Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " 0.0 MB .gitattributes\n", " 5138.3 MB HNE2Cell_v2_jit.pt\n", " 0.0 MB LICENSE\n", " 0.0 MB MODEL_LICENSE\n", " 0.0 MB README.md\n", " 36.0 MB TCGA-56-8628-01Z-00-DX1.AAC57164-E0F9-4DF0-87EA-5C50FB201895.svs\n", " 0.0 MB config.json\n", " 0.0 MB environment.yml\n", " 0.0 MB inference.py\n", " 0.0 MB normalize.py\n", " 0.0 MB patchify.py\n", " 0.0 MB post_processing.py\n", " 355.2 MB standard-ilc.tif\n", " 0.0 MB tools.py\n" ] } ], "source": [ "import os\n", "os.environ[\"HF_HUB_DISABLE_PROGRESS_BARS\"] = \"1\"\n", "from huggingface_hub import snapshot_download\n", "\n", "FILES = os.path.abspath(\"hne2cell_files\")\n", "snapshot_download(repo_id=\"roobee79/HNE2Cell\", revision=\"v2.0\", local_dir=FILES)\n", "\n", "for f in sorted(os.listdir(FILES)):\n", " p = os.path.join(FILES, f)\n", " if os.path.isfile(p):\n", " print(f\"{os.path.getsize(p) / 1e6:10.1f} MB {f}\")" ] }, { "cell_type": "markdown", "id": "cc09b016", "metadata": {}, "source": [ "| File | Purpose |\n", "|---|---|\n", "| `HNE2Cell_v2_jit.pt` | TorchScript model (v2.0) |\n", "| `config.json` | class names and model settings |\n", "| `normalize.py`, `patchify.py`, `inference.py` | the three pipeline steps (used in tutorial 3) |\n", "| `post_processing.py`, `tools.py` | cell instance extraction from the model outputs |\n", "| `standard-ilc.tif` | reference image for Reinhard color normalization |\n", "| `TCGA-56-8628-…svs` | example whole-slide image |\n", "\n", "## Step 4. Load the model and run a test input\n", "\n", "The model takes 224 × 224 RGB tensors (256 × 256 patches resized, see `inference.TRANSFORM`) and returns\n", "dense maps at 256 × 256 resolution." ] }, { "cell_type": "code", "execution_count": 3, "id": "a10c0b6f", "metadata": { "execution": { "iopub.execute_input": "2026-10-28T08:35:51.915529Z", "iopub.status.busy": "2026-10-28T08:35:51.915255Z", "iopub.status.idle": "2026-10-28T08:35:56.971634Z", "shell.execute_reply": "2026-10-28T08:35:56.970648Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "model version: 2.0 | 16 classes\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "model loaded in 4 s\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "organ_types (2, 13)\n", "nuclei_binary_map (2, 2, 256, 256)\n", "hv_map (2, 2, 256, 256)\n", "tissue_type_map (2, 6, 256, 256)\n", "cell_type_map (2, 16, 256, 256)\n" ] } ], "source": [ "import json, time\n", "import torch\n", "\n", "with open(os.path.join(FILES, \"config.json\")) as f:\n", " config = json.load(f)\n", "print(\"model version:\", config[\"model_version\"], \"|\", config[\"num_classes\"], \"classes\")\n", "\n", "t0 = time.time()\n", "model = torch.jit.load(os.path.join(FILES, config[\"weights_file\"]), map_location=\"cuda\").eval()\n", "print(f\"model loaded in {time.time() - t0:.0f} s\")\n", "\n", "x = torch.zeros(2, 3, 224, 224, device=\"cuda\")\n", "with torch.no_grad(), torch.autocast(\"cuda\"):\n", " out = model(x)\n", "for k, v in out.items():\n", " print(f\"{k:<18} {tuple(v.shape)}\")" ] }, { "cell_type": "markdown", "id": "fccfc7d6", "metadata": {}, "source": [ "**Expected output maps** (batch of 2):\n", "\n", "| Output | Shape | Meaning |\n", "|---|---|---|\n", "| `nuclei_binary_map` | (2, 2, 256, 256) | nucleus vs background |\n", "| `hv_map` | (2, 2, 256, 256) | horizontal and vertical distance maps used to separate touching nuclei |\n", "| `cell_type_map` | (2, 16, 256, 256) | per-pixel cell-type logits (background + 15 cell types) |\n", "| `tissue_type_map`, `organ_types` | | auxiliary outputs, not used for cell classification |\n", "\n", "The 16 classes are:" ] }, { "cell_type": "code", "execution_count": 4, "id": "28e6f801", "metadata": { "execution": { "iopub.execute_input": "2026-10-28T08:35:56.976340Z", "iopub.status.busy": "2026-10-28T08:35:56.976183Z", "iopub.status.idle": "2026-10-28T08:35:56.987926Z", "shell.execute_reply": "2026-10-28T08:35:56.987223Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
class
0Background
1Malignant
2CD4 T
3CD8 T
4B
5Plasma
6Macrophage
7Myeloid
8DC
9Fibroblast
10Endothelial
11Pericyte
12Epithelial
13Immune_Other
14Stromal_Other
15Dead
\n", "
" ], "text/plain": [ " class\n", "0 Background\n", "1 Malignant\n", "2 CD4 T\n", "3 CD8 T\n", "4 B\n", "5 Plasma\n", "6 Macrophage\n", "7 Myeloid\n", "8 DC\n", "9 Fibroblast\n", "10 Endothelial\n", "11 Pericyte\n", "12 Epithelial\n", "13 Immune_Other\n", "14 Stromal_Other\n", "15 Dead" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import pandas as pd\n", "pd.DataFrame({\"class\": list(config[\"id2label\"].values())}, index=list(config[\"id2label\"].keys()))" ] }, { "cell_type": "markdown", "id": "81e1aa20", "metadata": {}, "source": [ "The installation is complete. Continue with **tutorial 2** (patch-level inference)." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (hne2cell)", "language": "python", "name": "hne2cell" }, "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.10.6" } }, "nbformat": 4, "nbformat_minor": 5 }