LazySlide

LazySlide is a Python framework designed for whole slide image (WSI) analysis. It is built to integrate with the scverse ecosystem, utilizing standardized data structures to ensure interoperability with tools like Scanpy, Anndata, and Squidpy.

Key capabilities include:

• Interoperability: Built on top of SpatialData and compatible with WSIData.
• Multimodal Integration: Ability to combine histological data with transcriptomics, genomics (omics data), and textual annotations.
• Foundation Model Support: Native integration with models such as UNI, CONCH, Gigapath, and Virchow for zero-shot learning and captioning.
• Deep Learning Readiness: Includes PyTorch dataloaders for machine learning pipelines.
• Scalability: Designed for efficient handling of large WSIs and high-throughput analyses.

LazySlide is a Python framework for whole slide image (WSI) analysis with the following capabilities:

• Interoperability: Built on top of SpatialData, ensuring compatibility with scverse tools like scanpy, anndata, and squidpy.
• Scalability: Efficient handling of large WSIs for high-throughput analyses.
• Multimodal integration: Combines histological data with transcriptomics, genomics, and textual annotations.
• Foundation model support: Native integration with models like UNI, CONCH, Gigapath, and Virchow for zero-shot classification and captioning.
• Deep learning ready: Provides PyTorch dataloaders for machine learning pipelines.

The LazySlide API is organized into several functional modules for Whole Slide Image (WSI) analysis. Depending on your task, you can access specific modules for preprocessing, segmentation, modeling, or visualization:

• Preprocessing: Functions for preparing WSI data.
• Tools: General utilities for WSI analysis.
• Plotting: Functions for visualizing WSI data.
• Segmentation: Specialized tasks for performing segmentation on WSI.
• Models: Pre-defined models for WSI analysis.
• Computer Vision (cv): Computer vision utilities tailored for WSI.
• IO: Input/Output operations specifically for annotations.
• Metrics: Tools for scoring and evaluation.

LazySlide uses mask objects (2D arrays or images) to represent segmentation results, tissue boundaries, or regions of interest. There are three primary types of masks:

• binary mask: A mask where each pixel is either 0 (background/negative) or 1 (foreground/positive). Used for general segmentation tasks.
• instance mask: A mask where each pixel value represents a specific object instance ID (e.g., a unique ID for every individual cell), with 0 typically representing the background. Used in instance segmentation to distinguish between individual objects of the same class.
• multi-class mask: A mask where pixel values represent different categories or classes.

A typical LazySlide analysis follows a linear progression: inspecting metadata, finding tissue, creating tiles, performing quality control, extracting features, and finally analyzing, predicting, or visualizing the results.

LazySlide uses a centralized data model centered around the WSIData object. Instead of returning disconnected arrays, most operations in LazySlide append results (such as spatial shapes, feature tables, or metadata) directly to the WSIData object. This ensures that the source image and all derived data remain spatially and contextually linked.

slide file -> inspect metadata -> find tissue -> create tiles
           -> quality control -> extract features -> analyze or predict
           -> visualize -> save

LazySlide relies on several key data structures for managing histopathology and spatial omics data:

• WSIData: The primary data structure for storing Whole Slide Image (WSI) data and its associated annotations.
• SpatialData: The underlying framework used by LazySlide for handling spatially resolved omics data.
• GeoDataFrame: A pandas DataFrame extension used extensively to store and manipulate spatial objects (such as tissue contours, tiles, and cell boundaries) as polygons.
• AnnData: Used for storing and manipulating single-cell and spatial omics data.

The physical width of a square tile is determined by its pixel size and the MPP. Use the following formula to calculate the field of view in microns:

field of view in microns = tile_px * mpp

Examples:

When using pretrained models, always choose the tile pixel size and MPP expected by the model rather than attempting to achieve the same FOV by changing only one variable.

When performing tissue segmentation, you can control the resolution level of the Whole Slide Image (WSI) used for the process.

• Level 0: The highest resolution level.
• Higher Levels: Progressively lower resolution levels.

By default, the optimal level is automatically determined based on available memory. However, you can manually set the resolution level using the level parameter in LazySlide's tissue segmentation function to ensure consistency across your analysis.

LazySlide uses the WSIData object as the primary container for analysis results. While the original Whole Slide Image (WSI) serves as the pixel source, all analysis outputs are organized into four specific collections within the wsi object:

• wsi.shapes: Contains spatial geometries like tissue polygons, tiles, cells, and annotations.
• wsi.tables: Contains matrices such as feature embeddings and other annotated data.
• wsi.images: Contains raster outputs, including segmentation masks or generated images.
• wsi.attrs: Contains metadata and specifications describing the results.

You can access elements using the shorthand wsi["key"], but for debugging and clarity, it is recommended to access the explicit collections.

# Inspect available keys in each collection
print(wsi.shapes.keys())
print(wsi.tables.keys())
print(wsi.images.keys())
print(wsi.attrs.keys())

In LazySlide, MPP (Microns Per Pixel) is the physical measurement used to define resolution, whereas magnification is scanner-specific terminology. While common approximations exist (e.g., 40x $\approx$ 0.25 MPP), you should always inspect the slide metadata to ensure accuracy.

Approximation Table:

To verify the actual resolution of a slide, inspect its properties and pyramid levels:

print(wsi.properties)
print(wsi.fetch.pyramids())

In LazySlide, a spatial tile graph represents the neighborhood relationships between tiles extracted from a Whole Slide Image (WSI). You can define these relationships using Delaunay triangulation instead of fixed distance thresholds. This geometric method creates a triangular mesh where no point lies inside the circumcircle of any triangle, ensuring natural spatial connectivity.

To use Delaunay triangulation for graph construction, set the use_delaunay parameter in the pp.tile_graph function.

# Example usage of the parameter mentioned in the glossary
pp.tile_graph(..., use_delaunay=True)