--- a
+++ b/docs-source/source/quickstart.rst
@@ -0,0 +1,168 @@
+Quickstart
+==========
+
+This section provides an example of using Slideflow to build a deep learning classifier from digital pathology slides. Follow the links in each section for more information.
+
+Preparing a project
+*******************
+
+Slideflow experiments are organized using :class:`slideflow.Project`, which supervises storage of data, saved models, and results. The ``slideflow.project`` module has three preconfigured projects with associated slides and clinical annotations: ``LungAdenoSquam``, ``ThyroidBRS``, and ``BreastER``.
+
+For this example, we will the ``LungAdenoSquam`` project to train a classifier to predict lung adenocarcinoma (Adeno) vs. squamous cell carcinoma (Squam).
+
+.. code-block:: python
+
+    import slideflow as sf
+
+    # Download preconfigured project, with slides and annotations.
+    project = sf.create_project(
+        root='data',
+        cfg=sf.project.LungAdenoSquam(),
+        download=True
+    )
+
+Read more about :ref:`setting up a project on your own data <project_setup>`.
+
+Data preparation
+****************
+
+The core imaging data used in Slideflow are image tiles :ref:`extracted from slides <filtering>` at a specific magnification and pixel resolution. Tile extraction and downstream image processing is handled through the primitive :ref:`slideflow.Dataset <datasets_and_validation>`. We can request a ``Dataset`` at a given tile size from our project using :meth:`slideflow.Project.dataset`. Tile magnification can be specified in microns (as an ``int``) or as optical magnification (e.g. ``'40x'``).
+
+.. code-block:: python
+
+    # Prepare a dataset of image tiles.
+    dataset = project.dataset(
+        tile_px=299,   # Tile size, in pixels.
+        tile_um='10x'  # Tile size, in microns or magnification.
+    )
+    dataset.summary()
+
+.. rst-class:: sphx-glr-script-out
+
+ .. code-block:: none
+
+    Overview:
+    ╒===============================================╕
+    │ Configuration file: │ /mnt/data/datasets.json │
+    │ Tile size (px):     │ 299                     │
+    │ Tile size (um):     │ 10x                     │
+    │ Slides:             │ 941                     │
+    │ Patients:           │ 941                     │
+    │ Slides with ROIs:   │ 941                     │
+    │ Patients with ROIs: │ 941                     │
+    ╘===============================================╛
+
+    Filters:
+    ╒====================╕
+    │ Filters:      │ {} │
+    ├--------------------┤
+    │ Filter Blank: │ [] │
+    ├--------------------┤
+    │ Min Tiles:    │ 0  │
+    ╘====================╛
+
+    Sources:
+
+    TCGA_LUNG
+    ╒==============================================╕
+    │ slides    │ /mnt/raid/SLIDES/TCGA_LUNG       │
+    │ roi       │ /mnt/raid/SLIDES/TCGA_LUNG       │
+    │ tiles     │ /mnt/rocket/tiles/TCGA_LUNG      │
+    │ tfrecords │ /mnt/rocket/tfrecords/TCGA_LUNG/ │
+    │ label     │ 299px_10x                        │
+    ╘==============================================╛
+
+    Number of tiles in TFRecords: 0
+    Annotation columns:
+    Index(['patient', 'subtype', 'site', 'slide'],
+        dtype='object')
+
+Tile extraction
+---------------
+
+We prepare imaging data for training by extracting tiles from slides. Background areas of slides will be filtered out with Otsu's thresholding.
+
+.. code-block:: python
+
+    # Extract tiles from all slides in the dataset.
+    dataset.extract_tiles(qc='otsu')
+
+Read more about tile extraction and :ref:`slide processing in Slideflow <filtering>`.
+
+Held-out test sets
+------------------
+
+Now that we have our dataset and we've completed the initial tile image processing, we'll split the dataset into a training cohort and a held-out test cohort with :meth:`slideflow.Dataset.split`. We'll split while balancing the outcome ``'subtype'`` equally in the training and test dataset, with 30% of the data retained in the held-out set.
+
+.. code-block:: python
+
+    # Split our dataset into a training and held-out test set.
+    train_dataset, test_dataset = dataset.split(
+        model_type='classification',
+        labels='subtype',
+        val_fraction=0.3
+    )
+
+Read more about :ref:`Dataset management <datasets_and_validation>`.
+
+Configuring models
+******************
+
+Neural network models are prepared for training with :class:`slideflow.ModelParams`, through which we define the model architecture, loss, and hyperparameters. Dozens of architectures are available in both the Tensorflow and PyTorch backends, and both neural network :ref:`architectures <tutorial3>` and :ref:`loss <custom_loss>` functions can be customized. In this example, we will use the included Xception network.
+
+.. code-block:: python
+
+    # Prepare a model and hyperparameters.
+    params = sf.ModelParams(
+        tile_px=299,
+        tile_um='10x',
+        model='xception',
+        batch_size=64,
+        learning_rate=0.0001
+    )
+
+Read more about :ref:`hyperparameter optimization in Slideflow <training>`.
+
+Training a model
+****************
+
+Models can be trained from these hyperparameter configurations using :meth:`Project.train`. Models can be trained to categorical, multi-categorical, continuous, or time-series outcomes, and the training process is :ref:`highly configurable <training>`. In this case, we are training a binary categorization model to predict the outcome ``'subtype'``, and we will distribute training across multiple GPUs.
+
+By default, Slideflow will train/validate on the full dataset using k-fold cross-validation, but validation settings :ref:`can be customized <validation_planning>`. If you would like to restrict training to only a subset of your data - for example, to leave a held-out test set untouched - you can manually specify a dataset for training. In this case, we will train on ``train_dataset``, and allow Slideflow to further split this into training and validation using three-fold cross-validation.
+
+.. code-block:: python
+
+    # Train a model from a set of hyperparameters.
+    results = P.train(
+        'subtype',
+        dataset=train_dataset,
+        params=params,
+        val_strategy='k-fold',
+        val_k_fold=3,
+        multi_gpu=True,
+    )
+
+Models and training results will be saved in the project ``models/`` folder.
+
+Read more about :ref:`training a model <training>`.
+
+Evaluating a trained model
+**************************
+
+After training, you can test model performance on a held-out test dataset with :meth:`Project.evaluate`, or generate predictions without evaluation (when ground-truth labels are not available) with :meth:`Project.predict`. As with :meth:`Project.train`, we can specify a :class:`slideflow.Dataset` to evaluate.
+
+.. code-block:: python
+
+    # Train a model from a set of hyperparameters.
+    test_results = P.evaluate(
+        model='/path/to/trained_model_epoch1'
+        outcomes='subtype',
+        dataset=test_dataset
+    )
+
+Read more about :ref:`model evaluation <evaluation>`.
+
+Post-hoc analysis
+*****************
+
+Slideflow includes a number of analytical tools for working with trained models. Read more about :ref:`heatmaps <evaluation>`, :ref:`model explainability <stylegan>`, :ref:`analysis of layer activations <activations>`, and real-time inference in an interactive :ref:`whole-slide image reader <studio>`.
\ No newline at end of file