### Install Pre-commit

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/CONTRIBUTING.rst

Installs the pre-commit tool into the virtual environment for managing pre-commit hooks.

```shell
pip install pre-commit
```

--------------------------------

### Install tiatoolbox Locally

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/CONTRIBUTING.rst

Installs the tiatoolbox project into a virtual environment for local development using setup.py.

```shell
mkvirtualenv tiatoolbox
cd tiatoolbox/
python setup.py develop
```

--------------------------------

### Setup Development Environment

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/README.md

Commands to clone the repository and create a virtual environment for TIAToolbox development.

```bash
git clone https://github.com/TissueImageAnalytics/tiatoolbox.git
cd tiatoolbox
conda create -n tiatoolbox-dev python=3.10
conda activate tiatoolbox-dev
pip install -r requirements/requirements_dev.txt
```

--------------------------------

### Install Git Hook for Pre-commit

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/CONTRIBUTING.rst

Sets up the git hook for pre-commit after installation to automatically run checks.

```shell
pre-commit install
```

--------------------------------

### Install TIAToolbox and Dependencies (Bash)

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/inference-pipelines/slide-graph.ipynb

Installs the tiatoolbox package from GitHub and its system-level dependencies using apt-get and pip. It's designed to be run in a bash environment, potentially within a Jupyter notebook cell. The `tail -n 1` command is used to capture only the last line of the output for cleaner logging.

```bash
%%bash
apt-get -y install libopenjp2-7-dev libopenjp2-tools openslide-tools libpixman-1-dev | tail -n 1
pip install git+https://github.com/TissueImageAnalytics/tiatoolbox.git@develop | tail -n 1
echo "Installation is done."
```

--------------------------------

### Python Data Downloading and Setup

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/inference-pipelines/slide-graph.ipynb

Handles the downloading of necessary sample data and pre-trained models if they are not already present. It includes logic to remove existing download directories and then proceeds to download files from specified URLs, ensuring the environment is set up for analysis.

```python
# ! Uncomment this to always download data
rmdir(DOWNLOAD_DIR)

# Downloading sample image tile
if not DOWNLOAD_DIR.exists():
    DOWNLOAD_DIR.mkdir(parents=True)
    URL_HOME = (
        "https://tiatoolbox.dcs.warwick.ac.uk/models/slide_graph/cell-composition"
    )
    SLIDE_CODE = "TCGA-C8-A278-01Z-00-DX1.188B3FE0-7B20-401A-A6B7-8F1798018162"
    download_data(f"{URL_HOME}/{SLIDE_CODE}.svs", WSI_PATH)
    download_data(f"{URL_HOME}/{SLIDE_CODE}.mask.png", MSK_PATH)
    download_data(f"{URL_HOME}/{SLIDE_CODE}.json", PRE_GENERATED_GRAPH_PATH)
    download_data(f"{URL_HOME}/node_scaler.dat", SCALER_PATH)
    download_data(f"{URL_HOME}/model.aux.logistic.dat", MODEL_AUX_PATH)
    download_data(f"{URL_HOME}/model.weights.pth", MODEL_WEIGHTS_PATH)
```

--------------------------------

### Install Pre-Commit Hooks

Source: https://github.com/tissueimageanalytics/tiatoolbox/wiki/Commits

Installs the pre-commit hooks for the repository. This ensures that code is automatically formatted and checked for style issues before each commit, using tools like black and flake8. Run this command once after cloning the repository.

```bash
$ pre-commit install
```

--------------------------------

### Install TIAToolbox and System Dependencies

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/01-wsi-reading.ipynb

Installs necessary system libraries and the TIAToolbox package via pip. This is intended for use in environments like Google Colab.

```bash
apt-get -y install libopenjp2-7-dev libopenjp2-tools libpixman-1-dev | tail -n 1
pip install git+https://github.com/TissueImageAnalytics/tiatoolbox.git@develop | tail -n 1
echo "Installation is done."
```

--------------------------------

### PyTest Fixture Example (Python)

Source: https://github.com/tissueimageanalytics/tiatoolbox/wiki/Unit-Testing

Demonstrates how to create a PyTest fixture for reusable setup code. The 'smtp_connection' fixture establishes an SMTP connection. Fixtures are injected into test functions as arguments.

```python
# content of ./test_smtpsimple.py
import pytest

@pytest.fixture
def smtp_connection():
    import smtplib
    return smtplib.SMTP("smtp.gmail.com", 587, timeout=5)


def test_ehlo(smtp_connection):
    response, msg = smtp_connection.ehlo()
    assert response == 250
    assert 0  # for demo purposes

```

--------------------------------

### Click CLI and Test Example (Python)

Source: https://github.com/tissueimageanalytics/tiatoolbox/wiki/Unit-Testing

Shows a basic Click command-line interface ('hello.py') and its corresponding unit test ('test_hello.py') using Click's testing utilities. The test invokes the command and asserts the exit code and output.

```python
import click

@click.command()
@click.argument('name')
def hello(name):
    click.echo('Hello %s!' % name)

```

```python
from click.testing
import CliRunner
from hello import hello

def test_hello_world():
    runner = CliRunner()
    result = runner.invoke(hello, ['Peter'])
    assert result.exit_code == 0
    assert result.output == 'Hello Peter!\n'

```

--------------------------------

### Configure UI Visualization Settings

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/docs/visualization.rst

Example of a JSON configuration file used to customize slide loading, annotation display colors, and initial UI settings.

```json
{
  "initial_views": {
    "slideA": [0, 19000, 35000, 44000]
  },
  "auto_load": 1,
  "color_dict": {
    "typeA": [252, 161, 3, 255]
  },
  "UI_settings": {
    "blur_radius": 0
  }
}
```

--------------------------------

### Launch Whole Slide Image Visualization Server with TIA Toolbox CLI

Source: https://context7.com/tissueimageanalytics/tiatoolbox/llms.txt

Starts a web-based visualization server for a whole slide image (SVS) on a specified port. Allows interactive viewing of large pathology images. Requires input slide path and port number.

```bash
tiatoolbox show-wsi --input-path slide.svs --port 5000
```

--------------------------------

### Get WSI Information using .info.as_dict() (Python)

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/03-tissue-masking.ipynb

Retrieves detailed information about the opened WSI, such as objective power, slide dimensions, level count, vendor, and microns per pixel (mpp). The information is returned as a dictionary, which is then printed item by item.

```python
wsi_info = wsi.info.as_dict()
# Print one item per line
print(*list(wsi_info.items()), sep="\n")  # noqa: T201
```

--------------------------------

### TIAToolbox IOSegmentorConfig for CoNIC Dataset (KongNet)

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/docs/pretrained.rst

Input/output configuration for the KongNet_CoNIC_1 model. This setup includes patch input shape, stride shape, input resolution, and save resolution.

```python
from tiatoolbox.models.engine.io_config import IOSegmentorConfig
ioconfig = IOSegmentorConfig(
    patch_input_shape=(256, 256),
    stride_shape=(248, 248),
    input_resolutions=[{"resolution": 0.5, "units": "mpp"}],
    save_resolution={'units': 'baseline', 'resolution': 1.0}
)
```

--------------------------------

### Use TIAToolbox Command Line Interface

Source: https://context7.com/tissueimageanalytics/tiatoolbox/llms.txt

Examples of using the TIAToolbox CLI to perform common tasks like retrieving slide information, generating thumbnails, and extracting regions without writing Python scripts.

```bash
tiatoolbox slide-info --input-path slide.svs
tiatoolbox slide-thumbnail --input-path slide.svs --output-path thumbnail.png
tiatoolbox read-bounds --input-path slide.svs --bounds 1000 2000 2000 3000 --resolution 0.5 --units mpp --output-path region.png
tiatoolbox tissue-mask --input-path slide.svs --method morphological --resolution 1.25 --units power --output-path mask.png
```

--------------------------------

### Foundation Models with TimmBackbone in TIAToolbox

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/HISTORY.md

Example showing the integration of foundation models using the `TimmBackbone` class in TIAToolbox, which leverages the `timm` API for running various PyTorch Image Models for feature extraction.

```python
# Example usage of TimmBackbone for feature extraction (conceptual)
# from tiatoolbox.models.timm_backbone import TimmBackbone
# backbone = TimmBackbone(model_name='UNI')
# features = backbone.extract_features(image)
```

--------------------------------

### Compressing SQLite Database with Zstandard

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/benchmarks/annotation_store.ipynb

Demonstrates compressing a SQLite database file using the Zstandard (zstd) algorithm. The first command uses default compression settings, while the second uses higher compression settings (-19) and the --long option for potentially better compression ratios on larger files, suitable for long-term archival. This process requires the zstd command-line utility to be installed.

```bash
# Basic Zstandard compression
! zstd -f -k integer-cells.db -o integer-cells.db.zstd
```

```bash
# Zstandard compression with higher settings for archival
! zstd -f -k -19 --long integer-cells.db -o integer-cells.db.19.zstd
```

--------------------------------

### Python Example: Using Stratified Split with Caching

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/full-pipelines/slide-graph.ipynb

Demonstrates how to use the `stratified_split` function to divide a dataset and save the splits to a cache file using `joblib`. If a cache file exists, it loads the splits from there; otherwise, it generates new splits and saves them. This approach is useful for ensuring reproducibility and speeding up data loading in subsequent runs.

```python
import joblib

CACHE_PATH = None
SPLIT_PATH = ROOT_OUTPUT_DIR / "splits.dat"

NUM_FOLDS = 5
TEST_RATIO = 0.2
TRAIN_RATIO = 0.8 * 0.9
VALID_RATIO = 0.8 * 0.1

if CACHE_PATH and CACHE_PATH.exists():
    splits = joblib.load(CACHE_PATH)
    SPLIT_PATH = CACHE_PATH
else:
    x = np.array(label_df["WSI-CODE"].to_list())
    y = np.array(label_df["LABEL"].to_list())
    splits = stratified_split(x, y, TRAIN_RATIO, VALID_RATIO, TEST_RATIO, NUM_FOLDS)

    joblib.dump(splits, SPLIT_PATH)
```

--------------------------------

### Install TIAToolbox via pip

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/README.md

Commands to install or upgrade the TIAToolbox package in a Python environment.

```bash
pip install tiatoolbox
pip install --ignore-installed --upgrade tiatoolbox
```

--------------------------------

### Load WSI and Retrieve Metadata

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/01-wsi-reading.ipynb

Demonstrates how to download a sample WSI, open it using the WSIReader, and extract comprehensive metadata such as dimensions, magnification, and vendor information.

```python
from tiatoolbox.wsicore.wsireader import WSIReader
from tiatoolbox.utils.data import small_svs
import logging
from pprint import pprint

logger = logging.getLogger()
file_path = small_svs()
reader = WSIReader.open(file_path)

# Print reader object and metadata
print(reader)
info_dict = reader.info.as_dict()
pprint(info_dict)
```

--------------------------------

### Download Sample WSI and Prepare Paths (Python)

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/03-tissue-masking.ipynb

Downloads a sample whole slide image (WSI) and sets up file paths for the image, thumbnail, and mask. This code illustrates a robust method for handling file downloads and path management, minimizing hard-coding and facilitating user customization.

```python
data_dir = "./tmp"
sample_file_name = "sample_wsi_small.svs"
sample_thumbnail_name = "sample_wsi_small_thumbnail.jpg"
sample_mask_name = "sample_wsi_small_mask.png"

user_sample_wsi_path = None
if user_sample_wsi_path is None:
    sample_wsi_path = f"{data_dir}/{sample_file_name}"
else:
    sample_wsi_path = user_sample_wsi_path
if not Path(sample_wsi_path).exists():
    Path(data_dir).mkdir()
    r = requests.get(
        "https://huggingface.co/datasets/TIACentre/TIAToolBox_Remote_Samples/resolve/main/sample_wsis/CMU-1-Small-Region.svs",
        timeout=60,  # 60s
    )
    with Path(sample_wsi_path).open("wb") as f:
        f.write(r.content)

sample_thumbnail_path = f"{data_dir}/{sample_thumbnail_name}"
sample_mask_path = f"{data_dir}/{sample_mask_name}"
```

--------------------------------

### Define CLI Entry Point in setup.py

Source: https://github.com/tissueimageanalytics/tiatoolbox/wiki/Command-Line-Interface-(CLI)

This snippet demonstrates how to register the 'tiatoolbox' command in the setup.py file. It maps the console script to the main function within the tiatoolbox.cli module.

```python
setup(
    author="TIA Lab",
    author_email='tialab@dcs.warwick.ac.uk',
    description="Computational pathology toolbox developed by TIA Lab.",
    entry_points={
        'console_scripts': [
            'tiatoolbox=tiatoolbox.cli:main',
        ],
    },
)
```

--------------------------------

### Install PyTorch Geometric (Bash)

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/inference-pipelines/slide-graph.ipynb

Installs the PyTorch Geometric library, which is an extension library for PyTorch, providing efficient implementations of graph neural networks. This command is typically executed in a bash environment.

```bash
%%bash
pip install torch-geometric
```

--------------------------------

### Download and Open WSI

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/04-patch-extraction.ipynb

Downloads a sample WSI file from a remote source and initializes a WSIReader to access the slide data.

```python
from tiatoolbox.utils.misc import download_data
from tiatoolbox.wsicore import WSIReader

wsi_file_name = "sample_wsi.svs"
wsi_path = download_data(
    "https://huggingface.co/datasets/TIACentre/TIAToolBox_Remote_Samples/resolve/main/sample_wsis/TCGA-3L-AA1B-01Z-00-DX1.8923A151-A690-40B7-9E5A-FCBEDFC2394F.svs",
    wsi_file_name,
)
wsi = WSIReader.open(wsi_path)
```

--------------------------------

### Install TIAToolbox and Dependencies

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/full-pipelines/slide-graph.ipynb

Installs specific versions of PyTorch, geometric deep learning libraries, and TIAToolbox required for compatibility with the SlideGraph+ notebook. Note that this requires version 1.6.0 of TIAToolbox due to API breaking changes in newer versions.

```bash
pip install -U numpy
pip install umap-learn ujson
pip uninstall -y torch-scatter torch-sparse torch-geometric
pip uninstall -y torch
pip install torch==1.10.0+cu113 torchvision==0.11.1+cu113 torchaudio==0.10.0+cu113 -f https://download.pytorch.org/whl/cu113/torch_stable.html
pip install torch-scatter -f https://data.pyg.org/whl/torch-1.10.0+cu113.html
pip install torch-sparse -f https://data.pyg.org/whl/torch-1.10.0+cu113.html
pip install torch-geometric
pip install tiatoolbox<=1.6.0
```

--------------------------------

### Download Sample WSI using tiatoolbox

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/02-stain-normalization.ipynb

Downloads a sample Whole Slide Image (WSI) from a URL if it does not already exist locally. It utilizes the `tiatoolbox.data` module and handles file saving and logging. Dependencies include `requests` and `pathlib`.

```python
import logging

if logging.getLogger().hasHandlers():
    logging.getLogger().handlers.clear()

from pathlib import Path

import matplotlib as mpl
import matplotlib.pyplot as plt
import requests
import skimage.color

from tiatoolbox import data, logger
from tiatoolbox.tools import stainnorm
from tiatoolbox.wsicore import wsireader

mpl.rcParams["figure.dpi"] = 150  # for high resolution figure in notebook

data_dir = "./tmp"
sample_file_name = "sample_wsi_small.svs"

user_sample_wsi_path = None


def download(url_path: str, save_path: str | Path) -> None:
    """Download url_path to save_path."""
    r = requests.get(url_path, timeout=60)
    with Path(save_path).open("wb") as f:
        f.write(r.content)


user_sample_wsi_path = None

if user_sample_wsi_path is None:
    sample_wsi_path = f"{data_dir}/{sample_file_name}"
else:
    sample_wsi_path = user_sample_wsi_path
if not Path(sample_wsi_path).exists():
    Path(sample_wsi_path).parent.mkdir(parents=True)
    url_path = "https://huggingface.co/datasets/TIACentre/TIAToolBox_Remote_Samples/resolve/main/sample_wsis/CMU-1-Small-Region.svs"
    download(url_path, sample_wsi_path)

logger.info("Download is complete.")
```

--------------------------------

### GET /stainnorm/get_normalizer

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/02-stain-normalization.ipynb

Retrieves a stain normalizer instance based on the specified method name.

```APIDOC
## GET /stainnorm/get_normalizer

### Description
Retrieves a stain normalizer object by its method name. Supported methods include Reinhard, Ruifrok, Macenko, and Vahadane.

### Method
GET

### Endpoint
/stainnorm/get_normalizer

### Parameters
#### Query Parameters
- **method_name** (string) - Required - The name of the normalization method (e.g., "Reinhard", "Vahadane").

### Request Example
GET /stainnorm/get_normalizer?method_name=Vahadane

### Response
#### Success Response (200)
- **normalizer** (object) - An instance of the requested stain normalizer class.

#### Response Example
{
  "status": "success",
  "normalizer": "VahadaneNormalizer"
}
```

--------------------------------

### Define Class and Init Docstrings

Source: https://github.com/tissueimageanalytics/tiatoolbox/wiki/Docstrings

Shows how to document classes, including attributes and __init__ methods, following the Google docstring convention.

```python
class ExampleClass(object):
    """The summary line for a class docstring should fit on one line.

    Attributes:
        attr1 (str): Description of `attr1`.
        attr2 (:obj:`int`, optional): Description of `attr2`.

    """

    def __init__(self, param1, param2, param3):
        """Example of docstring on the __init__ method.

        Args:
            param1 (str): Description of `param1`.
            param2 (:obj:`int`, optional): Description of `param2`.
            param3 (:obj:`list` of :obj:`str`): Description of `param3`.

        """
        self.attr1 = param1
        self.attr2 = param2
        self.attr3 = param3
```

--------------------------------

### GET /annotation/nquery

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/benchmarks/annotation_nquery.ipynb

Performs a spatial query to find annotations within a specified distance of a given geometry or existing annotations.

```APIDOC
## GET /annotation/nquery

### Description
Query for annotations within a distance of another annotation or geometry. This method supports various spatial predicates and distance calculation modes.

### Method
GET

### Endpoint
/annotation/nquery

### Parameters
#### Query Parameters
- **geometry** (Geometry) - Optional - A geometry to use for the initial search. If None, all annotations are considered.
- **where** (str/bytes/Callable) - Optional - Predicate to filter initial annotations.
- **n_where** (str/bytes/Callable) - Optional - Predicate to filter the resulting nearest annotations.
- **distance** (float) - Optional - The search radius. Defaults to 5.0.
- **geometry_predicate** (str) - Optional - Spatial predicate (e.g., 'intersects', 'within', 'contains'). Defaults to 'intersects'.
- **mode** (str) - Optional - Distance calculation mode ('poly-poly', 'boxpoint-boxpoint', 'box-box'). Defaults to 'box-box'.
- **as_wkb** (bool) - Optional - Return geometries as WKB bytes if True. Defaults to False.

### Request Example
{
  "distance": 10.0,
  "mode": "poly-poly",
  "geometry_predicate": "intersects"
}

### Response
#### Success Response (200)
- **dict** (dict[str, dict[str, Annotation]]) - A dictionary mapping annotation keys to their nearby neighbors.

#### Response Example
{
  "annotation_id_1": {
    "neighbor_id_a": { "id": "neighbor_id_a", "geometry": "..." }
  }
}
```

--------------------------------

### GET /config/ui

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/docs/visualization.rst

Explains the structure of the JSON configuration file used to control UI behavior, initial slide views, and annotation rendering styles.

```APIDOC
## GET /config/ui

### Description
Retrieves or defines the UI configuration settings for the overlay viewer, including initial views, auto-load preferences, and color mapping for annotation types.

### Method
GET

### Endpoint
/config/ui

### Request Body
- **initial_views** (object) - Optional - Mapping of slide names to coordinate bounds.
- **auto_load** (int) - Optional - Boolean flag (0 or 1) to enable automatic annotation loading.
- **color_dict** (object) - Optional - Mapping of annotation types to RGBA color arrays.

### Request Example
{
  "initial_views": {"slideA": [0, 19000, 35000, 44000]},
  "auto_load": 1,
  "color_dict": {"typeA": [252, 161, 3, 255]}
}

### Response
#### Success Response (200)
- **config** (object) - The current UI configuration object.
```

--------------------------------

### Initialize and Run Semantic Segmentation

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/07-advanced-modeling.ipynb

Sets up the prediction directory, initializes the BlurModel and SemanticSegmentor, and executes the inference pipeline on a WSI file.

```python
wsi_prediction_dir = "./tmp/wsi_prediction/"
rmdir(wsi_prediction_dir)
model = BlurModel()
segmentor = SemanticSegmentor(model=model, num_workers=WORKERS, batch_size=1)
wsi_output = segmentor.run(
    [wsi_file_name],
    patch_mode=False,
    device=device,
    ioconfig=iostate,
    save_dir=wsi_prediction_dir,
    overwrite=True,
)
```

--------------------------------

### Format Single File with Black

Source: https://github.com/tissueimageanalytics/tiatoolbox/wiki/Code-Formatting

This command formats a single Python file using the Black code formatter. Ensure Black is installed and accessible in your environment.

```bash
black file.py
```

--------------------------------

### Save Annotations to SQLite Store

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/docs/visualization.rst

Demonstrates how to initialize an annotation store, add annotations, create database indices for performance, and persist the data to a file.

```python
db.append_many(annotations)
db.create_index("area", '"area"')
db.dump("path/to/annotations.db")
```

--------------------------------

### Initialize Temporary Directory

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/10-wsi-registration.ipynb

Defines a global directory for storing temporary files and provides a helper function to clean up existing directories before starting a new process.

```python
warnings.filterwarnings("ignore")
global_save_dir = Path("./tmp/")


def rmdir(dir_path: str | Path) -> None:
    """Helper function to delete directory."""
    if Path(dir_path).is_dir():
        shutil.rmtree(dir_path)
        logger.info("Removing directory %s", dir_path)


rmdir(global_save_dir)  # remove  directory if it exists from previous runs
global_save_dir.mkdir()
logger.info("Creating new directory %s", global_save_dir)
```

--------------------------------

### Initialize Repository Fork and Remotes

Source: https://github.com/tissueimageanalytics/tiatoolbox/wiki/Workflow

Commands to clone a forked repository and configure the upstream remote to track the main Tiatoolbox repository.

```bash
git clone <url-to-your-fork>
cd tiatoolbox
git remote add upstream <url-to-your-fork>
```

--------------------------------

### Create a new Git branch

Source: https://github.com/tissueimageanalytics/tiatoolbox/wiki/Branching

Command to create and switch to a new branch based on the current branch. This is used for starting work on features, bug fixes, or other tasks.

```bash
git checkout -b feature-shiny-new
```

--------------------------------

### Build and Manage Docker Containers

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/docs/installation.rst

Standard console commands to build a Docker image from a Dockerfile, verify its creation, and execute a container instance.

```console
docker build -t <IMAGE_NAME> .
docker images
docker run -it --rm --name <CONTAINER_NAME> <IMAGE_NAME>
docker exec -it <CONTAINER_NAME> bash
```

--------------------------------

### Configuring IOSegmentor for TIAToolbox

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/07-advanced-modeling.ipynb

Demonstrates how to define the input and output resolution, patch shapes, and stride settings using the IOSegmentorConfig class for semantic segmentation tasks.

```python
iostate = IOSegmentorConfig(
    input_resolutions=[{"units": "mpp", "resolution": 1.0}],
    output_resolutions=[{"units": "mpp", "resolution": 1.0}],
    patch_input_shape=[512, 512],
    patch_output_shape=[512, 512],
    stride_shape=[512, 512],
    save_resolution={"units": "mpp", "resolution": 1.0}
)
```

--------------------------------

### Get and Sort File Sizes

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/benchmarks/annotation_store.ipynb

This code snippet retrieves the size of various annotation files and then sorts them in ascending order based on their file size. This is useful for comparing storage requirements.

```python
file_sizes = {
    path: path.stat().st_size for path in [Path.cwd() / name for name in file_names]
}

file_sizes = dict(sorted(file_sizes.items(), key=lambda x: x[1]))
```

--------------------------------

### Stain Normalization Setup

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/full-pipelines/slide-graph.ipynb

Sets up stain normalization by defining a target image and a normalizer. The `stain_norm_func` is a helper function to apply the transformation to input images, reducing staining variations in histopathology images.

```python
target_image = stain_norm_target()
stain_normalizer = get_normalizer("vahadane")
stain_normalizer.fit(target_image)

def stain_norm_func(img: np.ndarray) -> np.ndarray:
    """Helper function to perform stain normalization."""
    return stain_normalizer.transform(img)
```

--------------------------------

### Implement Custom Stain Normalization Matrix

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/02-stain-normalization.ipynb

Shows how to create a custom normalizer using a specific stain matrix, such as Feulgen + Light Green, and compare the results against standard methods like Vahadane.

```python
stain_matrix = skimage.color.fgx_from_rgb[:2]
custom_normalizer = stainnorm.CustomNormalizer(stain_matrix)
custom_normalizer.fit(target_image)

vahadane_normalizer = stainnorm.VahadaneNormalizer()
vahadane_normalizer.fit(target_image)

normed_sample1 = custom_normalizer.transform(sample.copy())
normed_sample2 = stain_normalizer.transform(sample.copy())

plt.subplot(2, 2, 1)
plt.imshow(sample)
plt.title("Source Image")
plt.axis("off")
plt.subplot(2, 2, 3)
plt.imshow(target_image)
plt.title("Target Image")
plt.axis("off")
plt.subplot(2, 2, 2)
plt.imshow(normed_sample1)
plt.title("Custom Stain Matrix")
plt.axis("off")
plt.subplot(2, 2, 4)
plt.imshow(normed_sample2)
plt.title("Vahadane")
plt.axis("off")
plt.show()
```

--------------------------------

### Configure and Execute Model Training Loop

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/full-pipelines/slide-graph.ipynb

This snippet demonstrates how to load data splits and scalers, define architecture and optimization hyperparameters, and iterate through data splits to execute training runs.

```python
splits = joblib.load(SPLIT_PATH)
node_scaler = joblib.load(SCALER_PATH)
loader_kwargs = {
    "num_workers": 8,
    "batch_size": 16,
}
arch_kwargs = {
    "dim_features": NUM_NODE_FEATURES,
    "dim_target": 1,
    "layers": [16, 16, 8],
    "dropout": 0.5,
    "pooling": "mean",
    "conv": "EdgeConv",
    "aggr": "max",
}
optim_kwargs = {
    "lr": 1.0e-3,
    "weight_decay": 1.0e-4,
}

if not MODEL_DIR.exists():
    for split_idx, split in enumerate(splits):
        new_split = {
            "train": split["train"],
            "infer-train": split["train"],
            "infer-valid-A": split["valid"],
            "infer-valid-B": split["test"],
        }
        split_save_dir = f"{MODEL_DIR}/{split_idx:02d}/"
        rm_n_mkdir(split_save_dir)
        reset_logging(split_save_dir)
        run_once(
            new_split,
            NUM_EPOCHS,
            save_dir=split_save_dir,
            arch_kwargs=arch_kwargs,
            loader_kwargs=loader_kwargs,
            optim_kwargs=optim_kwargs,
        )
```

--------------------------------

### Download Sample WSI Files

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/10-wsi-registration.ipynb

Downloads sample Whole Slide Images from a remote repository using the requests library and saves them to the local temporary directory for processing.

```python
fixed_img_file_name = global_save_dir / "fixed_image.tif"
moving_img_file_name = global_save_dir / "moving_image.tif"

# Downloading fixed image from COMET dataset
r = requests.get(
    "https://huggingface.co/datasets/TIACentre/TIAToolBox_Remote_Samples/resolve/main/testdata/registration/CRC/06-18270_5_A1MLH1_1.tif",
    timeout=120,  # 120s
)
with fixed_img_file_name.open("wb") as f:
    f.write(r.content)

# Downloading moving image from COMET dataset
r = requests.get(
    "https://huggingface.co/datasets/TIACentre/TIAToolBox_Remote_Samples/resolve/main/testdata/registration/CRC/06-18270_5_A1MSH2_1.tif",
    timeout=120,  # 120s
)
with moving_img_file_name.open("wb") as f:
    f.write(r.content)
```

--------------------------------

### Download Sample WSI with Hugging Face Hub (Python)

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/11-import-foundation-models.ipynb

Downloads a sample histology whole slide image (WSI) for feature extraction demonstration. It ensures a temporary directory exists and uses `hf_hub_download` to fetch the file. This download is needed once per Colab session.

```python
from pathlib import Path
from huggingface_hub import hf_hub_download

global_save_dir = "./tmp"
if not Path(global_save_dir).exists():
    Path(global_save_dir).mkdir(exist_ok=True)

# Downloading sample image tile
wsi_path = hf_hub_download(
    repo_id="TIACentre/TIAToolBox_Remote_Samples",
    filename="sample_wsis/TCGA-3L-AA1B-01Z-00-DX1.8923A151-A690-40B7-9E5A-FCBEDFC2394F.svs",
    repo_type="dataset",
    local_dir=global_save_dir,
)
```

--------------------------------

### Inference Step for Tiatoolbox Models

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/inference-pipelines/slide-graph.ipynb

Performs a single inference step for a WSI graph model. It sets the model to evaluation mode, disables gradient computation, and performs a forward pass to get predictions. It can optionally return labels if present in the batch data.

```python
    # Run one inference step
    @staticmethod
    def infer_batch(
        model: nn.Module,
        batch_data: torch.Tensor,
        device: str,
    ) -> list:
        """Model inference."""
        wsi_graphs = batch_data["graph"].to(device)
        model = model.to(device)

        # Data type conversion
        wsi_graphs.x = wsi_graphs.x.type(torch.float32)

        # Inference mode
        model.eval()
        # Do not compute the gradient (not training)
        with torch.inference_mode():
            wsi_output, _ = model(wsi_graphs)

        wsi_output = wsi_output.cpu().numpy()
        # Output should be a single tensor or scalar
        if "label" in batch_data:
            wsi_labels = batch_data["label"]
            wsi_labels = wsi_labels.cpu().numpy()
            return wsi_output, wsi_labels
        return [wsi_output]
```

--------------------------------

### Run TIAToolbox Semantic Segmentor for Tissue Mask

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/10-wsi-registration.ipynb

This code snippet initializes the SemanticSegmentor with a pre-trained tissue mask model and runs it on input images to generate tissue masks. It handles directory setup, model configuration, and specifies parameters for patch processing and device usage. The output masks are saved to a specified directory.

```python
save_dir = global_save_dir / "tissue_mask"
if save_dir.exists():
    shutil.rmtree(save_dir, ignore_errors=False, onerror=None)

segmentor = SemanticSegmentor(
    model="unet_tissue_mask_tsef",
    num_workers=0,
    batch_size=4,
)

output = segmentor.run(
    [
        global_save_dir / "fixed.png",
        global_save_dir / "moving.png",
    ],
    save_dir=save_dir,
    patch_mode=False,
    resolution=1.0,
    units="baseline",
    patch_input_shape=(1024, 1024),
    patch_output_shape=(512, 512),
    stride_shape=(512, 512),
    device=device,
    auto_get_mask=False,  # We need to generate the tissue mask for registration
)
```

--------------------------------

### Initialize TIAToolbox and Plotting Environment

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/01-wsi-reading.ipynb

Configures logging, imports required TIAToolbox modules, and sets Matplotlib parameters for high-quality visualization.

```python
import logging
if logging.getLogger().hasHandlers():
    logging.getLogger().handlers.clear()
from pprint import pprint
import matplotlib as mpl
import matplotlib.pyplot as plt
from tiatoolbox import logger
from tiatoolbox.data import small_svs
from tiatoolbox.wsicore.wsireader import WSIReader
mpl.rcParams["figure.dpi"] = 150
mpl.rcParams["figure.facecolor"] = "white"
plt.rcParams.update({"font.size": 5})
```

--------------------------------

### Download Sample Datasets

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/examples/07-advanced-modeling.ipynb

Downloads sample image tiles and whole-slide images from the TIAToolbox remote repository for testing and demonstration purposes.

```python
img_file_name = Path("./tmp/sample_tile.tif")
wsi_file_name = Path("./tmp/sample_wsi.svs")
logger.info("Download has started. Please wait...")
download_data("https://huggingface.co/datasets/TIACentre/TIAToolBox_Remote_Samples/resolve/main/sample_imgs/tile_mif.tif", img_file_name)
download_data("https://huggingface.co/datasets/TIACentre/TIAToolBox_Remote_Samples/resolve/main/sample_wsis/wsi_2000x2000_blur.svs", wsi_file_name)
```

--------------------------------

### Configure IOSegmentor for PanNuke Dataset (Python)

Source: https://github.com/tissueimageanalytics/tiatoolbox/blob/develop/docs/pretrained.rst

Sets up the input and output configuration for the IOSegmentor using parameters suitable for the PanNuke dataset. This includes defining input/output resolutions, margin, tile shape, patch dimensions, stride, and save resolution.

```python
from tiatoolbox.models import IOSegmentorConfig
ioconfig = IOSegmentorConfig(
    input_resolutions=[
        {'units': 'mpp', 'resolution': 0.25}
    ],
    output_resolutions=[
        {'units': 'mpp', 'resolution': 0.25},
        {'units': 'mpp', 'resolution': 0.25},
        {'units': 'mpp', 'resolution': 0.25}
    ],
    margin=128,
    tile_shape=[1024, 1024],
    patch_input_shape=(256, 256),
    patch_output_shape=(164, 164),
    stride_shape=(164, 164),
    save_resolution={'units': 'mpp', 'resolution': 0.25}
)
```