Slideflow

Latest version: v3.0.2

Safety actively analyzes 714973 Python packages for vulnerabilities to keep your Python projects secure.

Scan your dependencies

Page 2 of 11

2.3.1

This is a minor, bug-fix release. See the [Version 2.3 release notes](https://github.com/jamesdolezal/slideflow/releases/tag/2.3.0) for details about the latest major release.

Changes
- Fix TypeError when attempting to generate MIL predictions in Studio with a stain normalizer [346] - thanks siddhir
- Fix generation of MIL heatmaps during training & evaluation when using a stride > 1 [331] - thanks sz3029

2.3.0

Highlights
We are very happy to release Slideflow 2.3, the highlight of which is the introduction of **whole-slide tissue segmentation**. Both binary and multiclass tissue segmentation models can be trained from labeled ROIs and deployed for slide QC or used to generate ROIs. This release also adds **CycleGAN-based stain normalization**, as well as several smaller features and optimizations.

Table of Contents
1. **Tissue Segmentation**
a. Training segmentation models
b. Using models for QC
c. Generating ROIs
d. Deploying in Studio
2. **CycleGAN Stain Normalization**
3. **Other New Features**
4. **Dependencies**
5. **Known Issues**

Tissue segmentation

https://github.com/jamesdolezal/slideflow/assets/48372806/acac4415-eb4c-4a90-8483-56da26f76bfe

Slideflow now supports training and deploying [tissue segmentation](https://slideflow.dev/segmentation) models, both via the programmatic interface as well as in [Slideflow Studio](https://slideflow.dev/studio#tissue-segmentation). Tissue segmentation models can be trained in binary, multiclass, or multilabel mode using [labeled ROIs](https://slideflow.dev/studio#roi-annotations). Tissue segmentation is performed at the whole-slide level, trained on randomly cropped sections of the slide thumbnail at a specified resolution.

Training segmentation models

Segmentation models are configured using `SegmentConfig`, which determines the segmentation architecture (U-Net, FPN, DeepLabV3, etc), image resolution for segmentation in microns-per-pixel (MPP), and other training parameters.

python
from slideflow import segment

Create a config object
config = segment.SegmentConfig(mpp=20, mode='binary', arch='Unet')


Models can be trained with `slideflow.segment.train()`. Models will be saved in the given destination directory as `model.pth`, with an auto-generated `segment_config.json` file describing the architecture and parameters.

python
...

Load a dataset
project = sf.Project(...)
dataset = project.dataset(...)

Train the model
segment.train(config, dataset, dest='path/to/output')


Once trained, tissue segmentation models can either be used for slide-level QC or to generate ROIs.

Using models for QC

The new `slideflow.slide.qc.Segment` class provides an easy interface for generating QC masks from a segmentation model (e.g., for a model trained to identify tumor regions, pen marks, etc). This class takes a path to a trained segmentation model as an argument, and otherwise can be used for QC as outlined in the [documentation](https://slideflow.dev/slide_processing#filtering).

python

import slideflow as sf
from slideflow.slide import qc

Load the slide
wsi = sf.WSI('/path/to/slide', ...)

Create the QC algorithm
segmenter = qc.Segment('/path/to/model.pth')

Apply QC
applied_mask = wsi.qc(segmenter)


For multiclass segmentation models, `qc.Segment` provides [additional arguments](https://slideflow.dev/segmentation#generating-qc-masks) to customize how the model should be used for QC.

Generating ROIs

The same `qc.Segment` class can also be used to generate regions of interest (ROIs). Use `Segment.generate_rois()` to generate and apply ROIs to a single slide:

python
...

Create a QC mask
segmenter = qc.Segment('/path/to/model.pth')

Generate and apply ROIs to a slide
roi_outlines = segmenter.generate_rois(wsi)


Or use `Dataset.generate_rois()` to create ROIs for an entire dataset:

python
import slideflow as sf

Load a project and dataset.
project = sf.load_project('path/to/project')
dataset = project.dataset()

Generate ROIs for all slides in the dataset.
dataset.generate_rois('path/to/model.pth')


Deploying in Studio

The slide widget in Studio now has a "Segment" section. A trained segmentation model can be loaded and used for either QC or to generate ROIs. Further details regarding use are available in the [documentation](https://slideflow.dev/studio#tissue-segmentation).

CycleGAN Stain Normalization

Slideflow now includes a CycleGAN-based stain normalizer, `'cyclegan'`. Our implementation is based off of the work by [Zingman et al](https://github.com/Boehringer-Ingelheim/stain-transfer). The stain normalization algorithm is a two-step process utilizing two separate GANs. The H&E image to be transformed is first converted via GAN-1 into Masson's Trichrome (MT), and then converted back to H&E via GAN-2. By default, pretrained weights [provided by Zingman](https://osf.io/byf27/) will be used, although custom weights can also be provided.

At present, CycleGAN stain normalization requires PyTorch. If you would like us to port GAN normalizers to the Tensorflow backend, please head to our ongoing [Discussion](https://github.com/jamesdolezal/slideflow/discussions/343) and let us know!

This method can be used like any other stain normalizer:

python
Configure training parameters
to use CycleGAN stain normalization
params = sf.ModelParams(..., normalizer='cyclegan')


Other New Features
- Stain normalizers can now augment an image without also normalizing, using the new `.augment()` method.

python
import slideflow as sf

Get a Macenko normalizer
macenko = sf.norm.autoselect('macenko')

Perform stain augmentation
img = macenko.augment(img)


- Expanded support for more tile aggregation methods, for reducing tile-level predictions to slide- or patient-level predictions. The `reduce_method` argument to `Project.train()` and `.evaluate()` now supports 'median', 'sum', 'min', and 'max' (in addition to the previously supported 'average' and 'proportion'), as well as arbitrary callable functions. For example, to define slide-level predictions as the 75th percentile of tile-level predictions:

python
Project.train(
...
reduce_method=lambda x: np.percentile(x, 75)
)

- New utility function `Dataset.get_unique_roi_labels()` for getting a list of all unique ROI labels in a dataset.
- Improve inference speed of PyTorch feature extractors when called on `uint8` images.
- Much faster generation of tile-level predictions for MIL models
- Add function `sf.mil.get_mil_tile_predictions()`, which functions the same as `sf.mil.save_mil_tile_predictions()` but returns a pandas dataframe
- Add ability to calculate tile-level uncertainty for MIL models trained with UQ, by passing `uq=True` to `sf.mil.get_mil_tile_predictions()`

Dependencies

Dependencies are largely unchanged. Updates include:
- Tissue segmentation requires the `segmentation-models-pytorch` package.

Known Issues

- **Tissue segmentation is performed at the whole-slide level (based on cropped thumbnails), and performs best at lower magnifications (microns-per-pixel of 10 or greater)**. Attempting to train or deploy a tissue segmentation model at higher magnification may significantly increase memory requirements. Optimization work is ongoing to reduce memory requirements when training and deploying tissue segmentation models that operate at higher magnification.

2.2.2

This is a *minor*, bug-fix release. See the [Version 2.2 release notes](https://github.com/jamesdolezal/slideflow/releases/tag/2.2.0) for details about the latest major release.

Changes
- Fix bug with GPU stain augmentation in PyTorch (`ValueError: Stain augmentation (n) requires a stain normalizer, which was not provided`)
- Fix bug with generating intermediate layer activations from a pytorch model
- Fix bug in Otsu's thresholding if `roi_method == 'outside'` (340) - thanks matte-esse
- Improve handling of edge case where there is 1 tile in a slide
- Fix rare "LiveError" when generating feature bags
- Slideflow Studio: fix handling the case where there are no tiles in a slide (e.g. a JPEG image smaller than the tile size)
- Slideflow Studio [Cellpose extension]: Fix inconsistent transparency for displayed masks when zooming out
- Slideflow Studio [Cellpose extension]: Fix bug with whole-slide cell segmentation

2.2.1post1

This is a *minor*, bug-fix release. See the [Version 2.2 release notes](https://github.com/jamesdolezal/slideflow/releases/tag/2.2.0) for details about the latest major release.

Changes
- Fix ballooning memory requirements when training MIL models on large datasets for many epochs
- Fix documentation typo (337) - thanks luiscarm9
- Fix stain augmentation string parsing in PyTorch (335) - thanks luiscarm9
- Fix bug when specifying `normalizer=None` during feature bag generation
- Fix bug where feature generation from a WSI would hang when using a PyTorch feature extractor and non-OpenCV stain normalizer
- Fix slide thumbnail orientation when using a transformation (rotation)
- Fix bug with `WSI.align_tiles_to(..., align_by='tile')`
- Fix rendering of ALT hover and ROI labeling in Slideflow Studio on high-DPI devices
- Add support for loading float16 bags for MIL models, auto-converting to float32
- Improve check for empty arrays in DatasetFeatures (332) - thanks Mr-Milk
- Add forward compatibility for upcoming MIL hyperparameters

2.2

- A new fully-transformer model, `"bistro.transformer"` (from [this paper](https://www.cell.com/cancer-cell/pdf/S1535-6108(23)00278-7.pdf))
- New `aggregation_level` MIL config option. If any patients have multiple slides, use `aggregation_level="patient"`. (316)
- MIL models can be further customized with a new argument `mil_config(model_kwargs={...})`. Use `model_kwargs` in the MIL configuration to pass through keyword arguments to the model initializer. This can be used, for example, to specify the softmax temperature and attention gating for the `Attention_MIL` model through the model keyword arguments `temperature` and `attention_gate`.

python
from slideflow.mil import mil_config

config = mil_config(
'attention_mil',
model_kwargs={'temperature': 0.3},
...
)


- New experimental uncertainty quantification support for MIL models. Enable uncertainty estimation with the argument `uq=True` to either `P.train_mil` or `P.evaluate_mil`. The model must support a `uq` argument in it's `forward()` function. At present, MIL UQ is only available for the `Attention_MIL` model.
- New class initializer `DatasetFeatures.from_bags()`, for loading a `DatasetFeatures` objects from previously generated feature bags. This makes it easier to perform latent space exploration and visualization, using `DatasetFeatures.map_activations()` (see [docs](https://slideflow.dev/posthoc/#mapping-activations))
- New `sf.mil.MILFeatures` class to assist with calculating and visualizing last-layer activations from MIL models, prior to final logits. This class is analogous to the `DatasetFeatures` interface, but for MIL model layer activations.

Slideflow Studio Updates
The latest version of Slideflow Studio includes a number of usability improvements and new features.
- **ROI labels**: You can now [assign labels](https://slideflow.dev/#studio-roi) to Regions of Interest (ROIs) in Studio. These labels can be used for downstream [strongly-supervised training](https://slideflow.dev/tile_labels), where labels are determined from ROIs rather than inherited from the slide label.
- **ALT hover**: Press Left ALT while hovering over a heatmap to show the raw prediction/attention values beneath your cursor.
- **Progress bars**: A progress bar is now displayed when generating predictions for a slide.
- **Tile predictions with MIL**: Show tile-level predictions and attention for MIL models by right-clicking anywhere on a slide
- **GAN seed tracking**: Keep track of GAN seeds with easy saving and loading. Quickly scroll through seeds by pressing left/right on your keyboard.
- Scale sidebar icons with font size
- Improved low-memory mode for MIL models (supports devices with < 8 GB RAM)
- Preserve ROIs and slide settings when changing models
- Default to Otsu's thresholding instead of grayspace filtering, for improved efficiency
- Various bug fixes and stability improvement

Documentation Expansion
Documentation at https://slideflow.dev has been further expanded, and a new **Developer Notes** section has been added. Developer Notes are intended to provide a deeper dive into selected topics of interest for developers or advanced users. Our first developer notes include:
- **TFRecords: Reading and Writing**: a detailed description of our TFRecord data format, with examples of how to create, inspect, and read from these files.
- **Dataloaders: Sampling and Augmentation**: descriptions of how to create PyTorch `DataLoaders` or Tensorflow `tf.data.Datasets` and apply custom image transformations, labeling, and sampling. Includes a detailed examination of our oversampling and undersampling methods.
- **Custom Feature Extractors**: A look at how to construct custom feature extractors for MIL models.
- **Strong Supervision with Tile Labels**: An example of how Region of Interest (ROI) labels can be leveraged for training strongly-supervised models.

In addition to these new Dev Notes, we've also added two tutorials ([Tutorial 7: Training with Custom Augmentations](https://slideflow.dev/tutorial7) and [Tutorial 8: Multiple-Instance Learning](https://slideflow.dev/tutorial8)), as well as expanded our [Slideflow Studio](https://slideflow.dev/studio) docs to reflect the latest features.

Other New Features
- Align two slides together using `sf.WSI.align_to()`. This coarse alignment is fast and effective for slides in the proper orientation, without distortion. Use the more accurate `sf.WSI.align_tiles_to()` method for a higher accuracy alignment, finetuned at each tile location.
- Rotate a whole-slide image upon initial load using the new `transforms` argument [**Libvips only**]. This is particularly useful when attempting to align slides:

python
wsi = sf.WSI(..., transforms=[sf.slide.ROTATE_90_CLOCKWISE])


- Use OpenSlide bounding boxes, if present, with the new WSI argument `use_bounds` [**Libvips only**]. If `True`, will use existing OpenSlide bounding boxes. If a tuple, will crop the whole-slide image to the specified bounds. This is particularly useful when aligning slides.

python
Use OpenSlide bounds
wsi = sf.WSI(..., use_bounds=True)

Manually define the bounding box
wsi = sf.WSI(..., use_bounds=(41445, 112000, 48000, 70000))


- New [Indexable PyTorch dataset](https://slideflow.dev/dataloaders/#direct-indexing), for easier integration of Slideflow datasets into external projects
- Improved progress bars during tfrecord interleaving
- Add support for protobuf version 4
- Train GANs at odd image sizes with the new ``resize`` argument (see [docs](https://slideflow.dev/stylegan))
- Train a GAN conditioned on tile-level labels (see [docs](https://slideflow.dev/stylegan))

Version Requirements
Version requirements are largely unchanged. Notable differences include:
- The new `PLIP` feature extractor requires the `transformers` package.
- The `TransMIL` model requires the `nystom_attention` package.
- protobuf version compatibility expanded to support version 4
- imgui version increase to >= 2.0.0

**Note: the default backend has been switched from Tensorflow to PyTorch.** The backend can be manually set using the environmental variable "SF_BACKEND":


export SF_BACKEND=tensorflow

2.2.0

Highlights
Slideflow 2.2 further extends multiple-instance learning (MIL) capabilities, with the introduction of **multi-magnification MIL**, new models, experimental uncertainty quantification, and various other enhancements. This release also includes two new pretrained feature extractors - **HistoSSL** and **PLIP** - as well as support for the self-supervised learning framework, **DINOv2**. Slideflow Studio has been updated with several new features and quality of life improvements. Finally, the documentation has been enriched with Developer Notes and new tutorials, providing deeper insights on select topics.

Table of Contents
1. **Multi-Magnification MIL**
2. **New Feature Extractors**
a. Pretrained
b. DINOv2
3. **New MIL Features**
4. **Slideflow Studio Updates**
5. **Documentation Expansion**
6. **Other New Features**
7. **Version Requirements**


Multi-Magnification MIL
Slideflow now supports multi-modal MIL, with feature bags generated from multiple feature extractors at different magnifications. Multi-magnification MIL offers potential advantages if there are valuable histologic features at both low and high magnification.

Working with multi-magnification MIL is easy - you can use the same training API as standard MIL models. Simply provide multiple bag paths (one for each magnification) and use the new `"mm_attention_mil"` model.

python
Configure a multimodal MIL model.
config = mil_config('mm_attention_mil', lr=1e-4)

Set the bags paths for each modality.
bags_10x = '/path/to/bags_10x'
bags_40x = '/path/to/bags_40x'

P.train_mil(
config=config,
outcomes='HPV_status',
train_dataset=train,
val_dataset=val,
bags=[bags_10x, bags_40x]
)


Slideflow Studio also supports multi-magnification MIL models, allowing you to visualize attention and tile-level predictions from each mode separately.

New Feature Extractors
We've introduced support for two new pretrained feature extractors, as well as the self-supervised learning framework [DINOv2](https://github.com/jamesdolezal/dinov2).

Pretrained
The new pretrained feature extractors include:
- **[HistoSSL](https://github.com/owkin/HistoSSLscaling)**: a pan-cancer, pretrained ViT-based iBOT model (`iBOT[ViT-B]PanCancer`). [Paper](https://www.medrxiv.org/content/10.1101/2023.07.21.23292757v2.full.pdf)
- **[PLIP](https://github.com/PathologyFoundation/plip)**: feature encoder used for a CLIP model finetuned on pathology images and text descriptions. [Paper](https://www.nature.com/articles/s41591-023-02504-3)

Licenses and citations are available for all feature extractors through the new `.license` and `.citation` attributes.

python
>>> ctranspath = sf.model.build_feature_extractor('ctranspath', tile_px=299)
>>> ctranspath.license

Page 2 of 11

© 2025 Safety CLI Cybersecurity Inc. All Rights Reserved.