----------------------------------------------------------------------
This is the API documentation for the omero_screen_napari library.
----------------------------------------------------------------------


## Data model

The shared object the widgets read and write.



## Loading well data

Fetching plate and well data from OMERO into napari.



----------------------------------------------------------------------
This is the CLI documentation for the package.
----------------------------------------------------------------------

## CLI: omero-train

```
Usage: omero-train [OPTIONS] COMMAND [ARGS]...

  Manage the Omero Screen training-data database.

  Migrate existing '.npy' training-data files into the database, list
  available classifiers, inspect their statistics, and export annotations for
  analysis.

  Classifiers can be referred to by either their ID (e.g. 1) or their name
  (e.g. 'Experiment_1').

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  delete   Delete one or more classifiers.
  export   Export training data for CLASSIFIER to a file.
  list     List all classifiers.
  migrate  Migrate existing .npy files into the database.
  stats    Show statistics for CLASSIFIER.
```

### omero-train migrate

```
Usage: omero-train migrate [OPTIONS]

  Migrate existing .npy files into the database.

  Scans the given directory for training-data folders and imports them.

Options:
  --dry-run    Simulate the migration without writing to the database.
  --path PATH  Base directory containing classifier folders (default:
               ~/omeroscreen_trainingdata).
  --help       Show this message and exit.
```

### omero-train list

```
Usage: omero-train list [OPTIONS]

  List all classifiers.

  Shows a table of every classifier with its ID, name and summary statistics.

Options:
  --help  Show this message and exit.
```

### omero-train stats

```
Usage: omero-train stats [OPTIONS] CLASSIFIER

  Show statistics for CLASSIFIER.

  CLASSIFIER is an ID or a name, e.g. 1 or 'MyClassifier'. Prints general
  statistics, the class distribution, and a per-image breakdown.

Options:
  --help  Show this message and exit.
```

### omero-train export

```
Usage: omero-train export [OPTIONS] CLASSIFIER

  Export training data for CLASSIFIER to a file.

  CLASSIFIER is an ID or a name. Annotations are written as CSV, JSON or
  Parquet, optionally filtered by plate and well.

Options:
  --format [csv|json|parquet]  Output format.  [default: csv]
  -o, --output PATH            Output file path (default:
                               {name}_export.{format}).
  --plate INTEGER              Filter by plate ID.
  --well TEXT                  Filter by well.
  --help                       Show this message and exit.
```

### omero-train delete

```
Usage: omero-train delete [OPTIONS] IDENTIFIERS...

  Delete one or more classifiers.

  IDENTIFIERS are IDs or names, e.g. 1 2 'MyClassifier'. Deletes the
  classifier along with its classes, sessions and annotations, and removes the
  associated .npy files and folder from disk.

Options:
  -y, --yes        Skip the confirmation prompt.
  --plate INTEGER  Delete only sessions for the given plate ID(s). Accepts one
                   or more values. If omitted, the entire classifier is
                   deleted.
  --help           Show this message and exit.
```


----------------------------------------------------------------------
This is the User Guide documentation for the package.
----------------------------------------------------------------------


## Guide

### Overview

**omero-screen-napari** adds interactive [Napari](https://napari.org) widgets to your image viewer so you can load microscopy plates from an OMERO server, browse individual cells, and build labelled training datasets for machine learning classifiers — all without writing code.

The package registers five widgets accessible from the **Plugins → Omero Screen Napari** menu:

*  **Welldata Widget** — Load well images from an OMERO plate, cache them locally, and stitch tiled acquisitions into a single composite view.
*  **Gallery Widget** — Extract individual cell crops as a montage grid, filter by cell cycle phase, and define new classifiers.
*  **Training Widget** — Navigate crops one by one, assign class labels with keyboard shortcuts, and save annotated sessions.
*  **Aligned Plate Widget** — Overlay images from multiple spatially registered plates for side-by-side comparison.
*  **Tracks Widget** — Overlay temporal cell tracks, inspect lineages, export per-track measurements, and prepare wells for curation in Mastodon.

Supporting dialogs launched from within the widgets:

*  **Session Manager** — Browse all annotation sessions for a classifier, check data integrity, load or delete sessions, and add new data.
*  **Direct Load Dialog** — Fetch fresh cell crops from OMERO directly into the Training Widget without going through the Gallery workflow.
*  **Plate Info Dialog** — Inspect well metadata, cache status, and select wells to load.

A command-line companion tool, **omero-train**, provides the same database operations without opening Napari.


## Prerequisites

- **Python 3.12, 3.13 or 3.14**
- **Napari 0.6.2+** with Qt backend
- Access to an **OMERO server** (5.x) with valid credentials
- Segmented plate data on OMERO (nucleus/cell masks uploaded by the omero-screen pipeline)

## Install from the Monorepo

The recommended way to install is from the omero-screen monorepo, which includes all
packages:

```bash
git clone https://github.com/Helfrid/omero-screen.git
cd omero-screen
uv sync --dev
source .venv/bin/activate
```

This installs `omero-screen-napari` along with all workspace dependencies.

## Standalone Install

If you only need the Napari widgets:

```bash
uv add omero-screen-napari
```

## OMERO Connection

The widgets connect to OMERO using credentials from environment files. Create a
`.env.development` (or `.env`) in the project root:

```ini
USERNAME=your_omero_username
PASSWORD=your_omero_password
HOST=your.omero.server.com
```

Select the environment with the `ENV` variable:

```bash
export ENV=development   # default
export ENV=production    # for production server
```

## Verify Installation

Launch Napari and check that the widgets appear under the **Plugins** menu:

```bash
napari
```

You should see:

- Welldata Widget
- Gallery Widget
- Training Widget
- Aligned Plate Widget

## Troubleshooting

**Widgets not appearing in Plugins menu**
: Ensure the package is installed in the same environment as Napari. Run
  `napari --info` and check that `omero-screen-napari` is listed.

**OMERO connection fails**
: Verify your `.env` file exists and contains valid credentials. Check that the
  OMERO server is reachable from your machine.

**Import errors for zeroc-ice**
: The OMERO Python bindings require `zeroc-ice`. Platform-specific wheels are
  configured in the root `pyproject.toml`. If you encounter issues, check the
  [omero-py documentation](https://pypi.org/project/omero-py/).


## What this widget does

The Welldata Widget is your starting point. It connects to your OMERO server, downloads images from a specific well on a plate, and displays them in the Napari viewer complete with segmentation masks and experimental metadata. It also caches plate data to your local disk so that future loads are nearly instant.

If your microscope acquired images across multiple overlapping positions (tiled acquisitions), the widget can stitch these positions together into a single, seamless composite image.

## Opening the widget

In Napari, go to **Plugins → Omero Screen Napari → Welldata Widget**. The widget opens as a panel on the right side of the viewer.

---

## Step 1 — Load a well

### What you need to fill in

| Field | What to enter | Example |
|-------|--------------|---------|
| **Plate ID** | The numeric ID of your plate in OMERO | `3869` |
| **Well Position** | One or more well positions, comma-separated | `A1` or `A1, B3, C5` |
| **Images** | Which images to load from the well | `All`, `0`, `0, 1, 2`, or a range `3-5` |
| **Time** | Timepoint index, or `All` for a time series | `0` |
| **Cache** | Tick this to download the full plate to disk in the background | ☑ |

Click **Enter** to start loading.

### What appears in the viewer

Once loading completes:

- **Fluorescence channels** are added as separate image layers with automatic colormaps:
  - DAPI / Hoechst → blue
  - Tubulin → green
  - EdU → red
  - Additional channels → magenta, cyan, yellow
- **Segmentation masks** (nucleus outlines, cell outlines) are added as label layers if they were generated during the analysis pipeline.
- A **metadata panel** appears showing the experimental annotations for the well (cell line, condition, timepoint, etc.). When you navigate between images or timepoints, this panel updates automatically.

### Loading multiple wells

Separate well positions with commas: `A1, A2, A3`. All wells are loaded in sequence and stacked in the viewer.

---

## Step 2 — Browse the Plate Info Dialog

Instead of typing well positions manually, you can open the **Plate Info Dialog** by clicking on the plate dropdown at the top of the widget.

The dialog shows a table of every well in the plate with:

- Well position, cell line, condition, timepoint
- Number of images per well
- Whether segmentation masks are available
- Real-time cache download progress

You can:
- **Double-click any row** to load that well immediately.
- **Select multiple rows** using the checkboxes and load them all at once.
- **Sort and filter** the table to find wells quickly.

---

## Step 3 — Cache the plate for faster access

Downloading images from OMERO every time is slow. The **Cache** feature downloads a plate to your local disk once, so subsequent loads are instant.

There are two cache backends, and the widget picks one for you based on how the plate was processed:

| Backend | Used when | What's stored | How loads work |
|---------|-----------|---------------|----------------|
| **Disk cache** (legacy) | Plates processed in per-field mode | Raw per-image TCZYX pixels (uint16) | Pixels fetched per field at view time; stitching done in memory |
| **OME-Zarr cache** | Plates processed with `--stitch` (see [stitched-mode segmentation](https://hocheggerlab.github.io/omero-screen/pipeline.html#stitched-mode-segmentation)) | Pre-stitched whole-well canvas in OME-Zarr v0.4 (NGFF) format | Lazy chunk loads straight into napari — bounded memory, instant pan/zoom |

The widget detects stitched-mode plates automatically (by looking for `_stitched_segmentation` images in the OMERO segmentation dataset) and uses OME-Zarr. Everything else uses the disk cache.

### How to cache

1. Tick the **Cache** checkbox before clicking Enter, **or**
2. Open the **Cached Plates panel** at the top of the widget and click the **Cache** button next to the plate you want, **or**
3. Open the **Plate Info dialog** (see Step 1) and click **Cache Plate** there.

For OME-Zarr builds you'll see a determinate progress bar (`building D1 (0/12)` → `wrote D1 (1/12), building D2` …). Cancelling mid-build is safe — wells already written stay on disk, and clicking Cache Plate again resumes from where it stopped.

### The Cached Plates panel

| Control | What it does |
|---------|-------------|
| **Plate dropdown** | Shows all locally cached plates with their status (disk or zarr) |
| **Cache Size** | Total disk space used by the cache |
| **Cache button** | Downloads the full plate in the background, using the right backend |
| **Delete button** | Removes the cached data for a plate (clears both backends if both are present) and the per-plate OME-Zarr directory |
| **Refresh button** | Rescans the cache folder (useful if you cached from another session) |

The cache persists between Napari sessions — you do not need to re-download when you restart.

### Where the caches live on disk

The cache root is `~/omero-cache` by default (a *visible* folder, so the
OME-Zarr stores can also be opened directly by Fiji/Mastodon). Override it with
`OMERO_SCREEN_CACHE_PATH`.

```
~/omero-cache/
├── images/    # disk cache: per-image TCZYX pixel blobs (diskcache + sqlite index)
├── plates/    # disk cache: plate metadata + well layout
└── zarr/      # OME-Zarr cache: one plate_<id>.zarr directory per cached plate
    └── registry.json    # tracks last-accessed times for LRU eviction
```

> **Note:** The default location moved from the old hidden `~/.cache/omero_screen`
> to the visible `~/omero-cache`. On the first run after upgrading you may see a
> one-time log line noting this; rebuild plates in the new location (the old
> folder can then be deleted), or set `OMERO_SCREEN_CACHE_PATH` to keep the old path.

Size limits are configurable via environment variables:
- `OMERO_SCREEN_IMAGE_CACHE_SIZE_LIMIT` (default **20 GiB**, for the legacy disk cache; raw bytes)
- `OMERO_SCREEN_ZARR_MAX_GB` (default **100 GiB**, for the OME-Zarr cache; integer GiB, clamped to a 10 GiB minimum)

When a new build would exceed its cap, the least-recently-accessed plate is evicted automatically. For the full set of cache environment variables, layout, and eviction/pinning rules, see the [Local Caching & Interactive Viewing](https://hocheggerlab.github.io/omero-screen/caching.html) guide.

> **Tip:** For large plates (>20 wells), start the cache download while you work on the first few wells. By the time you need the later wells, they will already be on disk.

> **Tip:** If you suspect orphan files (e.g. after a crash), `rm -rf ~/omero-cache` is always safe — all three caches rebuild on demand.

### Disk cache vs OME-Zarr — which is "better"?

For the **future direction**: OME-Zarr is the destination. Loads are dramatically lighter on memory (no in-memory stitching at view time), and the format is standard so the same data can be opened by other tools (`napari-ome-zarr`, Fiji, `ome-zarr-py`).

For **today**: the disk cache covers per-field plates that haven't been re-run with `--stitch`, and is still the path used by the gallery / training widgets via per-image crops. Both backends coexist; the dispatcher chooses the right one. You don't normally need to think about this — but if you're processing a new plate and want the fastest viewer experience, run with `--stitch` so the OME-Zarr path is available.

---

## Step 4 — Stitch tiled images (multi-position acquisitions)

Some microscope setups acquire several overlapping fields of view per well, which need to be joined together to see the full well. The stitching panel handles this.

### When you need stitching

If your well contains images named in a way that suggests a grid (e.g. position 1, 2, 3 … 25 for a 5×5 grid), or if the metadata indicates a tiled acquisition, use stitching.

### Stitching parameters

| Parameter | Default | What it controls |
|-----------|---------|-----------------|
| **Stitch** | on | Whether to stitch the loaded fields into a single canvas. |
| **Overlap X / Y** | 7 | Tile overlap in **pixels** along each axis. Match this to your microscope's acquisition overlap. |
| **Translate X / Y** | −3 / 3 | Fine pixel offset applied between tiles to correct small residual misalignment (range −20…20). |
| **Edge** | 7 | Edge-blending width in **pixels** at tile seams, to hide illumination steps. |

After loading your well, fill in the stitching parameters and click **Enter** in the stitching panel. The stitched composite appears as a new layer in the viewer.

> **Tip:** If the stitched image looks misaligned, nudge **Translate X / Y** by 1–2 pixels at a time, then adjust **Overlap X / Y** if seams remain. These defaults match typical Operetta/Opera acquisitions.

---

## Tips and common questions

**Q: The images look very dim.**
A: Use napari's contrast controls (the coloured bar on each layer) to adjust brightness. The images are stored at full bit depth — napari's auto-scaling sometimes sets a conservative range.

**Q: No segmentation masks appear.**
A: Masks are only shown if your plate was processed through the omero-screen analysis pipeline. If you only have raw images, the masks will not be available.

**Q: I see "Plate not found" error.**
A: Double-check the Plate ID in OMERO.web. The ID is the number shown in the plate URL or in the left-hand tree.

**Q: Can I load images without an OMERO connection?**
A: Yes, if the plate is already cached locally. Cached plates load without any server connection.


## What this widget does

The Gallery Widget takes the images you loaded in the Welldata Widget and cuts out individual cells as small square crops, then displays all of them as a grid (montage). This lets you see many cells at once to get a feel for the data and check that segmentation looks correct.

The widget also contains the **Create Classifier** section, where you define the categories you want to sort cells into and save those settings so the Training Widget knows what classes exist.

## Opening the widget

In Napari, go to **Plugins → Omero Screen Napari → Gallery Widget**.

> **You must load well data first.** The Gallery Widget needs images and segmentation masks in the viewer. Use the [Welldata Widget](welldata_widget.qmd) to load a well before generating a gallery.

---

## Part 1 — Generate a cell gallery

### Gallery parameters

| Field | What it controls | Typical value |
|-------|-----------------|---------------|
| **Well** | Which well to crop from. Defaults to the currently loaded well — leave blank unless you want a different one. | `A1` |
| **Segmentation** | Whether to use nucleus or whole-cell outlines as the crop boundary | `nucleus` |
| **Crop size** | Side length of each crop in pixels | `50` for most cells; `100` for larger cells |
| **Cell cycle** | Only show cells in a specific phase: All, G1, S, G2/M, G2, M, or Polyploid | `All` |
| **Timepoint** | Which timepoint to use for time-series data | `0` |
| **Columns / Rows** | Grid dimensions. Total crops = rows × columns | 4 × 4 = 16 crops |
| **Reload** | Re-extract crops from the images. Turn off to reuse the same crops with different display settings | ☑ on |
| **Contour** | Draw a white outline around each cell to show the segmentation boundary | ☑ on |
| **No Background** | Set all pixels outside the segmentation mask to black, so only the cell itself is visible | ☑ on |
| **Blue channel** | Channel name mapped to the blue component of the RGB display | `DAPI` |
| **Green channel** | Channel name mapped to green | `Tub` |
| **Red channel** | Channel name mapped to red | `EdU` |

Click **Enter** to generate the gallery. The montage appears as an RGB image layer in the viewer.

### What the gallery shows you

Each tile in the grid is one cell, cropped to the size you specified and centred on its nucleus (or cell body). The channels are merged into a false-colour RGB image using the mapping you set. This is the same representation that will be shown one cell at a time in the Training Widget.

### Adjusting the display

- **Crop size**: Too small and you lose context around the cell; too large and cells overlap. 50 px works for most mammalian cells with a 20× objective; use 100 px for spread-out cells or low magnification.
- **Cell cycle filter**: If you only want to annotate mitotic cells, set this to `G2/M` or `M`. The gallery will show only cells the pipeline classified in that phase.
- **No Background**: Very useful when cells are densely packed — it removes signals from neighbouring cells so you are scoring the target cell only.
- **Contour**: Lets you check whether the segmentation boundary looks correct. If you see many cells where the outline is clearly wrong, the segmentation may need to be re-run.

### The Reset button

Clicking the **Reset** button (just below the gallery parameters) clears all cropped images from memory. Use this before generating a gallery from a new well to avoid mixing crops from different experiments.

---

## Part 2 — Create a new classifier

The **Create Classifier** section at the bottom of the Gallery Widget is where you set up a new classification project. You only need to do this once per classifier.

### What is a classifier?

A classifier is a named collection of training sessions where cells are sorted into defined categories. For example, you might create a classifier called `mitosis-rpe` to distinguish normal interphase cells from cells in different stages of mitosis in RPE cells. Each classifier has its own folder on disk and its own record in the training database.

### Step-by-step: creating a classifier

**1. Define your classes**

Type the name of one class in the **Class name** field and click **Add** (or press Enter). Repeat for each class you want.

> The class `unassigned` is always present — it is the default label for cells you have not yet scored. You do not need to add it.

Example classes for a mitosis classifier:
- `interphase`
- `prophase`
- `metaphase`
- `anaphase`
- `telophase`

The class list below the input field shows all classes you have added so far.

**2. Set the cell cycle filter**

The **Cell cycle** dropdown records which cell cycle phase filter was active when this training data was collected. This is stored in the classifier's settings so that when you add more data later (from a different plate), the same filter is applied automatically, keeping all sessions consistent.

If you generated your gallery with `G2/M` filtered, set this to `G2/M`. If you used `All`, leave it at `All`.

**3. Name the classifier**

Type a descriptive name in the **Classifier name** field. Use lowercase letters, numbers, and hyphens — no spaces.

Good examples: `mitosis-rpe`, `apoptosis-hela`, `drug-response-u2os`

**4. Click Save classifier**

The widget will:
- Create a folder at `~/omeroscreen_trainingdata/<classifier-name>/`
- Save a `metadata.json` file recording all your settings (crop size, channels, cell cycle filter, class names)
- Register the classifier in the training database
- Save the crops currently in memory as the first training session (so you do not need to reload the gallery in the Training Widget)

After saving, the class list and name field reset so you can immediately define another classifier if needed.

### CLI equivalent

You can inspect classifiers from the terminal without opening Napari:

```bash
omero-train list               # see all classifiers
omero-train stats mitosis-rpe  # detailed info for one classifier
```

---

## Channel mapping

The gallery builds an RGB composite from three channels. The default mapping is:

| RGB colour | Default channel name | Typical marker |
|------------|---------------------|----------------|
| Blue | DAPI | DNA / chromatin |
| Green | Tub | Tubulin / cytoplasm |
| Red | EdU | S-phase marker |

Change the channel names to match your experiment. Channel names must match the names stored in OMERO (visible in the plate metadata). If your experiment only has two channels, leave the third field blank — it will be set to zero. Single-channel images are displayed in greyscale.

---

## Tips

- **Start with a small grid** (4 × 4 = 16 crops) to check that everything looks right. Once satisfied, generate a larger gallery (8 × 8 = 64 crops) to save as your first training session.
- **Check the contours** before creating a classifier. If many cells have clearly wrong outlines, fix the segmentation first — bad masks produce bad training data.
- **Filter by cell cycle** when your phenotype of interest is rare. For example, if you are scoring mitotic stages, filter to `G2/M` so the gallery is not dominated by G1 cells.
- **The same gallery is used for the first session.** When you click Save classifier, the crops currently displayed in the gallery become session 1. Generate your gallery with the grid size you want (e.g. 10 × 10 = 100 crops) before saving.


## What this widget does

The Training Widget is where you do the actual work of labelling cells. It shows you one cell crop at a time in the viewer and lets you assign it to a class using radio buttons or keyboard shortcuts. When you are done, you save the annotated session to disk.

Over time, as you label more cells from more plates and wells, the training database grows and you can use it to train a machine learning classifier.

## Opening the widget

In Napari, go to **Plugins → Omero Screen Napari → Training Widget**.

---

## The layout

The widget is divided into three sections from top to bottom:

1. **Classifier selector** — Choose which classifier you are working on.
2. **Navigation and annotation** — Move through crops and assign labels.
3. **Save** — Persist all your annotations to disk.

---

## Step 1 — Select a classifier

The dropdown at the top lists all classifiers stored in the training database. Select the one you want to work on.

Beneath the dropdown, the **info panel** shows a summary of the selected classifier:

- Number of annotation sessions
- Total cells annotated across all sessions
- Class distribution (how many cells are in each category)

If you have not created a classifier yet, do this first in the [Gallery Widget](gallery_widget.qmd).

---

## Step 2 — Load cell crops

You need crops in memory before you can annotate. There are two ways to get them:

### Option A — From the Gallery Widget (recommended for new sessions)

1. Use the [Welldata Widget](welldata_widget.qmd) to load a plate well.
2. Use the [Gallery Widget](gallery_widget.qmd) to generate a cell gallery and create a classifier (or just generate a gallery for an existing classifier).
3. Switch to the Training Widget — the crops transfer automatically and the first cell is displayed.

### Option B — Load a previous session

If you have annotated some cells before and want to continue:

1. Select your classifier from the dropdown.
2. Click **Manage Sessions** to open the Session Manager.
3. Find the session you want in the table and click **Load**.
4. The widget restores all crops and your existing annotations. Continue from where you left off.

### Option C — Add new data from OMERO

If you want to annotate cells from a different plate or well than the one currently loaded in the viewer:

1. Click **Manage Sessions** → **Add New Data**.
2. The [Direct Load Dialog](session_manager.qmd#direct-load-dialog) opens.
3. Enter the plate and well you want, then click **Load Data**.
4. Crops are fetched from OMERO using the classifier's saved parameters and loaded automatically.

---

## Step 3 — Annotate cells

### Navigating through crops

| Action | How |
|--------|-----|
| Next cell | Click **Next Image** button, or press **W** |
| Previous cell | Click **Previous Image** button, or press **Q** |

The current cell number is shown implicitly by the image title in the viewer (e.g. `Cropped Image 7`). The napari status bar shows the total number of layers.

### Assigning a class

The **Select class** radio buttons show all classes defined for this classifier (e.g. `interphase`, `prophase`, `metaphase`, …). Click the button for the class that matches the cell you are looking at.

The assignment is stored immediately in memory for that crop. When you move to the next cell, the radio buttons update to show whatever class was previously assigned to it (so you can review and change earlier decisions).

### Assigning all cells to one class at once

If most cells in a session belong to the same class, you can use the **Assign all cells to:** section. It shows one button for each of your classes (excluding `unassigned`). Clicking a button sets **every cell in the current session** to that class in one go.

> ⚠ A confirmation dialog will appear before any bulk assignment — this is intentional, because it overwrites all existing annotations for this session. Click **Yes** only if you are sure.

This is useful, for example, when you load a session filtered to `G1` phase: you can immediately assign all cells to `interphase` and then step through to correct the few exceptions.

### Reading the crop display

Each cell is shown as a small square image:

- **Channels** are merged into an RGB composite using the mapping saved in the classifier (blue = DNA, green = cytoplasm, red = S-phase marker by default).
- **Contour overlay** (white outline) shows the segmentation boundary, if this was enabled when the classifier was created.
- **Background removal** (pixels outside the mask set to black) is applied if `No Background` was enabled when the classifier was created.

These display settings are fixed per classifier — they were chosen when you created it in the Gallery Widget.

### Napari contrast controls

Napari automatically scales the brightness of each crop. If the auto-scaling looks wrong (images appear all black or all white), use the contrast slider in the Layers panel to adjust. Your contrast setting is preserved as you move between cells.

---

## Step 4 — Save your annotations

Click **Save training data** to write everything to disk.

This saves:

- An **NPY file** at `~/omeroscreen_trainingdata/<classifier>/<plate>_<well>_<images>_<timepoint>.npy` containing the image crops and segmentation masks.
- **Database records** — each crop's class assignment is stored in the training SQLite database, linked to the session and classifier.

The info panel in the classifier selector updates immediately to show the new annotation counts and class distribution.

> **Save frequently.** Annotations are held in memory until you click Save. If Napari crashes, unsaved work is lost.

---

## Keyboard shortcuts

| Key | Action |
|-----|--------|
| **W** | Next cell |
| **Q** | Previous cell |

These shortcuts work whenever the Napari viewer has focus. They are designed so you can keep one hand on the keyboard for navigation while your other hand uses the mouse to click radio buttons.

---

## Managing sessions

Click **Manage Sessions** on the classifier info panel to open the Session Manager. This shows a table of every annotation session for the selected classifier, with the following information:

| Column | Meaning |
|--------|---------|
| **Plate ID** | OMERO plate the crops came from |
| **Well** | Well position |
| **Images** | Image indices used |
| **Timepoint** | Timepoint index |
| **Cell Cycle** | The cell cycle filter active when the session was created |
| **Cells** | Number of crops in this session |
| **Class Distribution** | How many cells are assigned to each class |
| **Status** | ✓ Valid (green) = data file is present; ✗ Error (red) = file missing |

From the Session Manager you can:
- **Load** a previous session to continue annotating it.
- **Delete** a session (with confirmation).
- **Add New Data** to fetch fresh crops from a different plate or well.

See [Session Manager & Direct Load](session_manager.qmd) for full details.

---

## CLI equivalent

You can inspect and export annotation data without opening Napari:

```bash
omero-train list                        # all classifiers and session counts
omero-train stats mitosis-rpe           # class distribution for one classifier
omero-train export mitosis-rpe          # export all annotations to CSV
omero-train export mitosis-rpe --plate 3869  # export only one plate's data
```

See the [CLI reference](cli_reference.qmd) for full details.

---

## Tips

- **Label a manageable batch** at a time — 100–200 cells per session is a good target. It is better to save and add more data later than to try to label 1000 cells in one sitting.
- **Aim for balanced classes.** If you have 200 interphase cells and 5 mitotic cells, the classifier will be biased. Use the cell cycle filter in the Gallery Widget to enrich for rare phenotypes.
- **Use the Assign All button for easy cases.** When a plate's well has almost entirely one phenotype (e.g. drug-treated cells that are all apoptotic), bulk-assign first and then correct the exceptions.
- **Multiple sessions per classifier are fine** — and encouraged. Data from different plates, wells, and experimental repeats makes the classifier more robust.


## What this widget does

The Tracks Widget visualises the temporal tracks produced by the omero-screen
pipeline's `--track` option (see [Temporal Tracking](https://hocheggerlab.github.io/omero-screen/pipeline.html#temporal-tracking)). Once a live-cell
plate has been tracked, every nucleus carries a stable `track_id` across time
and a `parent_track_id` linking daughters to their mother at divisions. This
widget overlays those tracks on the well image, lets you inspect a single
lineage, export one track's measurements for analysis, and hand a well off to
[Mastodon](https://mastodon.readthedocs.io/) for manual curation.

It does **not** generate tracks — that happens in the pipeline. Here you view,
export, and protect them.

## Before you start

* The plate must have been run with `omero-screen <id> --stitch --track`, and
  imported into CellView (`cellview import-plate <id>`), so the `track_id`
  columns exist.
* Load the well first with the **Welldata Widget** — the Tracks Widget reads
  the well that is currently loaded in the viewer.

## Opening the widget

In Napari, go to **Plugins → Omero Screen Napari → Tracks Widget**. The panel
stacks several sections, each with its own button:

1. **Load tracks**
2. **Export track CSV**
3. **Export well for Mastodon**
4. **Pin plate**
5. **Unpin plate**

If the lower buttons are cut off, drag the dock taller or undock it.

---

## Load tracks

Fills in (or leave **Well** blank to use the currently-loaded well), then click
**Load tracks**.

| Field | What to enter |
|-------|---------------|
| **Well** | Well position, e.g. `B2`. Blank = the loaded well. |
| **Color by** | `track_id` (rainbow) or `cell_cycle` (if cell-cycle analysis ran). |
| **Tail length** | How many past frames trail behind each track head (default 10). |
| **Show divisions (lineage)** | Off by default. When on, the division lineage graph is passed to the Tracks layer so mother→daughter links are drawn. Building the graph for thousands of divisions can briefly freeze the UI, so it is opt-in. |

A napari **Tracks** layer appears, overlaid on the nuclei. The track positions
are scaled to match the image, so they sit directly on the cells. Scrub the
time slider to watch tracks move; a division shows as one track splitting into
two.

::: {.callout-note}
If you see *"No track data in the loaded plate"*, the plate was not tracked or
not yet imported into CellView. Re-run the pipeline with `--track` (and
`--stitch`), then `cellview import-plate`.
:::

## Inspecting a single lineage (napari-arboretum)

For the lineage *tree* of a single track, use the
[napari-arboretum](https://www.napari-hub.org/plugins/napari-arboretum) plugin
(installed as a dependency), which is purpose-built for this:

1. Open **Plugins → arboretum → Arboretum**.
2. Select the **tracks** layer in the layer list.
3. **Double-click a track** in the viewer — Arboretum draws that founder's
   lineage tree, with divisions as branch points.

We delegate the tree view to Arboretum rather than reinventing it — it is made
by the same lab that contributed napari's Tracks layer.

## Export track CSV

To pull one track's full measurement time-course out for downstream analysis
(e.g. picking the longest, cleanest tracks):

1. Enter the **track id** (read it off the Tracks layer or the Arboretum tree).
2. Optionally set the **Well**.
3. Click **Export track CSV** and choose a save location.

The CSV contains every measurement column for that single track across time.

## Export well for Mastodon (CTC)

Prepares a well for manual curation in Mastodon as a Cell Tracking Challenge
bundle:

1. Optionally set the **Well**.
2. Click **Export well for Mastodon (CTC)**.

This writes `~/mastodon_exports/plate_<id>_<well>_ctc/` containing per-frame
`mask*.tif` label images (from the cached zarr — no image copy), `res_track.txt`
(the lineage), `manifest.json` (for the CellView round-trip) and a `README.txt`
with the exact CTC-import steps. Import it via Mastodon's **Import from
CellTrackingChallenge** — this preserves lineages and divisions, which the CSV
importer does not. See the [Live-cell tracking](https://hocheggerlab.github.io/omero-screen/tracking.html) overview for the full walkthrough.

::: {.callout-note}
Use the CTC importer, **not** Mastodon's CSV importer: the CSV importer creates
spots but no links, so it silently drops every track. The bundle is written on
demand per well (not at cache-build time), since it includes a per-frame TIFF
stack.
:::

## Pin / Unpin plate

The OME-Zarr cache is size-bounded and evicts least-recently-used plates. If you
will curate a well in Mastodon over time (a separate Fiji session that can span
days), protect it first:

* **Pin plate** — exempt the loaded plate from eviction. The pin persists across
  napari restarts.
* **Unpin plate** — release it when you are done curating, so it can be
  reclaimed. The button also reports which plates are still pinned.

Pinning is deliberately a manual choice: caching a plate does not mean you are
curating it, and pinning everything would defeat the cache.


## Session Manager

### What it does

The Session Manager is a dialog that gives you a complete overview of all annotation sessions belonging to a classifier. You can see how many cells have been labelled in each session, check whether the underlying data files are intact, load a session to continue annotating it, delete sessions you no longer need, and add fresh data from OMERO.

### Opening the Session Manager

In the Training Widget, click **Manage Sessions** on the classifier info panel. The button appears once a classifier with at least one session is selected.

### The Sessions table

Each row in the table represents one annotation session — one batch of crops from a specific plate, well, and set of images.

| Column | What it shows |
|--------|--------------|
| **#** | Row number |
| **Plate ID** | The OMERO plate ID the crops came from |
| **Well** | The well position (e.g. `A1`) |
| **Images** | Which images were used (e.g. `0`, `1, 2`, `All`) |
| **Timepoint** | The timepoint index |
| **Cell Cycle** | The cell cycle filter active when this session was created (e.g. `All`, `G1`, `G2/M`) |
| **Cells** | Total number of crops (annotated + unassigned) |
| **Class Distribution** | How many crops are assigned to each class |
| **Status** | ✓ Valid (green) = data file exists and is readable; ✗ Error (red) = file missing or unreadable |
| **Actions** | **Load** and **Delete** buttons |

### Summary header

Above the table, a summary line shows:
- Total number of sessions
- Total cells annotated across all sessions
- Number of distinct plates contributing data
- When the database was last updated

### Loading a session

Click **Load** on any row to restore that session into the Training Widget. This:
1. Reads the NPY file from disk (image crops and masks).
2. Restores the display settings (contour, background removal, channel mapping) from the classifier's saved metadata.
3. Restores all class assignments you previously made.
4. Displays the first crop in the viewer.

You can then continue annotating and click **Save training data** in the Training Widget when finished.

> If the Status column shows ✗ Error, the data file is missing. You can still delete the database record using the Delete button, but you cannot load the session.

### Deleting a session

Click **Delete** on a row. A confirmation dialog asks you to confirm. Once confirmed:
- The database records (session and all its annotations) are removed.
- The NPY data file is deleted from disk, **unless** another session is using the same file.
- If this was the last session for the classifier, you are asked whether to delete the classifier itself (including its folder and `metadata.json`).

> Deletion is permanent. Use the **omero-train export** command to back up your data before deleting anything important.

### Action buttons

| Button | What it does |
|--------|-------------|
| **Add New Data** | Opens the Direct Load Dialog to fetch crops from a new plate or well |
| **Refresh** | Re-queries the database and updates the table (useful if another user added data) |
| **Close** | Closes the Session Manager without making any changes |

---

## Direct Load Dialog

### What it does

The Direct Load Dialog lets you fetch cell crops directly from OMERO and add them as a new session for the current classifier — without having to go back through the Welldata Widget and Gallery Widget. It uses the classifier's saved settings (crop size, channels, segmentation type, cell cycle filter) automatically, so all sessions are consistent.

This is the fastest way to add more training data from a different plate or well.

### Opening the Direct Load Dialog

In the Session Manager, click **Add New Data**.

### What to fill in

| Field | What to enter | Example |
|-------|--------------|---------|
| **Plate ID** | The OMERO plate ID to load from | `3869` |
| **Well ID** | The well position. A dropdown offers all 96-well positions (A1–H12); type directly for larger formats | `B4` |
| **Images** | Which images to use. Accepts: `All`, a single number, a comma-separated list, or a range | `All`, `0`, `0, 1`, `3-5` |
| **Timepoint** | Timepoint index | `0` |

### The classifier settings preview

The dialog shows the settings that will be applied, read from the classifier's `metadata.json`:
- Crop size
- Channel names and RGB mapping
- Segmentation type (nucleus or cell)
- Cell cycle filter

These are applied automatically. You do not need to re-enter them.

### Loading the data

1. Fill in the Plate ID, Well, Images, and Timepoint fields.
2. Click **Validate** to check the inputs and see a formatted preview.
3. Click **Load Data** to:
   - Connect to OMERO and fetch the plate.
   - Find the well and retrieve the images.
   - Apply flatfield correction (if available).
   - Look up cell centroids from the CellView database.
   - Extract crops using the classifier's crop size, centred on each centroid.
   - Apply the cell cycle filter to select only cells in the relevant phase.
   - Display the first crop in the Training Widget.
4. The dialog closes automatically on success.

### What happens behind the scenes

- Crops are normalised to a consistent brightness range using the 99.9th percentile of each channel — the same approach used by the Gallery Widget, so new sessions look the same as existing ones.
- Only the target cell's segmentation mask is retained per crop (other cells in the field of view are removed), matching the Gallery Widget's behaviour.
- The session is not saved to disk automatically. Annotate in the Training Widget and click **Save training data** when finished.

### CLI equivalent

You cannot load crops from OMERO via the CLI, but you can inspect the sessions that result:

```bash
omero-train stats mitosis-rpe     # see all sessions including newly added ones
```

---

## Tips

- **Add data from multiple plates and wells.** A classifier trained on a single plate will not generalise well to other experiments. Aim for at least 3–5 different wells from different repeats.
- **Use the cell cycle filter consistently.** The filter is stored per session and shown in the Cell Cycle column. If some sessions used `All` and others used `G2/M`, the training data will be inconsistent. Create separate classifiers for different filter settings.
- **Check the Status column regularly.** Red entries mean the data file has moved or been deleted. Clean up orphaned records with the Delete button to keep the database tidy.
- **Back up before deleting.** Run `omero-train export <classifier>` to save a CSV of all annotations before doing any deletions.


## What this widget does

The Aligned Plate Widget loads images from multiple OMERO plates that have been spatially registered and overlays them in the Napari viewer. This is useful when the same well position was imaged across separate plates — for example, different drug treatments, time series acquired on different days, or repeated experiments — and you want to compare them side by side with the cells in the same positions.

## Opening the widget

In Napari, go to **Plugins → Omero Screen Napari → Aligned Plate Widget**.

## What you need to fill in

| Field | What to enter | Example |
|-------|--------------|---------|
| **Plate ID** | The primary OMERO plate to load | `3869` |
| **Well Position** | A single well position | `A1` |
| **Image index** | Which image within the well to display | `0` |
| **Sample Alignments** | Tick this to display alignment reference points for verification | off |

Click **Enter** to load.

## What happens

1. The widget loads the primary plate image for the well you specified.
2. It discovers all aligned plates from the alignment data stored in OMERO or a local CSV file (`agg_data.csv`).
3. X/Y translation offsets are applied to each aligned plate so that cells from different plates land on the same pixel coordinates in the viewer.
4. Each fluorescence channel is added as a separate layer with an appropriate colourmap.
5. Duplicate channels (same channel name appearing in more than one plate) are filtered so the viewer is not cluttered.

## Navigating the overlay

Use Napari's standard layer controls to explore the overlay:

- Toggle individual layers on/off using the eye icon next to each layer.
- Adjust opacity sliders to blend layers visually.
- Switch between **Additive** and **Translucent** blending modes for different comparison styles.

## Alignment data

Spatial alignment means that a prior analysis has calculated how much each plate's images need to be shifted (in X and Y, in pixels) to match a reference plate. This offset data must already exist — either as an OMERO annotation or as a `agg_data.csv` file — before using this widget.

The pixel size from the image metadata is used to convert physical distances into pixel shifts correctly.

## Tips

- Only a **single well** can be loaded at a time.
- Enable **Sample Alignments** to display the reference points used for registration, which lets you verify visually that the overlay is correct before drawing biological conclusions.
- If the overlay looks misaligned, the alignment data may have been generated with a different image size or pixel size. Check that all plates were acquired with the same objective and settings.
- Use **Additive** blending to see both plates' signals simultaneously; use **Translucent** with reduced opacity to compare one plate against another.


### omero-screen-images CLI

::: {.callout-note}
This page covers what the tool is for and how it is used. For every option,
its default and its type, run `omero-screen-images <command> --help`: the help
text is generated from the code, so it is always current.
:::

## What this tool does

`omero-screen-images` renders the images the napari widgets produce, without
opening napari, so a script, a notebook or an agent can regenerate them
reproducibly:

| Command | Output |
|---|---|
| `gallery` | A grid of cell crops per well, optionally one classifier class or an explicit cell selection |
| `well` | A whole-well overview: stitched multichannel composite with a caption and scale bar, the whole well or zoomed in 2x steps |
| `batch` | Everything listed in a plan file, one run per plate and render |

Each run writes a JSON manifest next to the images (`gallery_export.json`,
`well_overview.json`, `batch.json`). It records the version, the settings, the
seed, the display limits and the outcome for every well, so a panel can be
traced and replayed months later. Add `--json` to also print the manifest:
stdout then carries only the manifest and the logs go to stderr, so the output
can be piped straight into a parser.

`omero-screen-images` is installed with `omero-screen-napari`. Like the other
CLIs it reads the `.env.{name}` configuration; choose it with `--env` before the
command:

```bash
omero-screen-images --env production gallery 5108 --wells G5 --channels DAPI
```

## Where the pixels come from

- **Plates with a zarr cache** (stitched plates cached from the plate-info
  dialog) are read lazily from the cache. Nothing is downloaded.
- **Per-field plates** are loaded through the plate disk cache, downloading from
  OMERO on a miss, one well at a time to bound memory. Overviews are stitched in
  memory from the stage positions with the plate's per-objective stitch
  calibration, as in the welldata widget.
- A stitched plate without a zarr cache is refused: build the cache first.

Galleries also need the plate's measurements in CellView; overviews do not.

## Display limits

Every well of one call shares one set of display limits, so wells rendered
together can be compared side by side. By default these are the
0.1/99.9 percentiles pooled over the requested wells (exact zeros, i.e. canvas
no field covers, are ignored). The same call always gives the same limits,
whatever the order of the wells.

To compare across calls, or to match an earlier figure, fix them with
`--limits CHANNEL=LO:HI` (repeatable). The limits used, and whether each was
given or pooled, are in the manifest.

## Galleries

```bash
# 5x5 DAPI crops of micronucleated cells in two wells
omero-screen-images --env production gallery 5108 --wells E2,G5 \
    --classifier-column classifier_nuclei4 --class micronuclei \
    --channels DAPI --grid 5x5 --seed 1 --out qc/micronuclei
```

- `--channels` packs up to three channels into R, G, B. One channel gives the
  inverted greyscale gallery.
- `--classifier-column` / `--class` keep one class of one classifier column.
  Naming the column avoids the widget's fallback (the first classifier column
  that contains the value).
- `--seed` fixes the draw: the same command reproduces the same gallery, and
  each well draws independently.
- The background around each cell is **kept** by default. `--blank-background`
  blanks everything outside the cell's mask; that hides objects outside the
  mask, such as micronuclei, and makes crops look processed.

### Galleries from an analysis gate

`--cells cells.csv` (or `.parquet`) restricts the draw to cells chosen
downstream, for example EdU-negative 2N cells gated in a CellView analysis. The
table needs `image_id` and `label` (the CellView nucleus label), and optionally
`timepoint`; the wells are taken from the selection when `--wells` is omitted.

```python
gate = df.filter(...)  # a CellView export, filtered in a notebook
gate.select("image_id", "label").write_csv("gate.csv")
```

```bash
omero-screen-images gallery 5108 --cells gate.csv --channels DAPI,EdU --json
```

## Whole-well overviews

```bash
# Every channel of four wells, same contrast for all four
omero-screen-images --env production well 5108 --wells B2,E2,B5,E5 --out qc/wells

# DAPI with nuclei outlines, zoomed 8x into the upper left of the well
omero-screen-images well 5108 --wells G5 --layers DAPI,nuclei_masks \
    --zoom 8 --center 0.3,0.3
```

- `--layers` lists what to draw: channel names plus `nuclei_masks` and
  `cell_masks`, drawn as outlines. The default is every channel and no masks.
- `--zoom 1` is the whole well; each step halves the field of view around
  `--center Y,X` (fractions of the well height and width).
- The image is read at the resolution closest to `--size` (default 2000 px on
  the longer side) and downsampled by averaging, so it is not aliased.
- Channels keep their napari colours whichever subset is drawn. The caption
  carries the plate, well and all the well's metadata.

## Batches

A plan is a CSV with one row per image:

```text
plate_id,well,render
5108,B2,well
5108,G5,well
5108,G5,gallery:micronuclei
5108,E2,gallery:normal
```

`render` is `well`, `gallery`, or `gallery:<class>` (a class of
`--classifier-column`).

```bash
omero-screen-images --env production batch plan.csv \
    --channels DAPI --classifier-column classifier_nuclei4 --out qc/
```

Rows with the same plate and render are rendered together, so they share
display limits, into `qc/<plate>_<render>/` with their own manifest;
`qc/batch.json` lists every run. The options apply to every row. A plate that
fails is recorded in the batch manifest and the rest of the plan still runs.


### omero-train CLI

::: {.callout-note}
The full option detail for every `omero-train` command — flags, defaults,
arguments and types — is generated directly from the code in the
[CLI reference](../reference/cli/index.html). This page covers what the tool is
for and how it is used in practice; go to the generated pages for the exact
switches.
:::

## What this tool does

`omero-train` is a command-line tool that lets you manage your training database, inspect annotation statistics, and export data — without opening Napari. It is useful for:

- Quickly checking how many cells have been labelled for a classifier.
- Exporting annotation data to CSV for downstream analysis or sharing with collaborators.
- Cleaning up classifiers or sessions that are no longer needed.
- Migrating training data created before the database was introduced.

## Installation

`omero-train` is installed automatically as part of `omero-screen-napari`. After installation, it is available in your terminal:

```bash
omero-train --help
```

## Commands overview

| Command | What it does |
|---------|-------------|
| [`list`](../reference/cli/list.html) | Show all classifiers with summary statistics |
| [`stats`](../reference/cli/stats.html) | Show detailed statistics for one classifier |
| [`export`](../reference/cli/export.html) | Export annotations to CSV, JSON, or Parquet |
| [`delete`](../reference/cli/delete.html) | Remove a classifier and its sessions |
| [`migrate`](../reference/cli/migrate.html) | Import existing NPY files into the database (for legacy data) |

---

## `omero-train list`

Lists all classifiers in the training database with a summary table.

```bash
omero-train list
```

**Output columns:**

| Column | Description |
|--------|-------------|
| ID | Internal database ID |
| Name | Classifier name |
| Sessions | Number of annotation sessions |
| Annotations | Total crops labelled |
| Classes | Class names defined for this classifier |
| Created | Date the classifier was first created |

**Example output:**
```
┌────┬─────────────┬──────────┬─────────────┬──────────────────────────────────┐
│ ID │ Name        │ Sessions │ Annotations │ Classes                          │
├────┼─────────────┼──────────┼─────────────┼──────────────────────────────────┤
│  1 │ mitosis-rpe │        4 │         320 │ interphase, mitosis, apoptosis   │
│  2 │ drug-u2os   │        2 │         150 │ normal, stressed                 │
└────┴─────────────┴──────────┴─────────────┴──────────────────────────────────┘
```

---

## `omero-train stats`

Shows detailed statistics for a single classifier, identified by name or database ID.

```bash
omero-train stats <name-or-id>
```

**Examples:**
```bash
omero-train stats mitosis-rpe
omero-train stats 1
```

**Output includes:**
- General info (ID, total sessions, total annotations, classes)
- Class distribution table with counts and percentages
- Per-session breakdown (plate, well, images, timepoint, cell cycle filter, cell count, class distribution)

**Example output:**
```
Classifier: mitosis-rpe
Sessions: 4  |  Total cells: 320  |  Classes: interphase, mitosis, apoptosis

Class Distribution
┌─────────────┬───────┬────────────┐
│ Class       │ Count │ Percentage │
├─────────────┼───────┼────────────┤
│ interphase  │   224 │      70.0% │
│ mitosis     │    80 │      25.0% │
│ apoptosis   │    16 │       5.0% │
│ unassigned  │     0 │       0.0% │
└─────────────┴───────┴────────────┘

Sessions
┌────┬──────────┬──────┬────────┬──────────────┬────────┬───────────────┐
│ ID │ Plate ID │ Well │ Images │ Cell Cycle   │ Cells  │ Distribution  │
├────┼──────────┼──────┼────────┼──────────────┼────────┼───────────────┤
│  1 │     3869 │ E2   │ All    │ All          │     80 │ interph.: 60  │
│  2 │     3869 │ F3   │ 0, 1   │ All          │     80 │ mitosis: 20   │
└────┴──────────┴──────┴────────┴──────────────┴────────┴───────────────┘
```

---

## `omero-train export`

Exports all annotations for a classifier to a file. Useful for sharing data, computing statistics in R or Python, or backing up before deletion.

```bash
omero-train export <name-or-id> [options]
```

You can choose the output format, set the output path, and restrict the export
to a single plate or well — see [`omero-train export`](../reference/cli/export.html)
for the option list and defaults.

**Examples:**

```bash
# Export everything to CSV
omero-train export mitosis-rpe

# Export to JSON with a custom filename
omero-train export mitosis-rpe --format json --output ~/Desktop/mitosis_data.json

# Export only data from plate 3869
omero-train export mitosis-rpe --plate 3869

# Export only well A1 from plate 3869
omero-train export mitosis-rpe --plate 3869 --well A1
```

**Output columns (CSV):**

| Column | Description |
|--------|-------------|
| session_id | Database ID of the session |
| plate_id | OMERO plate ID |
| well | Well position |
| image_id | OMERO image ID |
| timepoint | Timepoint index |
| cell_index | Index of the crop within the session |
| class_label | Assigned class name |
| centroid_row | Row coordinate of the cell centroid in the full image |
| centroid_col | Column coordinate of the cell centroid |

---

## `omero-train delete`

Removes one or more classifiers and all their associated sessions and annotation records. This also deletes the NPY data files from disk.

```bash
omero-train delete <name-or-id> [<name-or-id> ...] [options]
```

You can skip the confirmation prompt, or delete only the sessions belonging to
one plate — see [`omero-train delete`](../reference/cli/delete.html) for the
option list.

**Examples:**

```bash
# Delete a single classifier (will ask for confirmation)
omero-train delete mitosis-rpe

# Delete without confirmation prompt
omero-train delete mitosis-rpe --yes

# Delete only the sessions from plate 3869, keep the classifier and other sessions
omero-train delete mitosis-rpe --plate 3869

# Delete multiple classifiers at once
omero-train delete mitosis-rpe drug-u2os --yes
```

::: {.callout-warning}
**Deletion is permanent.** Export your data first with `omero-train export` if you may need it later.
:::

---

## `omero-train migrate`

Imports existing NPY training data files (created before the database was introduced) into the training database. This is a one-time operation for legacy data.

```bash
omero-train migrate [options]
```

You can point the scan at a different root directory, or preview the import
without writing anything — see [`omero-train migrate`](../reference/cli/migrate.html)
for the option list and defaults.

**Examples:**

```bash
# Preview what would be migrated without making any changes
omero-train migrate --dry-run

# Run the migration from the default location
omero-train migrate

# Run from a custom directory
omero-train migrate --path /data/training_backup
```

The command scans the directory tree for `.npy` files and `metadata.json` files, infers the classifier structure from the folder layout, and creates the corresponding database records.

---

## Where is the database?

The training database is an SQLite file stored at:

```
~/omeroscreen_trainingdata/training_data.db
```

You can open this file with any SQLite browser (e.g. [DB Browser for SQLite](https://sqlitebrowser.org/)) if you want to query the data directly.

---

## Tips

- Run `omero-train list` regularly to get a quick health check on your training data.
- Before deleting anything, always run `omero-train export` first.
- Use `omero-train stats` to check class balance before starting a training run — heavily imbalanced classes (e.g. 95% interphase, 5% mitosis) may need more data for the rare class.
- The `--plate` filter on both `export` and `delete` is useful when one plate's data turned out to be low quality and you want to remove it without losing everything else.