Skip to content

Commit 4c82e39

Browse files
srivarraedyoshikun
srivarra
and
edyoshikun
authored
Cell State Annotator (#31)
* feat: added the cell state annotator Signed-off-by: Sricharan Reddy Varra <[email protected]> * add how to use markdown * feat: added ability to load back a exported csv Signed-off-by: Sricharan Reddy Varra <[email protected]> * fix: added the ability to write back to a loaded csv Signed-off-by: Sricharan Reddy Varra <[email protected]> * add backup folder and the resume csv path. --------- Signed-off-by: Sricharan Reddy Varra <[email protected]> Co-authored-by: Sricharan Reddy Varra <[email protected]> Co-authored-by: Eduardo Hirata-Miyasaki <[email protected]>
1 parent 8ccff7c commit 4c82e39

File tree

5 files changed

+1080
-0
lines changed

5 files changed

+1080
-0
lines changed

‎docs/CELL_STATE_ANNOTATOR.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Cell State Annotator Tutorial
2+
3+
The Cell State Annotator is an interactive napari widget for annotating cell states in time-lapse microscopy data. It exports annotations to ultrack-compatible CSV format.
4+
5+
It supports annotation of:
6+
7+
- **cell_division_state**: Track cells undergoing mitosis (`mitosis`) vs cells in interphase (`interphase`)
8+
- **infection_state**: Mark cells as `infected` or `uninfected` (e.g., viral infection experiments)
9+
- **organelle_state**: Annotate organelle remodeling events (`remodel` vs `noremodel`)
10+
- **cell_death_state**: Track cell death events (`dead` vs `alive`)
11+
12+
## Launching the Widget
13+
14+
### From the command line
15+
16+
```bash
17+
napari --plugin napari-iohub "Cell state annotation"
18+
```
19+
20+
### From Python
21+
22+
```python
23+
import napari
24+
25+
viewer = napari.Viewer()
26+
viewer.window.add_plugin_dock_widget("napari-iohub", "Cell state annotation")
27+
napari.run()
28+
```
29+
30+
### From the napari GUI
31+
32+
1. Launch napari
33+
2. Go to `Plugins` → `napari-iohub` → `Cell state annotation`
34+
35+
36+
## Workflow
37+
38+
### 1. Load Your Data
39+
40+
1. **Browse images**: Click "Browse images" and select your OME-Zarr dataset containing the raw images.
41+
42+
2. **Browse tracks**: Click "Browse tracks" and select your OME-Zarr dataset containing tracking labels. This will populate the Row/Well/FOV navigation dropdowns.
43+
44+
3. **Select FOV**: Use the Row, Well, and FOV dropdowns to navigate to the field of view you want to annotate.
45+
46+
4. **Load Data**: Click "Load Data" to load the images, tracking labels, and set up annotation layers.
47+
48+
### 2. Annotate Cell States
49+
50+
The widget creates four annotation layers, each with a distinct color:
51+
52+
| Layer | Color | Event Type |
53+
|-------|-------|------------|
54+
| `_mitosis_events` | Blue | Cell division |
55+
| `_infected_events` | Orange | Infection |
56+
| `_remodel_events` | Purple | Organelle remodeling |
57+
| `_death_events` | Red | Cell death |
58+
59+
To annotate:
60+
1. Select the appropriate annotation layer (use `q`/`e` to cycle)
61+
2. Navigate to the timepoint of interest (use `a`/`d` to step through time)
62+
3. Click on a cell to add an annotation point
63+
64+
### 3. Keyboard Shortcuts
65+
66+
| Key | Action |
67+
|-----|--------|
68+
| `a` | Step backward in time |
69+
| `d` | Step forward in time |
70+
| `q` | Cycle to previous annotation layer |
71+
| `e` | Cycle to next annotation layer |
72+
| `r` | Toggle interpolation mode |
73+
| `s` | Save annotations |
74+
75+
### 4. Interpolation Mode
76+
77+
For events that span multiple timepoints (e.g., a cell undergoing mitosis over several frames):
78+
79+
1. Click on the cell at the **start** timepoint
80+
2. Press `r` to enable interpolation mode
81+
3. Navigate to the **end** timepoint
82+
4. Click on the cell again
83+
84+
The widget will automatically add annotation points for all intermediate timepoints with linear interpolation.
85+
86+
### 5. Save Annotations
87+
88+
1. **Set output folder**: Click "Output folder" to choose where to save the CSV files (defaults to the tracks dataset location).
89+
90+
2. **Save**: Click "Save Annotations" or press `s`.
91+
92+
The widget saves two CSV files:
93+
- A timestamped version: `annotations_{fov_name}_{username}_{timestamp}.csv`
94+
- A canonical version: `annotations_{fov_name}.csv`
95+
96+
## Output Format
97+
98+
The CSV output is ultrack-compatible with the following columns:
99+
100+
| Column | Description |
101+
|--------|-------------|
102+
| `fov_name` | Field of view identifier |
103+
| `track_id` | Cell track identifier |
104+
| `t` | Timepoint |
105+
| `z`, `y`, `x` | Spatial coordinates |
106+
| `cell_division_state` | `mitosis` or `interphase` |
107+
| `infection_state` | `infected`, `uninfected`, or `null` |
108+
| `organelle_state` | `remodel` or `noremodel` |
109+
| `cell_death_state` | `dead`, `alive`, or `null` |
110+
| `annotator` | Username of annotator |
111+
| `annotation_date` | ISO format timestamp |
112+
| `annotation_version` | Annotation schema version |
113+
114+
## Annotation Logic
115+
116+
- **Mitosis**: Marked at specific timepoints where the cell is dividing
117+
- **Infection**: Once marked, the cell is considered infected from that timepoint onward
118+
- **Organelle remodeling**: Once marked, the cell is considered remodeled from that timepoint onward
119+
- **Death**: Once marked, the cell is considered dead from that timepoint onward (all other states become `null`)
120+
121+
## Tips
122+
123+
- The widget matches annotation points to cell labels using a 10-pixel diameter window around the clicked location
124+
- Points that don't map to a cell (background) will generate a warning in the logs
125+
- Use interpolation mode for events that span multiple consecutive timepoints to save time
126+
- The status bar at the bottom shows the current state and any errors

‎src/napari_iohub/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import logging
22
import os
33

4+
from ._cell_state_annotator import CellStateAnnotatorWidget
45
from ._edit_labels import EditLabelsWidget
56
from ._reader import napari_get_reader
67
from ._view_tracks import open_image_and_tracks
@@ -11,6 +12,7 @@
1112
"MainWidget",
1213
"EditLabelsWidget",
1314
"open_image_and_tracks",
15+
"CellStateAnnotatorWidget",
1416
)
1517

1618
_logger = logging.getLogger(__name__)

0 commit comments

Comments
 (0)