slideflow / Git / [78ef36] /docs/tutorial5/index.html

Models:
DanielG/
slideflow
Downloads: 1
[78ef36]: / docs / tutorial5 / index.html
History
Download this file
592 lines (435 with data), 36.9 kB

<!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>Tutorial 5: Creating a mosaic map &mdash; 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="Tutorial 6: Custom slide filtering" href="../tutorial6/" />
    <link rel="prev" title="Tutorial 4: Model evaluation &amp; heatmaps" href="../tutorial4/" />




  <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>
<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"><a class="reference internal" href="../training/">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 class="current">
<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 &amp; heatmaps</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">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> &gt;
      </li>


      <li>Tutorial 5: Creating a mosaic map</li>


      <li class="pytorch-breadcrumbs-aside">


            <a href="../_sources/tutorial5.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="tutorial-5-creating-a-mosaic-map">
<h1>Tutorial 5: Creating a mosaic map<a class="headerlink" href="#tutorial-5-creating-a-mosaic-map" title="Permalink to this heading">¶</a></h1>
<p>Mosaic maps are useful explainability tools used to describe the landscape of image features a model learned during training. In this tutorial, we will walk through the process of creating a mosaic map, reproducing results similar to what is shown in Figure 5 of <a class="reference external" href="https://arxiv.org/abs/2204.04516">this article by Dolezal et al</a>.</p>
<section id="train-a-model">
<h2>Train a model<a class="headerlink" href="#train-a-model" title="Permalink to this heading">¶</a></h2>
<p>The first step is to train a model, as described in <a class="reference internal" href="../tutorial1/#tutorial1"><span class="std std-ref">Tutorial 1: Model training (simple)</span></a>. For the purposes of this tutorial, we will assume data has been collected and annotated as described in the referenced manuscript, with models trained to predict lung adenocarcinoma vs. squamous cell carcinoma. We will assume that a project has been initialized at <code class="docutils literal notranslate"><span class="pre">/mnt/data/projects/TCGA_LUNG</span></code> and configured to use whole-slide images from <a class="reference external" href="https://portal.gdc.cancer.gov/">TCGA</a>, with the annotations header <code class="docutils literal notranslate"><span class="pre">'cohort'</span></code> indicating whether a tumor is adenocarcinoma (<code class="docutils literal notranslate"><span class="pre">'LUAD'</span></code>) or squamous (<code class="docutils literal notranslate"><span class="pre">'LUSC'</span></code>). Training models for such a project would look like:</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="c1"># Load a preconfigured project at some directory</span>
<span class="n">P</span> <span class="o">=</span> <span class="n">sf</span><span class="o">.</span><span class="n">Project</span><span class="p">(</span><span class="s1">&#39;/mnt/data/projects/TCGA_LUNG&#39;</span><span class="p">)</span>

<span class="c1"># Extract tiles</span>
<span class="n">P</span><span class="o">.</span><span class="n">extract_tiles</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">qc</span><span class="o">=</span><span class="s1">&#39;both&#39;</span>
<span class="p">)</span>

<span class="c1"># Configure 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">epochs</span><span class="o">=</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span>
  <span class="n">model</span><span class="o">=</span><span class="s1">&#39;xception&#39;</span><span class="p">,</span>
  <span class="n">batch_size</span><span class="o">=</span><span class="mi">128</span><span class="p">,</span>
  <span class="o">...</span>
<span class="p">)</span>

<span class="c1"># Train the model</span>
<span class="c1"># using three-fold cross-validation</span>
<span class="n">P</span><span class="o">.</span><span class="n">train</span><span class="p">(</span>
  <span class="s1">&#39;cohort&#39;</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">val_strategy</span><span class="o">=</span><span class="s1">&#39;k-fold&#39;</span><span class="p">,</span>
  <span class="n">val_k_fold</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
</section>
<section id="locate-a-saved-model">
<h2>Locate a saved model<a class="headerlink" href="#locate-a-saved-model" title="Permalink to this heading">¶</a></h2>
<p>Once training is finished, locate the model from the first k-fold split in your project’s model directory. For the Tensorflow backend, the saved model would look like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>models/
├── 00001-cohort-HP0-kfold1 /
│   ├── cohort-HP0-epoch1/
         ...
...
</pre></div>
</div>
<p>And for PyTorch:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>models/
├── 00001-cohort-HP0-kfold1 /
│   ├── cohort-HP0-epoch1.zip
         ...
...
</pre></div>
</div>
</section>
<section id="generate-layer-activations">
<h2>Generate layer activations<a class="headerlink" href="#generate-layer-activations" title="Permalink to this heading">¶</a></h2>
<p>The next step is to calculate layer activations for images in the model’s validation dataset. First, let’s find the slides belonging to our model’s validation dataset:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">slideflow.util</span> <span class="kn">import</span> <span class="n">get_slides_from_model_manifest</span>

<span class="c1"># Path to the saved model</span>
<span class="n">model_path</span> <span class="o">=</span> <span class="o">...</span>

<span class="c1"># Read the list of validation slides</span>
<span class="n">val_slides</span> <span class="o">=</span> <span class="n">get_slides_from_model_manifest</span><span class="p">(</span>
  <span class="n">model_path</span><span class="p">,</span>
  <span class="n">dataset</span><span class="o">=</span><span class="s1">&#39;validation&#39;</span>
<span class="p">)</span>
</pre></div>
</div>
<p>We can then calculate layer activations from these validation slides. For this experiment, we will be calculating layer activations from the post-convolutional layer (after pooling). Any combination of layers can be chosen, requiring only that you past a list of layer names to the argument <code class="docutils literal notranslate"><span class="pre">layers</span></code>.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Calculate layer activations</span>
<span class="n">df</span> <span class="o">=</span> <span class="n">P</span><span class="o">.</span><span class="n">generate_features</span><span class="p">(</span>
  <span class="n">model_path</span><span class="p">,</span>
  <span class="n">filters</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;slide&#39;</span><span class="p">:</span> <span class="n">val_slides</span><span class="p">},</span>
  <span class="n">layers</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;postconv&#39;</span><span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Calculating layer activations may take a substantial amount of time depending on the dataset size and your computational infrastructure. Layer activations can be cached after calculation using the <code class="docutils literal notranslate"><span class="pre">cache</span></code> argument. If provided, a <code class="docutils literal notranslate"><span class="pre">DatasetFeatures</span></code> object will store activations in this pkl file, and if the script is run again, activations will be automatically loaded from cache.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">df</span> <span class="o">=</span> <span class="n">P</span><span class="o">.</span><span class="n">generate_features</span><span class="p">(</span>
  <span class="o">...</span><span class="p">,</span>
  <span class="n">cache</span><span class="o">=</span><span class="s1">&#39;activations.pkl&#39;</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Layer activations calculated on very large datasets may result in high memory usage, as each slide may have thousands of image tiles or more. To cap the maximum number of tiles to use per slide, use the <code class="docutils literal notranslate"><span class="pre">max_tiles</span></code> argument:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">df</span> <span class="o">=</span> <span class="n">P</span><span class="o">.</span><span class="n">generate_features</span><span class="p">(</span>
  <span class="o">...</span><span class="p">,</span>
  <span class="n">max_tiles</span><span class="o">=</span><span class="mi">100</span>
<span class="p">)</span>
</pre></div>
</div>
<p>This function will return an instance of <a class="reference internal" href="../dataset_features/#slideflow.DatasetFeatures" title="slideflow.DatasetFeatures"><code class="xref py py-class docutils literal notranslate"><span class="pre">slideflow.DatasetFeatures</span></code></a>, which contains tile-level predictions (in <code class="docutils literal notranslate"><span class="pre">DatasetFeatures.predictions</span></code>), tile X,Y locations from their respective slides (in <code class="docutils literal notranslate"><span class="pre">DatasetFeatures.locations</span></code>), layer activations (in <code class="docutils literal notranslate"><span class="pre">DatasetFeatures.activations</span></code>), and uncertainty (if applicable, in <code class="docutils literal notranslate"><span class="pre">DatasetFeatures.uncertainty</span></code>).</p>
</section>
<section id="create-the-mosaic-map">
<h2>Create the mosaic map<a class="headerlink" href="#create-the-mosaic-map" title="Permalink to this heading">¶</a></h2>
<p>From this collection of layer activations, we can generate a mosaic map from this <code class="docutils literal notranslate"><span class="pre">DatasetFeatures</span></code> object. Use <a class="reference internal" href="../project/#slideflow.Project.generate_mosaic" title="slideflow.Project.generate_mosaic"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Project.generate_mosaic()</span></code></a> to create the mosaic. We will use the <code class="docutils literal notranslate"><span class="pre">umap_cache</span></code> argument to cache the UMAP created during mosaic map generation, so it can be reused if necessary.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Generate a mosaic map</span>
<span class="n">mosaic</span> <span class="o">=</span> <span class="n">P</span><span class="o">.</span><span class="n">generate_mosaic</span><span class="p">(</span>
  <span class="n">df</span><span class="p">,</span>
  <span class="n">filters</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;slide&#39;</span><span class="p">:</span> <span class="n">val_slides</span><span class="p">},</span>
  <span class="n">umap_cache</span><span class="o">=</span><span class="s1">&#39;umap.pkl&#39;</span>
<span class="p">)</span>
</pre></div>
</div>
<p>We can then render and save the mosaic map to disc using the <code class="docutils literal notranslate"><span class="pre">.save()</span></code> function:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Render and save map to disc</span>
<span class="n">mosaic</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="s1">&#39;mosaic.png&#39;</span><span class="p">)</span>
</pre></div>
</div>
<img alt="https://i.imgur.com/kt8O85l.png" src="https://i.imgur.com/kt8O85l.png" />
</section>
<section id="save-corresponding-umaps">
<h2>Save corresponding UMAPs<a class="headerlink" href="#save-corresponding-umaps" title="Permalink to this heading">¶</a></h2>
<p>Now that we have the mosaic generated, we need to create corresponding labeled UMAP plots to aid in interpretability. UMAP plots are stored in <a class="reference internal" href="../slidemap/#slideflow.SlideMap" title="slideflow.SlideMap"><code class="xref py py-class docutils literal notranslate"><span class="pre">slideflow.SlideMap</span></code></a> objects. A mosaic’s underlying <code class="docutils literal notranslate"><span class="pre">SlideMap</span></code> can be accessed via <code class="docutils literal notranslate"><span class="pre">mosaic.slide_map</span></code>.</p>
<p>The <a class="reference internal" href="../slidemap/#slideflow.SlideMap" title="slideflow.SlideMap"><code class="xref py py-class docutils literal notranslate"><span class="pre">slideflow.SlideMap</span></code></a> class provides several functions useful for labeling. To start, we will label the umap according to the raw predictions for each tile image. As this is a binary categorical outcome, there will be two post-softmax predictions. We will label the UMAP according to the second logit (id=1), and then save the image to disc.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Label by raw predictions</span>
<span class="n">umap</span> <span class="o">=</span> <span class="n">mosaic</span><span class="o">.</span><span class="n">slide_map</span>
<span class="n">umap</span><span class="o">.</span><span class="n">label_by_preds</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="n">umap</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="s1">&#39;umap_preds.png&#39;</span><span class="p">)</span>
</pre></div>
</div>
<img alt="https://i.imgur.com/FT7nH90.png" src="https://i.imgur.com/FT7nH90.png" />
<p>Next, we will discretize the predictions, showing the final prediction as a categorical label. The <code class="docutils literal notranslate"><span class="pre">SlideMap</span></code> object contains a dictionary of metadata for each image tile, and the final categorical prediction is assigned to the <code class="docutils literal notranslate"><span class="pre">prediction</span></code> key. We will use the <code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.SlideMap.label_by_meta()</span></code> function to label the umap with these categorical predictions.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Label by raw preds</span>
<span class="n">umap</span><span class="o">.</span><span class="n">label_by_meta</span><span class="p">(</span><span class="s1">&#39;prediction&#39;</span><span class="p">)</span>
<span class="n">umap</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="s1">&#39;umap_predictions.png&#39;</span><span class="p">)</span>
</pre></div>
</div>
<img alt="https://i.imgur.com/oQwRPY2.png" src="https://i.imgur.com/oQwRPY2.png" />
<p>For reference, let’s see the ground truth categorical labels. For this, we will need a dictionary mapping slide names to labels, which we will then pass to <a class="reference internal" href="../slidemap/#slideflow.SlideMap.label_by_slide" title="slideflow.SlideMap.label_by_slide"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.SlideMap.label_by_slide()</span></code></a>. We can retrieve our slide labels from the project annotations file, using <a class="reference internal" href="../dataset/#slideflow.Dataset.labels" title="slideflow.Dataset.labels"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.Dataset.labels()</span></code></a>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Get slide labels</span>
<span class="n">labels</span><span class="p">,</span> <span class="n">unique</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="o">.</span><span class="n">labels</span><span class="p">(</span><span class="s1">&#39;cohort&#39;</span><span class="p">)</span>

<span class="c1"># Label with slide labels</span>
<span class="n">umap</span><span class="o">.</span><span class="n">label_by_slide</span><span class="p">(</span><span class="n">labels</span><span class="p">)</span>
<span class="n">umap</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="s1">&#39;umap_labels.png&#39;</span><span class="p">)</span>
</pre></div>
</div>
<img alt="https://i.imgur.com/BDNR68h.png" src="https://i.imgur.com/BDNR68h.png" />
<p>Finally, if we are a using a model that was trained with uncertainty quantification (UQ) enabled, (passing <code class="docutils literal notranslate"><span class="pre">uq=True</span></code> to <code class="docutils literal notranslate"><span class="pre">ModelParams</span></code>), we can label the UMAP with tile-level uncertainty:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Label by uncertainty</span>
<span class="n">umap</span><span class="o">.</span><span class="n">label_by_uncertainty</span><span class="p">()</span>
<span class="n">umap</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="s1">&#39;umap_uncertainty.png&#39;</span><span class="p">)</span>
</pre></div>
</div>
<img alt="https://i.imgur.com/fnv8eQj.png" src="https://i.imgur.com/fnv8eQj.png" />
<p>In all cases, the UMAP plots can be customized by passing keyword arguments accepted by Seaborn’s <a class="reference external" href="https://seaborn.pydata.org/generated/seaborn.scatterplot.html">scatterplot</a> function, as well as a number of other arguments described in <a class="reference internal" href="../slidemap/#slideflow.SlideMap.save" title="slideflow.SlideMap.save"><code class="xref py py-meth docutils literal notranslate"><span class="pre">slideflow.SlideMap.save()</span></code></a>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">umap</span><span class="o">.</span><span class="n">save</span><span class="p">(</span>
    <span class="s1">&#39;umap_uncertainty.png&#39;</span><span class="p">,</span> <span class="c1"># Save path</span>
    <span class="n">title</span><span class="o">=</span><span class="s1">&#39;Uncertainty&#39;</span><span class="p">,</span>    <span class="c1"># Title for plot</span>
    <span class="n">dpi</span><span class="o">=</span><span class="mi">150</span><span class="p">,</span>                <span class="c1"># DPI for saved figure</span>
    <span class="n">subsample</span><span class="o">=</span><span class="mi">1000</span><span class="p">,</span>         <span class="c1"># Subsample the data</span>
    <span class="n">s</span><span class="o">=</span><span class="mi">3</span>                     <span class="c1"># Marker size</span>
<span class="p">)</span>
</pre></div>
</div>
</section>
</section>


             </article>

            </div>
            <footer>

    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">

        <a href="../tutorial6/" class="btn btn-neutral float-right" title="Tutorial 6: Custom slide filtering" accesskey="n" rel="next">Next <img src="../_static/images/chevron-right-orange.svg" class="next-page"></a>


        <a href="../tutorial4/" class="btn btn-neutral" title="Tutorial 4: Model evaluation &amp; heatmaps" accesskey="p" rel="prev"><img src="../_static/images/chevron-right-orange.svg" class="previous-page"> Previous</a>

    </div>




    <hr>



  <div role="contentinfo">
    <p>
        &copy; 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="#">Tutorial 5: Creating a mosaic map</a><ul>
<li><a class="reference internal" href="#train-a-model">Train a model</a></li>
<li><a class="reference internal" href="#locate-a-saved-model">Locate a saved model</a></li>
<li><a class="reference internal" href="#generate-layer-activations">Generate layer activations</a></li>
<li><a class="reference internal" href="#create-the-mosaic-map">Create the mosaic map</a></li>
<li><a class="reference internal" href="#save-corresponding-umaps">Save corresponding UMAPs</a></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>