Quickstart

==========

This section provides an example of using Slideflow to build a deep learning classifier from digital pathology slides. Follow the links in each section for more information.

Preparing a project

*******************

Slideflow experiments are organized using :class:`slideflow.Project`, which supervises storage of data, saved models, and results. The ``slideflow.project`` module has three preconfigured projects with associated slides and clinical annotations: ``LungAdenoSquam``, ``ThyroidBRS``, and ``BreastER``.

For this example, we will the ``LungAdenoSquam`` project to train a classifier to predict lung adenocarcinoma (Adeno) vs. squamous cell carcinoma (Squam).

.. code-block:: python

    import slideflow as sf

    # Download preconfigured project, with slides and annotations.

    project = sf.create_project(

        root='data',

        cfg=sf.project.LungAdenoSquam(),

        download=True

    )

Read more about :ref:`setting up a project on your own data <project_setup>`.

Data preparation

****************

The core imaging data used in Slideflow are image tiles :ref:`extracted from slides <filtering>` at a specific magnification and pixel resolution. Tile extraction and downstream image processing is handled through the primitive :ref:`slideflow.Dataset <datasets_and_validation>`. We can request a ``Dataset`` at a given tile size from our project using :meth:`slideflow.Project.dataset`. Tile magnification can be specified in microns (as an ``int``) or as optical magnification (e.g. ``'40x'``).

.. code-block:: python

    # Prepare a dataset of image tiles.

    dataset = project.dataset(

        tile_px=299,   # Tile size, in pixels.

        tile_um='10x'  # Tile size, in microns or magnification.

    )

    dataset.summary()

.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Overview:

    ╒===============================================╕

    │ Configuration file: │ /mnt/data/datasets.json │

    │ Tile size (px):     │ 299                     │

    │ Tile size (um):     │ 10x                     │

    │ Slides:             │ 941                     │

    │ Patients:           │ 941                     │

    │ Slides with ROIs:   │ 941                     │

    │ Patients with ROIs: │ 941                     │

    ╘===============================================╛

    Filters:

    ╒====================╕

    │ Filters:      │ {} │

    ├--------------------┤

    │ Filter Blank: │ [] │

    ├--------------------┤

    │ Min Tiles:    │ 0  │

    ╘====================╛

    Sources:

    TCGA_LUNG

    ╒==============================================╕

    │ slides    │ /mnt/raid/SLIDES/TCGA_LUNG       │

    │ roi       │ /mnt/raid/SLIDES/TCGA_LUNG       │

    │ tiles     │ /mnt/rocket/tiles/TCGA_LUNG      │

    │ tfrecords │ /mnt/rocket/tfrecords/TCGA_LUNG/ │

    │ label     │ 299px_10x                        │

    ╘==============================================╛

    Number of tiles in TFRecords: 0

    Annotation columns:

    Index(['patient', 'subtype', 'site', 'slide'],

        dtype='object')

Tile extraction

---------------

We prepare imaging data for training by extracting tiles from slides. Background areas of slides will be filtered out with Otsu's thresholding.

.. code-block:: python

    # Extract tiles from all slides in the dataset.

    dataset.extract_tiles(qc='otsu')

Read more about tile extraction and :ref:`slide processing in Slideflow <filtering>`.

Held-out test sets

------------------

Now that we have our dataset and we've completed the initial tile image processing, we'll split the dataset into a training cohort and a held-out test cohort with :meth:`slideflow.Dataset.split`. We'll split while balancing the outcome ``'subtype'`` equally in the training and test dataset, with 30% of the data retained in the held-out set.

.. code-block:: python

    # Split our dataset into a training and held-out test set.

    train_dataset, test_dataset = dataset.split(

        model_type='classification',

        labels='subtype',

        val_fraction=0.3

    )

Read more about :ref:`Dataset management <datasets_and_validation>`.

Configuring models

******************

Neural network models are prepared for training with :class:`slideflow.ModelParams`, through which we define the model architecture, loss, and hyperparameters. Dozens of architectures are available in both the Tensorflow and PyTorch backends, and both neural network :ref:`architectures <tutorial3>` and :ref:`loss <custom_loss>` functions can be customized. In this example, we will use the included Xception network.

.. code-block:: python

    # Prepare a model and hyperparameters.

    params = sf.ModelParams(

        tile_px=299,

        tile_um='10x',

        model='xception',

        batch_size=64,

        learning_rate=0.0001

    )

Read more about :ref:`hyperparameter optimization in Slideflow <training>`.

Training a model

****************

Models can be trained from these hyperparameter configurations using :meth:`Project.train`. Models can be trained to categorical, multi-categorical, continuous, or time-series outcomes, and the training process is :ref:`highly configurable <training>`. In this case, we are training a binary categorization model to predict the outcome ``'subtype'``, and we will distribute training across multiple GPUs.

By default, Slideflow will train/validate on the full dataset using k-fold cross-validation, but validation settings :ref:`can be customized <validation_planning>`. If you would like to restrict training to only a subset of your data - for example, to leave a held-out test set untouched - you can manually specify a dataset for training. In this case, we will train on ``train_dataset``, and allow Slideflow to further split this into training and validation using three-fold cross-validation.

.. code-block:: python

    # Train a model from a set of hyperparameters.

    results = P.train(

        'subtype',

        dataset=train_dataset,

        params=params,

        val_strategy='k-fold',

        val_k_fold=3,

        multi_gpu=True,

    )

Models and training results will be saved in the project ``models/`` folder.

Read more about :ref:`training a model <training>`.

Evaluating a trained model

**************************

After training, you can test model performance on a held-out test dataset with :meth:`Project.evaluate`, or generate predictions without evaluation (when ground-truth labels are not available) with :meth:`Project.predict`. As with :meth:`Project.train`, we can specify a :class:`slideflow.Dataset` to evaluate.

.. code-block:: python

    # Train a model from a set of hyperparameters.

    test_results = P.evaluate(

        model='/path/to/trained_model_epoch1'

        outcomes='subtype',

        dataset=test_dataset

    )

Read more about :ref:`model evaluation <evaluation>`.

Post-hoc analysis

*****************

Slideflow includes a number of analytical tools for working with trained models. Read more about :ref:`heatmaps <evaluation>`, :ref:`model explainability <stylegan>`, :ref:`analysis of layer activations <activations>`, and real-time inference in an interactive :ref:`whole-slide image reader <studio>`.