Version 2.3.1

This is a minor, bug-fix release. See the Version 2.3 release notes 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

Version 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

tissue_seg-3.mp4

Slideflow now supports training and deploying tissue segmentation models, both via the programmatic interface as well as in Slideflow Studio. Tissue segmentation models can be trained in binary, multiclass, or multilabel mode using labeled ROIs. 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.

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.

...

# 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.

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 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:

...

# 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:

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.

CycleGAN Stain Normalization

Slideflow now includes a CycleGAN-based stain normalizer, 'cyclegan'. Our implementation is based off of the work by Zingman et al. 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 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 and let us know!

This method can be used like any other stain normalizer:

# 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.

  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:

  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.

Version 2.2.2

This is a minor, bug-fix release. See the Version 2.2 release notes 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

Version 2.2.1

This is a minor, bug-fix release. See the Version 2.2 release notes 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

Version 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.

# 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.

Pretrained

The new pretrained feature extractors include:

• HistoSSL: a pan-cancer, pretrained ViT-based iBOT model (iBOT[ViT-B]PanCancer). Paper
• PLIP: feature encoder used for a CLIP model finetuned on pathology images and text descriptions. Paper

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

>>> ctranspath = sf.model.build_feature_extractor('ctranspath', tile_px=299)
>>> ctranspath.license
'GNU General Public License v3.0'
>>> print(ctranspath.citation)

@{wang2022,
  title={Transformer-based Unsupervised Contrastive Learning for Histopathological Image Classification},
  author={Wang, Xiyue and Yang, Sen and Zhang, Jun and Wang, Minghui and Zhang, Jing  and Yang, Wei and Huang, Junzhou  and Han, Xiao},
  journal={Medical Image Analysis},
  year={2022},
  publisher={Elsevier}
}

DINOv2

As with SimCLR, Slideflow now supports generating features from a trained DINOv2 model. Use the feature extractor 'dinov2', and pass the *.pth teacher weights to the argument weights, and the YAML configuration file to the argument cfg:

dinov2 = sf.model.build_feature_extractor(
  'dinov2',
  weights='/path/to/teacher_checkpoint.pth',
  cfg='/path/to/config.yaml'

We've also provided a modified version of DINOv2 that allows you to train the network using Slideflow projects and datasets. See our documentation for instructions on how to train and use DINOv2.

New MIL Features

Slideflow 2.2 includes a number of updates in MIL functionality, including:

• A new fully-transformer model, "bistro.transformer" (from this paper)

• 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.

  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)

• 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 to Regions of Interest (ROIs) in Studio. These labels can be used for downstream strongly-supervised training, 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 and Tutorial 8: Multiple-Instance Learning), as well as expanded our Slideflow 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:

  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.

  # 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, 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)

• Train a GAN conditioned on tile-level labels (see docs)

Version Requirements

Version requirements are largely unchanged. Notable differences include:

• The new PLIP feature extractor requires the transformers package.
• ...

Version 2.1.1

This is a minor, bug-fix release. See the Version 2.1 release notes for details about the latest major release.

Changes

• Fix error when providing a feature extractor argument to sf.mil.predict_slide() [#310] (thanks @bplee)
• Fix Neptune logging with latest API [#312, #313, #314] (thanks @luiscarm9)
• Fix unknown argument save_checkpoints when performing SMAC hyperparameter search in PyTorch [#309]
• Fix MIL inference support on MacOS (MPS) devices
• Fix attention heatmap generation from MIL model TransMIL
• Fix feature generation during MIL inference from finetuned SimCLR model
• Opening a slide in Studio with WSI.view() will load the slide at the same tile_px/tile_um
• Dataset.rebuild_index() will now remove old index files, fixing various allow_pickle errors when using old TFRecords
• Fix minor inconsistency in masking algorithm with Reinhard between OpenCV/Numpy and Tensorflow/PyTorch implementations
• Fix "Random pixel interpolation not implemented" error when using augment=True
• Minor documentation typo fixes

Version 2.1.0

Highlights

Slideflow 2.1 includes a number of new features and optimizations, with a focus on improving Multiple-Instance Learning (MIL) model development and deployment. Key improvements include an MIL / Attention Heatmaps extension for Slideflow Studio, improvements to both feature extraction and MIL training, new QC algorithms, and dozens of other enhancements and bug fixes.

Table of Contents

1. Slideflow Studio: MIL & Attention Heatmaps
2. MIL Training Enhancements
   a. Rebuilding feature extractors used for MIL
   b. Single-slide predictions, without feature bags
   c. QOL improvements
3. Streamlined Feature Extraction
   a. Features from layer activations of an ImageNet-pretrained model
   b. Features from a public pretrained network
   c. Features from a SimCLR model (self-supervised learning)
   d. Using feature extractors
4. Slideflow Studio: Tile Extraction Preview & More
5. Slide Filtering / QC Updates
   a. DeepFocus
   b. GaussianV2
6. Smaller updates
   a. PyTorch Image Preprocessing Improvements
   b. Mini-batch sample diversity for PyTorch dataloaders
   c. TFRecord optimizations
   d. Other new features
   e. Other improvements
   f. Bug fixes

Slideflow Studio: MIL & Attention Heatmaps

Slideflow Studio now includes an MIL extension, allowing you to generate MIL predictions for slides and visualize attention as a heatmap.

Start by navigating to the Extensions tab in the bottom-left corner, and enable the "Multiple-instance Learning" extension.

A new icon will appear in the left-hand toolbar. Use this button to open the MIL widget. Models can be loaded by clicking the "Load MIL model" button, with "File -> Load MIL Model...", or by dragging-and-dropping an MIL model folder onto the window.

Information about the feature extractor and MIL model will be shown in the toolbar. MIL model architecture and hyperparameters can be viewed by clicking the "HP" button. Click "Predict Slide" to generate a whole-slide prediction. If applicable, attention will be displayed as a heatmap. The heatmap color and display can be customized in the Heatmap widget.

MIL Training Enhancements

Several changes in the MIL training process have been made to improve the user experience and facilitate deployment of trained MIL models on new slides.

Rebuilding feature extractors used for MIL

One of the previous challenges with MIL models was the reliance on generated feature "bags", even for model evaluation. Slideflow now includes tools to generate predictions from MIL models without manually generating feature bags, greatly simplifying evaluation and single-slide testing.

When image tile features are calculated and exported for a dataset (either with Project.generate_feature_bags() or DatasetFeatures.to_torch()), the feature extractor configuration is now saved as bags_config.json in the same directory as the exported feature bags. This configuration file contains all information necessary for rebuilding the feature extractor. An example file is shown below.

{
 "extractor": {
  "class": "slideflow.model.extractors.retccl.RetCCLFeatures",
  "kwargs": {
   "center_crop": true
  }
 },
 "normalizer": {
  "method": "macenko",
  "fit": {
   "stain_matrix_target": [
    [
     0.5062568187713623,
     0.22186939418315887
    ],
    [
     0.7532230615615845,
     0.8652154803276062
    ],
    [
     0.4069173336029053,
     0.42241501808166504
    ]
   ],
   "target_concentrations": [
    1.7656903266906738,
    1.2797492742538452
   ]
  }
 },
 "num_features": 2048,
 "tile_px": 299,
 "tile_um": 302
}

The feature extractor can then be rebuilt with sf.model.rebuild_extractor():

from slideflow.model.extractors import rebuild_extractor

# Recreate the feature extractor
# and stain normalizer, if applicable
extractor, normalizer = rebuild_extractor("/path/to/bags_config.json")

Single-slide predictions, without feature bags

The new sf.mil.predict_slide() function allows you to generate a whole-slide prediction (and attention heatmap) from a saved MIL model, without requiring the user to manually generate feature bags.

This is accomplished by including feature extraction information in the mil_params.json file stored in MIL model folders. When performing single-slide inference, Slideflow will automatically rebuild the feature extractor, calculate features for all tiles in the given slide, and pass these features to the loaded MIL model.

You can generate single-slide predictions using a path to a slide:

from slideflow.mil import predict_slide

slide = '/path/to/slide.svs'
model = '/path/to/mil_model'

# Calculate predictions and attention heatmap
y_pred, y_att = predict_slide(model, slide)

You can also generate single-slide predictions from a loaded WSI object, allowing you to customize slide processing or QC before generating predictions:

import slideflow as sf
from slideflow.mil import predict_slide
from slideflow.slide import qc

# Load slide and apply Otsu thresholding
slide = '/path/to/slide.svs'
wsi = sf.WSI(slide, ...)
wsi.qc(qc.Otsu())

# Calculate predictions and attention heatmap
y_pred, y_att = predict_slide('/path/to/mil_model', wsi)

QOL improvements for MIL training

Several smaller quality of life improvements have been made for MIL training. In addition to the feature extraction configuration, the mil_params.json file now also includes information about the input and output shapes of the MIL network and outcome labels. An example file is shown below.

{
 "trainer": "fastai",
 "params": {
  ...
 },
 "outcomes": "histology",
 "outcome_labels": {
  "0": "Adenocarcinoma",
  "1": "Squamous"
 },
 "bags": "/mnt/data/projects/example_project/bags/simclr-263510/",
 "input_shape": 1024,
 "output_shape": 2,
 "bags_encoder": {
  "extractor": {
   "class": "slideflow.model.extractors.simclr.SimCLR_Features",
   "kwargs": {
    "center_crop": false,
    "ckpt": "/mnt/data/projects/example_project/simclr/00001-EXAMPLE/ckpt-263510.ckpt"
   }
  },
  "normalizer": null,
  "num_features": 1024,
  "tile_px": 299,
  "tile_um": 302
 }
}

When exporting feature bags for MIL training with Project.generate_feature_bags(), memory consumption is reduced by performing the feature bag calculation in smaller batches of slides at a time. [#261]

Finally, when validating or evaluation MIL models with a categorical outcome, accuracy within each class is reported separately. [#265] (thank you @andrewsris)

INFO     Validation metrics for outcome histology:                                                                         
INFO     slide-level AUC (cat # 0): 0.993 AP: 0.998 (opt. threshold: 0.565)                                                
INFO     slide-level AUC (cat # 1): 0.993 AP: 0.974 (opt. threshold: 0.439)                                                
INFO     Category 0 acc: 97.3% (146/150)                                                                                   
INFO     Category 1 acc: 92.3% (36/39)

Streamlined Feature Extraction

Extracting features from image tiles - commonly used for training Multiple-instance Learning (MIL) models - has been streamlined with sf.model.build_feature_extractor(), providing a common API for preparing many types of feature extractors.

Features from layer activations of an ImageNet-pretrained model

Generate features from a neural network pretrained on ImageNet simply by passing the name of the network to sf.model.build_feature_extractor(). If a tile size is specified, input tiles will be center cropped before calculating features.

from slideflow.model import build_feature_extractor

resnet50_extractor = build_feature_extractor(
  'resnet50', 
  tile_px=299
)

This will calculate features using activations from the post-convolutional layer of the network. You can also concatenate activations from multiple layers and apply pooling for layers with 2D output shapes.

extractor = build_feature_extractor(
  'resnet50', 
  layers=['conv1_relu', 'conv3_block1_2_relu'],
  pooling='avg',
  tile_px=299
)

Features from layer activations of a fine-tuned model

Generate features from a model fine-tuned in Slideflow by calculating activations at any number of arbitrary neural network layers.

extractor = build_feature_extractor(
  '/path/to/trained_model.zip'
)

Features from a public pretrained network

Generate features from the pre-trained CTransPath or RetCCL networks. Weights for these pretrained networks will be automatically downloaded from HuggingFace.

extractor = build_feature_extractor(
  'retccl',
  tile_px=299
)

Features from a SimCLR model (self-supervised learning)

Generate features from a model trained with self-supervised learning using SimCLR. Specify a saved model folder or path to a model checkpoint (*.ckpt).

extractor = build_feature_extractor(
  'simclr'
  ckpt='/path/to/simclr.ckpt'
)

Using feature extractors

All feature extractors can then be used to calculate features from individual image tiles, generate feature bags for MIL training, or calculate features for an entire slide using a loaded WSI object.

Slideflow Studio: Tile Extraction Preview & More

Studio now facilitates quickly p...

Version 2.0.5

This is a minor, bug-fix release. See the Version 2.0 release notes for details about the latest major release.

Changes

• Fix ConcatOp error when training multi-modal models with continuous variables [#282]
• Minor docstring updates and typo fixes [#281]

Version 2.0.4

This is a minor, bug-fix and optimization release. See the Version 2.0 release notes for details about the latest major release.

Bug fixes

• Fix bug which caused the predictions.parquet file for MIL models to have incorrect ground-truth labels. This also impacted accuracy of results calculated with Project.evaluate_mil().
• Fix bug with Dataset.kfold_split()
• Fix bug with DatasetFeatures.to_csv() [#260]
• Fix bug with loading JPG/PNG files in Slideflow Studio
• Fix DatasetFeatures.remove_slide() when activations are not generated

Other changes

• Allow using relative paths with sf.create_project() [#272]
• Update Project.extract_tiles() docstring [#273]
• Add libvips version info in sf.about(), for easier troubleshooting
• Improve clarity of slide backend error messages [#266]
• Remove status bar when capturing main view in Slideflow Studio [#270]
• Improve accuracy of mosaic map grid
• Return original image when linalg errors would be raised during stain Macenko normalization in the Tensorflow backend, instead of raising an error
• Improve documentation clarity regarding CPH backend support [#276]

Version 2.0.3

This is a minor, bug-fix and optimization release. See the Version 2.0 release notes for details about the latest major release.

Bug fixes

• Fix bug with attention heatmaps: Fix bug where attention heatmaps were not appropriately displayed.
• Fix 'input tensor too large' error when using PyTorch GPU accelerated normalizers. Fix is applied by capping the batch size for
  normalization at 32.

Optimizations

• Improve PyTorch training speed by using channels-last memory format
• Improve quality of slide thumbnails in tile extraction PDF reports by decreasing the rectangle line width.
• Optimizations to PyTorch real-time stain normalization speed, by increasing the number of default threads.
• Minor optimizations for PyTorch dataloaders: file handlers are closed when the dataloader is destroyed.
• Improve Dataset.build_index() speed if index files are not missing.

Other changes

• Set required cellpose version to <2.2
• Set pandas version to <2.0 to avoid breaking issues with Seaborn
• Handle linalg errors during PyTorch Macenko normalization, returning the original image instead of raising an error.
• Improve error message for MIL_fc_mc model if outcomes are not multi-categorical.
• Update QuPath script to improve compatibility with MRXS files
• Stability improvements in Slideflow Studio when using Libvips backend
• Add additional debug logs during SimCLR training