Table of Contents
Shortcuts

slideflow.io.torch

The purpose of this module is to provide a performant, backend-agnostic TFRecord reader and interleaver to use as input for PyTorch models. Its TFRecord reader is a modified and optimized version of https://github.com/vahidk/tfrecord, included as the module slideflow.tfrecord. TFRecord file reading and interleaving is supervised by slideflow.io.torch.interleave(), while the slideflow.io.torch.interleave_dataloader() function provides a PyTorch DataLoader object which can be directly used.

PyTorch-specific I/O utilities.

class InterleaveIterator(tfrecords: List[str], *, img_size: int | None = None, labels: Dict[str, str] | Dict[str, int] | Dict[str, List[float]] | None = None, incl_slidenames: bool = False, incl_loc: bool = False, rank: int = 0, num_replicas: int = 1, augment: str | bool = False, standardize: bool = True, num_tiles: int | None = None, infinite: bool = True, prob_weights: Dict[str, float] | None = None, normalizer: StainNormalizer | None = None, clip: List[int] | None = None, chunk_size: int = 1, use_labels: bool = True, model_type: str = 'categorical', onehot: bool = False, indices: ndarray | None = None, from_wsi: bool = False, tile_um: int | None = None, rois: List[str] | None = None, roi_method: str = 'auto', pool: Any | None = None, transform: Any | None = None, **interleave_kwargs)[source]

Pytorch Iterable Dataset that interleaves tfrecords with the interleave() function below. Serves as a bridge between the python generator returned by interleave() and the pytorch DataLoader class.

Pytorch IterableDataset that interleaves tfrecords with slideflow.io.torch.interleave().

Parameters:

tfrecords (list(str)) – Path to tfrecord files to interleave.

Keyword Arguments:

  • img_size (int) – Image width in pixels.

  • labels (dict, optional) – Dict mapping slide names to labels. Defaults to None.

  • incl_slidenames (bool, optional) – Include slide names when iterated (returns image, label, slide). Defaults to False.

  • incl_loc (bool, optional) – Include location info (tile center coordinates). Returns samples in the form (returns ..., loc_x, loc_y). Defaults to False.

  • rank (int, optional) – Which GPU replica this dataset is used for. Assists with synchronization across GPUs. Defaults to 0.

  • num_replicas (int, optional) – Total number of GPU replicas. Defaults to 1.

  • augment (str or bool) –

    Image augmentations to perform. Augmentations include:

    • 'x': Random horizontal flip

    • 'y': Random vertical flip

    • 'r': Random 90-degree rotation

    • 'j': Random JPEG compression (50% chance to compress with quality between 50-100)

    • 'b': Random Gaussian blur (10% chance to blur with sigma between 0.5-2.0)

    • 'n': Random Stain Augmentation (requires stain normalizer)

    Combine letters to define augmentations, such as 'xyrjn'. A value of True will use 'xyrjb'.

  • standardize (bool, optional) – Standardize images to mean 0 and variance of 1. Defaults to True.

  • num_tiles (int, optional) – Dict mapping tfrecord names to number of total tiles. Defaults to None.

  • infinite (bool, optional) – Inifitely loop through dataset. Defaults to True.

  • prob_weights (list(float), optional) – Probability weights for interleaving tfrecords. Defaults to None.

  • normalizer (slideflow.norm.StainNormalizer, optional) – Normalizer. Defaults to None.

  • clip (list(int), optional) – Array of maximum tiles to take for each tfrecord. Defaults to None.

  • chunk_size (int, optional) – Chunk size for image decoding. Defaults to 1.

  • use_labels (bool, optional) – Enable use of labels (disabled for non-conditional GANs). Defaults to True.

  • model_type (str, optional) – Used to generate random labels (for StyleGAN2). Not required. Defaults to ‘categorical’.

  • onehot (bool, optional) – Onehot encode outcomes. Defaults to False.

  • indices (numpy.ndarray, optional) – Indices in form of array, with np.loadtxt(index_path, dtype=np.int64) for each tfrecord. Defaults to None.

  • max_size (bool, optional) – Unused argument present for legacy compatibility; will be removed.

  • from_wsi (bool) – Generate predictions from tiles dynamically extracted from whole-slide images, rather than TFRecords. Defaults to False (use TFRecords).

  • tile_um (int, optional) – Size of tiles to extract from WSI, in microns. Only used if from_wsi=True. Defaults to None.

  • rois (list(str), optional) – List of ROI paths. Only used if from_wsi=True. Defaults to None.

  • roi_method (str, optional) – Method for extracting ROIs. Only used if from_wsi=True. Defaults to ‘auto’.

  • pool (multiprocessing.Pool) – Shared multiprocessing pool. Useful if from_wsi=True, for sharing a unified processing pool between dataloaders. Defaults to None.

  • transform (Callable, optional) – Arbitrary torchvision transform function. Performs transformation after augmentations but before standardization. Defaults to None.

  • tfrecord_parser (Callable, optional) – Custom parser for TFRecords. Defaults to None.

class IndexedInterleaver(tfrecords: List[str], *, labels: Dict[str, str] | Dict[str, int] | Dict[str, List[float]] | None = None, incl_slidenames: bool = False, incl_loc: bool = False, rank: int = 0, num_replicas: int = 1, augment: bool | str = False, standardize: bool = True, normalizer: StainNormalizer | None = None, clip: Dict[str, int] | None = None, use_labels: bool = True, onehot: bool = False, indices: List[ndarray] | None = None, transform: Any | None = None, tfrecord_parser: Callable | None = None, **kwargs)[source]

Interleave TFRecords with an indexable torch.utils.data.Dataset.

Provides an alternative TFRecord IO pipeline to InterleaveIterator, which only supports Iterable-style datasets. This class supports both Iterable and Indexable datasets.

Differences from InterleaveIterator:

  • Supports direct indexing.

  • No “infinite” argument. Looping is handled by the dataloader.

  • No “prob_weights” argument. Sampling is handled by the dataloader.

  • Does not support dynamic reading from WSI (“from_wsi”, “tile_um”, “rois”, “roi_method”, and “pool” arguments).

Parameters:

tfrecords (list(str)) – Path to tfrecord files to interleave.

Keyword Arguments:

  • labels (dict, optional) – Dict mapping slide names to labels. Defaults to None.

  • incl_slidenames (bool, optional) – Include slide names when iterated (returns image, label, slide). Defaults to False.

  • incl_loc (bool, optional) – Include location info (tile center coordinates). Returns samples in the form (returns ..., loc_x, loc_y). Defaults to False.

  • rank (int, optional) – Which GPU replica this dataset is used for. Assists with synchronization across GPUs. Defaults to 0.

  • num_replicas (int, optional) – Total number of GPU replicas. Defaults to 1.

  • augment (str or bool) –

    Image augmentations to perform. Augmentations include:

    • 'x': Random horizontal flip

    • 'y': Random vertical flip

    • 'r': Random 90-degree rotation

    • 'j': Random JPEG compression (50% chance to compress with quality between 50-100)

    • 'b': Random Gaussian blur (10% chance to blur with sigma between 0.5-2.0)

    • 'n': Random Stain Augmentation (requires stain normalizer)

    Combine letters to define augmentations, such as 'xyrjn'. A value of True will use 'xyrjb'.

  • standardize (bool, optional) – Standardize images to mean 0 and variance of 1. Defaults to True.

  • normalizer (slideflow.norm.StainNormalizer, optional) – Normalizer. Defaults to None.

  • clip (list(int), optional) – Array of maximum tiles to take for each tfrecord. Defaults to None.

  • use_labels (bool, optional) – Enable use of labels (disabled for non-conditional GANs). Defaults to True.

  • onehot (bool, optional) – Onehot encode outcomes. Defaults to False.

  • indices (numpy.ndarray, optional) – Indices in form of array, with np.loadtxt(index_path, dtype=np.int64) for each tfrecord. Defaults to None.

  • transform (Callable, optional) – Arbitrary torchvision transform function. Performs transformation after augmentations but before standardization. Defaults to None.

  • tfrecord_parser (Callable, optional) – Custom parser for TFRecords. Defaults to None.

  • compression_type (str, optional) – Compression type for TFRecords. Either ‘gzip’ or None. Defaults to None.

  • shuffle (bool) – Shuffle records within TFRecord files during reading. Defaults to False.

  • seed (int, optional) – Seed for random TFRecord interleaving and intra-tfrecord shuffling. Defaults to None.