dataeval.core.TrackStatsResult¶

class dataeval.core.TrackStatsResult¶

Compute per-track statistics for one video sequence.

track_ids¶

Sorted list of track IDs present in the input. track_ids[i] gives the track ID whose stats are at index i in every other sequence field.

Type:¶

Sequence[int]

labels¶

Representative class label for each track, taken as the most frequent per-frame label. A track should be single-class in practice, but the raw per-frame labels may disagree; this reports the majority label so each track has exactly one class for downstream analysis.

Type:¶

Sequence[int]

label_confidence¶

Confidence in each track’s assigned labels entry: the assigned label’s share of total detection score across the track’s observations, sum(scores[labels == label]) / sum(scores). 1.0 for a single-class track; lower when observations disagree. With uniform scores (e.g. ground truth) this is the fraction of frames carrying the label — a purity / label-consistency signal.

Type:¶

Sequence[float]

mean_score¶

Mean detection confidence over the track’s observations. 1.0 for ground-truth tracks whose scores are all 1.0. NaN when scores are absent.

Type:¶

Sequence[float]

n_appearances¶

Number of frames in which the track ID appears. A track present in every frame of a 300-frame video has n_appearances = 300; a track present only in the first and last frames has n_appearances = 2.

Type:¶

Sequence[int]

track_duration¶

Total number of frames between a track’s first and last appearance, inclusive. Equal to n_appearances for contiguous tracks; greater than n_appearances when gaps are present. A track present only in the first and last frames of a 300-frame video has track_duration = 300.

Type:¶

Sequence[int]

n_gaps¶

Number of contiguous gap runs between a track’s first and last appearance. Zero for fully contiguous tracks.

Type:¶

Sequence[int]

total_gap_length¶

Total number of frames between a track’s first and last appearance where the track ID is absent. Equal to track_duration - n_appearances.

Type:¶

Sequence[int]

mean_speed¶

Mean per-frame displacement of the bounding-box center in pixels, computed over consecutive observed frame pairs and normalised by the inter-frame delta so gaps do not inflate the estimate.

Type:¶

Sequence[float]

speed_variance¶

Variance of per-frame center displacement across consecutive observed frame pairs. Zero for single-observation tracks.

Type:¶

Sequence[float]

net_displacement¶

Euclidean distance in pixels between the box center at the first and last observation, regardless of the path taken.

Type:¶

Sequence[float]

straightness_index¶

Ratio of net displacement to total path length (sum of per-step Euclidean distances between consecutive observed centers). Ranges from 0 (maximally tortuous / looping) to 1 (perfectly straight). NaN for single-observation tracks or perfectly stationary tracks (zero path length).

Type:¶

Sequence[float]

jitter_rate¶

Smoothness of the track’s speed profile, computed using SPARC (SPectral ARC length). Unlike the reference paper, the result is not negated, so higher = more jittery. NaN for tracks shorter than jitter_min_frames (default 10). Presented as a rate per track length.

Type:¶

Sequence[float]

entry_at_edge¶

True when the track’s first bounding box touches or crosses the frame border (within edge_threshold pixels on any side). Always False if frame_width / frame_height were not provided.

Type:¶

Sequence[bool]

exit_at_edge¶

True when the track’s last bounding box touches or crosses the frame border (within edge_threshold pixels on any side). Always False if frame_width / frame_height were not provided.

Type:¶

Sequence[bool]

Notes

1. Every sequence field is indexed by position in sorted track ID order, not by track ID directly. Use track_ids[i] to recover the original track ID for position i.

References

Balasubramanian, S., Melendez-Calderon, A., & Burdet, E. (2012). A robust and sensitive metric for quantifying movement smoothness. IEEE Transactions on Biomedical Engineering, 59(8), 2126-2136.

Batschelet, E. (1981). Circular Statistics in Biology. Academic Press.

Benhamou, S. (2004). How to reliably estimate the tortuosity of an animal’s path: straightness, sinuosity, or fractal dimension? Journal of Theoretical Biology, 229(2), 209-220.