made tutorial buildable

README.md

@@ -2,6 +2,4 @@
 
 ## Acknowledgements
 
-This workshop is based on [napari/napari-workshop-template](https://github.com/napari/napari-workshop-template).
-
-We make use of [napari-convpaint](https://github.com/guiwitz/napari-convpaint) for segmentation.
+This workshop is based on [napari/napari-workshop-template](https://github.com/napari/napari-workshop-template) and [scipy-2024-image-analysis/tutorial](https://github.com/scipy-2024-image-analysis/tutorial).

tutorial/_config.yml

@@ -1,9 +1,13 @@
 # Book settings
 # Learn more at https://jupyterbook.org/customize/config.html
 
-title: napari workshop template
-author: napari core developers
-logo: logo.ico
+title: ultrack 2024 i2k tutorial
+author: Jordao Bragantini
+logo: logo.png
+
+theme:
+  toggle:
+    default: "light"
 
 # Only build files in the table of contents.
 only_build_toc_files: true
@@ -15,6 +19,7 @@ launch_buttons:
 # See https://jupyterbook.org/content/execute.html
 execute:
   execute_notebooks: "cache"
+  timeout: 15_000
 
 # Define the name of the latex output file for PDF builds
 latex:

tutorial/installation.md

@@ -1,4 +1,4 @@
-# Python setup & napari installation
+# Environment setup
 
 ```{tip}
 If you have any issues with installation, please feel free to [open a github issue](https://github.com/royerlab/ultrack-i2k2024/issues/new) and
@@ -106,17 +106,9 @@ as well and you can skip to the next section.
     ```
 
     If you successfully activated the environment, you should now see
-   `(ultrack-i2k2024` to the left of your command prompt.
+   `(ultrack-i2k2024)` to the left of your command prompt.
 
-4. Install the additional workshop dependencies with the commands below.  
-
-   For the plugin template:
-
-    ```bash
-    pip install -r requirements.txt
-    ```
-
-5. Test that your notebook installation is working. We will be using notebooks
+4. Test that your notebook installation is working. We will be using notebooks
    for interactive analysis. Enter the command below and it should launch the
    `jupyter lab` application in a web browser. Once you've confirmed it
    launches, close the web browser and press `ctrl+c` in the terminal window to
@@ -126,7 +118,7 @@ as well and you can skip to the next section.
     jupyter lab
     ```
 
-6. Test your napari installation. Enter the command below and an empty napari
+5. Test your napari installation. Enter the command below and an empty napari
    viewer should open. You can close the window after it opens. Please note that
    it takes a bit of extra time to launch napari the first time.
 

tutorial/tracking.md

@@ -1,28 +1,43 @@
-# Ultrack I2K 2024 - Multiple hypotheses tracking
+---
+jupytext:
+  formats: ipynb,md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 1.0.4
+    jupytext_version: 1.16.4
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+
+# 2D cell tracking with multiple hypotheses
 
 This tutorial shows Ultrack's multiple hypotheses tracking capabilities. 
 
 Here, rather than searching for an optimal segmentation parameter, we sampled multiple segmentations with different parametrizations and used Ultrack to find the best segments, obtaining more accurate cell tracking.
 
-
-## Download Dataset
+## Download data
 
 Download the Fluo-C2DL-Huh7 dataset from the [Cell Tracking Challenge](celltrackingchallenge.net), which contains fluorescence microscopy images for cell tracking.
 
 The dataset will be used for demonstrating the segmentation and tracking workflow.
 
 
-```python
+```{code-cell} python
+:tags: [remove-output]
+
 !wget -nc http://data.celltrackingchallenge.net/training-datasets/Fluo-C2DL-Huh7.zip
 !unzip -n Fluo-C2DL-Huh7.zip
 ```
 
-## Import Libraries
+## Import libraries
 
 Import the libraries needed for reading images, processing them, cell segmentation, tracking, and performance metrics. 
 
 
-```python
+```{code-cell} python
 from pathlib import Path
 from typing import Dict
 
@@ -42,19 +57,21 @@ from ultrack.utils.array import array_apply
 from ultrack.utils import labels_to_contours
 ```
 
-```python
+## Setting up napari viewer
+
+```{code-cell} python
 viewer = napari.Viewer()
+viewer.window.resize(1800, 1200)
 
 def screenshot() -> None:
    display(nbscreenshot(viewer))
 ```
 
-## Load Data
+## Data loading
 
 Load the Fluo-C2DL-Huh7 dataset.
 
-
-```python
+```{code-cell} python
 dataset = "01"
 data_path = Path("Fluo-C2DL-Huh7") / dataset
 image = imread(str(data_path / "*.tif"))
@@ -73,7 +90,7 @@ Since the contours are combined by averaging, the previous value of 0.1 removed
 As a reminder, the configuration parameters documentation can be found [here](https://github.com/royerlab/ultrack/blob/main/ultrack/config/README.md).
 
 
-```python
+```{code-cell} python
 config = MainConfig()
 
 # Candidate segmentation parameters
@@ -95,12 +112,11 @@ config.tracking_config.appear_weight = -1
 print(config)
 ```
 
-## Cellpose Segmentation
+## Cellpose segmentation
 
 The same function as `intro.ipynb` to segment cells within each frame.
 
-
-```python
+```{code-cell} python
 cellpose = Cellpose(model_type="cyto2", gpu=True)
 
 def predict(frame: ArrayLike, gamma: float) -> ArrayLike:
@@ -110,10 +126,10 @@ def predict(frame: ArrayLike, gamma: float) -> ArrayLike:
 
 ## Metrics
 
-Helper function to evaluate tracking score using [Cell Tracking Challenge](celltrackingchallenge.net)'s metrics and annotations.
+We define a helper function to evaluate tracking score using [Cell Tracking Challenge](celltrackingchallenge.net)'s metrics and annotations using the [ctc-metrics](https://github.com/CellTrackingChallenge/py-ctcmetrics).
 
 
-```python
+```{code-cell} python
 def score(output_path: Path) -> Dict:
     gt_path = data_path.parent / f"{data_path.name}_GT"
     return evaluate_sequence(
@@ -127,8 +143,7 @@ def score(output_path: Path) -> Dict:
 
 Here, we evaluate the segmentation and tracking given multiple values of `gamma`, used on the normalization step before the Cellpose prediction.
 
-
-```python
+```{code-cell} python
 all_labels = []
 metrics = []
 gammas = [0.1, 0.25, 0.5, 1]
@@ -170,43 +185,35 @@ for gamma in gammas:
 print(metrics)
 ```
 
-## Combined Contours and Detection
+## Combined contours and foreground
 
-The `labels_to_contours` combines multiple segmentation labels into a single detection and contour map.
+The `labels_to_contours` combines multiple segmentation labels into a single foreground and contour map.
 
-The detection map is the maximum value between the binary masks of each label.
+The foreground map is the maximum value between the binary masks of each label.
 
 The contour map is the average contour map of the binary contours of each label.
 
-
-```python
+```{code-cell} python
 foreground, contours = labels_to_contours(all_labels, sigma=sigma)
 ```
 
-
-```python
-foreground
-```
-
-```python
+```{code-cell} python
 layer = viewer.add_labels(foreground.astype(int))
 screenshot()
 layer.visible = False
 ```
 
-
-```python
+```{code-cell} python
 layer = viewer.add_image(contours)
 screenshot()
 layer.visible = False
 ```
 
 ## Tracking
 
-Run the tracking algorithm on the provided configuration, and combined detections and contours.
-
+Run the tracking algorithm on the provided configuration, and combined foreground and contours.
 
-```python
+```{code-cell} python
 tracker.track(
    foreground=foreground,
    contours=contours,
@@ -216,8 +223,7 @@ tracker.track(
 
 Compute metrics for the multiple hypotheses tracking and compare the scores of the different approaches.
 
-
-```python
+```{code-cell} python
 output_path = Path(f"{dataset}_COMBINED") / "TRA"
 tracker.to_ctc(output_path, overwrite=True)
 
@@ -229,13 +235,13 @@ df.to_csv(f"{dataset}_scores.csv", index=False)
 df
 ```
 
-## Exporting and Visualization
+## Exporting and visualization
 
-The intermediate tracking data is stored on disk and must be exported to your preferred format.
-Here we convert the resulting tracks to a DataFrame and Zarr to visualize using napari if running locally.
+All intermediate tracking data is stored on disk and must be exported to your preferred format this is what enables Ultrack to process multi-terabyte datasets.
 
+Here the resulting tracks are exported to a pandas data frame, a napari friendly format, and zarr for the segmentation.
 
-```python
+```{code-cell} python
 tracks_df, graph = tracker.to_tracks_layer()
 tracks_df.to_csv(f"{dataset}_tracks.csv", index=False)