itasc.tracking_ultrack.validation_state

Persistent validation metadata for the nucleus workflow.

All functions take nucleus_dir — the directory that holds the nucleus annotation store (validated_frames.json, validated_cells.json, corrections.json). In the full orchestrator this is <pos>/2_nucleus; the standalone tracking piece points it at a flat working directory. The annotation files live directly in that directory.

Frame-level validation (validated_frames.json):

A “fully-validated” frame is one where every current (non-zero) cell ID has been individually validated. The file acts as a cache so UI counters can count fully-validated frames without scanning the whole stack.

Schema: JSON array of ints, e.g. [0, 3, 7].

Track-level validation (validated_cells.json):

Tracks which frames have been validated for each cell (track) ID.

Schema: JSON object keyed by cell ID string, value is a list of frame ints, e.g. {“47”: [10, 11, 12], “82”: [3, 4, 5]}. Cell IDs with no validated frames are omitted entirely (sparse).

Functions

add_anchor(nucleus_dir, cell_id, t, y, x, ...)	Add an anchor for cell_id at frame t and back-fill intermediate frames.
add_correction(nucleus_dir, correction)	Add or replace a correction for the same cell, frame, and kind.
add_corrections(nucleus_dir, corrections)	Add or replace several corrections with a single read+write.
invalidate_frame(nucleus_dir, t)	Remove the validated mark from frame t.
invalidate_track(nucleus_dir, cell_id)	Remove the entire entry for cell_id from the validated-tracks store.
is_track_validated(nucleus_dir, cell_id)	Return True if cell_id has any entry in the validated-tracks store.
is_validated(nucleus_dir, t)	Return True if frame t is in the validated set.
read_corrections(nucleus_dir)	Return persisted per-frame corrections, or an empty list if unavailable.
read_validated_cells_at_frame(nucleus_dir, t)	Return all cell IDs that have frame t in their validated set.
read_validated_frames(nucleus_dir)	Return the set of validated frame indices, or an empty set if none.
read_validated_tracks(nucleus_dir)	Return {cell_id: {frames}} for all validated tracks.
remap_validated_tracks(nucleus_dir, old_to_new)	Remap cell IDs in the validated-tracks store using old_to_new mapping.
validate_frame(nucleus_dir, t)	Mark frame t as validated.
validate_track(nucleus_dir, cell_id, frames)	Add the given frames to cell_id's validated set (idempotent, accumulates).
write_corrections(nucleus_dir, corrections)	Persist the full flat correction list to corrections.json.
write_validated_frames(nucleus_dir, frames)	Persist the full set of validated frames.

itasc.tracking_ultrack.validation_state.read_validated_frames(nucleus_dir)

Return the set of validated frame indices, or an empty set if none.

Return type:

set[int]

Parameters:

nucleus_dir (Path)

itasc.tracking_ultrack.validation_state.write_validated_frames(nucleus_dir, frames)

Persist the full set of validated frames.

Return type:

None

Parameters:

• nucleus_dir (Path)

• frames (set[int])

itasc.tracking_ultrack.validation_state.validate_frame(nucleus_dir, t)

Mark frame t as validated.

Return type:

None

Parameters:

• nucleus_dir (Path)

• t (int)

itasc.tracking_ultrack.validation_state.invalidate_frame(nucleus_dir, t)

Remove the validated mark from frame t.

Return type:

None

Parameters:

• nucleus_dir (Path)

• t (int)

itasc.tracking_ultrack.validation_state.is_validated(nucleus_dir, t)

Return True if frame t is in the validated set.

Return type:

bool

Parameters:

• nucleus_dir (Path)

• t (int)

itasc.tracking_ultrack.validation_state.read_validated_tracks(nucleus_dir)

Return {cell_id: {frames}} for all validated tracks.

Empty dict if the file is missing or corrupt. JSON keys are cell ID strings; values are lists of frame ints.

Return type:

dict[int, set[int]]

Parameters:

nucleus_dir (Path)

itasc.tracking_ultrack.validation_state.read_validated_cells_at_frame(nucleus_dir, t)

Return all cell IDs that have frame t in their validated set.

Derived from the track-keyed store; suitable for overlay rendering.

Return type:

set[int]

Parameters:

• nucleus_dir (Path)

• t (int)

itasc.tracking_ultrack.validation_state.is_track_validated(nucleus_dir, cell_id)

Return True if cell_id has any entry in the validated-tracks store.

Return type:

bool

Parameters:

• nucleus_dir (Path)

• cell_id (int)

itasc.tracking_ultrack.validation_state.validate_track(nucleus_dir, cell_id, frames)

Add the given frames to cell_id’s validated set (idempotent, accumulates).

Creates an entry for cell_id if none exists yet. Any existing per-frame anchor corrections for the same cell are dropped — whole-track validation supersedes them (the post-solve paste-back stamps the validated geometry, so anchor pins on the same cell are redundant).

Return type:

None

Parameters:

• nucleus_dir (Path)

• cell_id (int)

• frames (Iterable[int])

itasc.tracking_ultrack.validation_state.invalidate_track(nucleus_dir, cell_id)

Remove the entire entry for cell_id from the validated-tracks store.

No-op if cell_id is not present.

Return type:

None

Parameters:

• nucleus_dir (Path)

• cell_id (int)

itasc.tracking_ultrack.validation_state.remap_validated_tracks(nucleus_dir, old_to_new)

Remap cell IDs in the validated-tracks store using old_to_new mapping.

IDs not present in the mapping are dropped.

Return type:

None

Parameters:

• nucleus_dir (Path)

• old_to_new (dict[int, int])

itasc.tracking_ultrack.validation_state.read_corrections(nucleus_dir)

Return persisted per-frame corrections, or an empty list if unavailable.

Return type:

list[Correction]

Parameters:

nucleus_dir (Path)

itasc.tracking_ultrack.validation_state.write_corrections(nucleus_dir, corrections)

Persist the full flat correction list to corrections.json.

Return type:

None

Parameters:

• nucleus_dir (Path)

• corrections (Iterable[Correction])

itasc.tracking_ultrack.validation_state.add_correction(nucleus_dir, correction)

Add or replace a correction for the same cell, frame, and kind.

Writing a validated correction for a cell additionally drops every anchor correction for that cell — validation is whole-track and supersedes any anchor pinning on the same cell.

Return type:

None

Parameters:

• nucleus_dir (Path)

• correction (Correction)

itasc.tracking_ultrack.validation_state.add_corrections(nucleus_dir, corrections)

Add or replace several corrections with a single read+write.

Each correction replaces any existing one for the same cell, frame, and kind (later entries in corrections win over earlier ones). As with add_correction(), a validated correction for a cell additionally drops every anchor correction for that cell.

Unlike calling add_correction() in a loop, this reads and writes corrections.json exactly once, so validating a long track stays cheap instead of re-parsing and re-serialising the whole file per frame.

Return type:

None

Parameters:

• nucleus_dir (Path)

• corrections (Iterable[Correction])

itasc.tracking_ultrack.validation_state.add_anchor(nucleus_dir, cell_id, t, y, x, tracked_labels)

Add an anchor for cell_id at frame t and back-fill intermediate frames.

If another anchor for the same cell already exists at some frame A, find the nearest such A (smallest |A - t|). If cell_id is present in tracked_labels at every frame in [min(A, t), max(A, t)], add an anchor correction for each intermediate frame using the cell’s centroid in tracked_labels at that frame.

Returns the number of intermediate anchors added (0 if no neighbor exists or the track is not consecutive).

The strictness rule guarantees we never anchor onto a frame where the cell isn’t actually present in the corrected layer.

Return type:

int

Parameters:

• nucleus_dir (Path)

• cell_id (int)

• t (int)

• y (float)

• x (float)

• tracked_labels (ndarray)