spacr.timeflows_validation

Shared supplied-mask linking scores and held-out checks for Timeflows training.

These measurements condition on the provided segmentation and track labels. They do not measure end-to-end segmentation or whole-movie tracking accuracy.

Functions

check_pair_holdout(training_pairs, validation_pairs)	Reject validation frames identical to any normalized training input.
score_pair(labels_t, labels_t1, predictions[, seed, ...])	Score source objects after excluding explicitly unknown successors.
scramble(labels, seed)	Relabel target objects without changing their shapes or positions.
summarise(rows)	Aggregate object-weighted results with explicit missing-data denominators.
temporal_assignment_policy()	Describe the default decoder used by both validation entry points.
validate_timeflows(net, pairs, *[, device, seed, ...])	Score held-out pairs and controls without changing training state.

Module Contents

spacr.timeflows_validation.check_pair_holdout(training_pairs, validation_pairs)

Reject validation frames identical to any normalized training input.

Both endpoints participate. Channel filling, channel truncation and float32 conversion follow the model’s own input adapter. This detects identical inputs across paths or dtypes, not near-duplicates or different frames of the same biological movie; the CLI separately rejects shared movie paths. Return the validation input fingerprints for provenance.

Parameters:

• training_pairs – pairs whose input frames participate in training.

• validation_pairs – nonempty held-out pairs with both input endpoints.

Returns:

two normalized-input SHA-256 fingerprints per validation pair.

Raises:

ValueError – validation is empty or an input also occurs in training.

spacr.timeflows_validation.score_pair(labels_t, labels_t1, predictions, seed=0, unknown_successors=())

Score source objects after excluding explicitly unknown successors.

Shared track identities define the true links before target identities are shuffled. An absent target identity means no successor unless the source is in unknown_successors; missing annotations are not detected automatically. An IoU control is added to the supplied prediction arms.

Parameters:

• labels_t – source masks with positive track identities and zero background.

• labels_t1 – target masks using the same track identities.

• predictions – named prediction dictionaries accepted by spacr.timeflows_model.link_by_timeflows(); iou is reserved.

• seed – seed for shuffling target identities.

• unknown_successors – source identities omitted from every score.

Returns:

per-object truth, predictions, correctness and motion/density strata.

spacr.timeflows_validation.scramble(labels, seed)

Relabel target objects without changing their shapes or positions.

Parameters:

• labels – target label array, with zero reserved for background.

• seed – random seed for permuting the nonzero identities.

Returns:

the relabelled array and original-to-shuffled identity mapping.

spacr.timeflows_validation.summarise(rows)

Aggregate object-weighted results with explicit missing-data denominators.

Parameters:

rows – per-object records from score_pair().

Returns:

overall, motion, density and joint-stratum summaries. Successor accuracy is None where no true successors are available; false links and abstentions are counts with their population sizes retained.

spacr.timeflows_validation.temporal_assignment_policy()

Describe the default decoder used by both validation entry points.

spacr.timeflows_validation.validate_timeflows(net, pairs, *, device='cpu', seed=0, initial_head=None)

Score held-out pairs and controls without changing training state.

pairs contain normalized frames and full track-label masks. Call check_pair_holdout() before training to verify exact input separation. The result includes per-object rows and displacement/density strata for the current model, IoU, zero-motion and oracle controls, plus a copied-frame check. Optional initial_head is a complete snapshot of the head/up parameters and buffers from training start. It is called initial_head because a resumed model’s initial head is not necessarily untrained.

Module training/evaluation modes, current head weights and CPU/selected CUDA random states are restored even if scoring raises. No optimizer is touched. The returned scores concern supplied masks, not segmentation performance, lineage or whole-movie tracking.

Parameters:

• net – Timeflows network evaluated in its current state.

• pairs – nonempty full-frame pairs with matching track identities.

• device – device used for inference and random-state preservation.

• seed – starting seed for target-identity shuffles, incremented per pair.

• initial_head – optional complete head/up parameter and buffer snapshot.

Returns:

per-object rows, stratified summaries, copied-frame controls and temporal assignment metadata.

Raises:

ValueError – pairs are empty or the initial-head keys or shapes differ.

Nested helpers

summarise.group(selected)

Summarize correct successor links and abstentions for the selected ground-truth objects.

spacr/timeflows_validation.py:99