<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Training — slideflow 3.0.0 documentation</title>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<!-- <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> -->
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="index" title="Index" href="../genindex/" />
<link rel="search" title="Search" href="../search/" />
<link rel="next" title="Evaluation" href="../evaluation/" />
<link rel="prev" title="Slide Processing" href="../slide_processing/" />
<script src="../_static/js/modernizr.min.js"></script>
<!-- Preload the theme fonts -->
<link rel="preload" href="../_static/fonts/FreightSans/freight-sans-book.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="../_static/fonts/FreightSans/freight-sans-medium.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="../_static/fonts/IBMPlexMono/IBMPlexMono-Medium.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="../_static/fonts/FreightSans/freight-sans-bold.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="../_static/fonts/FreightSans/freight-sans-medium-italic.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="../_static/fonts/IBMPlexMono/IBMPlexMono-SemiBold.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<!-- Preload the katex fonts -->
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Math-Italic.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Main-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Main-Bold.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Size1-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Size4-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Size2-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Size3-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preload" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/fonts/KaTeX_Caligraphic-Regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.15.2/css/all.css" integrity="sha384-vSIIfh2YWi9wW0r9iZe7RJPrKwp6bG+s9QZMoITbCckVJqGCCRhc+ccxNcdpHuYu" crossorigin="anonymous">
<script defer data-domain="slideflow.dev" src="https://plausible.io/js/script.js"></script>
</head>
<div class="container-fluid header-holder tutorials-header" id="header-holder">
<div class="container">
<div class="header-container">
<a class="header-logo" href="https://slideflow.dev" aria-label="Slideflow"></a>
<div class="main-menu">
<ul>
<li class="active">
<a href="https://slideflow.dev">Docs</a>
</li>
<li>
<a href="https://slideflow.dev/tutorial1/">Tutorials</a>
</li>
<li>
<a href="https://github.com/slideflow/slideflow">GitHub</a>
</li>
</ul>
</div>
<a class="main-menu-open-button" href="#" data-behavior="open-mobile-menu"></a>
</div>
</div>
</div>
<body class="pytorch-body">
<div class="table-of-contents-link-wrapper">
<span>Table of Contents</span>
<a href="#" class="toggle-table-of-contents" data-behavior="toggle-table-of-contents"></a>
</div>
<nav data-toggle="wy-nav-shift" class="pytorch-left-menu" id="pytorch-left-menu">
<div class="pytorch-side-scroll">
<div class="pytorch-menu pytorch-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<div class="pytorch-left-menu-search">
<div class="version">
3.0
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search/" method="get">
<input type="text" name="q" placeholder="Search Docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<p class="caption" role="heading"><span class="caption-text">Introduction</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../installation/">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../overview/">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../quickstart/">Quickstart</a></li>
<li class="toctree-l1"><a class="reference internal" href="../project_setup/">Setting up a Project</a></li>
<li class="toctree-l1"><a class="reference internal" href="../datasets_and_val/">Datasets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../slide_processing/">Slide Processing</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Training</a></li>
<li class="toctree-l1"><a class="reference internal" href="../evaluation/">Evaluation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../posthoc/">Layer Activations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../uq/">Uncertainty Quantification</a></li>
<li class="toctree-l1"><a class="reference internal" href="../features/">Generating Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="../mil/">Multiple-Instance Learning (MIL)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../ssl/">Self-Supervised Learning (SSL)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stylegan/">Generative Networks (GANs)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../saliency/">Saliency Maps</a></li>
<li class="toctree-l1"><a class="reference internal" href="../segmentation/">Tissue Segmentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../cellseg/">Cell Segmentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../custom_loops/">Custom Training Loops</a></li>
<li class="toctree-l1"><a class="reference internal" href="../studio/">Slideflow Studio: Live Visualization</a></li>
<li class="toctree-l1"><a class="reference internal" href="../troubleshooting/">Troubleshooting</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Developer Notes</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../tfrecords/">TFRecords: Reading and Writing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dataloaders/">Dataloaders: Sampling and Augmentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../custom_extractors/">Custom Feature Extractors</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tile_labels/">Strong Supervision with Tile Labels</a></li>
<li class="toctree-l1"><a class="reference internal" href="../plugins/">Creating a Slideflow Plugin</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">API</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../slideflow/">slideflow</a></li>
<li class="toctree-l1"><a class="reference internal" href="../project/">slideflow.Project</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dataset/">slideflow.Dataset</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dataset_features/">slideflow.DatasetFeatures</a></li>
<li class="toctree-l1"><a class="reference internal" href="../heatmap/">slideflow.Heatmap</a></li>
<li class="toctree-l1"><a class="reference internal" href="../model_params/">slideflow.ModelParams</a></li>
<li class="toctree-l1"><a class="reference internal" href="../mosaic/">slideflow.Mosaic</a></li>
<li class="toctree-l1"><a class="reference internal" href="../slidemap/">slideflow.SlideMap</a></li>
<li class="toctree-l1"><a class="reference internal" href="../biscuit/">slideflow.biscuit</a></li>
<li class="toctree-l1"><a class="reference internal" href="../slideflow_cellseg/">slideflow.cellseg</a></li>
<li class="toctree-l1"><a class="reference internal" href="../io/">slideflow.io</a></li>
<li class="toctree-l1"><a class="reference internal" href="../io_tensorflow/">slideflow.io.tensorflow</a></li>
<li class="toctree-l1"><a class="reference internal" href="../io_torch/">slideflow.io.torch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../gan/">slideflow.gan</a></li>
<li class="toctree-l1"><a class="reference internal" href="../grad/">slideflow.grad</a></li>
<li class="toctree-l1"><a class="reference internal" href="../mil_module/">slideflow.mil</a></li>
<li class="toctree-l1"><a class="reference internal" href="../model/">slideflow.model</a></li>
<li class="toctree-l1"><a class="reference internal" href="../model_tensorflow/">slideflow.model.tensorflow</a></li>
<li class="toctree-l1"><a class="reference internal" href="../model_torch/">slideflow.model.torch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../norm/">slideflow.norm</a></li>
<li class="toctree-l1"><a class="reference internal" href="../simclr/">slideflow.simclr</a></li>
<li class="toctree-l1"><a class="reference internal" href="../slide/">slideflow.slide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../slide_qc/">slideflow.slide.qc</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stats/">slideflow.stats</a></li>
<li class="toctree-l1"><a class="reference internal" href="../util/">slideflow.util</a></li>
<li class="toctree-l1"><a class="reference internal" href="../studio_module/">slideflow.studio</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../tutorial1/">Tutorial 1: Model training (simple)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial2/">Tutorial 2: Model training (advanced)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial3/">Tutorial 3: Using a custom architecture</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial4/">Tutorial 4: Model evaluation & heatmaps</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial5/">Tutorial 5: Creating a mosaic map</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial6/">Tutorial 6: Custom slide filtering</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial7/">Tutorial 7: Training with custom augmentations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial8/">Tutorial 8: Multiple-Instance Learning</a></li>
</ul>
</div>
</div>
</nav>
<div class="pytorch-container">
<div class="pytorch-page-level-bar" id="pytorch-page-level-bar">
<div class="pytorch-breadcrumbs-wrapper">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="pytorch-breadcrumbs">
<li>
<a href="../">
Docs
</a> >
</li>
<li>Training</li>
<li class="pytorch-breadcrumbs-aside">
<a href="../_sources/training.rst.txt" rel="nofollow"><img src="../_static/images/view-page-source-icon.svg"></a>
</li>
</ul>
</div>
</div>
<div class="pytorch-shortcuts-wrapper" id="pytorch-shortcuts-wrapper">
Shortcuts
</div>
</div>
<section data-toggle="wy-nav-shift" id="pytorch-content-wrap" class="pytorch-content-wrap">
<div class="pytorch-content-left">
<div class="rst-content">
<div role="main" class="main-content" itemscope="itemscope" itemtype="http://schema.org/Article">
<article itemprop="articleBody" id="pytorch-article" class="pytorch-article">
<section id="training">
<span id="id1"></span><h1>Training<a class="headerlink" href="#training" title="Permalink to this heading">¶</a></h1>
<p>Slideflow offers tools for training many types of neural networks, including:</p>
<ul class="simple">
<li><p><strong>Weakly supervised, tile-based models</strong>: Models trained on image tiles, with labels inherited from the parent slide.</p></li>
<li><p><strong>Weakly supervised, multi-instance learning</strong>: Models trained on feature vectors, with labels inherited from the parent slide.</p></li>
<li><p><strong>Strongly supervised models</strong>: Models trained on image tiles, with labels assigned by ROI.</p></li>
<li><p><strong>Self-supervised pretraining</strong>: Contrastive pretraining with or without labels (e.g. <a class="reference external" href="https://arxiv.org/abs/2002.05709">SimCLR</a>).</p></li>
<li><p><strong>Generative adversarial networks</strong>: Models trained to generate synthetic images (e.g. <a class="reference external" href="https://arxiv.org/abs/1912.04958">StyleGAN2/3</a>).</p></li>
<li><p><strong>Segmentation models</strong>: Models trained to identify and classify tissue regions (e.g. <a class="reference external" href="https://arxiv.org/abs/1505.04597">U-Net</a>).</p></li>
</ul>
<p>In this section, we will walk through the process of training a weakly supervised tile-based model. <a class="reference internal" href="../tile_labels/#tile-labels"><span class="std std-ref">Strong supervision</span></a>, <a class="reference internal" href="../mil/#mil"><span class="std std-ref">Multi-instance learning (MIL)</span></a>, <a class="reference internal" href="../ssl/#simclr-ssl"><span class="std std-ref">self-supervised pretraining (SSL)</span></a>, <a class="reference internal" href="../stylegan/#stylegan"><span class="std std-ref">generative adversarial networks (GAN)</span></a>, and <a class="reference internal" href="../segmentation/#segmentation"><span class="std std-ref">Tissue Segmentation</span></a> are described in other sections.</p>
<section id="prepare-hyperparameters">
<h2>Prepare hyperparameters<a class="headerlink" href="#prepare-hyperparameters" title="Permalink to this heading">¶</a></h2>
<p>The first step of training a weakly-supervised model is configuring model parameters and hyperparameters with <a class="reference internal" href="../model_params/#slideflow.ModelParams" title="slideflow.ModelParams"><code class="xref py py-class docutils literal notranslate"><span class="pre">slideflow.ModelParams</span></code></a>. <code class="docutils literal notranslate"><span class="pre">ModelParams</span></code> determines the model architecture, loss, preprocessing augmentations, and training hyperparameters.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">slideflow</span> <span class="k">as</span> <span class="nn">sf</span>
<span class="n">hp</span> <span class="o">=</span> <span class="n">sf</span><span class="o">.</span><span class="n">ModelParams</span><span class="p">(</span>
<span class="n">epochs</span><span class="o">=</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">5</span><span class="p">],</span>
<span class="n">model</span><span class="o">=</span><span class="s1">'xception'</span><span class="p">,</span>
<span class="n">learning_rate</span><span class="o">=</span><span class="mf">0.0001</span><span class="p">,</span>
<span class="n">batch_size</span><span class="o">=</span><span class="mi">8</span><span class="p">,</span>
<span class="o">...</span>
<span class="p">)</span>
</pre></div>
</div>
<p>See the <a class="reference internal" href="../model_params/#slideflow.ModelParams" title="slideflow.ModelParams"><code class="xref py py-class docutils literal notranslate"><span class="pre">slideflow.ModelParams</span></code></a> API documentation for a list of available hyperparameters.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you are using a continuous variable as an outcome measure, be sure to use a regression loss function. Regression loss functions can be viewed in <code class="docutils literal notranslate"><span class="pre">slideflow.ModelParams.RegressionLossDict</span></code>, and all available loss functions are in <code class="docutils literal notranslate"><span class="pre">slideflow.ModelParams.AllLossDict</span></code>.</p>
</div>
</section>
<section id="training-a-model">
<h2>Training a model<a class="headerlink" href="#training-a-model" title="Permalink to this heading">¶</a></h2>
<p>Slideflow provides two methods for training models: with the high-level <a class="reference internal" href="../project/#slideflow.Project.train" title="slideflow.Project.train"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Project.train()</span></code></a> function or with the lower-level <a class="reference internal" href="../model/#slideflow.model.Trainer" title="slideflow.model.Trainer"><code class="xref py py-class docutils literal notranslate"><span class="pre">slideflow.model.Trainer</span></code></a>. The former provides an easier interface for executing complex training tasks with a single function call, while the latter provides lower-level access for greater customizability.</p>
<section id="training-with-a-project">
<span id="training-with-project"></span><h3>Training with a Project<a class="headerlink" href="#training-with-a-project" title="Permalink to this heading">¶</a></h3>
<p><a class="reference internal" href="../project/#slideflow.Project.train" title="slideflow.Project.train"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Project.train()</span></code></a> provides an easy API for executing complex training plans and organizing results in the project directory. This is the recommended way to train models in Slideflow. There are two required arguments for this function:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">outcomes</span></code>: Name (or list of names) of annotation header columns, from which to determine slide labels.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">params</span></code>: Model parameters.</p></li>
</ul>
<p>The default validation plan is three-fold cross-validation, but the validation strategy can be customized via keyword arguments (<code class="docutils literal notranslate"><span class="pre">val_strategy</span></code>, <code class="docutils literal notranslate"><span class="pre">val_k_fold</span></code>, etc) as described in the API documentation. If crossfold validation is used, each model in the crossfold will be trained sequentially. Read more about <a class="reference internal" href="../datasets_and_val/#validation-strategies"><span class="std std-ref">validation strategies</span></a>.</p>
<p>By default, all slides in the project will be used for training. You can restrict your training/validation data to only a subset of slides in the project with one of two methods: either by providing <code class="docutils literal notranslate"><span class="pre">filters</span></code> or a filtered <a class="reference internal" href="../dataset/#slideflow.Dataset" title="slideflow.Dataset"><code class="xref py py-class docutils literal notranslate"><span class="pre">slideflow.Dataset</span></code></a>.</p>
<p>For example, you can use the <code class="docutils literal notranslate"><span class="pre">filters</span></code> argument to train/validate only using slides labeled as “train_and_val” in the “dataset” column with the following syntax:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">results</span> <span class="o">=</span> <span class="n">P</span><span class="o">.</span><span class="n">train</span><span class="p">(</span>
<span class="n">outcomes</span><span class="o">=</span><span class="s2">"tumor_type"</span><span class="p">,</span>
<span class="n">params</span><span class="o">=</span><span class="n">sf</span><span class="o">.</span><span class="n">ModelParams</span><span class="p">(</span><span class="o">...</span><span class="p">),</span>
<span class="n">filters</span><span class="o">=</span><span class="p">{</span><span class="s2">"dataset"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"train_and_val"</span><span class="p">]}</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Alternatively, you can restrict the training/validation dataset by providing a <a class="reference internal" href="../dataset/#slideflow.Dataset" title="slideflow.Dataset"><code class="xref py py-class docutils literal notranslate"><span class="pre">slideflow.Dataset</span></code></a> to the <code class="docutils literal notranslate"><span class="pre">dataset</span></code> argument:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">dataset</span> <span class="o">=</span> <span class="n">P</span><span class="o">.</span><span class="n">dataset</span><span class="p">(</span><span class="n">tile_px</span><span class="o">=</span><span class="mi">299</span><span class="p">,</span> <span class="n">tile_um</span><span class="o">=</span><span class="mi">302</span><span class="p">)</span>
<span class="n">dataset</span> <span class="o">=</span> <span class="n">dataset</span><span class="o">.</span><span class="n">filter</span><span class="p">({</span><span class="s2">"dataset"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"train_and_val"</span><span class="p">]})</span>
<span class="n">results</span> <span class="o">=</span> <span class="n">P</span><span class="o">.</span><span class="n">train</span><span class="p">(</span>
<span class="n">outcomes</span><span class="o">=</span><span class="s2">"tumor_type"</span><span class="p">,</span>
<span class="n">params</span><span class="o">=</span><span class="n">sf</span><span class="o">.</span><span class="n">ModelParams</span><span class="p">(</span><span class="o">...</span><span class="p">),</span>
<span class="n">dataset</span><span class="o">=</span><span class="n">dataset</span>
<span class="p">)</span>
</pre></div>
</div>
<p>In both cases, slides will be further split into training and validation sets using the specified validation settings (defaulting to three-fold cross-validation).</p>
<p>For more granular control over the validation dataset used, you can supply a <a class="reference internal" href="../dataset/#slideflow.Dataset" title="slideflow.Dataset"><code class="xref py py-class docutils literal notranslate"><span class="pre">slideflow.Dataset</span></code></a> to the <code class="docutils literal notranslate"><span class="pre">val_dataset</span></code> argument. Doing so will cause the rest of the validation keyword arguments to be ignored.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">dataset</span> <span class="o">=</span> <span class="n">P</span><span class="o">.</span><span class="n">dataset</span><span class="p">(</span><span class="n">tile_px</span><span class="o">=</span><span class="mi">299</span><span class="p">,</span> <span class="n">tile_um</span><span class="o">=</span><span class="mi">302</span><span class="p">)</span>
<span class="n">train_dataset</span> <span class="o">=</span> <span class="n">dataset</span><span class="o">.</span><span class="n">filter</span><span class="p">({</span><span class="s2">"dataset"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"train"</span><span class="p">]})</span>
<span class="n">val_dataset</span> <span class="o">=</span> <span class="n">dataset</span><span class="o">.</span><span class="n">filter</span><span class="p">({</span><span class="s2">"dataset"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"val"</span><span class="p">]})</span>
<span class="n">results</span> <span class="o">=</span> <span class="n">P</span><span class="o">.</span><span class="n">train</span><span class="p">(</span>
<span class="n">outcomes</span><span class="o">=</span><span class="s2">"tumor_type"</span><span class="p">,</span>
<span class="n">params</span><span class="o">=</span><span class="n">sf</span><span class="o">.</span><span class="n">ModelParams</span><span class="p">(</span><span class="o">...</span><span class="p">),</span>
<span class="n">dataset</span><span class="o">=</span><span class="n">train_dataset</span>
<span class="n">val_dataset</span><span class="o">=</span><span class="n">val_dataset</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Performance metrics - including accuracy, loss, etc. - are returned as a dictionary and saved in <code class="docutils literal notranslate"><span class="pre">results_log.csv</span></code> in both the project directory and model directory. Additional data, including ROCs and scatter plots, are saved in the model directories. Pandas DataFrames containing tile-, slide-, and patient-level predictions are also saved in the model directory.</p>
<p>At each designated epoch, models are saved in their own folders. Each model directory will include a copy of its hyperparameters in a <code class="docutils literal notranslate"><span class="pre">params.json</span></code> file, and a copy of its training/validation slide manifest in <code class="docutils literal notranslate"><span class="pre">slide.log</span></code>.</p>
</section>
<section id="using-a-trainer">
<span id="training-with-trainer"></span><h3>Using a Trainer<a class="headerlink" href="#using-a-trainer" title="Permalink to this heading">¶</a></h3>
<p>You can also train models outside the context of a project by using <a class="reference internal" href="../model/#slideflow.model.Trainer" title="slideflow.model.Trainer"><code class="xref py py-class docutils literal notranslate"><span class="pre">slideflow.model.Trainer</span></code></a>. This lower-level interface provides greater flexibility for customization and allows models to be trained without requiring a Project to be set up. It lacks several convenience features afforded by using <a class="reference internal" href="../project/#slideflow.Project.train" title="slideflow.Project.train"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Project.train()</span></code></a>, however, such as cross-validation, logging, and label preparation for easy multi-outcome support.</p>
<p>For this training approach, start by building a trainer with <a class="reference internal" href="../model/#slideflow.model.build_trainer" title="slideflow.model.build_trainer"><code class="xref py py-func docutils literal notranslate"><span class="pre">slideflow.model.build_trainer()</span></code></a>, which requires:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">hp</span></code>: <a class="reference internal" href="../model_params/#slideflow.ModelParams" title="slideflow.ModelParams"><code class="xref py py-class docutils literal notranslate"><span class="pre">slideflow.ModelParams</span></code></a> object.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">outdir</span></code>: Directory in which to save models and checkpoints.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">labels</span></code>: Dictionary mapping slide names to outcome labels.</p></li>
</ul>
<p><a class="reference internal" href="../dataset/#slideflow.Dataset" title="slideflow.Dataset"><code class="xref py py-class docutils literal notranslate"><span class="pre">slideflow.Dataset</span></code></a> provides a <code class="docutils literal notranslate"><span class="pre">.labels()</span></code> function that can generate this required labels dictionary.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Prepare dataset and labels</span>
<span class="n">dataset</span> <span class="o">=</span> <span class="n">P</span><span class="o">.</span><span class="n">dataset</span><span class="p">(</span><span class="n">tile_px</span><span class="o">=</span><span class="mi">299</span><span class="p">,</span> <span class="n">tile_um</span><span class="o">=</span><span class="mi">302</span><span class="p">)</span>
<span class="n">labels</span><span class="p">,</span> <span class="n">unique_labels</span> <span class="o">=</span> <span class="n">dataset</span><span class="o">.</span><span class="n">labels</span><span class="p">(</span><span class="s1">'tumor_type'</span><span class="p">)</span>
<span class="c1"># Split into training/validation</span>
<span class="n">train_dataset</span> <span class="o">=</span> <span class="n">dataset</span><span class="o">.</span><span class="n">filter</span><span class="p">({</span><span class="s2">"dataset"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"train"</span><span class="p">]})</span>
<span class="n">val_dataset</span> <span class="o">=</span> <span class="n">dataset</span><span class="o">.</span><span class="n">filter</span><span class="p">({</span><span class="s2">"dataset"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"val"</span><span class="p">]})</span>
<span class="c1"># Determine model parameters</span>
<span class="n">hp</span> <span class="o">=</span> <span class="n">sf</span><span class="o">.</span><span class="n">ModelParams</span><span class="p">(</span>
<span class="n">tile_px</span><span class="o">=</span><span class="mi">299</span><span class="p">,</span>
<span class="n">tile_um</span><span class="o">=</span><span class="mi">302</span><span class="p">,</span>
<span class="n">batch_size</span><span class="o">=</span><span class="mi">32</span><span class="p">,</span>
<span class="o">...</span>
<span class="p">)</span>
<span class="c1"># Prepare a Trainer</span>
<span class="n">trainer</span> <span class="o">=</span> <span class="n">sf</span><span class="o">.</span><span class="n">model</span><span class="o">.</span><span class="n">build_trainer</span><span class="p">(</span>
<span class="n">hp</span><span class="o">=</span><span class="n">hp</span><span class="p">,</span>
<span class="n">outdir</span><span class="o">=</span><span class="s1">'path'</span><span class="p">,</span>
<span class="n">labels</span><span class="o">=</span><span class="n">labels</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Use <a class="reference internal" href="../model/#slideflow.model.Trainer.train" title="slideflow.model.Trainer.train"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.model.Trainer.train()</span></code></a> to train a model using your specified training and validation datasets.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Train a model</span>
<span class="n">trainer</span><span class="o">.</span><span class="n">train</span><span class="p">(</span><span class="n">train_dataset</span><span class="p">,</span> <span class="n">val_dataset</span><span class="p">)</span>
</pre></div>
</div>
<div class="sphx-glr-script-out highlight-none notranslate"><div class="highlight"><pre><span></span>{
"epochs": {
"epoch3": {
"train_metrics": {
"loss": 0.497
"accuracy": 0.806
"val_loss": 0.719
"val_accuracy": 0.778
},
"val_metrics": {
"loss": 0.727
"accuracy": 0.770
},
"tile": {
"Outcome 0": [
0.580
0.580
]
},
"slide": {
"Outcome 0": [
0.658
0.658
]
},
"patient": {
"Outcome 0": [
0.657
0.657
]
}
}
}
}
</pre></div>
</div>
<p>Read more about the <code class="docutils literal notranslate"><span class="pre">Trainer</span></code> class and available keyword arguments in the <a class="reference internal" href="../model/#slideflow.model.Trainer" title="slideflow.model.Trainer"><code class="xref py py-class docutils literal notranslate"><span class="pre">API</span> <span class="pre">documentation</span></code></a>.</p>
</section>
</section>
<section id="multiple-outcomes">
<h2>Multiple outcomes<a class="headerlink" href="#multiple-outcomes" title="Permalink to this heading">¶</a></h2>
<p>Slideflow supports both classification and regression, as well as training to single or multiple outcomes at once. To train with multiple outcomes simultaneously, simply pass multiple annotation headers to the <code class="docutils literal notranslate"><span class="pre">outcomes</span></code> argument of <a class="reference internal" href="../project/#slideflow.Project.train" title="slideflow.Project.train"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Project.train()</span></code></a>.</p>
</section>
<section id="time-to-event-survival-outcomes">
<h2>Time-to-event / survival outcomes<a class="headerlink" href="#time-to-event-survival-outcomes" title="Permalink to this heading">¶</a></h2>
<p>Models can also be trained to a time series outcome using Cox Proportional Hazards (CPH) and negative log likelihood loss. For time-to-event / survival models, use <code class="docutils literal notranslate"><span class="pre">'negative_log_likelihood'</span></code> loss and set <code class="docutils literal notranslate"><span class="pre">outcomes</span></code> equal to the annotation column indicating event <em>time</em>. Specify the event <em>type</em> (0 or 1) by passing the event type annotation column to the argument <code class="docutils literal notranslate"><span class="pre">input_header</span></code>. If you are using multiple clinical inputs, the first header passed to <code class="docutils literal notranslate"><span class="pre">input_header</span></code> must be event type. Survival models are not compatible with multiple outcomes.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Survival models are currently only available with the Tensorflow backend. PyTorch support for survival outcomes is in development.</p>
</div>
</section>
<section id="multimodal-models">
<h2>Multimodal models<a class="headerlink" href="#multimodal-models" title="Permalink to this heading">¶</a></h2>
<p>In addition to training using image data, clinical data can also be provided as model input by passing annotation column headers to the variable <code class="docutils literal notranslate"><span class="pre">input_header</span></code>. This input is concatenated at the post-convolutional layer, prior to any configured hidden layers.</p>
<p>If desired, models can also be trained with clinical input data alone, without images, by using the hyperparameter argument <code class="docutils literal notranslate"><span class="pre">drop_images=True</span></code>.</p>
</section>
<section id="hyperparameter-optimization">
<span id="id2"></span><h2>Hyperparameter optimization<a class="headerlink" href="#hyperparameter-optimization" title="Permalink to this heading">¶</a></h2>
<p>Slideflow includes several tools for assisting with hyperparameter optimization, as described in the next sections.</p>
<section id="testing-multiple-combinations">
<h3>Testing multiple combinations<a class="headerlink" href="#testing-multiple-combinations" title="Permalink to this heading">¶</a></h3>
<p>You can easily test a series of hyperparameter combinations by passing a list of <code class="docutils literal notranslate"><span class="pre">ModelParams</span></code> object to the <code class="docutils literal notranslate"><span class="pre">params</span></code> argument of <a class="reference internal" href="../project/#slideflow.Project.train" title="slideflow.Project.train"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Project.train()</span></code></a>.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">hp1</span> <span class="o">=</span> <span class="n">sf</span><span class="o">.</span><span class="n">ModelParams</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">batch_size</span><span class="o">=</span><span class="mi">32</span><span class="p">)</span>
<span class="n">hp2</span> <span class="o">=</span> <span class="n">sf</span><span class="o">.</span><span class="n">ModelParams</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">batch_size</span><span class="o">=</span><span class="mi">64</span><span class="p">)</span>
<span class="n">P</span><span class="o">.</span><span class="n">create_hp_sweep</span><span class="p">(</span>
<span class="o">...</span><span class="p">,</span>
<span class="n">params</span><span class="o">=</span><span class="p">[</span><span class="n">hp1</span><span class="p">,</span> <span class="n">hp2</span><span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
</section>
<section id="grid-search-sweep">
<h3>Grid-search sweep<a class="headerlink" href="#grid-search-sweep" title="Permalink to this heading">¶</a></h3>
<p>You can also prepare a grid-search sweep, testing every permutation across a series of hyperparameter ranges. Use <a class="reference internal" href="../project/#slideflow.Project.create_hp_sweep" title="slideflow.Project.create_hp_sweep"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Project.create_hp_sweep()</span></code></a>, which will calculate and save the sweep configuration to a JSON file. For example, the following would configure a sweep with only two combinations; the first with a learning rate of 0.01, and the second with a learning rate of 0.001:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">P</span><span class="o">.</span><span class="n">create_hp_sweep</span><span class="p">(</span>
<span class="n">filename</span><span class="o">=</span><span class="s1">'sweep.json'</span><span class="p">,</span>
<span class="n">model</span><span class="o">=</span><span class="p">[</span><span class="s1">'xception'</span><span class="p">],</span>
<span class="n">loss</span><span class="o">=</span><span class="s1">'sparse_categorical_crossentropy'</span><span class="p">,</span>
<span class="n">learning_rate</span><span class="o">=</span><span class="p">[</span><span class="mf">0.001</span><span class="p">,</span> <span class="mf">0.0001</span><span class="p">],</span>
<span class="n">batch_size</span><span class="o">=</span><span class="mi">64</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The sweep is then executed by passing the JSON path to the <code class="docutils literal notranslate"><span class="pre">params</span></code> argument of <a class="reference internal" href="../project/#slideflow.Project.train" title="slideflow.Project.train"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Project.train()</span></code></a>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">P</span><span class="o">.</span><span class="n">train</span><span class="p">(</span><span class="n">params</span><span class="o">=</span><span class="s1">'sweep.json'</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="bayesian-optimization">
<span id="id3"></span><h3>Bayesian optimization<a class="headerlink" href="#bayesian-optimization" title="Permalink to this heading">¶</a></h3>
<p>You can also perform Bayesian hyperparameter optimization using <a class="reference external" href="https://automl.github.io/SMAC3/master/">SMAC3</a>, which uses a <a class="reference external" href="https://automl.github.io/ConfigSpace/master/">configuration space</a> to determine the types and ranges of hyperparameters to search.</p>
<p>Slideflow provides several functions to assist with building these configuration spaces. <code class="xref py py-func docutils literal notranslate"><span class="pre">slideflow.util.create_search_space()</span></code> allows you to define a range to search for each hyperparameter via keyword arguments:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">slideflow</span> <span class="k">as</span> <span class="nn">sf</span>
<span class="n">config_space</span> <span class="o">=</span> <span class="n">sf</span><span class="o">.</span><span class="n">util</span><span class="o">.</span><span class="n">create_search_space</span><span class="p">(</span>
<span class="n">normalizer</span><span class="o">=</span><span class="p">[</span><span class="s1">'macenko'</span><span class="p">,</span> <span class="s1">'reinhard'</span><span class="p">,</span> <span class="s1">'none'</span><span class="p">],</span>
<span class="n">dropout</span><span class="o">=</span><span class="p">(</span><span class="mf">0.1</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">),</span>
<span class="n">learning_rate</span><span class="o">=</span><span class="p">(</span><span class="mf">1e-4</span><span class="p">,</span> <span class="mf">1e-5</span><span class="p">)</span>
<span class="p">)</span>
</pre></div>
</div>
<p><code class="xref py py-func docutils literal notranslate"><span class="pre">slideflow.util.broad_search_space()</span></code> and <code class="xref py py-func docutils literal notranslate"><span class="pre">slideflow.util.shallow_search_space()</span></code> provide preconfigured search spaces that will search a broad and narrow range of hyperparameters, respectively. You can also customize a preconfigured search space using keyword arguments. For example, to do a broad search but disable L1 searching:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">slideflow</span> <span class="k">as</span> <span class="nn">sf</span>
<span class="n">config_space</span> <span class="o">=</span> <span class="n">sf</span><span class="o">.</span><span class="n">util</span><span class="o">.</span><span class="n">broad_search_space</span><span class="p">(</span><span class="n">l1</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
</pre></div>
</div>
<p>See the linked API documentation for each function for more details about the respective search spaces.</p>
<p>Once the search space is determined, you can perform the hyperparameter optimization by simply replacing <a class="reference internal" href="../project/#slideflow.Project.train" title="slideflow.Project.train"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Project.train()</span></code></a> with <a class="reference internal" href="../project/#slideflow.Project.smac_search" title="slideflow.Project.smac_search"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Project.smac_search()</span></code></a>, providing the configuration space to the argument <code class="docutils literal notranslate"><span class="pre">smac_configspace</span></code>. By default, SMAC3 will optimize the tile-level AUROC, but the optimization metric can be customized with the keyword argument <code class="docutils literal notranslate"><span class="pre">smac_metric</span></code>.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Base hyperparameters</span>
<span class="n">hp</span> <span class="o">=</span> <span class="n">sf</span><span class="o">.</span><span class="n">ModelParams</span><span class="p">(</span><span class="n">tile_px</span><span class="o">=</span><span class="mi">299</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
<span class="c1"># Configuration space to optimize</span>
<span class="n">config_space</span> <span class="o">=</span> <span class="n">sf</span><span class="o">.</span><span class="n">util</span><span class="o">.</span><span class="n">shallow_search_space</span><span class="p">()</span>
<span class="c1"># Run the Bayesian optimization</span>
<span class="n">best_config</span><span class="p">,</span> <span class="n">history</span> <span class="o">=</span> <span class="n">P</span><span class="o">.</span><span class="n">smac_search</span><span class="p">(</span>
<span class="n">outcomes</span><span class="o">=</span><span class="s1">'tumor_type'</span><span class="p">,</span>
<span class="n">params</span><span class="o">=</span><span class="n">hp</span><span class="p">,</span>
<span class="n">smac_configspace</span><span class="o">=</span><span class="n">cs</span><span class="p">,</span>
<span class="n">smac_metric</span><span class="o">=</span><span class="s1">'tile_auc'</span><span class="p">,</span>
<span class="o">...</span>
<span class="p">)</span>
<span class="nb">print</span><span class="p">(</span><span class="n">history</span><span class="p">)</span>
</pre></div>
</div>
<div class="sphx-glr-script-out highlight-none notranslate"><div class="highlight"><pre><span></span> dropout l1 l2 metric
0 0.126269 0.306857 0.183902 0.271778
1 0.315987 0.014661 0.413443 0.283289
2 0.123149 0.311893 0.184439 0.250339
3 0.250000 0.250000 0.250000 0.247641
4 0.208070 0.018481 0.121243 0.257633
</pre></div>
</div>
<p><a class="reference internal" href="../project/#slideflow.Project.smac_search" title="slideflow.Project.smac_search"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Project.smac_search()</span></code></a> returns the best configuration and a history of models trained during the search. This history is a Pandas DataFrame with hyperparameters for columns, and a “metric” column with the optimization metric result for each trained model. The run history is also saved in CSV format in the associated model folder.</p>
<p>See the API documentation for available customization via keyword arguments.</p>
</section>
</section>
<section id="customizing-model-or-loss">
<span id="custom-loss"></span><h2>Customizing model or loss<a class="headerlink" href="#customizing-model-or-loss" title="Permalink to this heading">¶</a></h2>
<p>Slideflow supports dozens of model architectures, but you can also train with a custom architecture, as demonstrated in <a class="reference internal" href="../tutorial3/#tutorial3"><span class="std std-ref">Tutorial 3: Using a custom architecture</span></a>.</p>
<p>Similarly, you can also train with a custom loss function by supplying a dictionary to the <code class="docutils literal notranslate"><span class="pre">loss</span></code> argument in <code class="docutils literal notranslate"><span class="pre">ModelParams</span></code>, with the keys <code class="docutils literal notranslate"><span class="pre">type</span></code> (which must be either <code class="docutils literal notranslate"><span class="pre">'classification'</span></code>, <code class="docutils literal notranslate"><span class="pre">'regression'</span></code>, or <code class="docutils literal notranslate"><span class="pre">'survival'</span></code>) and <code class="docutils literal notranslate"><span class="pre">fn</span></code> (a callable loss function).</p>
<p>For Tensorflow/Keras, the loss function must accept arguments <code class="docutils literal notranslate"><span class="pre">y_true,</span> <span class="pre">y_pred</span></code>. For regression losses, <code class="docutils literal notranslate"><span class="pre">y_true</span></code> may need to be cast to <code class="docutils literal notranslate"><span class="pre">tf.float32</span></code>. An example custom regression loss is given below:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Custom Tensorflow loss</span>
<span class="k">def</span> <span class="nf">custom_regression_loss</span><span class="p">(</span><span class="n">y_true</span><span class="p">,</span> <span class="n">y_pred</span><span class="p">):</span>
<span class="n">y_true</span> <span class="o">=</span> <span class="n">tf</span><span class="o">.</span><span class="n">cast</span><span class="p">(</span><span class="n">y_true</span><span class="p">,</span> <span class="n">tf</span><span class="o">.</span><span class="n">float32</span><span class="p">)</span>
<span class="n">squared_difference</span> <span class="o">=</span> <span class="n">tf</span><span class="o">.</span><span class="n">square</span><span class="p">(</span><span class="n">y_true</span> <span class="o">-</span> <span class="n">y_pred</span><span class="p">)</span>
<span class="k">return</span> <span class="n">tf</span><span class="o">.</span><span class="n">reduce_mean</span><span class="p">(</span><span class="n">squared_difference</span><span class="p">,</span> <span class="n">axis</span><span class="o">=-</span><span class="mi">1</span><span class="p">)</span>
</pre></div>
</div>
<p>For PyTorch, the loss function must return a nested loss function with arguments <code class="docutils literal notranslate"><span class="pre">output,</span> <span class="pre">target</span></code>. An example regression loss is given below:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Custom PyTorch loss</span>
<span class="k">def</span> <span class="nf">custom_regression_loss</span><span class="p">():</span>
<span class="k">def</span> <span class="nf">loss_fn</span><span class="p">(</span><span class="n">output</span><span class="p">,</span> <span class="n">target</span><span class="p">):</span>
<span class="k">return</span> <span class="n">torch</span><span class="o">.</span><span class="n">mean</span><span class="p">((</span><span class="n">target</span> <span class="o">-</span> <span class="n">output</span><span class="p">)</span> <span class="o">**</span> <span class="mi">2</span><span class="p">)</span>
<span class="k">return</span> <span class="n">loss_fn</span>
</pre></div>
</div>
<p>In both cases, the loss function is applied as follows:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">hp</span> <span class="o">=</span> <span class="n">sf</span><span class="o">.</span><span class="n">ModelParams</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">loss</span><span class="o">=</span><span class="p">{</span><span class="s1">'type'</span><span class="p">:</span> <span class="s1">'regression'</span><span class="p">,</span> <span class="s1">'fn'</span><span class="p">:</span> <span class="n">custom_regression_loss</span><span class="p">})</span>
</pre></div>
</div>
</section>
<section id="using-multiple-gpus">
<h2>Using multiple GPUs<a class="headerlink" href="#using-multiple-gpus" title="Permalink to this heading">¶</a></h2>
<p>Slideflow can perform distributed training if multiple GPUs are available. Enable distributed training by passing the argument <code class="docutils literal notranslate"><span class="pre">multi_gpu=True</span></code>, which will allow Slideflow to use all available (and visible) GPUs.</p>
</section>
<section id="training-without-tfrecords">
<span id="from-wsi"></span><h2>Training without TFRecords<a class="headerlink" href="#training-without-tfrecords" title="Permalink to this heading">¶</a></h2>
<p>It is also possible to train deep learning models directly from slides, without first generating TFRecords. This may be advantageous for rapidly prototyping models on a large dataset, or when tuning the tile size for a dataset.</p>
<p>Use the argument <code class="docutils literal notranslate"><span class="pre">from_wsi=True</span></code> in either the <a class="reference internal" href="../project/#slideflow.Project.train" title="slideflow.Project.train"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Project.train()</span></code></a> or <a class="reference internal" href="../model/#slideflow.model.Trainer.train" title="slideflow.model.Trainer.train"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.model.Trainer.train()</span></code></a> functions. Image tiles will be dynamically extracted from slides during training, and background will be automatically removed via Otsu’s thresholding.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Using the <a class="reference internal" href="../installation/#slide-backend"><span class="std std-ref">cuCIM backend</span></a> will greatly improve performance when training without TFRecords.</p>
</div>
</section>
<section id="monitoring-performance">
<h2>Monitoring performance<a class="headerlink" href="#monitoring-performance" title="Permalink to this heading">¶</a></h2>
<section id="tensorboard">
<h3>Tensorboard<a class="headerlink" href="#tensorboard" title="Permalink to this heading">¶</a></h3>
<p>During training, progress can be monitored using Tensorflow’s bundled <code class="docutils literal notranslate"><span class="pre">Tensorboard</span></code> package by passing the argument <code class="docutils literal notranslate"><span class="pre">use_tensorboard=True</span></code>. This functionality was disabled by default due to a recent bug in Tensorflow. To use tensorboard to monitor training, execute:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>tensorboard<span class="w"> </span>--logdir<span class="o">=</span>/path/to/model/directory
</pre></div>
</div>
<p>… and open <a class="reference external" href="http://localhost:6006">http://localhost:6006</a> in your web browser.</p>
</section>
<section id="neptune-ai">
<h3>Neptune.ai<a class="headerlink" href="#neptune-ai" title="Permalink to this heading">¶</a></h3>
<p>Experiments can be automatically logged with <a class="reference external" href="https://app.neptune.ai">Neptune.ai</a>. To enable logging, first locate your Neptune API token and workspace ID, and configure the environmental variables <code class="docutils literal notranslate"><span class="pre">NEPTUNE_API_TOKEN</span></code> and <code class="docutils literal notranslate"><span class="pre">NEPTUNE_WORKSPACE</span></code>.</p>
<p>With the environmental variables set, Neptune logs are enabled by passing <code class="docutils literal notranslate"><span class="pre">use_neptune=True</span></code> to <code class="docutils literal notranslate"><span class="pre">sf.load_project</span></code>.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">P</span> <span class="o">=</span> <span class="n">sf</span><span class="o">.</span><span class="n">load_project</span><span class="p">(</span><span class="s1">'/project/path'</span><span class="p">,</span> <span class="n">use_neptune</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
</section>
</section>
</section>
</article>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="../evaluation/" class="btn btn-neutral float-right" title="Evaluation" accesskey="n" rel="next">Next <img src="../_static/images/chevron-right-orange.svg" class="next-page"></a>
<a href="../slide_processing/" class="btn btn-neutral" title="Slide Processing" accesskey="p" rel="prev"><img src="../_static/images/chevron-right-orange.svg" class="previous-page"> Previous</a>
</div>
<hr>
<div role="contentinfo">
<p>
© Copyright 2023, James M Dolezal.
</p>
</div>
<div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</div>
</footer>
</div>
</div>
<div class="pytorch-content-right" id="pytorch-content-right">
<div class="pytorch-right-menu" id="pytorch-right-menu">
<div class="pytorch-side-scroll" id="pytorch-side-scroll-right">
<ul>
<li><a class="reference internal" href="#">Training</a><ul>
<li><a class="reference internal" href="#prepare-hyperparameters">Prepare hyperparameters</a></li>
<li><a class="reference internal" href="#training-a-model">Training a model</a><ul>
<li><a class="reference internal" href="#training-with-a-project">Training with a Project</a></li>
<li><a class="reference internal" href="#using-a-trainer">Using a Trainer</a></li>
</ul>
</li>
<li><a class="reference internal" href="#multiple-outcomes">Multiple outcomes</a></li>
<li><a class="reference internal" href="#time-to-event-survival-outcomes">Time-to-event / survival outcomes</a></li>
<li><a class="reference internal" href="#multimodal-models">Multimodal models</a></li>
<li><a class="reference internal" href="#hyperparameter-optimization">Hyperparameter optimization</a><ul>
<li><a class="reference internal" href="#testing-multiple-combinations">Testing multiple combinations</a></li>
<li><a class="reference internal" href="#grid-search-sweep">Grid-search sweep</a></li>
<li><a class="reference internal" href="#bayesian-optimization">Bayesian optimization</a></li>
</ul>
</li>
<li><a class="reference internal" href="#customizing-model-or-loss">Customizing model or loss</a></li>
<li><a class="reference internal" href="#using-multiple-gpus">Using multiple GPUs</a></li>
<li><a class="reference internal" href="#training-without-tfrecords">Training without TFRecords</a></li>
<li><a class="reference internal" href="#monitoring-performance">Monitoring performance</a><ul>
<li><a class="reference internal" href="#tensorboard">Tensorboard</a></li>
<li><a class="reference internal" href="#neptune-ai">Neptune.ai</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</section>
</div>
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/sphinx_highlight.js"></script>
<script type="text/javascript" src="../_static/js/vendor/jquery-3.6.3.min.js"></script>
<script type="text/javascript" src="../_static/js/vendor/popper.min.js"></script>
<script type="text/javascript" src="../_static/js/vendor/bootstrap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/list.js/1.5.0/list.min.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
<!-- Begin Footer -->
<!-- End Footer -->
<!-- Begin Mobile Menu -->
<div class="mobile-main-menu">
<div class="container-fluid">
<div class="container">
<div class="mobile-main-menu-header-container">
<a class="header-logo" href="https://pytorch.org/" aria-label="PyTorch"></a>
<a class="main-menu-close-button" href="#" data-behavior="close-mobile-menu"></a>
</div>
</div>
</div>
<div class="mobile-main-menu-links-container">
<div class="main-menu">
<ul>
<li>
<a href="https://slideflow.dev">Docs</a>
</li>
<li>
<a href="https://slideflow.dev/tutorial1/">Tutorials</a>
</li>
<li>
<a href="https://github.com/slideflow/slideflow">Github</a>
</li>
</ul>
</div>
</div>
</div>
<!-- End Mobile Menu -->
<script script type="text/javascript">
var collapsedSections = [];
</script>
<script type="text/javascript" src="../_static/js/vendor/anchor.min.js"></script>
<script type="text/javascript">
$(document).ready(function() {
mobileMenu.bind();
mobileTOC.bind();
pytorchAnchors.bind();
sideMenus.bind();
scrollToAnchor.bind();
highlightNavigation.bind();
mainMenuDropdown.bind();
filterTags.bind();
// Add class to links that have code blocks, since we cannot create links in code blocks
$("article.pytorch-article a span.pre").each(function(e) {
$(this).closest("a").addClass("has-code");
});
})
</script>
</body>
</html>
Datasets
Models
