Histolytics

https://hautaniemilab.github.io/histolytics/
Admin
Histolytics is a Python library for scalable panoptic spatial analysis of histological whole slide...
Tokens:220,014
Snippets:1,322
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Histolytics using pip

Source: https://hautaniemilab.github.io/histolytics/installation

Install the Histolytics library using pip for a standard installation.

```bash
pip install histolytics

```

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

### Install Histolytics from Source using uv

Source: https://hautaniemilab.github.io/histolytics/installation

Install the latest development version of Histolytics directly from its GitHub repository using uv.

```bash
uv pip install git+https://github.com/HautaniemiLab/histolytics.git

```

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

### Install Seaborn

Source: https://hautaniemilab.github.io/histolytics/user_guide/workflows/nuclear_morphology

Install the seaborn library for visualizing results. This is a prerequisite for certain visualization steps.

```python
# Install seaborn for visualizing the results.
# !pip install seaborn

```

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

### Install Required Libraries

Source: https://hautaniemilab.github.io/histolytics/user_guide/seg/finetuning

Installs necessary libraries for the workflow, including torchdata and tables.

```python
# Some installations
# !pip install torchdata
# !pip install tables

```

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

### Install Required Libraries

Source: https://hautaniemilab.github.io/histolytics/user_guide/seg/panoptic_segmentation

Installs necessary libraries for the workflow, including albumentations and cucim-cu12.

```python
# !pip install albumentations
# !pip install cucim-cu12
```

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

### Initialize WSIPanopticSegmenter

Source: https://hautaniemilab.github.io/histolytics/api/wsi/wsi_segmenter

Initializes the WSIPanopticSegmenter with a slide reader, segmentation model, WSI level, tile coordinates, batch size, and optional transformations. It warns if the albumentations library is not installed when transforms are provided.

```python
class WsiPanopticSegmenter:
    def __init__(
        self,
        reader: SlideReader,
        model: BaseModelPanoptic,
        level: int,
        coordinates: List[Tuple[int, int, int, int]],
        batch_size: int = 8,
        transforms: A.Compose = None,
    ) -> None:
        """Class handling the panoptic segmentation of WSIs.

        Parameters:
            reader (SlideReader):
                The `SlideReader` object for reading the WSIs.
            model (BaseModelPanoptic):
                The model for segmentation.
            level (int):
                The level of the WSI to segment.
            coordinates (List[Tuple[int, int, int, int]]):
                The bounding box coordinates from `reader.get_tile_coordinates()`.
            batch_size (int):
                The batch size for the DataLoader.
            transforms (A.Compose):
                The transformations for the input patches.
        """
        if not has_albu:
            warnings.warn(
                "The albumentations lib is needed to apply transformations. "
                "Setting transforms=None"
            )
            transforms = None

        self.batch_size = batch_size
        self.coordinates = coordinates
        self.model = model

        self.dataset = WSIDatasetInfer(
            reader, coordinates, level=level, transforms=transforms
        )
        self.dataloader = DataLoader(
            self.dataset, batch_size=batch_size, shuffle=False, pin_memory=True
        )
        self._has_processed = False
```

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

### Example Usage of inst2gdf

Source: https://hautaniemilab.github.io/histolytics/api/utils/inst2gdf

Demonstrates how to load instance and type masks and convert them into a GeoDataFrame using the inst2gdf function. Shows the head of the resulting GeoDataFrame.

```python
from histolytics.utils.raster import inst2gdf
from histolytics.data import hgsc_cancer_inst_mask, hgsc_cancer_type_mask
# load raster masks
inst_mask = hgsc_cancer_inst_mask()
type_mask = hgsc_cancer_type_mask()
# convert to GeoDataFrame
gdf = inst2gdf(inst_mask, type_mask)
print(gdf.head(3))
```

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

### Get Transform Init Args Names

Source: https://hautaniemilab.github.io/histolytics/api/transforms/minmax

Retrieves the names of the arguments used to initialize the MinMaxNormalization transform.

```APIDOC
## get_transform_init_args_names

```python
get_transform_init_args_names()
```

### Description

Get the names of the transformation arguments.
```

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

### Example Usage of CellViT Post-processing

Source: https://hautaniemilab.github.io/histolytics/api/models/cellvit_panoptic

Demonstrates how to set the model to inference mode, obtain predictions, and then apply post-processing with specific parameters for asynchronous parallel execution.

```python
my_model.set_inference_mode()
x = my_model.predict(x=image, use_sliding_win=False)
x = my_model.post_process(
    x,
    use_async_postproc=True,
    start_method="threading",
    n_jobs=4,
)
```

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

### Get Transform Init Args Names

Source: https://hautaniemilab.github.io/histolytics/api/transforms/norm

Retrieves the names of the arguments used for initializing the Normalization transform.

```APIDOC
## get_transform_init_args_names 

### Description
Retrieves the names of the arguments used for initializing the Normalization transform.

### Returns
- **list** - A list of strings, where each string is the name of an initialization argument.
```

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

### Example: Compute Immune Density on H3 Grid

Source: https://hautaniemilab.github.io/histolytics/api/spatial_agg/grid_agg

This example demonstrates how to compute immune density within H3 grid cells using the grid_aggregate function. It involves loading sample data, defining a custom metric function, generating an H3 grid, and then aggregating nuclei data onto this grid.

```python
from histolytics.spatial_ops.h3 import h3_grid
from histolytics.data import cervix_tissue, cervix_nuclei
from histolytics.spatial_agg.grid_agg import grid_aggregate

# Define the immune density metric function
def immune_density(nuclei):
    if "inflammatory" in nuclei.value_counts("class_name"):
        frac = nuclei.value_counts("class_name", normalize=True)["inflammatory"]
    else:
        frac = 0
    return float(frac)

# Load the cervix nuclei and tissue data
nuc = cervix_nuclei()
tis = cervix_tissue()
# get the stromal tissue
stroma = tis[tis["class_name"] == "stroma"]
# Fit an H3 grid to the stromal tissue
h3_gr = h3_grid(stroma, resolution=9)
# Compute the immune density within the H3 grid cells
grid = grid_aggregate(
    objs=nuc,
    grid=h3_gr,
    metric_func=immune_density,
    new_col_names=["immune_density"],
    predicate="intersects",
    num_processes=1,
)
print(grid.head(3))
```

```python
geometry  immune_density
8982a939503ffff  POLYGON ((6672.79721 859.08743, 6647.90711 661...        0.500000
8982a939877ffff  POLYGON ((2556.61731 5658.46273, 2581.53692 58...        0.621951
8982a939c4bffff  POLYGON ((4546.44516 4059.58249, 4366.53531 39...        0.045455
```

```python
# Plot the results
ax = tis.plot(column="class_name", figsize=(5, 5), aspect=1, alpha=0.5)
h3_gr.plot(
    ax=ax,
    column="immune_density",
    legend=True,
    facecolor="none",
    lw=1,
    cmap="turbo",
)
ax.set_axis_off()
```

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

### Cellpose Panoptic Post-processing Example

Source: https://hautaniemilab.github.io/histolytics/api/models/cellpose_panoptic

Demonstrates how to use the `post_process` function after running a prediction. It shows setting inference mode, performing prediction, and then applying post-processing with specified parameters.

```python
>>> my_model.set_inference_mode()
>>> x = my_model.predict(x=image, use_sliding_win=False)
>>> x = my_model.post_process(
...     x,
...     use_async_postproc=True,
...     start_method="threading",
...     n_jobs=4,
... )
```

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

### List Available timm Models

Source: https://hautaniemilab.github.io/histolytics/user_guide/seg/backbones

Use this snippet to retrieve a list of all available pre-trained models from the timm library. Ensure timm is installed.

```python
import timm

timm.list_models()
```

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

### Load Example Nuclei and Tissue Data

Source: https://hautaniemilab.github.io/histolytics/user_guide/workflows/tls_lymphoid_aggregate

Loads example nuclei and tissue segmentation data for analysis. Visualizes the segmented nuclei overlaid on the tissue structure.

```python
from histolytics.data import hgsc_nuclei_wsi, hgsc_tissue_wsi

nuc = hgsc_nuclei_wsi()
tis = hgsc_tissue_wsi()

ax = tis.plot(figsize=(10, 10), column="class_name", alpha=0.2, aspect=1, legend=True)
nuc.plot(ax=ax, column="class_name", aspect=1)
ax.set_axis_off()

```

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

### Initialize WsiPanopticSegmenter

Source: https://hautaniemilab.github.io/histolytics/user_guide/seg/panoptic_segmentation

Initializes the WsiPanopticSegmenter with a SlideReader, model, and image transformations. The MinMaxNormalization transform is recommended as it was used during model training.

```python
import albumentations as A
from histolytics.transforms import MinMaxNormalization
from histolytics.wsi.wsi_segmenter import WsiPanopticSegmenter

# We will use the MinMaxNormalization transform to normalize the input images
# This was also used in the training of the model
img_transforms = A.Compose([MinMaxNormalization()])

wsi_segmenter = WsiPanopticSegmenter(
    reader=reader,
    model=model,
    level=0,  # 20x magnification
    coordinates=sub_coords,
    batch_size=8,
    transforms=img_transforms,
)
```

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

### __init__

Source: https://hautaniemilab.github.io/histolytics/api/losses/ssim

Initializes the SSIM loss module. This is used to set up the parameters for calculating structural similarity.

```APIDOC
## __init__

### Description
Initializes the SSIM loss module with specified window size and contrast sensitivity return option.

### Parameters
* **window_size** (int) - Optional - Size of the gaussian kernel. Defaults to `11`.
* **return_cs** (bool) - Optional - Return also the the contrast sensitivity coeff. Defaults to `False`.
```

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

### SlideReader.suffix

Source: https://hautaniemilab.github.io/histolytics/api/wsi/slide_reader

Gets the file extension of the slide.

```APIDOC
## suffix

### Description
Gets the file extension of the slide.

### Property
suffix: str
```

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

### SlideReader.name

Source: https://hautaniemilab.github.io/histolytics/api/wsi/slide_reader

Gets the filename of the slide without its extension.

```APIDOC
## name

### Description
Gets the filename of the slide without its extension.

### Property
name: str
```

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

### Initialize Model, Transforms, Datasets, and Loss Functions

Source: https://hautaniemilab.github.io/histolytics/user_guide/seg/finetuning

Sets up the CellposePanoptic model, image and instance transformations, training and validation datasets/dataloaders, and a multi-task loss function for finetuning.

```python
import torch.nn as nn
from torch.optim.lr_scheduler import CosineAnnealingLR

from histolytics.torch_datasets.h5dataset import DatasetH5
from histolytics.losses import CELoss, DiceLoss, JointLoss, MultiTaskLoss
from histolytics.models.cellpose_panoptic import CellposePanoptic
from histolytics.transforms import (
    AlbuStrongAugment,
    CellposeTransform,
    MinMaxNormalization,
    ApplyEach,
)

# panoptils (refined) classes
nuclei_classes = {
    "background": 0,
    "neoplastic": 1,
    "stromal": 2,
    "inflammatory": 3,
    "epithelial": 4,
    "other": 5,
    "unknown": 6,
}

tissue_classes = {
    "background": 0,
    "tumor": 1,
    "stroma": 2,
    "epithelium": 3,
    "junk/debris": 4,
    "blood": 5,
    "other": 6,
}


# Quick wrapper for MSE loss to make it fit the JointLoss API
class MSELoss(nn.Module):
    def __init__(self, **kwargs) -> None:
        super().__init__()

    def forward(
        self,
        yhat: torch.Tensor,
        target: torch.Tensor,
        **kwargs
    ) -> torch.Tensor:
        return F.mse_loss(yhat, target, reduction="mean").float()


batch_size = 8
in_keys = ("image", "sem_mask", "inst_mask", "type_mask")
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

# init  CellposePanoptic model
cpose_panoptic = CellposePanoptic(
    n_nuc_classes=len(nuclei_classes),
    n_tissue_classes=len(tissue_classes),
    enc_name="efficientnet_b5",  # you can change this to any supported encoder
    enc_pretrain=True,
)
model = cpose_panoptic.model.to(device)

# init training transforms
img_transforms = A.Compose(
    [
        A.HorizontalFlip(p=0.33),
        A.VerticalFlip(p=0.33),
        AlbuStrongAugment(),
        MinMaxNormalization(),
    ]
)

inst_transforms = ApplyEach([CellposeTransform(deduplicate=False)], as_list=True)

# init val dataset and dataloader
ds_train = DatasetH5(
    Path().home() / "panoptils_refined" / "panoptils_train_p224_224.h5",
    img_key="image",
    inst_keys=["inst_mask"],
    mask_keys=["type_mask", "sem_mask"],
    transforms=img_transforms,
    inst_transforms=inst_transforms,
)

loader_train = NodesDataLoader(
    ds_train,
    batch_size,
    shuffle=False,
    num_workers=batch_size,
    pin_memory=True,
    drop_last=True,
)
# init train dataset and dataloader
ds_val = DatasetH5(
    Path().home() / "panoptils_refined" / "panoptils_val_p224_224.h5",
    img_key="image",
    inst_keys=["inst_mask"],
    mask_keys=["type_mask", "sem_mask"],
    transforms=img_transforms,
    inst_transforms=inst_transforms,
)

loader_val = NodesDataLoader(
    ds_val,
    batch_size,
    shuffle=True,
    num_workers=batch_size,
    pin_memory=True,
    drop_last=True,
)

# init training multi-task loss
# The losses are defined for each task, and the weights are set for each task.
losses = {
    "cellpose": JointLoss([MSELoss()]),
    "type_mask": JointLoss([CELoss(apply_sd=True), DiceLoss()]),
    "sem_mask": JointLoss([CELoss(apply_sd=True), DiceLoss()]),
}
loss_weights = {"cellpose": 1.0, "type_mask": 1.0, "sem_mask": 2.0}
multitask_loss = MultiTaskLoss(losses, loss_weights=loss_weights).to(device)

# optimizer and lr scheduler
optimizer = torch.optim.AdamW(params=model.parameters(), lr=0.0001)
lr_scheduler = CosineAnnealingLR(optimizer, T_max=1000, eta_min=0, last_epoch=-1)

```

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

### SlideReader.level_count

Source: https://hautaniemilab.github.io/histolytics/api/wsi/slide_reader

Gets the total number of pyramid levels in the slide.

```APIDOC
## level_count

### Description
Gets the total number of pyramid levels in the slide.

### Property
level_count: int
```

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

### Setup for KMeans Clustering and Silhouette Score

Source: https://hautaniemilab.github.io/histolytics/user_guide/workflows/clustering_desmoplasia

Imports necessary libraries, defines helper functions for exporting legends and calculating silhouette scores, and sets scikit-learn's output to pandas DataFrames. This prepares the environment for clustering.

```python
import matplotlib.pyplot as plt
from sklearn.cluster import KMeans
from sklearn.metrics import silhouette_score
from sklearn.preprocessing import minmax_scale
from sklearn import set_config


set_config(transform_output="pandas")  # return pandas dataframes


def export_legend(legend, filename="legend.png", expand=[-5, -5, 5, 5]):
    fig = legend.figure
    fig.canvas.draw()
    bbox = legend.get_window_extent()
    bbox = bbox.from_extents(*(bbox.extents + np.array(expand)))
    bbox = bbox.transformed(fig.dpi_scale_trans.inverted())
    fig.savefig(filename, dpi="figure", bbox_inches=bbox)


# helper function to calculate Silhouette score for a range of clusters
def get_silhouette(range: range, clust_vars):
    sil_score = []
    for i in range:
        kmeans = KMeans(n_clusters=i, random_state=42)
        kmeans.fit(clust_vars)
        labels = kmeans.labels_

        # calculate Silhouette score
        score = silhouette_score(
            clust_vars, labels, metric="euclidean", sample_size=1000, random_state=200
        )
        sil_score.append(score)

    return sil_score
```

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

### SlideReader.backend_name

Source: https://hautaniemilab.github.io/histolytics/api/wsi/slide_reader

Gets the name of the backend used for reading the slide.

```APIDOC
## backend_name

### Description
Gets the name of the backend used for reading the slide.

### Property
backend_name: str
```

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

### Initialize Density Clustering Algorithm

Source: https://hautaniemilab.github.io/histolytics/api/spatial_clust/density_clustering

Selects and initializes a density-based clustering algorithm (ADBSCAN, DBSCAN, HDBSCAN, or OPTICS) based on the 'method' parameter. Requires 'eps', 'min_samples', and 'num_processes' as input.

```python
if method == "adbscan":
        xy = pd.DataFrame({"X": xy[:, 0], "Y": xy[:, 1]})
        clusterer = ADBSCAN(
            eps=eps, min_samples=min_samples, n_jobs=num_processes, **kwargs
        )
    elif method == "dbscan":
        clusterer = DBSCAN(
            eps=eps, min_samples=min_samples, n_jobs=num_processes, **kwargs
        )
    elif method == "hdbscan":
        clusterer = HDBSCAN(min_samples=min_samples, n_jobs=num_processes, **kwargs)
    elif method == "optics":
        clusterer = OPTICS(
            max_eps=eps, min_samples=min_samples, n_jobs=num_processes, **kwargs
        )

    labels = clusterer.fit(xy).labels_.astype(int)

    return labels
```

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

### SlideReader.path

Source: https://hautaniemilab.github.io/histolytics/api/wsi/slide_reader

Gets the full file path of the slide image.

```APIDOC
## path

### Description
Gets the full file path of the slide image.

### Property
path: str
```

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

### SlideReader.level_dimensions

Source: https://hautaniemilab.github.io/histolytics/api/wsi/slide_reader

Gets the image dimensions (height, width) for each pyramid level.

```APIDOC
## level_dimensions

### Description
Gets the image dimensions (height, width) for each pyramid level.

### Property
level_dimensions: dict[int, tuple[int, int]]
```

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

### __init__

Source: https://hautaniemilab.github.io/histolytics/api/losses/bce

Initializes the Binary Cross Entropy loss function. It supports several optional regularization and weighting strategies.

```APIDOC
## __init__

### Description
Initializes the Binary Cross Entropy loss function with options for spectral decoupling, label smoothing, spatially varying label smoothing, masking, edge weighting, and class weighting.

### Parameters
- **apply_sd** (bool, optional): If True, Spectral decoupling regularization will be applied to the loss matrix. Defaults to False.
- **apply_ls** (bool, optional): If True, Label smoothing will be applied to the target. Defaults to False.
- **apply_svls** (bool, optional): If True, spatially varying label smoothing will be applied to the target. Defaults to False.
- **apply_mask** (bool, optional): If True, a mask will be applied to the loss matrix. Mask shape: (B, H, W). Defaults to False.
- **edge_weight** (float, optional): Weight that is added to object borders. Defaults to None.
- **class_weights** (torch.Tensor, optional): Class weights. A tensor of shape (n_classes,). Defaults to None.
```

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

### SlideReader.dimensions

Source: https://hautaniemilab.github.io/histolytics/api/wsi/slide_reader

Gets the image dimensions (height, width) at level 0.

```APIDOC
## dimensions

### Description
Gets the image dimensions (height, width) at level 0.

### Property
dimensions: tuple[int, int]
```

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

### SlideReader.level_downsamples

Source: https://hautaniemilab.github.io/histolytics/api/wsi/slide_reader

Gets the image downsample factors (height, width) for each pyramid level.

```APIDOC
## level_downsamples

### Description
Gets the image downsample factors (height, width) for each pyramid level.

### Property
level_downsamples: dict[int, tuple[float, float]]
```

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

### Initialize SlideReader with CUCIM Backend

Source: https://hautaniemilab.github.io/histolytics/user_guide/seg/selecting_tiles

Initializes the SlideReader for a specified WSI file using the CUCIM backend. Ensure the test WSIs are downloaded and accessible.

```python
from histolytics.wsi.slide_reader import SlideReader
from pathlib import Path

in_dir = Path().home() / "openslide_test"
slide = in_dir / "CMU-1-JP2K-33005.svs"
reader = SlideReader(slide, backend="CUCIM")

```

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

### __init__

Source: https://hautaniemilab.github.io/histolytics/api/transforms/apply_each

Initializes the ApplyEach transform. This transform applies a list of transforms to the input non-sequentially and returns outputs for each transform.

```APIDOC
## __init__

### Description
Initializes the ApplyEach transform. This transform applies a list of transforms to the input non-sequentially and returns outputs for each transform.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **transforms** (List[Any]) - Required - List of transforms to apply.
- **p** (float) - Optional - Probability of applying the transform. Default is 1.0.
- **as_list** (bool) - Optional - Return the outputs as list with shapes (H, W, C). Default is False.
```

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

### SSIM Initialization

Source: https://hautaniemilab.github.io/histolytics/api/losses/ssim

Initializes the SSIM loss function with specified window size and an option to return contrast sensitivity coefficients.

```python
__init__(window_size: int = 11, return_cs: bool = False, **kwargs) -> None


```

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

### Get MinMaxNormalization Argument Names

Source: https://hautaniemilab.github.io/histolytics/api/transforms/minmax

Retrieves the names of the arguments used to initialize the MinMaxNormalization transform.

```python
from histolytics.transforms import MinMaxNormalization

arg_names = MinMaxNormalization.get_transform_init_args_names()
```

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

### WsiPanopticSegmenter Initialization

Source: https://hautaniemilab.github.io/histolytics/api/wsi/wsi_segmenter

Initializes the WsiPanopticSegmenter with the necessary components for WSI segmentation. This includes the slide reader, segmentation model, desired level, tile coordinates, batch size, and optional image transformations.

```APIDOC
## class histolytics.wsi.wsi_segmenter.WsiPanopticSegmenter

### Description
Class handling the panoptic segmentation of WSIs.

### Parameters
* **reader** (SlideReader) - The `SlideReader` object for reading the WSIs.
* **model** (BaseModelPanoptic) - The model for segmentation.
* **level** (int) - The level of the WSI to segment.
* **coordinates** (List[Tuple[int, int, int, int]]) - The bounding box coordinates from `reader.get_tile_coordinates()`.
* **batch_size** (int) - Optional. The batch size for the DataLoader. Defaults to 8.
* **transforms** (A.Compose) - Optional. The transformations for the input patches. Defaults to None.
```

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

### Run Inference on a Single Image

Source: https://hautaniemilab.github.io/histolytics/user_guide/seg/getting_started_seg

Prepare an image by applying transformations like resizing and normalization, then run inference using the loaded model.

```python
from albumentations import Resize, Compose
from histolytics.utils import FileHandler
from histolytics.transforms import MinMaxNormalization

model.set_inference_mode()

# Resize to multiple of 32 of your own choosing
transform = Compose([Resize(1024, 1024), MinMaxNormalization()])

im = FileHandler.read_img(IMG_PATH)
im = transform(image=im)["image"]

prob = model.predict(im)
out = model.post_process(prob)
# out = {"nuc": [(nuc instances (H, W), nuc types (H, W))], "cyto": None, "tissue": None}


```

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

### Get Normalization Transform Argument Names

Source: https://hautaniemilab.github.io/histolytics/api/transforms/norm

Retrieves the names of the arguments used to initialize the normalization transformation.

```python
get_transform_init_args_names()
```

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

### SlideReader.data_bounds

Source: https://hautaniemilab.github.io/histolytics/api/wsi/slide_reader

Gets the data bounds defined by xywh-coordinates at level 0. This may differ from actual image dimensions for certain formats.

```APIDOC
## data_bounds

### Description
Gets the data bounds defined by xywh-coordinates at level 0. This may differ from actual image dimensions for certain formats.

### Property
data_bounds: tuple[int, int, int, int]
```

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

### __init__

Source: https://hautaniemilab.github.io/histolytics/api/losses/multi_task_loss

Initializes the MultiTaskLoss module. It takes a dictionary of head losses and an optional dictionary of loss weights to combine them into a single loss function.

```APIDOC
## __init__

### Description
Initializes the MultiTaskLoss module. It takes a dictionary of head losses and an optional dictionary of loss weights to combine them into a single loss function.

### Parameters
#### Parameters
- **head_losses** (Dict[str, Module]) - Required - Dictionary of head names mapped to a loss module. e.g. {"inst": JointLoss(MSE(), Dice()), "type": Dice()}.
- **loss_weights** (Dict[str, float]) - Optional - Dictionary of head names mapped to the weight used for that head loss. Defaults to None.

### Raises
- **ValueError**: If the input arguments have different lengths or mismatching keys.
```

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

### Initialize CellposePanoptic Model and Training Components

Source: https://hautaniemilab.github.io/histolytics/user_guide/seg/finetuning

Sets up the CellposePanoptic model, defines nuclei and tissue class mappings, and initializes training-specific transformations for image and instance masks. This is a prerequisite for training or finetuning.

```python
import torch.nn as nn
from torch.optim.lr_scheduler import CosineAnnealingLR
from histolytics.torch_datasets.h5dataset import DatasetH5
from histolytics.losses import CELoss, DiceLoss, JointLoss, MultiTaskLoss
from histolytics.models.cellpose_panoptic import CellposePanoptic
from histolytics.transforms import (
    AlbuStrongAugment,
    CellposeTransform,
    MinMaxNormalization,
    ApplyEach,
)

# panoptils (refined) classes
nuclei_classes = {
    "background": 0,
    "neoplastic": 1,
    "stromal": 2,
    "inflammatory": 3,
    "epithelial": 4,
    "other": 5,
    "unknown": 6,
}
tissue_classes = {
    "background": 0,
    "tumor": 1,
    "stroma": 2,
    "epithelium": 3,
    "junk/debris": 4,
    "blood": 5,
    "other": 6,
}

# Quick wrapper for MSE loss to make it fit the JointLoss API
class MSELoss(nn.Module):
    def __init__(self, **kwargs) -> None:
        super().__init__()

    def forward(
        self,
        yhat: torch.Tensor,
        target: torch.Tensor,
        **kwargs
    ) -> torch.Tensor:
        return F.mse_loss(yhat, target, reduction="mean").float()

batch_size = 8
in_keys = ("image", "sem_mask", "inst_mask", "type_mask")
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

# init CellposePanoptic model
cpose_panoptic = CellposePanoptic(
    n_nuc_classes=len(nuclei_classes),
    n_tissue_classes=len(tissue_classes),
    enc_name="efficientnet_b5",  # you can change this to any supported encoder
    enc_pretrain=True,
)
model = cpose_panoptic.model.to(device)

# init training transforms
img_transforms = A.Compose([
    A.HorizontalFlip(p=0.33),
    A.VerticalFlip(p=0.33),
    AlbuStrongAugment(),
    MinMaxNormalization(),
])
inst_transforms = ApplyEach([CellposeTransform(deduplicate=False)], as_list=True)

# init val dataset and dataloader
ds_train = DatasetH5(
    Path().home() / "panoptils_refined" / "panoptils_train_p224_224.h5",
    img_key="image",
    inst_keys=["inst_mask"],
    mask_keys=["type_mask", "sem_mask"],
    transforms=img_transforms,
    inst_transforms=inst_transforms,
)
loader_train = NodesDataLoader(
    ds_train,
    batch_size,
    shuffle=False,
    num_workers=batch_size,
    pin_memory=True,
    drop_last=True,
)

# init train dataset and dataloader
ds_val = DatasetH5(
    Path().home() / "panoptils_refined" / "panoptils_val_p224_224.h5",
    img_key="image",
    inst_keys=["inst_mask"],
    mask_keys=["type_mask", "sem_mask"],
    transforms=img_transforms,
    inst_transforms=inst_transforms,
)
loader_val = NodesDataLoader(
    ds_val,
    batch_size,
    shuffle=True,
    num_workers=batch_size,
    pin_memory=True,
    drop_last=True,
)

# init training multi-task loss
# The losses are defined for each task, and the weights are set for each task.
losses = {
    "cellpose": JointLoss([MSELoss()]),
    "type_mask": JointLoss([CELoss(apply_sd=True), DiceLoss()]),
    "sem_mask": JointLoss([CELoss(apply_sd=True), DiceLoss()]),
}
loss_weights = {"cellpose": 1.0, "type_mask": 1.0, "sem_mask": 2.0}
multitask_loss = MultiTaskLoss(losses, loss_weights=loss_weights).to(device)

# optimizer and lr scheduler
optimizer = torch.optim.AdamW(params=model.parameters(), lr=0.0001)
lr_scheduler = CosineAnnealingLR(optimizer, T_max=1000, eta_min=0, last_epoch=-1)
```

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

### PercentileNormalization Init Args Names

Source: https://hautaniemilab.github.io/histolytics/api/transforms/percentile

Retrieves the names of the initialization arguments for the PercentileNormalization transform.

```APIDOC
## Get Transform Init Args Names

### Description
Gets the names of the transformation arguments.

### Method
`get_transform_init_args_names()`

### Returns
- **list** - A list of strings representing the names of the initialization arguments.
```

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

### Load and Display HGSC Stroma H&E Image

Source: https://hautaniemilab.github.io/histolytics/api/data/hgsc_stroma_he

Loads the hgsc_stroma_he image and displays it using Matplotlib. Ensure Matplotlib is installed.

```python
>>> import matplotlib.pyplot as plt
>>> from histolytics.data import hgsc_stroma_he
>>> fig, ax = plt.subplots(figsize=(4, 4))
>>> im = hgsc_stroma_he()
>>> ax.imshow(im)
>>> ax.set_axis_off()
```

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

### Load and Visualize Cervix Data

Source: https://hautaniemilab.github.io/histolytics/user_guide/spatial/querying

Loads cervix tissue and nuclei data using Histolytics and visualizes them with Matplotlib. Ensure Histolytics and Matplotlib are installed.

```python
import matplotlib.pyplot as plt
from histolytics.data import cervix_nuclei, cervix_tissue

tis = cervix_tissue()
nuc = cervix_nuclei()

fig, ax = plt.subplots(figsize=(10, 10))
tis.plot(ax=ax, column="class_name", aspect=1, alpha=0.5, legend=True)
nuc.plot(ax=ax, column="class_name", aspect=1, legend=False)
ax.set_axis_off()
```

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

### Initialize StarDistPanoptic Model

Source: https://hautaniemilab.github.io/histolytics/api/models/stardist_panoptic

Initializes the StarDistPanoptic model with specified parameters for nuclei and tissue classes, encoder configuration, and device. Use this to set up the model for training or inference.

```python
class StarDistPanoptic(BaseModelPanoptic):
    model_name = "stardist_panoptic"

    def __init__(
        self, 
        n_nuc_classes: int,
        n_tissue_classes: int,
        n_rays: int = 32,
        enc_name: str = "efficientnet_b5",
        enc_pretrain: bool = True,
        enc_freeze: bool = False,
        device: torch.device = torch.device("cuda"),
        model_kwargs: Dict[str, Any] = {},
    ) -> None:
        """StardistPanoptic model for panoptic segmentation of nuclei and tissues.

        Note:
            [Stardist article](https://arxiv.org/abs/1806.03535)

        Parameters:
            n_nuc_classes (int):
                Number of nuclei type classes.
            n_tissue_classes (int):
                Number of tissue type classes.
            n_rays (int):
                Number of rays for the Stardist model.
            enc_name (str):
                Name of the pytorch-image-models encoder.
            enc_pretrain (bool):
                Whether to use pretrained weights in the encoder.
            enc_freeze (bool):
                Freeze encoder weights for training.
            device (torch.device):
                Device to run the model on.
            model_kwargs (dict):
                Additional keyword arguments for the model.
        """
        super().__init__()
        self.model = stardist_panoptic(
            n_rays=n_rays,
            n_nuc_classes=n_nuc_classes,
            n_tissue_classes=n_tissue_classes,
            enc_name=enc_name,
            enc_pretrain=enc_pretrain,
            enc_freeze=enc_freeze,
            **model_kwargs,
        )

        self.device = device
        self.model.to(device)

```

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

### Run Inference on an Image Batch

Source: https://hautaniemilab.github.io/histolytics/user_guide/seg/getting_started_seg

Process a batch of images for inference. This example uses random tensors for demonstration; replace with actual image data.

```python
import torch
from histolytics.utils import FileHandler

model.set_inference_mode()

# dont use random matrices IRL
batch = torch.rand(8, 3, 1024, 1024)

prob = model.predict(im)
out = model.post_process(prob)
# out = {
#  "nuc": [
#    (nuc instances (H, W), nuc types (H, W)),
#    (nuc instances (H, W), nuc types (H, W)),
#    .
#    .
#    .
#    (nuc instances (H, W), nuc types (H, W))
#  ],
#  "tissue": [
#    (nuc instances (H, W), nuc types (H, W)),
#    (nuc instances (H, W), nuc types (H, W)),
#    .
#    .
#    .
#    (nuc instances (H, W), nuc types (H, W))
#  ],
#  "cyto": None,
#}


```

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

### cluster_tendency

Source: https://hautaniemilab.github.io/histolytics/api/spatial_clust/cluster_tendency

Get the centroid of a GeoDataFrame using specified method. This function calculates the central point of a spatial dataset based on different statistical methods.

```APIDOC
## cluster_tendency

### Description
Get the centroid of a GeoDataFrame using specified method.

### Method Signature
`cluster_tendency(gdf: gpd.GeoDataFrame, centroid_method: str = "mean", weight_col: str = None) -> Point`

### Parameters
#### Path Parameters
- **gdf** (`GeoDataFrame`) - Required - Input GeoDataFrame with a properly set geometry column.
- **centroid_method** (`str`) - Optional - The method to use for calculating the centroid. Options are: "mean", "median", "weighted_mean". Defaults to "mean".
- **weight_col** (`str`) - Optional - The name of the column to use for weights when calculating the weighted mean center. Required if `centroid_method` is "weighted_mean". Defaults to None.

### Returns
- **Point** (`Point`) - A shapely Point object representing the centroid of the GeoDataFrame.

### Examples:
```python
>>> from histolytics.spatial_clust.centrography import cluster_tendency
>>> from histolytics.spatial_clust.density_clustering import density_clustering
>>> from histolytics.data import hgsc_cancer_nuclei
>>> 
>>> nuc = hgsc_cancer_nuclei()
>>> nuc_imm = nuc[nuc["class_name"] == "neoplastic"]
>>> labels = density_clustering(nuc_imm, eps=250, min_samples=100, method="dbscan")
>>> nuc_imm = nuc_imm.assign(labels=labels)
>>> # Calculate the centroids for each cluster
>>> clust_centroids = (
...    nuc_imm.groupby("labels")
...    .apply(lambda g: cluster_tendency(g, "mean"), include_groups=False)
...    .reset_index(name="centroid")
... )
>>> print(clust_centroids)
    labels                                     centroid
    0      -1  POINT (785.5438556958384 806.2601606856466)
    1       0  POINT (665.1678800342971 695.4346142894398)
```
```

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

### BinarizeTransform Initialization

Source: https://hautaniemilab.github.io/histolytics/api/transforms/binarize

Initializes an instance of the BinarizeTransform for creating a binary mask.

```python
__init__()


```

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

### Initialize WSI Segmenter

Source: https://hautaniemilab.github.io/histolytics/api/wsi/wsi_segmenter

Initializes the WSI Segmenter with necessary components for segmentation. Requires a SlideReader, a segmentation model, the WSI level, and bounding box coordinates. Optional parameters include batch size and image transformations.

```python
def __init__(
    self,
    reader: SlideReader,
    model: BaseModelPanoptic,
    level: int,
    coordinates: List[Tuple[int, int, int, int]],
    batch_size: int = 8,
    transforms: A.Compose = None,
) -> None:
    """Class handling the panoptic segmentation of WSIs.

    Parameters:
        reader (SlideReader):
            The `SlideReader` object for reading the WSIs.
        model (BaseModelPanoptic):
            The model for segmentation.
        level (int):
            The level of the WSI to segment.
        coordinates (List[Tuple[int, int, int, int]]):
            The bounding box coordinates from `reader.get_tile_coordinates()`.
        batch_size (int):
            The batch size for the DataLoader.
        transforms (A.Compose):
            The transformations for the input patches.
    """
    if not has_albu:
        warnings.warn(
            "The albumentations lib is needed to apply transformations. "
            "Setting transforms=None"
        )
        transforms = None

    self.batch_size = batch_size
    self.coordinates = coordinates
    self.model = model

    self.dataset = WSIDatasetInfer(
        reader, coordinates, level=level, transforms=transforms
    )
    self.dataloader = DataLoader(
        self.dataset, batch_size=batch_size, shuffle=False, pin_memory=True
    )
    self._has_processed = False

```

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

### Example Usage of Legendgram

Source: https://hautaniemilab.github.io/histolytics/api/utils/legendgram

Demonstrates how to use the legendgram function to add a custom legend to a plot, showing the distribution of 'eccentricity' for neoplastic nuclei with a 'turbo' colormap.

```python
>>> from histolytics.data import cervix_tissue, cervix_nuclei
>>> from histolytics.spatial_ops.ops import get_objs
>>> from histolytics.spatial_geom.shape_metrics import shape_metric
>>> 
>>> # Get the cervix nuclei and tissue data
>>> nuc = cervix_nuclei()
>>> tis = cervix_tissue()
>>> # Filter the tissue data for CIN lesions and get the neoplastic nuclei
>>> lesion = tis[tis["class_name"] == "cin"]
>>> neo = get_objs(lesion, nuc)
>>> neo = neo[neo["class_name"] == "neoplastic"]
>>> # Calculate the eccentricity for the neoplastic nuclei
>>> neo = shape_metric(neo, ["eccentricity"])
>>> 
>>> # Plot the neoplastic nuclei with eccentricity as a color scale
>>> col = "eccentricity"
>>> ax = nuc.plot(
...     column="class_name",
...     figsize=(6, 6),
...     aspect=1,
...     alpha=0.5,
... )
>>> ax = neo.plot(
...     ax=ax,
...     column=col,
...     legend=False,
...     cmap="turbo",
... )
>>> ax.set_axis_off()
>>> 
>>> # Add a legendgram to the plot
>>> legendgram(
...     neo,
...     column=col,
...     ax=ax,
...     n_bins=50,
...     cmap="turbo",
...     frame_on=False,
...     lw=2,
...     lc="black",
...     ticks=3,
...     legend_size=("30%", "20%"),
... )
```

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

### Load and Plot Nuclear Data

Source: https://hautaniemilab.github.io/histolytics/user_guide/spatial/nuclear_features

Loads example nuclei and H&E image data, then plots the nuclei with class names and displays the first 5 rows.

```python
from histolytics.data import hgsc_cancer_he, hgsc_cancer_nuclei

# Load some example data
nuc = hgsc_cancer_nuclei()  # Nuclei vector segmentation
he = hgsc_cancer_he()  # Corresponding H&E image

ax = nuc.plot(figsize=(10, 10), column="class_name")
ax.set_axis_off()
nuc.head(5)
```

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

### Create H5 Files for Training and Validation

Source: https://hautaniemilab.github.io/histolytics/user_guide/seg/finetuning

This script preprocesses image and mask data, applies augmentations, and saves them into H5 files for efficient training and validation. It's designed to be run once before training begins.

```python
import tables as tb
import albumentations as A

from pathlib import Path
from histolytics.utils import H5Handler
from cellseg_models_pytorch.inference.predictor import Predictor
from cellseg_models_pytorch.wsi.tiles import _pad_tile
from tqdm import tqdm

import warnings
import pandas as pd
import numpy as np

from cellseg_models_pytorch.utils.io import png_bytes_to_array

warnings.filterwarnings("ignore")

# we will apply some simple augmentations to the patches
img_transforms = A.Compose(
    [
        A.HorizontalFlip(p=0.33),
        A.VerticalFlip(p=0.33),
    ]
)

# we'll save the h5 file in a directory in the home folder
h5handler = H5Handler()
save_dir = Path.home() / "panoptils_refined"
save_dir.mkdir(parents=True, exist_ok=True)


# Helper function to patch the images and to create H5 files from the patches
def create_h5(df: pd.DataFrame, fold: str, stride: int, patch_size: tuple):
    fname = save_dir / f"panoptils_{fold}_p{patch_size[0]}_{stride}.h5"
    h5 = tb.open_file(fname, "w")
    h5handler.init_img(h5, patch_size)
    h5handler.init_mask(h5, "inst_mask", patch_size)
    h5handler.init_mask(h5, "type_mask", patch_size)
    h5handler.init_mask(h5, "sem_mask", patch_size)

    try:
        for i, row in tqdm(
            df.iterrows(), total=len(df), desc=f"Processing {fold} patches"
        ):
            image = png_bytes_to_array(row["image"])
            inst_mask = png_bytes_to_array(row["inst"])
            type_mask = png_bytes_to_array(row["type"])
            sem_mask = png_bytes_to_array(row["sem"])

            data = np.concatenate(
                [
                    image,
                    inst_mask[..., None],
                    type_mask[..., None],
                    sem_mask[..., None],
                ],
                axis=2,
            )
            slices, pady, padx = Predictor._get_slices(
                stride, patch_size, image.shape[:2]
            )

            padx, modx = divmod(padx, 2)
            pady, mody = divmod(pady, 2)
            padx += modx
            pady += mody

            for yslice, xslice in slices:
                x_i = _pad_tile(data[yslice, xslice, ...], shape=patch_size, fill=0)
                x_i = img_transforms(image=x_i)("image")  # apply flips
                im_i = x_i[..., :3]
                inst_i = x_i[..., 3]
                type_i = x_i[..., 4]
                sem_i = x_i[..., 5]
                h5handler.append_array(h5, im_i[None, ...], "image")
                h5handler.append_array(h5, inst_i[None, ...], "inst_mask")
                h5handler.append_array(h5, type_i[None, ...], "type_mask")
                h5handler.append_array(h5, sem_i[None, ...], "sem_mask")

        h5.close()
    except Exception as e:
        h5.close()
        raise e


# Create H5 files for train and validation sets
# Assuming df_train and df_val are pre-defined pandas DataFrames
# create_h5(df_train, "train", stride=224, patch_size=(224, 224))
# create_h5(df_val, "val", stride=224, patch_size=(224, 224))

```
Tokens:
Raw