HOCT

Inference and tracking for the Higher-Order Cell Tracking Transformer (HOCT) model with JIT-compiled models.

Documentation

Read the documentation site for installation, tracking workflows, incremental correction, and the Python API reference. The documentation source and incremental correction guide are also available in this repository.

Quick start (for biologists)

If all you want is to track cells from images and segmentation masks, you do not need to write any Python. The steps below take you from "nothing installed" to "a tracking result on disk" in about a minute.

1. Install uv (one-time)

uv is a small Python launcher. It downloads everything else automatically.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close and reopen your terminal so uv is on your PATH. Verify:

uv --version

2. Run tracking

uvx runs the CLI in a temporary, isolated environment — nothing is installed permanently and there is no virtual environment to manage:

uvx --from "hoct[bioio]" hoct track \
    <IMAGES> <SEGMENTATION> \
    -o <OUTPUT.geff>

• <IMAGES>: a single image file (whole time series) or a folder of single-frame files sorted alphabetically.
• <SEGMENTATION>: same format as <IMAGES> (file with file, folder with folder), with one integer label per object.
• <OUTPUT.geff>: where to write the result. Default is a folder in the GEFF format. Pass -f ctc to instead write a Cell Tracking Challenge folder of per-frame label TIFFs plus res_track.txt.

No model is specified above, so HOCT downloads the default pre-trained model (general_v1) and caches it; later runs reuse the cache. To use the model trained for Cell Tracking Challenge data, pass -m ctc_v0; to use your own checkpoint, pass -m /path/to/model.pt. Set HOCT_CACHE_DIR to change where downloads are cached.

The first run also downloads the Python dependencies; later runs start almost instantly.

Example: a CTC dataset

uvx --from "hoct[bioio]" hoct track \
    /data/Fluo-C3DL-MDA231/01 \
    /data/Fluo-C3DL-MDA231/01_ERR_SEG \
    -o tracks.geff

This loads 12 frames of 3D images and segmentation masks, builds the candidate graph, runs the model on the GPU (falling back to CPU if none is available), solves the tracking ILP, and writes tracks.geff/.

To benchmark against the Cell Tracking Challenge ground truth, write the result directly in CTC format:

uvx --from "hoct[bioio]" hoct track \
    /data/Fluo-C3DL-MDA231/01 \
    /data/Fluo-C3DL-MDA231/01_ERR_SEG \
    -o /data/Fluo-C3DL-MDA231/01_RES \
    -f ctc

This produces the standard CTC layout (maskNNN.tif per timepoint plus res_track.txt).

Useful flags

Run uvx --from "hoct[bioio]" hoct track --help for the full list.

Customising the solver

Generate a template config you can edit and pass with -c:

uvx --from hoct hoct init-config -o solver_config.yaml
# ...edit the file...
uvx --from "hoct[bioio]" hoct track ... -c solver_config.yaml

Tracking from an existing GEFF

If you already have a candidate graph in GEFF form (e.g. produced by hoct.features.create_graph), use predict instead of track. Pass -s to write just the tracking solution; omit it to keep the full candidate graph with predicted scores:

uvx --from hoct hoct predict candidate.geff -s -o tracks.geff

Installation

pip install "hoct[bioio]"

The bioio extra is needed for the track CLI (reading image/label files).

Installation (for developers)

git clone https://github.com/royerlab/hoct
cd hoct
uv sync --extra dev --extra bioio

Test data

Most of the suite runs on tiny synthetic inputs. The data/tracking tests need candidate-graph GEFF fixtures built from two small Cell Tracking Challenge training sets; they are skipped until you build them:

uv run python scripts/prepare_test_data.py

This downloads the datasets into .test-data/ (gitignored) and writes the GEFF fixtures. To use existing graphs instead, point HOCT_TEST_GEFF_2D / HOCT_TEST_GEFF_3D at them.

Python API

import numpy as np
from hoct import load_model, predict

# Downloads and caches the default pre-trained model on first use. Pass a name
# (see hoct.available_models()) or a local .pt path to use a different one.
model = load_model(device="cuda")

# labels: (T, Y, X) or (T, Z, Y, X) integer array; images: same shape (optional)
labels = np.load("labels.npy")
images = np.load("images.npy")

solution_graph = predict(model, labels=labels, images=images)
solution_graph.to_geff("tracks.geff")

See hoct.predict for the full signature (custom solver config, tiled inference, test-time augmentation, etc.).

Incremental correction demo

Review candidate links, fine-tune a linear head on frozen HOCT embeddings, and refresh tracking after each annotation batch:

uv run --extra demo python examples/incremental_fine_tuning.py /data/Fluo-C2DL-Huh7

The demo loads a local CTC sequence lazily with Dask and provides a Napari viewer for tracks and interactive link correction.

Read the incremental correction and fine-tuning documentation for installation, CTC data preparation, Napari keyboard controls, GEFF outputs, and examples of adapting the correction session to your own interface and UI loop. The guide also explains how the demo relates to the paper's correction protocol.

Pre-trained models

load_model() (and the CLI without -m) fetch a JIT-compiled checkpoint from the project's GitHub releases, verify its SHA256, and cache it under the OS cache directory (override with HOCT_CACHE_DIR). List the available names with hoct.available_models(). The registered models are:

• general_v1 — the default model for general datasets;
• ctc_v0 — the model trained for Cell Tracking Challenge datasets;
• general_v0 — the previous general model, retained for reproducibility.

Select one by passing its name to load_model() or to the CLI's --model / -m option. The registry lives in src/hoct/_models.py.

Publishing new weights (maintainers)

1. Create a GitHub release with a new weights tag (e.g. weights-v2) and upload the .pt asset.
2. Compute its hash: shasum -a 256 model.pt.
3. Add an entry to MODELS in src/hoct/_models.py with the tagged release asset URL and hash, and bump DEFAULT_MODEL if it should become the default.

Development

# Run tests
pytest

# Run linting
ruff check .

# Format code
ruff format .

# Preview or build the documentation (no tracking dependencies needed)
uv run --only-group docs mkdocs serve
uv run --only-group docs mkdocs build --strict

Citing

@article{bragantini2026higher,
  title={Higher-Order Cell Tracking Transformer},
  author={Bragantini, Jord{\~a}o and Theodoro, Ilan and Royer, Lo{\"\i}c A},
  journal={arXiv preprint arXiv:2607.11754},
  year={2026}
}