ENACT_demo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "88dfe185-575f-484b-87a5-662d54a8aa14",
   "metadata": {},
   "source": [
    "## ENACT Demo Notebook - Human Colorectal Cancer"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ef3a94f5-4189-4c46-b4fa-570989cb78e9",
   "metadata": {},
   "source": [
    "This notebook provides a demo for running ENACT on the Human Colorectal Cancer sample provided on 10X Genomics' website."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "31994db6-6997-4124-a4d5-bf09dbf64f69",
   "metadata": {},
   "source": [
    "### Download VisiumHD data from the 10X Genomics website"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e56081b4-2eb0-45e4-9f46-7ed118b51551",
   "metadata": {},
   "source": [
    "Whole slide image: full resolution tissue image"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "712a9e76-d7e1-4cc1-b0ae-afad223a1713",
   "metadata": {},
   "outputs": [],
   "source": [
    "!curl -O https://cf.10xgenomics.com/samples/spatial-exp/3.0.0/Visium_HD_Human_Colon_Cancer/Visium_HD_Human_Colon_Cancer_tissue_image.btf"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bfa4bd8e-4b4d-4593-b5f2-8cc881c1a2b1",
   "metadata": {},
   "source": [
    "Visium HD output file. The transcript counts are provided in a .tar.gz file that needs to be extracted:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6f7bc5a4-6f56-4ffa-8b1c-9c178d5c6022",
   "metadata": {},
   "outputs": [],
   "source": [
    "!curl -O https://cf.10xgenomics.com/samples/spatial-exp/3.0.0/Visium_HD_Human_Colon_Cancer/Visium_HD_Human_Colon_Cancer_binned_outputs.tar.gz\n",
    "!tar -xvzf Visium_HD_Human_Colon_Cancer_binned_outputs.tar.gz"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c838e47e-0e91-4462-a099-ff061cd4f94f",
   "metadata": {},
   "source": [
    "Locate the following two files from the extracted outputs file. These are the files we will use later as input to ENACT.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "08ea9a56-14c5-4ebc-bb09-e7535bbc1fee",
   "metadata": {},
   "outputs": [],
   "source": [
    ".\n",
    "└── binned_outputs/\n",
    "    └── square_002um/\n",
    "        ├── filtered_feature_bc_matrix.h5   <---- Transcript counts file (2um resolution)\n",
    "        └── spatial/\n",
    "            └── tissue_positions.parquet    <---- Bin locations relative to the full resolution image\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d760ee8-f5a0-4a0f-ace6-c0b91176f4e1",
   "metadata": {},
   "source": [
    "### Install ENACT\n",
    "This will install the ENACT package and its dependencies.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d555ae41-0776-4047-bfe2-1ee3ebc475bb",
   "metadata": {
    "scrolled": true,
    "tags": []
   },
   "outputs": [],
   "source": [
    "!pip install enact-SO"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "39736162-ba27-435f-8dc6-876b2f507315",
   "metadata": {},
   "source": [
    "### Access and update the `configs.yaml` file"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56f81b7a-e58e-498b-8589-0fd9cfc82c08",
   "metadata": {},
   "source": [
    "To run the ENACT pipeline, you will need a configuration file that specifies all the required settings. You can download the template configuration file from the GitHub repository.\n",
    "\n",
    "Refer to [Defining ENACT Configurations](https://github.com/Sanofi-OneAI/oneai-dda-spatialtr-enact/tree/release/ospo-new?tab=readme-ov-file#defining-enact-configurations) for a full list of parameters to configure."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19207eb1-f22a-48d7-80ba-08b6fc118872",
   "metadata": {},
   "source": [
    "#### Step 1\n",
    "Download the `configs.yaml` template from the `config` folder of [this repository](https://github.com/Sanofi-OneAI/oneai-dda-spatialtr-enact), and save it in your working directory."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8996161d-5164-4931-bfdc-ca0065686d44",
   "metadata": {},
   "source": [
    "#### Step 2\n",
    "Edit the input file locations in `configs.yaml` to the downloaded Visium HD files' location."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff15bcbd-681e-4947-8277-cffc30f69df4",
   "metadata": {},
   "source": [
    "```yaml\n",
    "analysis_name: \"demo-colon\"                           \n",
    "cache_dir: \"enact_output\"                   \n",
    "paths:\n",
    "    wsi_path: \"Visium_HD_Human_Colon_Cancer_tissue_image.btf\"      \n",
    "    visiumhd_h5_path: \"binned_outputs/square_002um/filtered_feature_bc_matrix.h5\"         \n",
    "    tissue_positions_path: \"binned_outputs/square_002um/spatial/tissue_positions.parquet\"      \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81daa91f-e34e-4018-8a46-89ddb9b6cf99",
   "metadata": {},
   "source": [
    "#### Step 3\n",
    "Next, we set all the steps in the `configs.yaml` file to `True`, in order to run the whole ENACT pipeline later"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a4eb5a6-2436-4cf3-8b52-e06d431fc3a0",
   "metadata": {},
   "source": [
    "```yaml\n",
    "steps:\n",
    "        segmentation: True                                   \n",
    "        bin_to_geodataframes: True                             \n",
    "        bin_to_cell_assignment: True                           \n",
    "        cell_type_annotation: True         \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4af04737-6ece-431f-b5d5-1eaefe63efca",
   "metadata": {},
   "source": [
    "#### Step 4\n",
    "Lastly, choose the `bin_to_cell_method` and `cell_annotation_method` we want to run with. In this demo, we will go with `\"weighted_by_area\"`, and `\"celltypist\"`.\n",
    "\n",
    "To run Celltypist as our cell annotation method, we also need to input the `cell_typist_model` parameter based on the type of sample we use."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b495d82-cfce-4973-aed0-84aec7d2ac31",
   "metadata": {},
   "source": [
    "```yaml\n",
    " params:\n",
    "      bin_to_cell_method: \"weighted_by_area\"                \n",
    "      cell_annotation_method: \"celltypist\"                     \n",
    "      cell_typist_model: \"Human_Colorectal_Cancer.pkl\"         \n",
    "      seg_method: \"stardist\"                                    \n",
    "      patch_size: 4000                                         \n",
    "      use_hvg: True                                            \n",
    "      n_hvg: 1000                                              \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13a165e4-7f63-4cfd-80ed-52a0823692f9",
   "metadata": {},
   "source": [
    "### Run ENACT"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2aadbd97-ddf2-4252-9bb0-c59ba4600c4c",
   "metadata": {},
   "source": [
    "Running ENACT on the whole sample image will take around 40 minutes. Output of the pipeline will be stored in the `\"enact_output\"` directory"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "393087e7-9598-4ebe-a628-14cc0ac673a8",
   "metadata": {},
   "outputs": [],
   "source": [
    "from enact.pipeline import ENACT\n",
    "import yaml\n",
    "\n",
    "configs_path = \"config/configs.yaml\" # Change this to the location of the configs.yaml file that you just edited\n",
    "with open(configs_path, \"r\") as stream:\n",
    "    configs = yaml.safe_load(stream)\n",
    "\n",
    "so_hd = ENACT(configs_dict=configs)\n",
    "so_hd.run_enact()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cfc23f74",
   "metadata": {},
   "source": [
    "New! Alternatively, users can specify ENACT configurations directly in the class constructor with the following *minimum* configurations. Refer to Readme for full list of ENACT parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "87648e0c",
   "metadata": {},
   "outputs": [],
   "source": [
    "from enact.pipeline import ENACT\n",
    "\n",
    "# Running ENACT with `weighted-by-area` bin-to-cell assignment, and `celltypist` for cell type annotation\n",
    "so_hd = ENACT(\n",
    "    cache_dir=\"/home/oneai/test_cache\",\n",
    "    wsi_path=\"Visium_HD_Human_Colon_Cancer_tissue_image.btf\",\n",
    "    visiumhd_h5_path=\"binned_outputs/square_002um/filtered_feature_bc_matrix.h5\",\n",
    "    tissue_positions_path=\"binned_outputs/square_002um/spatial/tissue_positions.parquet\",\n",
    "    analysis_name=\"demo-colon\", #optional\n",
    "    bin_to_cell_method=\"weighted_by_area\", #optional    \n",
    "    cell_annotation_method=\"celltypist\", #optional                \n",
    "    cell_typist_model=\"Human_Colorectal_Cancer.pkl\" #optional  \n",
    ")\n",
    "so_hd.run_enact()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ac1595f3",
   "metadata": {},
   "source": [
    "Example: Only running the cell segmentation step and disabling all the other steps"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1fbef539",
   "metadata": {},
   "outputs": [],
   "source": [
    "from enact.pipeline import ENACT\n",
    "\n",
    "so_hd = ENACT(\n",
    "    cache_dir=\"/home/oneai/test_cache\",\n",
    "    wsi_path=\"Visium_HD_Human_Colon_Cancer_tissue_image.btf\",\n",
    "    visiumhd_h5_path=\"binned_outputs/square_002um/filtered_feature_bc_matrix.h5\",\n",
    "    tissue_positions_path=\"binned_outputs/square_002um/spatial/tissue_positions.parquet\",\n",
    "    analysis_name=\"demo-colon\",\n",
    "    bin_to_cell_method=\"weighted_by_area\",    \n",
    "    cell_annotation_method=\"celltypist\",                \n",
    "    cell_typist_model=\"Human_Colorectal_Cancer.pkl\",\n",
    "    segmentation=True,\n",
    "    bin_to_geodataframes=False,\n",
    "    bin_to_cell_assignment=False,\n",
    "    cell_type_annotation=False\n",
    ")\n",
    "so_hd.run_enact()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2ae423f9",
   "metadata": {},
   "source": [
    "Example: Running ENACT with `naive` bin-to-cell assignment and `cellassign` for cell type annotation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from enact.pipeline import ENACT\n",
    "\n",
    "so_hd = ENACT(\n",
    "    cache_dir=\"/home/oneai/test_cache\",\n",
    "    wsi_path=\"Visium_HD_Human_Colon_Cancer_tissue_image.btf\",\n",
    "    visiumhd_h5_path=\"binned_outputs/square_002um/filtered_feature_bc_matrix.h5\",\n",
    "    tissue_positions_path=\"binned_outputs/square_002um/spatial/tissue_positions.parquet\",\n",
    "    analysis_name=\"demo-colon\",\n",
    "    bin_to_cell_method=\"naive\",    \n",
    "    cell_annotation_method=\"cellassign\"\n",
    ")\n",
    "so_hd.run_enact()"
   ]
  }
 ],
 "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.10.14"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}