Merge pull request #9 from dlmbl/v2024

Update exercise for v2024

.github/workflows/build_notebook.yaml

@@ -0,0 +1,32 @@
+name: Build Notebooks
+on:
+  push:
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install jupytext nbconvert
+
+
+      - name: Build notebooks
+        run: |
+          jupytext --to ipynb --update-metadata '{"jupytext":{"cell_metadata_filter":"all"}}' solution.py
+
+          jupyter nbconvert solution.ipynb --TagRemovePreprocessor.enabled=True --TagRemovePreprocessor.remove_cell_tags solution --to notebook --output exercise.ipynb
+          jupyter nbconvert solution.ipynb --TagRemovePreprocessor.enabled=True --TagRemovePreprocessor.remove_cell_tags task --to notebook --output solution.ipynb
+
+      - uses: EndBug/add-and-commit@v9
+        with:
+          add: solution.ipynb exercise.ipynb

.gitignore

@@ -1,4 +1,8 @@
 /iframe_figures
+*.zarr
+.DS_Store
+/data
+data.zip
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

README.md

@@ -1,52 +1,54 @@
-# Exercise 8 - Tracking
+# Exercise 9 - Tracking
 
-This exercise was created by Benjamin Gallusser and Albert Dominguez Mantes.
+This exercise was created by Benjamin Gallusser and Albert Dominguez Mantes,
+and updated for 2024 by Caroline Malin-Mayor.
 
 <img src="figures/tracking.gif" width="500"/><img src="figures/ilp_nodiv.png" width="500"/>
 
+## Objective:
+- Write a pipeline that takes in cell detections and links them across time to obtain lineage trees
+
+
 ## Setup
 1. Go into the folder with this repo and run
     ```
     source setup.sh
     ```
-    to set up the environments for this exercise. This will take a few minutes.
+    to set up the environment for this exercise. This will take a few minutes.
    
-1. Run
+2. Run
     ```
     jupyter lab
     ```
-    , double-click on the `exercise{1|2|3}.ipynb` files and follow the instructions in the notebook.
-
+    , double-click on the `exercise.ipynb` files and follow the instructions in the notebook.
+    
+    Alternatively, open `exercise.ipynb` in VSCode with the jupyter extension and the `09-tracking` environment activated.
 
-## Overview
 
-### 1. Tracking by detection and simple frame by frame matching
+## Overview: Tracking by detection with an integer linear program (ILP)
 
-Here we will walk through all basic components of a tracking-by-detection algorithm.
-
-You will learn
-- to **store and visualize** tracking results with `napari` (Exercise 1.1).
-- to use a robust pretrained deep-learning-based **object detection** algorithm called *StarDist* (Exercise 1.2).
-- to implement a basic **nearest-neighbor linking algorithm** (Exercises 1.3 - 1.6).
-- to compute optimal frame-by-frame linking by setting up a **bipartite matching problem** and using a python-based solver (Exercise 1.7).
-- to compute suitable object **features** for the object linking process with `scikit-image` (Exercise 1.8, bonus).
+### Methods/Tools:
 
+- **`networkx`**: To represent the tracking inputs and outputs as graphs. Tracking is often framed
+    as a graph optimization problem. Nodes in the graph represent detections, and edges represent links
+    across time. The "tracking" task is then framed as selecting the correct edges to link your detections.
+- **`motile`**: To set up and solve an Integer Lineage Program (ILP) for tracking.
+    ILP-based methods frame tracking as a constrained optimization problem. The task is to select a subset of nodes/edges from a "candidate graph" of all possible nodes/edges. The subset must minimize user-defined costs (e.g. edge distance), while also satisfying a set of tracking constraints (e.g. each cell is linked to at most one cell in the previous frame). Note: this tracking approach is not inherently using
+    "deep learning" - the costs and constraints are usually hand-crafted to encode biological and data-based priors, although cost features can also be learned from data.
+- **`napari`**: To visualize tracking inputs and outputs. Qualitative analysis is crucial for tuning the 
+    weights of the objective function and identifying data-specific costs and constraints.
+- **`traccuracy`**: To evaluate tracking results. Metrics such as accuracy can be misleading for tracking,
+    because rare events such as divisions are much harder than the common linking tasks, and might
+    be more biologically relevant for downstream analysis. Therefore, it is important to evaluate on
+    a wide range of error metrics and determine which are most important for your use case.
 
-### 2. Tracking with an integer linear program (ILP)
-
-Here we will introduce a modern formulation of tracking-by-detection.
-
-You will learn
-- how linking with global context can be modeled and solved efficiently as a **network flow** using `motile` ([docs here](https://funkelab.github.io/motile/)) for a small-scale problem (Exercise 2.1).
-- to adapt the previous formulation to allow for **arbitrary track starting and ending points** (Exercise 2.2).
-- to extend the ILP to properly model **cell divisions** (Exercise 2.3).
-- to tune the **hyperparameters** of the ILP (Exercise 2.4, bonus).
-
+After running through the full tracking pipeline, from loading to evaluation, we will learn how to **incorporate custom costs** based on dataset-specific prior information. As a bonus exercise, 
+you can learn how to **learn the best cost weights** for a task from
+from a small amount of ground truth tracking information.
 
-### 3. Bonus: Tracking with two-step Linear Assignment Problem (LAP)
+### Bonus: Tracking with two-step Linear Assignment Problem (LAP)
 
-Here we will use an extended version of the tracking algorithm introduced in exercise 1 which uses a linking algorithm that considers more than two frames at a time in a second optimization step.
+There is a bonus notebook showing how to use a two-step linking algorithm implemented in the Fiji plugin TrackMate. We will not go over this in the exercise time, but it is available for those who are interested in learning on their own.
 
 You will learn
-- how this formulation addresses **typical challenges of tracking in bioimages**, like cell division and objects temporarily going out of focus.
 - how to use **Trackmate**, a versatile ready-to-go implementation of two-step LAP tracking in `ImageJ/Fiji`.