Slideflow

https://slideflow.dev/
Admin
Slideflow is a deep learning framework for digital pathology that enables building and testing...
Tokens:714,634
Snippets:4,233
Trust Score:6.4
Update:6 months ago
Show doc for...
Tokens:
Raw
### Complete Strong Supervision Training Example

Source: https://slideflow.dev/tile_labels

A full example demonstrating the workflow for training a model with strong supervision, assuming project setup, tile extraction, and ROI labeling are complete.

```python
import slideflow as sf

# Load project and dataset
P = sf.load_project('/path/to/project')
dataset = P.dataset(tile_px=256, tile_um=256)

# Build tile label dataframe, and filter

```

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

### Launch Slideflow Studio via CLI

Source: https://slideflow.dev/studio

Commands to start the Studio application depending on the installation method.

```bash
slideflow-studio
```

```bash
python slideflow-studio.py
```

```bash
python -m slideflow.studio
```

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

### Complete Saliency Map Generation and Plotting Example

Source: https://slideflow.dev/_sources/saliency.rst.txt

A full example demonstrating loading a WSI, extracting a tile, loading a model, preparing the SaliencyMap, calculating integrated gradients, and displaying the result as an overlay. Ensure all file paths and model loading parameters are correct.

```python
import slideflow as sf
from slideflow.grad import SaliencyMap
from slideflow.grad.plot_utils import overlay
from PIL import Image

# Load a slide and find the desired image tile.
wsi = sf.WSI('slide.svs', tile_px=299, tile_um=302)
image = wsi[20, 20]

# Load a model and preprocessing function.
model = sf.model.load_model(../saved_model)
preprocess = sf.util.get_preprocess_fn('../saved_model')

# Prepare the saliency map
sal_map = SaliencyMap(model, class_idx=0)

# Calculate saliency map using integrated gradients.
ig_map = sal_map.integrated_gradients(preprocess(image))

# Display the saliency map as an overlay.
overlay_img = overlay(image, ig_map)
Image.fromarray(overlay_img).show()
```

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

### Build Slideflow from source

Source: https://slideflow.dev/_sources/installation.rst.txt

Clones the Slideflow repository, sets up a Conda environment, activates it, builds a wheel distribution, and installs it. Ensure you have Git and Conda installed.

```bash
git clone https://github.com/slideflow/slideflow
cd slideflow
conda env create -f environment.yml
conda activate slideflow
python setup.py bdist_wheel
pip install dist/slideflow* cupy-cuda11x
```

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

### Load project and prepare datasets

Source: https://slideflow.dev/tutorial7

Initialize the project and split the dataset for training and validation.

```python
>>> import slideflow as sf
>>> P = sf.load_project('/home/er_project')
>>> full_dataset = P.dataset(
...   tile_px=256,
...   tile_um=128,
...   filters={
...     'er_status_by_ihc': ['Positive', 'Negative']
... })
>>> labels, _ = full_dataset.labels('er_status_by_ihc')
>>> train, val = full_dataset.split(
...   labels='er_status_by_ihc',
...   val_strategy='k-fold',
...   val_k_fold=3,
...   k_fold_iter=1
... )
```

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

### Get Relative Path

Source: https://slideflow.dev/_modules/slideflow/util

Returns a relative path from a given root directory. It handles paths starting with '.' and raises an error for paths starting with '$ROOT'.

```python
def relative_path(path: str, root: str):
    """Returns a relative path, from a given root directory."""
    if path[0] == '.':
        return join(root, path[2:])
    elif path.startswith('$ROOT'):
        raise ValueError("Invalid path prefix $ROOT; update project settings")
    else:
        return path
```

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

### Create a Project from Configuration

Source: https://slideflow.dev/slideflow

Initializes a project using a pre-defined configuration template and optionally downloads data from TCGA.

```python
import slideflow as sf

project = sf.create_project(
    root='path',
    cfg=sf.project.LungAdenoSquam(),
    download=True
)
```

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

### Example Usage of sf.about()

Source: https://slideflow.dev/util

This example demonstrates how to call the `about()` function to display Slideflow version and backend information. No specific setup is required beyond importing the library.

```python
>>> sf.about()
╭=======================╮
│       Slideflow       │
│    Version: 3.0.0     │
│  Backend: torch       │
│ Slide Backend: cucim  │
```

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

### Load Dataset from Project

Source: https://slideflow.dev/datasets_and_val

Initialize a dataset using an existing project configuration.

```python
import slideflow as sf

P = sf.load_project('/project/path')
dataset = P.dataset(tile_px=299, tile_um='10x', sources=['Source1'])
```

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

### Complete Slideflow Project Setup and Training Script

Source: https://slideflow.dev/_sources/tutorial1.rst.txt

This script demonstrates the complete workflow: creating a project, extracting tiles, defining model parameters, and performing both cross-validation and full dataset training.

```python
import slideflow as sf

# Create a new project
P = sf.create_project(
        root='/home/er_project',
        slides='/path/to/slides'
    )

# Extract tiles at 256 pixels, 0.5 um/px
P.extract_tiles(tile_px=256, tile_um=128)

hp = ModelParams(
        tile_px=256,
        tile_um=128,
        model='xception',
        batch_size=32,
        epochs=[3, 5, 10]
    )

# Train with 5-fold cross-validation
P.train(
        'er_status_by_ihc',
        params=hp,
        val_k_fold=5,
        filters={'dataset': ['train'],
                    'er_status_by_ihc': ['Positive', 'Negative']}
    )

# Train across the entire training dataset
P.train(
        'er_status_by_ihc',
        params=hp,
        val_strategy='none',
        filters={'dataset': ['train'],
                    'er_status_by_ihc': ['Positive', 'Negative']}
    )
```

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

### Multiprocessing Pool Setup for Tile Extraction

Source: https://slideflow.dev/_modules/slideflow/dataset

Initializes a multiprocessing pool for parallel tile extraction. Selects the multiprocessing start method ('fork' or 'spawn') based on the slide backend to avoid compatibility issues.

```python
# Use multithreading if specified, extracting tiles
            # from all slides in the filtered list
            if len(slide_list):
                q = Queue()  # type: Queue
                # Forking incompatible with some libvips configurations
                ptype = 'spawn' if sf.slide_backend() == 'libvips' else 'fork'
                ctx = mp.get_context(ptype)
                manager = ctx.Manager()
                reports = manager.dict()
                kwargs['report'] = report

                # Use a single shared multiprocessing pool
                if 'num_threads' not in kwargs:
                    num_threads = sf.util.num_cpu()
                    if num_threads is None:
                        num_threads = 8
                    if sf.slide_backend() == 'libvips':
                        num_threads = min(num_threads, 32)
                else:
                    num_threads = kwargs['num_threads']
```

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

### Prepare Training Directory

Source: https://slideflow.dev/_modules/slideflow/mil/_params

Sets up the output directory for model training, creating it if it doesn't exist and generating a unique model directory name based on experiment label.

```python
import os
import slideflow as sf

log.info("Training FastAI MIL model with config:")
log.info(f"{str(self)}")
# Set up experiment label
if exp_label is None:
    try:
        if isinstance(self.model_config.model, str):
            model_name = self.model_config.model
        else:
            model_name = self.model_config.model.__name__
        exp_label = '{}-{}'.format(
            model_name,
            "-".join(outcomes if isinstance(outcomes, list) else [outcomes])
        )
    except Exception:
        exp_label = 'no_label'
# Set up output model directory
if outdir:
    if not os.path.exists(outdir):
        os.makedirs(outdir)
    outdir = sf.util.create_new_model_dir(outdir, exp_label)
return outdir
```

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

### Run Slideflow Docker container (Tensorflow backend)

Source: https://slideflow.dev/_sources/installation.rst.txt

Pulls the latest Docker image for Slideflow with the Tensorflow backend and runs it in interactive mode with GPU support. This is an easy way to get started with compatible dependencies.

```bash
docker pull jamesdolezal/slideflow:latest-tf
```

```bash
docker run -it --gpus all jamesdolezal/slideflow:latest-tf
```

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

### Initialize Training and Configure Environment

Source: https://slideflow.dev/_modules/slideflow/model/tensorflow

Handles model compatibility checks, normalizer fitting, and environment setup for training.

```python
if self.hp.model_type() != self._model_type:
    hp_model = self.hp.model_type()
    raise errors.ModelError(f"Incompatible models: {hp_model} (hp) and "
                            f"{self._model_type} (model)")

self._detect_patients(train_dts, val_dts)

# Verify image format across datasets.
img_format = self._verify_img_format(train_dts, val_dts)
if img_format and self.config['img_format'] is None:
    self.config['img_format'] = img_format
    sf.util.write_json(self.config, join(self.outdir, 'params.json'))

# Clear prior Tensorflow graph to free memory
tf.keras.backend.clear_session()
results_log = os.path.join(self.outdir, 'results_log.csv')

# Fit the normalizer to the training data and log the source mean/stddev
if self.normalizer and self.hp.normalizer_source == 'dataset':
    self.normalizer.fit(train_dts)
else:
    self._fit_normalizer(norm_fit)

if self.normalizer:
    config_path = join(self.outdir, 'params.json')
    if not exists(config_path):
        config = {
            'slideflow_version': sf.__version__,
            'hp': self.hp.to_dict(),
            'backend': sf.backend()
        }
    else:
        config = sf.util.load_json(config_path)
    config['norm_fit'] = self.normalizer.get_fit(as_list=True)
    sf.util.write_json(config, config_path)

# Prepare multiprocessing pool if from_wsi=True
if from_wsi:
    pool = mp.Pool(
        sf.util.num_cpu(default=8),
        initializer=sf.util.set_ignore_sigint
    )
else:
    pool = None

# Save training / validation manifest
if val_dts is None:
    val_paths = None
elif from_wsi:
    val_paths = val_dts.slide_paths()
else:
    val_paths = val_dts.tfrecords()
log_manifest(
    train_dts.tfrecords(),
    val_paths,
    labels=self.labels,
    filename=join(self.outdir, 'slide_manifest.csv')
)

# Neptune logging
if self.use_neptune:
    tags = ['train']
    if 'k-fold' in self.config['validation_strategy']:
        tags += [f'k-fold{self.config["k_fold_i"]}']
    self.neptune_run = self.neptune_logger.start_run(
        self.name,
        self.config['project'],
        train_dts,
        tags=tags
    )
    self.neptune_logger.log_config(self.config, 'train')
    self.neptune_run['data/slide_manifest'].upload(  # type: ignore
        os.path.join(self.outdir, 'slide_manifest.csv')
    )

# Set up multi-GPU strategy
if multi_gpu:
    strategy = tf.distribute.MirroredStrategy()
    log.info('Multi-GPU training with '
             f'{strategy.num_replicas_in_sync} devices')
```

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

### Get Valid Model Directories

Source: https://slideflow.dev/_modules/slideflow/util

Retrieves a list of directories within a root path that are considered valid model directories. These directories must be indented and start with a 5-digit number followed by a hyphen. This function is useful for identifying previously trained models.

```python
def get_valid_model_dir(root: str) -> List:
    '''
    This function returns the path of the first indented directory from root.
    This only works when the indented folder name starts with a 5 digit number,
    like "00000%."

    Examples
        If the root has 3 files:
        root/00000-foldername/
        root/00001-foldername/
        root/00002-foldername/

        The function returns "root/00000-foldername/"
    ''

    prev_run_dirs = [
        x for x in os.listdir(root)
        if isdir(join(root, x))
    ]
    prev_run_ids = [re.match(r'^\d+', x) for x in prev_run_dirs]
    prev_run_ids = [int(x.group()) for x in prev_run_ids if x is not None]
    return prev_run_ids, prev_run_dirs
```

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

### prepare_training

Source: https://slideflow.dev/_modules/slideflow/mil/_params

Sets up the output directory for the model and initializes the experiment label.

```APIDOC
## prepare_training

### Description
Sets up the output directory for the model and initializes the experiment label for training.

### Parameters
#### Request Body
- **outcomes** (str | List[str]) - Required - Outcomes.
- **exp_label** (str) - Optional - Experiment label.
- **outdir** (str) - Optional - Output directory.

### Response
- **outdir** (str) - The path to the created output directory.
```

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

### Build FastAI Learner for MIL

Source: https://slideflow.dev/_modules/slideflow/mil/train

Initializes a FastAI Learner for training a Multiple Instance Learning (MIL) model. This function prepares datasets, aggregates bags by slide or patient, and configures the learner without starting the training process. Useful for custom learner setup.

```python
from slideflow import Dataset, TrainerConfig
from typing import Union, List
import numpy as np

# Assuming necessary imports for utils, log, and _fastai are present
# from . import utils, log, _fastai

# Placeholder for TrainerConfig and Dataset for demonstration
class TrainerConfig:
    def __init__(self, aggregation_level='slide', is_classification=True):
        self.aggregation_level = aggregation_level
        self.is_classification = is_classification

class Dataset:
    def get_bags(self, bags_param):
        return []
    def slides(self):
        return []
    def patients(self):
        return {}

# Placeholder for log and _fastai
class log:
    @staticmethod
    def info(msg):
        print(f"INFO: {msg}")

class _fastai:
    @staticmethod
    def build_learner(config, bags, targets, train_idx, val_idx, unique_categories, outdir, **kwargs):
        print("Building learner...")
        return (None, (100, 1)) # Dummy learner and shape

# Placeholder for utils
class utils:
    @staticmethod
    def get_labels(datasets, outcomes, is_classification):
        return [], []
    @staticmethod
    def aggregate_trainval_bags_by_slide(bags, labels, train_slides, val_slides, log_manifest):
        return [], [], [], []
    @staticmethod
    def aggregate_trainval_bags_by_patient(bags, labels, train_slides, val_slides, slide_to_patient, log_manifest):
        return [], [], [], []

from os.path import join, isdir

def build_fastai_learner(
    config: TrainerConfig,
    train_dataset: Dataset,
    val_dataset: Dataset,
    outcomes: Union[str, List[str]],
    bags: Union[str, np.ndarray, List[str]],
    *,
    outdir: str = 'mil',
    return_shape: bool = False,
    **kwargs
) -> "Learner":
    """Build a FastAI Learner for training an MIL model.

    Does not execute training. Useful for customizing a Learner object
    prior to training.

    Args:
        train_dataset (:class:`slideflow.Dataset`): Training dataset.
        val_dataset (:class:`slideflow.Dataset`): Validation dataset.
        outcomes (str): Outcome column (annotation header) from which to
            derive category labels.
        bags (str): list of paths to individual *.pt files. Each file should
            contain exported feature vectors, with each file containing all tile
            features for one patient.

    Keyword args:
        outdir (str): Directory in which to save model and results.
        return_shape (bool): Return the input and output shapes of the model.
            Defaults to False.
        exp_label (str): Experiment label, used for naming the subdirectory
            in the ``outdir`` folder, where training history
            and the model will be saved.
        lr (float): Learning rate, or maximum learning rate if
            ``fit_one_cycle=True``.
        epochs (int): Maximum epochs.
        **kwargs: Additional keyword arguments to pass to the FastAI learner.

    Returns:
        fastai.learner.Learner, and optionally a tuple of input and output shapes
        if ``return_shape=True``.

    """
    from . import _fastai

    labels, unique = utils.get_labels((train_dataset, val_dataset), outcomes, config.is_classification())

    # Prepare bags
    if isinstance(bags, str) or (isinstance(bags, list) and isdir(bags[0])):
        train_bags = train_dataset.get_bags(bags)
        if val_dataset is train_dataset:
            bags = train_bags
        else:
            val_bags = val_dataset.get_bags(bags)
            bags = np.concatenate((train_bags, val_bags))
    else:
        bags = np.array(bags)

    train_slides = train_dataset.slides()
    val_slides = val_dataset.slides()

    if config.aggregation_level == 'slide':
        # Aggregate feature bags across slides.
        bags, targets, train_idx, val_idx = utils.aggregate_trainval_bags_by_slide(
            bags,  # type: ignore
            labels,
            train_slides,
            val_slides,
            log_manifest=(join(outdir, 'slide_manifest.csv') if outdir else None)
        )

    elif config.aggregation_level == 'patient':
        # Associate patients and their slides.
        # This is a dictionary where each key is a slide name and each value
        # is a patient code. Multiple slides can match to the same patient.
        slide_to_patient = { **train_dataset.patients(),
                             **val_dataset.patients() }

        # Aggregate feature bags across patients.
        n_slide_bags = len(bags)
        bags, targets, train_idx, val_idx = utils.aggregate_trainval_bags_by_patient(
            bags,  # type: ignore
            labels,
            train_slides,
            val_slides,
            slide_to_patient=slide_to_patient,
            log_manifest=(join(outdir, 'slide_manifest.csv') if outdir else None)
        )
        log.info(f"Aggregated {n_slide_bags} slide bags to {len(bags)} patient bags.")

    log.info("Training dataset: {} merged bags (from {} possible slides)".format(
        len(train_idx), len(train_slides)))
    log.info("Validation dataset: {} merged bags (from {} possible slides)".format(
        len(val_idx), len(val_slides)))

    # Build FastAI Learner
    learner, (n_in, n_out) = _fastai.build_learner(
        config,
        bags=bags,
        targets=targets,
        train_idx=train_idx,
        val_idx=val_idx,
        unique_categories=unique,
        outdir=outdir,
        **kwargs
    )
    if return_shape:
        return learner, (n_in, n_out)
    else:
        return learner

```

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

### Initialize Trainer and Prepare Datasets

Source: https://slideflow.dev/_sources/training.rst.txt

Prepare datasets, labels, and model parameters before building a Trainer instance.

```python
# Prepare dataset and labels
dataset = P.dataset(tile_px=299, tile_um=302)
labels, unique_labels = dataset.labels('tumor_type')

# Split into training/validation
train_dataset = dataset.filter({"dataset": ["train"]})
val_dataset = dataset.filter({"dataset": ["val"]})

# Determine model parameters
hp = sf.ModelParams(
    tile_px=299,
    tile_um=302,
    batch_size=32,
    ...
)

# Prepare a Trainer
trainer = sf.model.build_trainer(
    hp=hp,
    outdir='path',
    labels=labels
)
```

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

### Install GigaPath dependencies for Slideflow

Source: https://slideflow.dev/_sources/installation.rst.txt

Installs specific dependencies for the GigaPath feature extractor, which is part of the Slideflow-NonCommercial extension. This requires installing from a Git SSH URL.

```bash
pip install slideflow-noncommercial[gigapath] git+ssh://git@github.com/prov-gigapath/prov-gigapath
```

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

### Install DINOv2

Source: https://slideflow.dev/_sources/ssl.rst.txt

Installs the modified DINOv2 package via pip.

```bash
pip install git+https://github.com/jamesdolezal/dinov2.git
```

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

### Initialize Model Configuration and Inputs

Source: https://slideflow.dev/_modules/slideflow/model/tensorflow

Handles directory creation, outcome label formatting, and input setup for model training.

```python
        self.eval_callback = _PredictionAndEvaluationCallback  # type: tf.keras.callbacks.Callback
        self.load_method = load_method
        self.custom_objects = custom_objects
        self.patients = dict()

        if not os.path.exists(outdir):
            os.makedirs(outdir)

        # Format outcome labels (ensures compatibility with single
        # and multi-outcome models)
        outcome_labels = np.array(list(labels.values()))
        if len(outcome_labels.shape) == 1:
            outcome_labels = np.expand_dims(outcome_labels, axis=1)
        if not outcome_names:
            outcome_names = [
                f'Outcome {i}'
                for i in range(outcome_labels.shape[1])
            ]
        outcome_names = sf.util.as_list(outcome_names)
        if labels and (len(outcome_names) != outcome_labels.shape[1]):
            num_names = len(outcome_names)
            num_outcomes = outcome_labels.shape[1]
            raise errors.ModelError(f'Size of outcome_names ({num_names}) != '
                                    f'number of outcomes {num_outcomes}')
        self.outcome_names = outcome_names
        self._setup_inputs()
        if labels:
            self.num_classes = self.hp._detect_classes_from_labels(labels)
            with tf.device('/cpu'):
                for oi in range(outcome_labels.shape[1]):
                    self.annotations_tables += [tf.lookup.StaticHashTable(
                        tf.lookup.KeyValueTensorInitializer(
                            self.slides,
                            outcome_labels[:, oi]
                        ), -1
                    )]
        else:
            self.num_classes = None  # type: ignore

        # Normalization setup
        self.normalizer = self.hp.get_normalizer()
        if self.normalizer:
            log.info(f'Using realtime {self.hp.normalizer} normalization')

        # Mixed precision and Tensorfloat-32
        if self.mixed_precision:
            _policy = 'mixed_float16'
            log.debug(f'Enabling mixed precision ({_policy})')
            if version.parse(tf.__version__) > version.parse("2.8"):
                tf.keras.mixed_precision.set_global_policy(_policy)
            else:
                policy = tf.keras.mixed_precision.experimental.Policy(_policy)
                tf.keras.mixed_precision.experimental.set_policy(policy)
        tf.config.experimental.enable_tensor_float_32_execution(allow_tf32)

        # Custom transforms
        self._process_transforms(transform)

        # Log parameters
        if config is None:
            config = {
                'slideflow_version': sf.__version__,
                'backend': sf.backend(),
                'git_commit': sf.__gitcommit__,
                'model_name': self.name,
                'full_model_name': self.name,
                'outcomes': self.outcome_names,
                'model_type': self.hp.model_type(),
                'img_format': None,
                'tile_px': self.hp.tile_px,
                'tile_um': self.hp.tile_um,
                'input_features': None,
                'input_feature_sizes': None,
                'input_feature_labels': None,
                'hp': self.hp.to_dict()
            }
        sf.util.write_json(config, join(self.outdir, 'params.json'))
        self.config = config
        self.img_format = config['img_format'] if 'img_format' in config else None

        # Initialize Neptune
        self.use_neptune = use_neptune
        if self.use_neptune:
            if neptune_api is None or neptune_workspace is None:
                raise ValueError("If using Neptune, must supply values "
                                 "neptune_api and neptune_workspace.")
            self.neptune_logger = sf.util.neptune_utils.NeptuneLog(
                neptune_api,
                neptune_workspace
            )
```

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

### Initialize Model with Configuration

Source: https://slideflow.dev/_modules/slideflow/project

Constructs the full model name, including k-fold information if specified, and determines the model directory. Logs detailed configuration settings and hyperparameters for the model.

```python
full_name = s_args.model_name
        if s_args.k is not None:
            full_name += f'-kfold{s_args.k}'
        model_dir = sf.util.get_new_model_dir(self.models_dir, full_name)
```

```python
config = {
            'slideflow_version': sf.__version__,
            'project': self.name,
            'backend': sf.backend(),
            'git_commit': sf.__gitcommit__,
            'model_name': s_args.model_name,
            'full_model_name': full_name,
            'stage': 'training',
            'img_format': train_dts.img_format,
            'tile_px': hp.tile_px,
            'tile_um': hp.tile_um,
            'max_tiles': s_args.max_tiles,
            'min_tiles': s_args.min_tiles,
            'model_type': hp.model_type(),
            'outcomes': s_args.outcomes,
            'input_features': s_args.input_header,
            'input_feature_sizes': feature_sizes,
            'input_feature_labels': inpt_labels,
            'outcome_labels': s_args.outcome_labels,
            'dataset_config': self.dataset_config,
            'sources': self.sources,
            'annotations': self.annotations,
            'validation_strategy': val_settings.strategy,
            'validation_fraction': val_settings.fraction,
            'validation_k_fold': val_settings.k_fold,
            'k_fold_i': s_args.k,
            'filters': s_args.filters,
            'hp': hp.to_dict(),
            'training_kwargs': s_args.training_kwargs,
        }
```

```python
model_kwargs = {
            'hp': hp,
            'name': full_name,
            'feature_names': s_args.input_header,
            'feature_sizes': feature_sizes,
            'outcome_names': s_args.outcomes,
            'outdir': model_dir,
            'config': config,
            'slide_input': slide_inp,
            'labels': s_args.labels,
            'mixed_precision': s_args.mixed_precision,
            'allow_tf32': s_args.allow_tf32,
            'use_neptune': self.use_neptune,
            'neptune_api': self.neptune_api,
            'neptune_workspace': self.neptune_workspace,
            'load_method': s_args.load_method
        }
```

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

### Install and Use Plugin Package

Source: https://slideflow.dev/_sources/plugins.rst.txt

After building and distributing your plugin package, users can install it using pip. Once installed, Slideflow will automatically recognize and utilize the registered models and extractors.

```bash
pip install my_package
```

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

### Install PyTorch ViT Library

Source: https://slideflow.dev/_sources/tutorial3.rst.txt

Install the required vit-pytorch package via pip.

```bash
pip3 install vit-pytorch
```

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

### Prepare Optimizers and Loss Function

Source: https://slideflow.dev/_modules/slideflow/model/torch

Initializes the optimizer, learning rate scheduler (if configured), and loss function. Includes setup for mixed precision scaling on CUDA devices.

```python
def _prepare_optimizers_and_loss(self) -> None:
        if self.model is None:
            raise ValueError("Model has not yet been initialized.")
        self.optimizer = self.hp.get_opt(self.model.parameters())
        if self.hp.learning_rate_decay:
            self.scheduler = torch.optim.lr_scheduler.ExponentialLR(
                self.optimizer,
                gamma=self.hp.learning_rate_decay
            )
            log.debug("Using exponentially decaying learning rate")
        else:
            self.scheduler = None  # type: ignore
        self.loss_fn = self.hp.get_loss()
        if self.mixed_precision and self.device.type == 'cuda':
            self.scaler = torch.cuda.amp.GradScaler()
```

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

### Launch Slideflow Studio from Source

Source: https://slideflow.dev/_sources/studio.rst.txt

Start Slideflow Studio by executing the main script from the GitHub repository.

```bash
python slideflow-studio.py
```

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

### Start Network Runner Thread

Source: https://slideflow.dev/_modules/slideflow/cellseg

Starts the network inference process in a separate thread.

```python
runner = threading.Thread(target=net_runner)
runner.start()
```

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

### Install Slideflow extensions

Source: https://slideflow.dev/installation

Install additional GPL or Non-Commercial extensions and specific dependencies for GigaPath.

```bash
# Install Slideflow-GPL and Slideflow-NonCommercial
pip install slideflow-gpl slideflow-noncommercial

# Install GigaPath dependencies, if desired
pip install slideflow-noncommercial[gigapath] git+ssh://git@github.com/prov-gigapath/prov-gigapath
```

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

### Generate Numpy Image from Starting Class

Source: https://slideflow.dev/_modules/slideflow/gan/interpolate

Generates a numpy image from the starting class embedding.

```APIDOC
## Generate Numpy Image from Starting Class

### Description
Generates a numpy image (uint8, shape=(height, width, 3)) using the pre-defined starting class embedding.

### Method
This is a method within a class, not a direct API endpoint.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Assuming 'self' is an instance of the class
seed = 456
image_np_start = self.generate_np_start(seed)
```

### Response
#### Success Response (200)
- **np.ndarray**: Image (uint8, shape=(height, width, 3))

#### Response Example
```python
# Example numpy array representing an image
# image_np_start = np.array([...])
```
```

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

### Start Model Training

Source: https://slideflow.dev/_sources/tutorial2.rst.txt

Initiate the training process by calling the `train` method on the trainer instance, passing the training and validation datasets. The results, including metrics across epochs, are returned.

```python
>>> results = trainer.train(train_dts, val_dts)
```

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

### Initialize WSI and Generate Heatmap

Source: https://slideflow.dev/_sources/evaluation.rst.txt

Sets up a WSI object with specific tile parameters and generates a heatmap using a specified model.

```python
wsi = sf.WSI('slide.svs', tile_px=299, tile_um=302, rois='/path')
wsi.qc([qc.Otsu(), qc.Gaussian()])

# Generate a heatmap
heatmap = sf.Heatmap(
  slide=wsi,
  model='/path/to/model'
  batch_size=64,
  num_processes=16
)
```

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

### Guided Integrated Gradients

Source: https://slideflow.dev/_modules/slideflow/grad

Calculate a saliency map using the guided integrated gradients method.

```APIDOC
## guided_integrated_gradients

### Description
Calculate saliency map using guided integrated gradients.

### Parameters
#### Request Body
- **img** (np.ndarray) - Required - Pre-processed input image in W, H, C format.
- **x_steps** (int) - Optional - Steps for gradient calculation. Defaults to 25.
- **max_dist** (float) - Optional - Maximum distance for gradient calculation. Defaults to 1.0.
- **fraction** (float) - Optional - Fraction for gradient calculation. Defaults to 0.5.
- **smooth** (bool) - Optional - Smooth gradients. Defaults to False.

### Response
- **Returns** (np.ndarray) - Saliency map.
```

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

### Initialize Interface Components

Source: https://slideflow.dev/_modules/slideflow/studio

Initializes core widgets and sets up the initial window state, including icon, position, and font scaling.

```python
        self.capture_widget     = CaptureWidget(self)
        self.settings_widget    = SettingsWidget(self)

        # User-defined widgets.
        self.widgets = []
        if widgets is None:
            widgets = self.get_default_widgets()
        self.add_widgets(widgets)

        # Extensions widget.
        self.extensions_widget  = ExtensionsWidget(self)

        # Initialize window.
        self.set_window_icon(imgui_utils.logo_image())
        self.set_position(0, 0)
        self._update_window_limits()
        self._set_default_font_size()
        self.skip_frame() # Layout may change after first frame.
        self.load_slide('')
```

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

### Install Slideflow via pip

Source: https://slideflow.dev/installation

Install the core package with either Tensorflow or PyTorch backend support.

```bash
# Update to latest pip
pip install --upgrade pip wheel

# Current stable release, Tensorflow backend
pip install slideflow[tf] cucim cupy-cuda11x

# Alternatively, install with PyTorch backend
pip install slideflow[torch] cucim cupy-cuda11x
```

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

### Install Bonmin Solver

Source: https://slideflow.dev/io

Use this command to install the Bonmin solver via conda for use with site-preserved cross-validation.

```bash
conda install -c conda-forge coinbonmin
```

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

### Execute model training

Source: https://slideflow.dev/tutorial7

Start the training process using the prepared datasets.

```python
>>> results = trainer.train(train, val)
```

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

### Install slideflow-gpl for CLAMModelConfig

Source: https://slideflow.dev/_sources/mil_module.rst.txt

Install the slideflow-gpl package to use the CLAMModelConfig class. This is a prerequisite for CLAM model configurations.

```bash
pip install slideflow-gpl
```

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

### Prepare Optimizers, Loss Function, and Begin Epoch Loop

Source: https://slideflow.dev/_modules/slideflow/model/torch

Prepares the optimizers and loss function for training. Initializes the epoch loop, setting random seeds and logging the current epoch number. Resets training records and sets the model to training mode.

```python
# Model parameters and optimizer
        self._prepare_optimizers_and_loss()

        # === Epoch loop ======================================================
        for self.epoch in range(starting_epoch, max(self.hp.epochs)+1):
            np.random.seed(seed+self.epoch)
            log.info(f'[bold]Epoch {self.epoch}/{max(self.hp.epochs)}')

            # Training loop ---------------------------------------------------
            self.epoch_records = 0
            self.running_loss = 0.0
            self.step = 1
            self.running_corrects = self._empty_corrects()  # type: ignore
            self.model.train()
            pb = Progress(
                *Progress.get_default_columns(),
                TimeElapsedColumn(),
                ImgBatchSpeedColumn(self.hp.batch_size),

```

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

### Initialize Dataset via Keyword Arguments

Source: https://slideflow.dev/dataset

Use this method to load a single dataset source by providing paths to the data components directly.

```python
dataset = Dataset(
    tfrecords='../path',
    slides='../path',
    annotations='../file.csv'
)
```

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

### Create TFRecord Example

Source: https://slideflow.dev/_modules/slideflow/io/tensorflow

Generates a Tensorflow Data example for TFRecord storage. Includes optional location coordinates.

```python
def tfrecord_example(
    slide: bytes,
    image_raw: bytes,
    loc_x: Optional[int] = 0,
    loc_y: Optional[int] = 0
) -> "Example":
    """Return a Tensorflow Data example for TFRecord storage.

    Args:
        slide (bytes): Slide name.
        image_raw (bytes): Image bytes.
        loc_x (Optional[int], optional): X coordinate of image. Defaults to 0.
        loc_y (Optional[int], optional): Y coordinate of image. Defaults to 0.

    Returns:
        Example: Tensorflow Data example.

    """
    feature = {
        'slide': _bytes_feature(slide),
        'image_raw': _bytes_feature(image_raw),
    }
    if loc_x is not None:
        feature.update({'loc_x': _int64_feature(loc_x)})
    if loc_y is not None:
        feature.update({'loc_y': _int64_feature(loc_y)})
    return tf.train.Example(features=tf.train.Features(feature=feature))
```

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

### Initialize and Configure Slideflow Project

Source: https://slideflow.dev/tutorial1

Create a new project instance and extract tiles from slide images.

```python
P = sf.create_project(
    root='/home/er_project',
    slides='/path/to/slides'
)

# Extract tiles at 256 pixels, 0.5 um/px
P.extract_tiles(tile_px=256, tile_um=128)
```

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

### Install Cellpose

Source: https://slideflow.dev/_sources/cellseg.rst.txt

Install the Cellpose library using pip. This is a prerequisite for using Slideflow's cell segmentation features.

```bash
pip install cellpose
```

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

### Install slideflow-noncommercial Package

Source: https://slideflow.dev/_sources/biscuit.rst.txt

Install the slideflow-noncommercial package, which is a requirement for this module. This package provides necessary functionalities for the BISCUIT algorithm.

```bash
pip install slideflow-noncommercial
```

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

### Configure and Run Model Training

Source: https://slideflow.dev/_modules/slideflow/model/tensorflow

Sets up training arguments, initializes callbacks (History, validation, checkpointing, TensorBoard), and initiates the model fitting process. Handles potential resource exhaustion errors during training.

```python
cb_args = SimpleNamespace(
                starting_epoch=starting_epoch,
                using_validation=using_validation,
                validate_on_batch=validate_on_batch,
                validation_steps=validation_steps,
                ema_observations=ema_observations,
                ema_smoothing=ema_smoothing,
                steps_per_epoch=steps_per_epoch,
                validation_data=validation_data,
                mid_train_validation_data=mid_train_validation_data,
                num_val_tiles=val_tiles,
                save_predictions=save_predictions,
                save_model=save_model,
                results_log=results_log,
                reduce_method=reduce_method,
                log_frequency=log_frequency
            )

            # Create callbacks for early stopping, checkpoint saving,
            # summaries, and history
            val_callback = self.eval_callback(self, cb_args)
            callbacks = [tf.keras.callbacks.History(), val_callback]
            if save_checkpoints:
                cp_callback = tf.keras.callbacks.ModelCheckpoint(
                    os.path.join(self.outdir, 'cp.ckpt'),
                    save_weights_only=True,
                    verbose=(sf.getLoggingLevel() <= 20)
                )
                callbacks += [cp_callback]
            if use_tensorboard:
                log.debug(
                    "Logging with Tensorboard to {} every {} batches.".format(
                        self.outdir, log_frequency
                    )
                )
                tensorboard_callback = tf.keras.callbacks.TensorBoard(
                    log_dir=self.outdir,
                    histogram_freq=0,
                    write_graph=False,
                    update_freq='batch'
                )
                callbacks += [tensorboard_callback]

            # Retrain top layer only, if using transfer learning and
            # not resuming training
            total_epochs = (self.hp.toplayer_epochs
                            + (max(self.hp.epochs) - starting_epoch))
            if self.hp.toplayer_epochs:
                self._retrain_top_layers(
                    train_data,
                    steps_per_epoch,
                    callbacks=None,
                    epochs=self.hp.toplayer_epochs
                )
            self._compile_model()

            # Train the model
            log.info('Beginning training')
            try:
                self.model.fit(
                    train_data,
                    steps_per_epoch=steps_per_epoch,
                    epochs=total_epochs,
                    verbose=(sf.getLoggingLevel() <= 20),
                    initial_epoch=self.hp.toplayer_epochs,
                    callbacks=callbacks
                )
            except tf.errors.ResourceExhaustedError as e:
                log.error(f"Training failed for [bold]{self.name}[/]. "
                          f"Error: \n {e}")
            results = val_callback.results
            if self.use_neptune and self.neptune_run is not None:
                self.neptune_run['results'] = results['epochs']
                self.neptune_run.stop()

            # Cleanup
            if pool is not None:
                pool.close()
            del mid_train_validation_data

            return results
```

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

### Initialize Slideflow Project

Source: https://slideflow.dev/_sources/tutorial2.rst.txt

Set up a Slideflow project instance. Ensure the project path and name are correctly specified. The 'annotations' argument should be configured as needed.

```python
>>> import slideflow as sf
>>> P = sf.Project('/home/er_project', name="Breast_ER", annotations=...)
```

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

### Create Multi-Image TFRecord Example

Source: https://slideflow.dev/_modules/slideflow/io/tensorflow

Generates a Tensorflow Data example for storage with multiple images associated with a single slide.

```python
def multi_image_example(slide: bytes, image_dict: Dict) -> "Example":
    """Returns a Tensorflow Data example for storage with multiple images.

    Args:
        slide (bytes): Slide name.
        image_dict (Dict): Dictionary of image names and image bytes.

    Returns:
        Example: Tensorflow Data example.

    """
    feature = {
        'slide': _bytes_feature(slide)
    }
    for image_label in image_dict:
        feature.update({
            image_label: _bytes_feature(image_dict[image_label])
        })
    return tf.train.Example(features=tf.train.Features(feature=feature))
```

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

### Initialize WSI Processing

Source: https://slideflow.dev/_modules/slideflow/project

Sets up WSI processing by creating output directories and preparing the dataset and model configuration. It verifies dataset parameters and logs extraction settings.

```python
log.info('Generating WSI prediction / activation maps...')
        if not exists(outdir):
            os.makedirs(outdir)

        if source:
            sources = sf.util.as_list(source)
        else:
            sources = self.sources
        if dataset.tile_px is None or dataset.tile_um is None:
            raise errors.DatasetError(
                "Dataset must have non-zero tile_px and tile_um"
            )
        # Prepare dataset & model
        if img_format == 'auto':
            config = sf.util.get_model_config(model)
            img_format = config['img_format']

        # Log extraction parameters
        sf.slide.log_extraction_params(**kwargs)
```

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

### Generate NumPy Image from Starting Class Embedding

Source: https://slideflow.dev/_modules/slideflow/gan/interpolate

Generates a NumPy image using the starting class embedding. Relies on `generate_np_from_embedding`.

```python
return self.generate_np_from_embedding(seed, self.embed0)
```

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

### Monitor training with Tensorboard

Source: https://slideflow.dev/_sources/tutorial1.rst.txt

Use this command to start Tensorboard and monitor training logs. Access Tensorboard via https://localhost:6006.

```bash
$ tensorboard --logdir=/project_path/models/00001-outcome-HP0
```

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

### Build Feature Extractor Examples

Source: https://slideflow.dev/model

Examples demonstrating how to initialize different feature extractors and use them for dataset or slide-level feature calculation.

```python
import slideflow as sf

extractor = sf.build_feature_extractor(
    'resnet50_imagenet'
)
```

```python
extractor = sf.build_feature_extractor(
    'resnet50_imagenet',
    layers='conv4_block4_2_relu
)
```

```python
extractor = sf.build_feature_extractor('ctranspath')
```

```python
import slideflow as sf

# Load a project and dataset
P = sf.load_project(...)
dataset = P.dataset(...)

# Create a feature extractor
resnet = sf.build_feature_extractor(
    'resnet50_imagenet'
)

# Calculate features for the entire dataset
features = sf.DatasetFeatures(
    resnet,
    dataset=dataset
)
```

```python
import slideflow as sf

# Load a slide
wsi = sf.WSI(...)

# Create a feature extractor
retccl = sf.build_feature_extractor(
    'retccl',
    resize=True
)

# Create a feature map, a 2D array of shape
```

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

### Get and Set ROI Label

Source: https://slideflow.dev/_modules/slideflow/slide/utils

Allows getting and setting the label for an ROI. When a label is set, it is also applied to all associated holes.

```python
@property
    def label(self) -> Optional[str]:
        """Return the label of the ROI."""
        return self._label

    @label.setter
    def label(self, label: str) -> None:
        """Set the label of the ROI."""
        self._label = label
        for h in self.holes.values():
            h.label = label
```

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

### Initialize and Prepare Experiments

Source: https://slideflow.dev/_modules/slideflow_noncommercial/biscuit/experiment

Initializes experiments by ensuring annotations are correctly set up and adding new experiments if they don't exist. This prepares the environment for training.

```python
P = self.train_project
eval_Ps = self.eval_projects
exp_annotations = join(P.root, 'experiments.csv')
if P.annotations != exp_annotations:
 if not exists(exp_annotations):
 shutil.copy(P.annotations, exp_annotations)
 P.annotations = exp_annotations
exp_to_add = [
 e for e in exp_to_run
 if f'include_{e}' not in pd.read_csv(exp_annotations).columns.tolist()
]
for exp in exp_to_add:
 self.add(exp_annotations, label=exp, **exp_to_run[exp])
```

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

### Configure Plugin Entry Points in setup.py

Source: https://slideflow.dev/_sources/plugins.rst.txt

Define plugin connections in your package's `setup.py` file using the `entry_points` key to link with the Slideflow plugin interface.

```python
...,
    entry_points={
        'slideflow.plugins': [
            'extras = my_package:register_extras',
        ],
    },
```

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

### Install Slideflow extensions

Source: https://slideflow.dev/_sources/installation.rst.txt

Installs the Slideflow-GPL and Slideflow-NonCommercial extensions via pip. These packages provide additional functionality under different licensing terms.

```bash
pip install slideflow-gpl slideflow-noncommercial
```

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

### Generate TensorFlow Image from Starting Class Embedding

Source: https://slideflow.dev/_modules/slideflow/gan/interpolate

Generates processed TensorFlow images using the starting class embedding. Calls `generate_tf_from_embedding`.

```python
return self.generate_tf_from_embedding(seed, self.embed0)
```

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

### Build Model and Setup DataLoaders

Source: https://slideflow.dev/_modules/slideflow/model/torch

Builds the model, potentially using a checkpoint or pre-trained weights. Configures the model for multi-GPU training if specified and moves it to the appropriate device. Sets up training and validation dataloaders.

```python
# Prepare neptune run
        self._prepare_neptune_run(train_dts, 'train')

        # Build model
        self._build_model(checkpoint, pretrain)
        assert self.model is not None

        # Print model summary
        self._print_model_summary(train_dts)

        # Multi-GPU
        if multi_gpu:
            self.model = torch.nn.DataParallel(self.model)
        self.model = self.model.to(self.device)

        # Setup dataloaders
        self._setup_dataloaders(
            train_dts=train_dts,
            val_dts=val_dts,
            mid_train_val=True,
            roi_method=roi_method,
            from_wsi=from_wsi,
            pool=pool)
```

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

### Generate TensorFlow Image from Starting Class

Source: https://slideflow.dev/_modules/slideflow/gan/interpolate

Creates processed TensorFlow images from GAN output using a given seed and the starting class embedding.

```APIDOC
## Generate TensorFlow Image from Starting Class

### Description
Creates processed TensorFlow images (unprocessed and processed versions) from the GAN output, using a given seed and the pre-defined starting class embedding.

### Method
This is a method within a class, not a direct API endpoint.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Assuming 'self' is an instance of the class
seed = 112
unprocessed_img_tf_start, processed_img_tf_start = self.generate_tf_start(seed)
```

### Response
#### Success Response (200)
- **Tuple[tf.Tensor, tf.Tensor]**: A tuple containing:
    - tf.Tensor: Unprocessed image (tf.Tensor), uint8.
    - tf.Tensor: Processed image (tf.Tensor), standardized and normalized.

#### Response Example
```python
# Example TensorFlow tensors representing images
# unprocessed_img_tf_start = tf.Tensor(...)
# processed_img_tf_start = tf.Tensor(...)
```
```

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

### Run Experiments with UQ (Step 3)

Source: https://slideflow.dev/_modules/slideflow_noncommercial/biscuit/experiment

Initiates experiments incorporating Uncertainty Quantification (UQ) with a single epoch setting. This step is for advanced analysis requiring UQ.

```python
print(sf.util.bold("[Step 3] Running experiments with UQ..."))
exp_hp.epochs = [1]
```
Tokens:
Raw