Slideflow

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

Minor features
- Update cuCIM micron-per-pixel detection. When detecting MPP from TIFF metadata, recognize the singular form of units (centimeter, millimeter, micrometer) in addition to plural form [420]
- Add `show_progress` keyword argument for the feature extractor `tfrecord_inference()` method, for optionally displaying a progress bar.
- Add new `run_batched_inference()` method to pytorch feature extractors, used for generating features from a large tensor dataset of images.
- When generating features (using a feature extractor) from a loaded pytorch tensor of images, add a new `batch_size` argument that runs batch inference, decreasing memory requirements:

ctranspath = sf.build_feature_extractor('ctranspath')
images = torch.load(...)
features = ctranspath(images, batch_size=32)


Fixes
- Skip disk logs if Slideflow is in a read-only directory
- Fix rare `TypeError: 'NoneType' object is not subscriptable` error when attempting to get an image tile from a slide via indexing and the image tile is invalid (e.g. out of bounds; corrupted; etc)
- Minor fix to progress bar accuracy during bag generation
- Fix/remove `lifelines` requirement [414]
- Add numpy 2.0 compatibility to PyTorch dataloaders
- Require `spacy<3.8` to prevent numpy version incompatibility with FastAI
- Add `pyarrow` to requirements (required for parquet reading/writing)
- Fix dataset splitting for survival models
- Various unit test updates

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

Changes
- Fix inability to use ImageNet-pretrained feature extractors for generating feature bags [412]
- Fix crash in Slideflow Studio when expanding the slide list in the Project widget [413]
- Fix rare `cupy_backends.cuda.api.runtime.CUDARuntimeError` when extracting edge tiles in cuCIM backend
- Handle `ValueError` encountered when an out-of-bounds tile cannot be extracted in cuCIM
- Improve ROI filtering accuracy for whole-slide images when `use_edge_tiles=True`
- Add `disable_grid` argument to `sf.WSI`, for disabling grid-based extraction (useful for high-magnification cell segmentation extraction)
- Fix `'outlines_list' not found` error with cell segmentation
- Add missing Studio segmentation sidebar button

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

python
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](https://github.com/jamesdolezal/dinov2) that allows you to train the network using Slideflow projects and datasets. See our [documentation](https://slideflow.dev/ssl/#dinov2) for instructions on how to train and use DINOv2.

New MIL Features

Highlights

We are very excited to announce the release of **Slideflow 3.0**, a pivotal update that not only introduces powerful new features and models but also marks a significant shift in our licensing structure to better support the needs of our community. This release includes **three new foundation models, expanded MIL capabilities, faster tissue segmentation, and an improved toolset for Slideflow Studio**. Slideflow 3.0 also introduces **plugin support** for seamless integration of custom tools and models, along with a number of other new features and optimizations.

Table of Contents

1. **Open-Source License**
2. **Slideflow Studio Updates**
- New ROI Annotation Tools
- Tissue Segmentation
- Improved MIL Support
3. **New Foundation Models**
- Virchow
- UNI
- GigaPath
4. **MIL Updates**
- Continuous Outcomes
- BYOM (Bring Your Own Model)
- Improved API
5. **Plugin Support**
6. **Other New Features**
7. **Dependencies**

Open-Source License

With the release of Slideflow 3.0, **we've made significant changes to our licensing structure** to better support open-source collaboration and accommodate a broader range of users, from academic researchers to industry professionals. These changes reflect our ongoing commitment to supporting open science while respecting the legal considerations of the third-party tools we integrate.

Core Package: Apache-2.0 License

The core Slideflow package is now licensed under the **Apache-2.0** license. This permissive license allows users to freely use, modify, and distribute Slideflow, whether in commercial or non-commercial settings.

>[!NOTE]
> While the Apache-2.0 license allows for commercial use, it’s important to remember that Slideflow remains a research-focused tool, developed by a small academic team. We encourage users, especially those considering commercial applications, to thoroughly test and validate the software within their specific environments.

Extensions: Tailored Licensing

To respect the original licenses of various third-party tools integrated into Slideflow, we've created separate extensions with tailored licenses:
- **[Slideflow-NonCommercial](https://github.com/slideflow/slideflow-noncommercial)**: Licensed under **Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)**. This package includes advanced tools and models available for non-commercial use only, such as StyleGAN3, BISCUIT, and the newly introduced UNI and GigaPath models.
- **[Slideflow-GPL](https://github.com/slideflow/slideflow-gpl)**: Licensed under **GPL-3.0**. This package includes tools that are distributed under the GPL-3.0 license, such as RetCCL, CTransPath, and CLAM models. Users are free to use, modify, and distribute these tools under the same GPL-3.0 license, which requires that derivative works also be open-sourced under the same license. Please note that the authors of these tools have requested that use be restricted to academic, non-commercial purposes.

While all of these tools are accessible for academic, non-commercial use, please be aware that respecting these licenses is important when using Slideflow in a commercial environment to avoid potential legal issues.

How to Install

Installing Slideflow and its extensions is straightforward:
- **Core Slideflow**: `pip install slideflow`
- **Non-Commercial Tools**: `pip install slideflow-noncommercial`
- **GPL-3 Licensed Tools**: `pip install slideflow-gpl`

Slideflow Studio Updates

Version 3.0 brings improved functionality to Slideflow Studio, with more advanced ROI annotation tools, a new tissue segmentation widget, and other performance and quality of life enhancements designed to save you time and effort.

New ROI Tools
Studio now includes two tools for annotating ROIs: a lasso tool and polygon tool. The new polygon tool enables users to more precisely outline tricky features and comes with a new ability to manually edit ROIs that have been created. Although Slideflow Studio does not yet contain a full arsenal of ROI tools you might find in other software, these new additions will make it easier to make minor adjustments directly within Slideflow, decreasing the need to edit ROIs in other software.

https://github.com/user-attachments/assets/edf7c377-af40-4f8e-a4cb-f84024988e91

ROIs are now displayed as filled by default, making it easier to both see and interact with slide annotations.

Tissue Segmentation Widget
Tissue segmentation models can now be trained within Slideflow Studio, using ROI annotations also created in Studio. This exciting new functionality means that you can execute a full segmentation experiment - from training to deployment - directly within the UI. For example, you can now annotate tissues with labeled ROIs, train segmentation models, and deploy these models to new slides, all within the same user interface.

https://github.com/user-attachments/assets/6f0da6be-da47-443e-b08e-1bab978fb345

Improved MIL Support

MIL model compatibility for Slideflow Studio has been further expanded. All MIL model architectures, including both classification and regression MIL models, as well as multi-attention and multi-magnification MIL models, can be used for live predictions in Studio.

[CLAM_MB.webm](https://github.com/user-attachments/assets/7f4eabbc-6a9c-4239-bc38-896f23c1dcf1)

Other Studio Updates
The project pane now contains a tool for filtering a slide list:

https://github.com/user-attachments/assets/e55339a9-69ce-4fa6-a3de-66a4a5244704

New Foundation Models

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
- Improve compatibility checks in Studio for MIL models trained by magnification ("10x") rather than micron size [365] - thank you jziggles
- Fix inability to load multi-class CLAM models in Studio
- Fix bug where `outdir` could not be set for `Project.train_mil()`
- AUROC plots generated when training an MIL model are now saved in the MIL output directory instead of current working directory
- Fix "unsupported operand type(s)" error when loading some GANs in Studio
- Fix bug where Otsu thresholding ignored `roi_method='ignore'`
- Fix export of MIL attention heatmaps for multi-dimensional attention models (e.g. CLAM_MB) [360] - thank you jziggles
- Fix sf.mil.get_mil_tile_predictions for CLAM models [401] = thank you sz3029
- Fix bug where slide view in Slideflow Studio would gradually drift / zoom out at some window sizes
- Improve compatibility with Neptune 2.2.0 [338] - thank you luiscarm9
- Compatibility update for `timm` >= 1.0 (ctranspath) [381] - thank you maxxfarma
- Loosen seaborn requirements [373] - thank you johnurbanik
- Reduce incidence of `Tcl_AsyncDelete: async handler deleted by the wrong thread` errors when training MIL models in a loop