Package: slideflow
ArXiv|Docs|Slideflow Studio|Cite🔬 OverviewSlideflow is a deep learning library for digital pathology, offering a user-friendly interface for model development.Designed at University of Chicago for both medical researchers and AI enthusiasts, the goal of Slideflow is to provide an accessible, easy-to-use interface for developing state-of-the-art pathology models. Slideflow has been built with the future in mind, offering a scalable platform for digital biomarker development that bridges the gap between ever-evolving, sophisticated methods and the needs of a clinical researcher. For developers, Slideflow provides multiple endpoints for integration with other packages and external training paradigms, allowing you to leverage highly optimized, pathology-specific processes with the latest ML methodologies.🚀 FeaturesEasy-to-use, highly customizable training pipelinesRobustslide processingandstain normalizationtoolkitSupport for training withweakly-supervisedorstrongly-supervisedlabelsMultiple-instance learning (MIL)Self-supervised learning (SSL)Generative adversarial networks (GANs)Explainability tools:Heatmaps,mosaic maps,saliency maps,synthetic histologyRobustlayer activation analysistoolsUncertainty quantificationInteractive user interfacefor model deployment... and more!Full documentation with example tutorials can be found atslideflow.dev.RequirementsPython >= 3.7 (<3.10 if usingcuCIM)Tensorflow2.5-2.11orPyTorch1.9-2.1GAN functions require PyTorch <1.13OptionalLibvips>= 8.9 (alternative slide reader, adds support for *.scn, *.mrxs, *.ndpi, *.vms, and *.vmu files).Linear solver (for preserved-site cross-validation)CPLEX20.1.0 withPython APIorPyomowithBonminsolver📥 InstallationSlideflow can be installed with PyPI, as a Docker container, or run from source.Method 1: Install via pippip3 install --upgrade setuptools pip wheel
pip3 install slideflow[cucim] cupy-cuda11xThecupypackage name depends on the installed CUDA version;see herefor installation instructions.cupyis not required if using Libvips.Method 2: Docker imageAlternatively, pre-configureddocker imagesare available with OpenSlide/Libvips and the latest version of either Tensorflow and PyTorch. To install with the Tensorflow backend:docker pull jamesdolezal/slideflow:latest-tf
docker run -it --gpus all jamesdolezal/slideflow:latest-tfTo install with the PyTorch backend:docker pull jamesdolezal/slideflow:latest-torch
docker run -it --shm-size=2g --gpus all jamesdolezal/slideflow:latest-torchMethod 3: From sourceTo run from source, clone this repository, install the conda development environment, and build a wheel:git clone https://github.com/jamesdolezal/slideflow
cd slideflow
conda env create -f environment.yml
conda activate slideflow
python setup.py bdist_wheel
pip install dist/slideflow* cupy-cuda11x⚙️ ConfigurationDeep learning (PyTorch vs. Tensorflow)Slideflow supports both PyTorch and Tensorflow, defaulting to PyTorch if both are available. You can specify the backend to use with the environmental variableSF_BACKEND. For example:export SF_BACKEND=tensorflowSlide reading (cuCIM vs. Libvips)By default, Slideflow reads whole-slide images usingcuCIM. Although much faster than other openslide-based frameworks, it supports fewer slide scanner formats. Slideflow also includes aLibvipsbackend, which adds support for *.scn, *.mrxs, *.ndpi, *.vms, and *.vmu files. You can set the active slide backend with the environmental variableSF_SLIDE_BACKEND:export SF_SLIDE_BACKEND=libvipsGetting startedSlideflow experiments are organized intoProjects, which supervise storage of whole-slide images, extracted tiles, and patient-level annotations. The fastest way to get started is to use one of our preconfigured projects, which will automatically download slides from the Genomic Data Commons:importslideflowassfP=sf.create_project(root='/project/destination',cfg=sf.project.LungAdenoSquam,download=True)After the slides have been downloaded and verified, you can skip toExtract tiles from slides.Alternatively, to create a new custom project, supply the location of patient-level annotations (CSV), slides, and a destination for TFRecords to be saved:importslideflowassfP=sf.create_project('/project/path',annotations="/patient/annotations.csv",slides="/slides/directory",tfrecords="/tfrecords/directory")Ensure that the annotations file has aslidecolumn for each annotation entry with the filename (without extension) of the corresponding slide.Extract tiles from slidesNext, whole-slide images are segmented into smaller image tiles and saved in*.tfrecordsformat.Extract tilesfrom slides at a given magnification (width in microns size) and resolution (width in pixels) usingsf.Project.extract_tiles():P.extract_tiles(tile_px=299,# Tile size, in pixelstile_um=302# Tile size, in microns)If slides are on a network drive or a spinning HDD, tile extraction can be accelerated by buffering slides to a SSD or ramdisk:P.extract_tiles(...,buffer="/mnt/ramdisk")Training modelsOnce tiles are extracted, models can betrained. Start by configuring a set ofhyperparameters:params=sf.ModelParams(tile_px=299,tile_um=302,batch_size=32,model='xception',learning_rate=0.0001,...)Models can then be trained using these parameters. Models can be trained to categorical, multi-categorical, continuous, or time-series outcomes, and the training process ishighly configurable. For example, to train models in cross-validation to predict the outcome'category1'as stored in the project annotations file:P.train('category1',params=params,save_predictions=True,multi_gpu=True)Evaluation, heatmaps, mosaic maps, and moreSlideflow includes a host of additional tools, including modelevaluation and prediction,heatmaps, analysis oflayer activations,mosaic maps, and more. See ourfull documentationfor more details and tutorials.📚 PublicationsSlideflow has been used by:Dolezal et al,Modern Pathology, 2020Rosenberg et al,Journal of Clinical Oncology[abstract], 2020Howard et al,Nature Communications, 2021Dolezal et alNature Communications, 2022Storozuk et al,Modern Pathology[abstract], 2022Partin et alFront Med, 2022Dolezal et alJournal of Clinical Oncology[abstract], 2022Dolezal et alMediastinum[abstract], 2022Howard et alnpj Breast Cancer, 2023Dolezal et alnpj Precision Oncology, 2023Hieromnimon et al[bioRxiv], 2023Carrillo-Perez et alCancer Imaging, 2023🔓 LicenseThis code is made available under the GPLv3 License and is available for non-commercial academic purposes.🔗 ReferenceIf you find our work useful for your research, or if you use parts of this code, please consider citing as follows:Dolezal, J. M., Kochanny, S., Dyer, E.,et al. Slideflow: Deep Learning for Digital Histopathology with Real-Time Whole-Slide Visualization. ArXiv [q-Bio.QM] (2023).http://arxiv.org/abs/2304.04142@misc{dolezal2023slideflow,
      title={Slideflow: Deep Learning for Digital Histopathology with Real-Time Whole-Slide Visualization},
      author={James M. Dolezal and Sara Kochanny and Emma Dyer and Andrew Srisuwananukorn and Matteo Sacco and Frederick M. Howard and Anran Li and Prajval Mohan and Alexander T. Pearson},
      year={2023},
      eprint={2304.04142},
      archivePrefix={arXiv},
      primaryClass={q-bio.QM}
}