Utilities

Convert explicit tracks to dense per-session label arrays.

Compute the cheapest assignment among maximum-cardinality matchings.

Compute the k best one-to-one 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.

Return a boolean candidate mask for a pairwise association matrix.

Normalize optional pruning config inputs.

Replace pruned candidate entries by a large finite cost.

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.

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).

Enumerate candidate prefix/suffix completions for incomplete track rows.

Parameters

track_matrix: Matrix-like object with rows as tracks and columns as sessions. Missing values are parsed by :func:pyrecest.utils.normalize_track_matrix. max_path_length: Maximum number of candidate edges per emitted path. direction: Which fragment endpoints to complete. "suffix" extends after the last observation in a row, "prefix" extends before the first observation, and "both" does both. candidate_provider: Callback candidate_provider(anchor_session, anchor_observation, candidate_session) returning observations in candidate_session. For suffix completion the candidate session is after the anchor; for prefix completion it is before the anchor. Returned values may be raw integer observation ids or :class:CompletionCandidate objects. candidate_session_provider: Optional callback returning candidate session indices for an endpoint. If omitted, only the adjacent previous/next session is considered. allow_duplicate_source / allow_duplicate_target: Whether paths may reuse already-occupied observations. In ordinary track completion both should remain false. score_path: Optional aggregate scorer for a tuple of chronological steps. If omitted, path scores are the sum of step scores. max_paths_per_fragment: Optional post-enumeration cap per endpoint, keeping the lowest-score paths first. This is intended for diagnostics and small candidate sets; high-branching production trackers should pre-prune in the provider.

Return occupancy counts keyed by (session, observation).

Return chronological observation ids in a completion path.

Return chronological session indices in a completion path.

Apply edit to track_matrix and return the edited matrix.

Missing observations are represented as None in the returned matrix. Callers that use integer -1 sentinels can convert the result after the edit, while scoring functions in this module can consume it directly.

Return independent edits sorted by complete-track then pairwise F1 gain.

Score the metric delta produced by one edit.

By default, pairwise and complete tracks are scored as identity sets, matching PyRecEst's generic track-evaluation helpers. Set count_duplicates=True for benchmark protocols where duplicate predicted rows or links should count as false positives.

Score a collection of independent one-edit what-ifs.

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.