API reference

These entries are generated from the source docstrings. Start with tracking for a complete workflow or incremental correction for a UI integration example.

Models and prediction

hoct.load_model

load_model(model=None, *, device='cpu')

Load a JIT-compiled HOCT model, downloading it on demand.

Parameters:

Name	Type	Description	Default
model	str | PathLike | None	Model specification, forwarded to :func:resolve_model.	None
device	str	Device to map the model onto (e.g. "cuda", "mps", "cpu").	'cpu'

Returns:

Type	Description
ScriptModule	The model in eval mode on device.

hoct.available_models

available_models()

Return the names of the registered pre-trained models.

hoct.predict

predict(model, *, graph=None, labels=None, images=None, solver_config=None, distance_threshold=300.0, n_neighbors=5, max_delta_t=3, scale=None, window_size=5, tiling_scheme=None, test_time_augs=0, return_solution=True)

Run end-to-end cell tracking prediction from raw data.

This is the main high-level API for HOCT inference. It takes raw segmentation labels (and optionally intensity images), creates a candidate tracking graph, runs the neural network to predict edge probabilities and orphan probabilities, and solves the tracking problem using ILP optimization.

Parameters:

Name	Type	Description	Default
model	EdgeModel	Trained HOCT edge prediction model (PyTorch JIT or regular model).	required
graph	BaseGraph | None	Graph with features ready for prediction.	None
labels	ArrayLike | None	Segmentation labels of shape (T, [Z,] Y, X)	None
images	ArrayLike | None	Optional intensity images of shape (T, [Z,] Y, X).	None
solver_config	ILPSolverConfig | None	Configuration for the ILP tracking solver. If None, uses defaults.	None
distance_threshold	float	Maximum distance for creating candidate edges.	300.0
n_neighbors	int	Maximum number of neighbors to connect per node.	5
max_delta_t	int	Maximum temporal gap for edges.	3
scale	tuple[float, ...] | None	Physical spacing (t, [z,] y, x). If None, uses isotropic spacing. If provided distance_threshold is in physical units and features are scaled to physical units.	None
window_size	int	Temporal window size for the frame dataset. Only used if tiling_scheme is None.	5
tiling_scheme	TilingScheme | None	Optional tiling scheme for spatially tiled inference. If provided, uses TiledRoiDataset instead of FrameDataset. Useful for large volumes that don't fit in memory.	None
test_time_augs	int	Number of test time augmentations to apply. If 0, no augmentations are applied. If > 0, a random augmentation is applied for each augmentation.	0
return_solution	bool	Whether to return the solution graph or not.	True

Returns:

Type	Description
InMemoryGraph	Solved tracking graph with 'solution' attributes on nodes and edges. Nodes and edges with solution=True form the final tracking result.

Examples:

>>> import torch
>>> import numpy as np
>>> from hoct import predict
>>> from hoct.tracking import ILPSolverConfig
>>>
>>> # Load model
>>> model = torch.jit.load("hoct_model.pt")
>>>
>>> # Create synthetic labels
>>> labels = np.random.randint(0, 20, size=(10, 256, 256))
>>>
>>> # Run prediction with default settings
>>> graph = predict(model, labels=labels)
>>>
>>> # Access solution
>>> solution_nodes = graph.node_attrs(["solution"])
>>> solution_edges = graph.edge_attrs(["solution"])
>>>
>>> # Run with custom solver config
>>> config = ILPSolverConfig(
...     appearance_weight=2.0,
...     division_weight=1e6,  # disable divisions
...     delta_t_weight=0.5,
... )
>>> graph = predict(model, labels=labels, solver_config=config)

Notes

This function performs the following steps: 1. Creates candidate tracking graph from labels using hoct.features.create_graph 2. Creates dataset (FrameDataset or TiledRoiDataset depending on tiling_scheme) 3. Runs model inference to predict edge similarities and orphan probabilities 4. Solves tracking using ILP optimization 5. Returns graph with solution attributes

When tiling_scheme is provided, the function uses TiledRoiDataset for spatially tiled inference, which is useful for large volumes that cannot fit in GPU memory at once.

Candidate graph

hoct.features.create_graph

create_graph(labels, *, distance_threshold, n_neighbors, delta_t, scale=None, images=None, normalize_images=True, normalize_kwargs=None, gt_graph=None, out_graph=None)

Creates a graph from segmentation labels and optional intensity images.

This function supports both training (with ground truth) and inference (without ground truth) modes.

Parameters:

Name	Type	Description	Default
labels	ArrayLike	Segmentation labels of shape (T, [Z,] Y, X) where T is time.	required
distance_threshold	float	Maximum distance for creating candidate edges.	200.0
n_neighbors	int	Number of nearest neighbors to connect per node.	required
delta_t	float	Maximum temporal gap for edges.	required
scale	tuple[float, ...]	Physical spacing (t, [z,] y, x). If None, inferred from data dimensions.	None
images	ArrayLike | None	Optional intensity images of shape (T, [Z,] Y, X). If None, only geometric features are computed.	None
normalize_images	bool	If True and images is provided, normalize each time point with :func:hoct.features.normalize_image before extracting intensity features. Has no effect when images is None.	True
normalize_kwargs	dict[str, Any] | None	Keyword arguments forwarded to :func:hoct.features.normalize_image (e.g. clip, uq). Defaults to an empty dict.	None
gt_graph	BaseGraph | None	Optional ground truth graph for training. If provided, adds ground truth edge labels. If None (inference mode), skips ground truth-related features.	None
out_graph	BaseGraph | None	Optional output graph to write to, modified in place if provided. If None, a new in-memory graph is created.	None

Returns:

Type	Description
InMemoryGraph	The candidate tracking graph with nodes and edges. If gt_graph provided, includes ground truth edge labels.

Notes

• For 2D+t data (T, Y, X), automatically adds a singleton Z dimension
• Scale is inferred as (1, 1, 1, 1) if not provided
• Ground truth features are only added if gt_graph is provided

Solver configuration

Use ILPSolverConfig.default() to obtain the package's current tracking defaults. When constructing a configuration directly, supply all required weight fields and tracklet_solver.

hoct.tracking.ILPSolverConfig

Bases: BaseModel

Configuration for the ILP tracking solver.

Use ILPSolverConfig.default() for the package's tracking defaults. Direct construction requires all weight fields and tracklet_solver.

Attributes:

Name	Type	Description
appearance_weight	float | Attr	Cost weight for appearances, modulated by predicted orphan probability.
disappearance_weight	float | Attr	Cost weight for cells disappearing before the last frame.
division_weight	float | Attr	Cost weight for divisions. A large positive value discourages divisions.
node_weight	float | Attr	Node-selection cost. Negative values encourage including detections.
delta_t_weight	float | Attr	Decay applied to link weights as the temporal gap grows.
edge_bias	float | Attr	Added to negative similarity when computing edge cost. Positive values increase link costs.
timeout	float	Maximum solver time in seconds. Direct-construction default is 600.
tracklet_solver	bool	Enable two-pass solving: form tracklets, then link those tracklets.

Examples:

>>> config = ILPSolverConfig.default()
>>> # Keep the remaining defaults and discourage divisions.
>>> config = config.model_copy(update={"division_weight": 1e6})

default classmethod

default()

Correction

hoct.correction.label_edge

label_edge(graph, source_id, target_id, attr_key, value)

Set the label of an edge in the graph.

When value is True, the chosen edge is marked True and all other edges sharing the same target node are marked False (mutual exclusion). When value is False, only the specified edge is marked False.

Parameters:

Name	Type	Description	Default
graph	BaseGraph	The graph to update.	required
source_id	int	The source node id of the edge to label.	required
target_id	int	The target node id of the edge to label.	required
attr_key	str	The edge attribute key to write the label into.	required
value	bool	The label value.	required

hoct.correction.fit_from_labels

fit_from_labels(graph, model, label_mask_key, label_key, tiling_scheme=None, window_size=5, test_time_augs=5, n_steps=500, lr=0.1, l2_weight=1.0, consistency_weight=0.25)

Fit a linear probe from sparse edge corrections and return an adapted model.

Extracts backbone features for labeled edges, fits a logistic regression head via full-batch L-BFGS and returns a ProbedModel wrapping the original backbone. The head is always initialised from the backbone's own head layer (no warm-start across rounds).

Two regularization terms prevent the probe from disrupting the global solution:

• Adaptive L2 (l2_weight): penalizes large head weights, scaled inversely with the number of labeled edges so that early rounds are strongly regularized.
• Consistency loss (consistency_weight): anchors the probe's predictions on unlabeled edges to the current ILP solution (0/1), preventing local corrections from propagating destructively across the rest of the graph. Scaled the same way.

Parameters:

Name	Type	Description	Default
graph	BaseGraph	The graph containing labeled edges.	required
model	EdgeModel	The pretrained backbone model (or a ProbedModel from a previous round).	required
label_mask_key	str	Edge attribute key whose boolean values indicate which edges are labeled.	required
label_key	str	Edge attribute key holding the label values (True = correct edge).	required
tiling_scheme	TilingScheme | None	Spatial tiling scheme; if None, uses temporal windowing.	None
window_size	int	Temporal window size when not tiling.	5
test_time_augs	int	Number of test-time augmentations.	5
n_steps	int	Maximum number of L-BFGS iterations (full-batch).	500
lr	float	L-BFGS learning rate.	0.1
l2_weight	float	L2 regularization weight on head.weight (not bias). Effective weight is scaled as l2_weight x n_features / n_labels. Default: 1.0.	1.0
consistency_weight	float	Weight on the ILP-consistency loss for unlabeled edges. Effective weight is scaled as consistency_weight x n_features / n_labels. Default: 0.25.	0.25

Returns:

Type	Description
ProbedModel	The backbone with a fitted linear probe as its classification head.

hoct.correction.ProbedModel

Bases: EdgeModel

EdgeModel with a learned linear probe replacing the original classification head.

The backbone is kept frozen; only the linear head is trained from user corrections.

Parameters:

Name	Type	Description	Default
edge_model	EdgeModel	The pretrained backbone model.	required
coeffs	ndarray	Linear head weight coefficients; any shape is accepted (raveled to 1D).	required
bias	float	Logistic regression intercept (scalar).	required