Utilities

Compute the k best one-to-one partial assignments.

Parameters

cost_matrix : array_like, shape (n_rows, n_cols) Matrix containing the cost of assigning each row to each column. Forbidden assignments can be encoded as numpy.inf. k : int, default=1 Number of ranked assignments to return. row_non_assignment_costs : array_like, optional Cost incurred when a row remains unassigned. If omitted, zero cost is used for all rows. col_non_assignment_costs : array_like, optional Cost incurred when a column remains unassigned. If omitted, zero cost is used for all columns.

Returns

list[dict] Ranked assignment solutions in ascending cost order. Each dictionary has the keys assignment (matched column per row or -1), unassigned_rows, unassigned_cols, and cost.

Notes

The implementation follows Murty's partitioning strategy on an augmented square assignment formulation. Branching is performed only over the original rows, which directly yields unique ranked partial assignments.

Build a pairwise feature tensor from named component planes.

All feature planes must have the same shape. Non-finite values are converted to finite sentinels: nan -> 0, +inf -> 1e6, and -inf -> -1e6.

Backward-compatible alias for average NEES.

Return two-sided chi-square bounds for an averaged NEES/NIS statistic.

Alias for :func:chi_square_confidence_bounds.

Return the fraction of scalar values inside [lower, upper].

Return polygon IoU for extended-object shape estimates.

Alias for :func:extent_matrix_error.

Alias for polygon IoU used by extended-object tracking metrics.

Return matrix-norm error between estimated and reference extents.

Return the covariance/extent part of the Gaussian 2-Wasserstein distance.

Return the 2-Wasserstein distance between Gaussian distributions.

Return the generalized OSPA distance between two finite sets.

Return intersection over union for two polygonal shapes.

Return whether a scalar statistic lies inside chi-square bounds.

Alias for :func:is_chi_square_consistent.

Return mean OSPA over a sequence of finite-set estimates.

Return chi-square consistency bounds for NEES or ANEES.

Alias for :func:nees_confidence_bounds.

Return chi-square consistency bounds for NIS or ANIS.

Alias for :func:nis_confidence_bounds.

Return the optimal sub-pattern assignment distance between two finite sets.

Recover globally consistent tracks across multiple sessions.

Parameters

pairwise_costs Either a mapping from (source_session, target_session) to a cost matrix of shape (n_source, n_target), or a sequence of consecutive session-to-session cost matrices. When a sequence is supplied, matrix k is interpreted as the cost matrix for session k to session k + 1. session_sizes Optional per-session detection counts. This is only required when some sessions have no pairwise cost matrix, or when isolated singleton detections should still be represented in the result. A sequence is interpreted as counts for sessions 0, 1, ..., S-1. start_cost Penalty for starting a new track. end_cost Penalty for ending a track. gap_penalty Additional penalty applied per skipped session for non-consecutive edges. This penalty is added on top of the supplied edge cost. cost_threshold Optional upper bound for admissible link costs after gap penalties are applied. Edges with larger costs are forbidden.

Returns

MultiSessionAssignmentResult Globally optimal tracks and the selected directed edges.

Notes

Let N be the total number of observations. If every observation starts as a singleton track, the baseline cost is

N * (start_cost + end_cost).

Adding an admissible edge with adjusted cost c merges two track ends and therefore changes the objective by c - start_cost - end_cost. The implementation maximizes the total gain

start_cost + end_cost - c

subject to at-most-one-predecessor and at-most-one-successor constraints. This is equivalent to the minimum-cost path-cover objective. Internally, the sparse matching problem is reduced to a rectangular assignment in which every source observation can either connect to an admissible successor or to its own dummy "unmatched" column.

Convert explicit tracks to dense per-session label arrays.

Parameters

tracks Sequence of track representations. Each track can either be a mapping from session index to detection index or a sequence of (session_index, detection_index) pairs. session_sizes Optional per-session detection counts. When omitted, sizes are inferred from the maximum detection index present in each session. Missing sessions are represented by empty arrays. fill_value Value used for detections that are not assigned to any track.

Returns

tuple One integer array per session, indexed by session number.

Solve multi-session assignment with per-observation start/end costs.

Score-native wrapper around :func:solve_multisession_assignment.

Track2p-style alias for the score-native wrapper.

Convert tracks to a dense track x session ROI-index matrix.

Estimate a thin-plate-spline transform from matched 2D point pairs.

Parameters

source_points, target_points: Arrays of shape (n_points, 2) describing matched point pairs. regularization: Non-negative ridge penalty applied to the TPS kernel matrix.

Alternating thin-plate-spline registration and one-to-one assignment.

This function alternates between: 1. assigning transformed reference points to moving points using the Hungarian algorithm with optional gating; and 2. refitting a smooth thin-plate-spline warp from the current matches.

Parameters

reference_points: Landmark locations from the reference session, shape (n_ref, 2). moving_points: Landmark locations from the moving/current session, shape (n_moving, 2). initial_transform: Optional starting transform. If omitted, the transform is initialized with a robust median-based translation. max_cost: Optional gating threshold on the association cost. cost_function: Optional callable receiving transformed reference points and moving points and returning a cost matrix of shape (n_ref, n_moving). This allows centroid costs, ROI overlap costs, or morphology-aware hybrid costs to be plugged into the registration loop. max_iterations: Maximum number of alternating assignment/refit iterations. tolerance: Convergence threshold on the change of the transformed reference point set. min_matches: Minimum number of matched pairs required before refitting the TPS warp. regularization: Non-negative ridge penalty for TPS fitting.

Return pairwise covariance shape, scale, and similarity components.

The covariance-shape cost compares trace-normalized covariance matrices with a Frobenius norm. This makes the feature sensitive to orientation and anisotropy while ignoring overall scale. The log-determinant cost measures scale mismatch separately. The shape similarity is exp(-shape_cost).

Parameters

covariances_a, covariances_b: Covariance stacks with shape (dim, dim, n_items). epsilon: Strictly positive floor used for traces and determinants.

Returns

shape_cost, logdet_cost, shape_similarity: Three matrices with shape (n_a, n_b).

Return covariance-normalized distances between two Gaussian stacks.

For a pair of items i and j, the returned value is

sqrt((mu_i - nu_j)^T (Sigma_i + Lambda_j + regularization * I)^+ (mu_i - nu_j)),

where ^+ denotes the Moore-Penrose pseudoinverse. Using the summed covariance makes the feature symmetric in the two uncertain estimates and is the standard normalization for comparing two independent Gaussian position estimates.

Parameters

means_a, means_b: Mean stacks with shape (dim, n_items). covariances_a, covariances_b: Covariance stacks with shape (dim, dim, n_items). The number of covariance matrices must match the corresponding number of means. regularization: Optional non-negative diagonal loading added to every summed covariance before inversion.

Returns

array-like Matrix with shape (n_a, n_b).

Return exact full-track tuples present in every selected session.

Return an object matrix containing integer observation indices or None.

Backward-compatible alias for :func:track_pair_set.

Return the number of predicted fragments covering each reference track.

Score exact complete-track recovery with precision, recall, and F1.

Score predicted forward links that contradict the reference identity map.

Backward-compatible alias for :func:score_track_fragmentation.

Score pairwise links using BayesCaTrack-compatible metric names.

Score fragmentation of reference identities across predicted tracks.

Score pairwise links induced by predicted and reference track matrices.

Return aggregate link, complete-track, fragmentation, and ledger metrics.

Return aggregate track-level error metrics.

Summarize the number and length of tracks.

Return detailed track-, link-, and duplicate-observation error ledgers.

Return the number of present observations in each track row.

Return pairwise track links as (session_a, session_b, obs_a, obs_b).

Return the fraction of evaluated predicted tracks that are false.

Return the fraction of evaluated reference tracks that are missed.

Return metrics for predicted tracks that contain no reference observation.

Return metrics for reference tracks with no predicted observation support.

Return aggregate first-detection latency metrics.

Return fragmentation, purity, false-track, missed-track, and latency metrics.

Return predicted-track identity purity metrics.

A predicted track's purity is the fraction of its observations that belong to its dominant reference identity. Observations absent from the reference matrix count as impure in mean_track_purity and observation_weighted_track_purity.

Return first-detection latency for each non-empty reference track.

Return observation-weighted predicted-track purity.