traccuracy.matchers

Subpackage for matching ground truth and prediction tracks

This subpackage contains functions that match nodes and edges of a ground truth and predicted tracking solution.

Each matching function has the following spec:

param ground_truth:

The ground truth or reference tracking solution

type ground_truth:

TrackingGraph

param prediction:

A generated tracking solution to be compared with the ground truth

type prediction:

TrackingGraph

returns:

A list of pairs of node_ids. The first node_id refers to a node in ground_truth, and the second node_id refers to a node in prediction. There is no restriction on how many matches a ground truth or prediction node can be a part of, although there are helper functions to check if you wish to enforce a one-to-one, one-to-many, or many-to-one relationship.

rtype:

list[(gt_node_id, pred_node_id)]

It is assumed that edges are matched if and only if both endpoints are matched. For example, if (gt_1, pred_1) and (gt_2, pred_2) are in the list of matched nodes, and edges (gt_1, gt_2) and (pred_1, pred_2) exist, they are also considered matched.

While we specify ground truth and prediction, it is possible to write a matching function that matches two arbitrary tracking solutions.

Package Contents

Classes

CTCMatcher

Match graph nodes based on measure used in cell tracking challenge benchmarking.

IOUMatcher

Constructs a mapping between gt and pred nodes using the IoU of the segmentations

Matched

Data class storing gt graph, pred graph, computed mapping, and matcher info.

PointMatcher

A one-to-one matcher that uses Hungarian matching to minimize global

PointSegMatcher

A matcher that constructs a mapping from a set of points to a segmentation

Functions

get_labels_with_overlap(→ list[tuple[int, int, float]])

Get all labels IDs in gt_frame and res_frame whose bounding boxes overlap,
traccuracy.matchers.get_labels_with_overlap(gt_frame: numpy.ndarray, res_frame: numpy.ndarray, gt_boxes: numpy.ndarray | None = None, res_boxes: numpy.ndarray | None = None, gt_labels: numpy.ndarray | None = None, res_labels: numpy.ndarray | None = None, overlap: str = 'iou') → list[tuple[int, int, float]][source]

Get all labels IDs in gt_frame and res_frame whose bounding boxes overlap, and a metric of pixel overlap (either iou or iogt).

Parameters:

  • gt_frame (np.ndarray) – ground truth segmentation for a single frame

  • res_frame (np.ndarray) – result segmentation for a given frame

  • gt_boxes (np.ndarray) – ground truth bounding boxes for a single frame

  • res_boxes (np.ndarray) – result bounding boxes for a given frame

  • gt_labels (np.ndarray) – ground truth labels for a single frame

  • res_labels (np.ndarray) – result labels for a given frame

  • overlap (str, optional) – Choose between intersection-over-ground-truth (iogt) or intersection-over-union (iou). Defaults to iou.

Returns: list[tuple[int, int, float]] A list of tuples of overlapping labels and their

overlap values. Each tuple contains (gt_label, res_label, overlap_value).

class traccuracy.matchers.CTCMatcher[source]

Match graph nodes based on measure used in cell tracking challenge benchmarking.

A computed marker (segmentation) is matched to a reference marker if the computed marker covers a majority of the reference marker.

Each reference marker can therefore only be matched to one computed marker, but multiple reference markers can be assigned to a single computed marker.

See https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0144959 for complete details.

property info: dict[str, Any]

Dictionary of Matcher name and any parameters

compute_mapping(gt_graph: traccuracy._tracking_graph.TrackingGraph, pred_graph: traccuracy._tracking_graph.TrackingGraph) → traccuracy.matchers._matched.Matched

Run the matching on a given set of gt and pred TrackingGraph and returns a Matched object with a new copy of each TrackingGraph

Parameters:
Returns:

Matched data object

Return type:

matched (traccuracy.matchers.Matched)

Raises:

ValueError – gt and pred must be a TrackingGraph object

class traccuracy.matchers.IOUMatcher(iou_threshold: float = 0.6, one_to_one: bool = False)[source]

Constructs a mapping between gt and pred nodes using the IoU of the segmentations

Lower values for iou_threshold will be more permissive of imperfect matches

Parameters:

  • iou_threshold (float, optional) – Minimum IoU value to assign a match. Defaults to 0.6.

  • one_to_one (optional, bool) – If True, forces the mapping to be one-to-one by running linear assignment on the thresholded iou array. Default False.

property info: dict[str, Any]

Dictionary of Matcher name and any parameters

compute_mapping(gt_graph: traccuracy._tracking_graph.TrackingGraph, pred_graph: traccuracy._tracking_graph.TrackingGraph) → traccuracy.matchers._matched.Matched

Run the matching on a given set of gt and pred TrackingGraph and returns a Matched object with a new copy of each TrackingGraph

Parameters:
Returns:

Matched data object

Return type:

matched (traccuracy.matchers.Matched)

Raises:

ValueError – gt and pred must be a TrackingGraph object

class traccuracy.matchers.Matched(gt_graph: traccuracy._tracking_graph.TrackingGraph, pred_graph: traccuracy._tracking_graph.TrackingGraph, mapping: list[tuple[Any, Any]], matcher_info: dict)[source]

Data class storing gt graph, pred graph, computed mapping, and matcher info.

The computed mapping type (e.g. one-to-one) is computed in the matched object.

Variables:

  • gt_pred_map – A dictionary from gt node to list of matched pred nodes

  • pred_gt_map – A dictionary from pred node to list of matched gt nodes

Parameters:

  • gt_graph (traccuracy.TrackingGraph) – Tracking graph object for the gt

  • pred_graph (traccuracy.TrackingGraph) – Tracking graph object for the pred

  • mapping (list[tuple[Any, Any]]) – List of tuples where each tuple maps a gt node to a pred node

  • matcher_info (dict) – Dictionary containing name and parameters from the matcher that generated the mapping

property matching_type: str

Determines the matching type from gt to pred: one-to-one, one-to-many, many-to-one, many-to-many

get_gt_pred_match(gt_node: collections.abc.Hashable) → collections.abc.Hashable | None[source]

Looks for a single pred node matched to a gt node

Assumes the matching is one-to-one

Parameters:

gt_node (Hashable) – ground truth node

Returns:

Predicted node id if there is a match or none

if there is no match

Return type:

Hashable | None

get_pred_gt_match(pred_node: collections.abc.Hashable) → collections.abc.Hashable | None[source]

Looks for a single gt node that matches a pred node

Parameters:

pred_node (Hashable) – predicted node id

Returns:

Ground truth node id if there is a match or none

if there is no match

Return type:

Hashable | None

get_gt_pred_matches(gt_node: collections.abc.Hashable) → list[collections.abc.Hashable][source]

Look for predicted node matches to a gt node

Parameters:

gt_node (Hashable) – Ground truth node id

Returns:

List of matching predicted nodes

Return type:

list(Hashable)

get_pred_gt_matches(pred_node: collections.abc.Hashable) → list[collections.abc.Hashable][source]

Look for gt node matches to a predicted node

Parameters:

pred_node (Hashable) – Predicted node ID

Returns:

List of matching ground truth nodes

Return type:

list(hashable)

class traccuracy.matchers.PointMatcher(threshold: float, scale_factor: tuple[float, Ellipsis] | list[float] | None = None)[source]

A one-to-one matcher that uses Hungarian matching to minimize global distance of node pairs with a maximum distance threshold beyond which nodes will not be matched. Note: this matcher computes the Euclidean distance based on the location on the points. If the data is not isotropic, the scale parameter can be used to rescale the locations in each dimension to reflect “real-world” distances.

Parameters:

  • threshold (float) – The maximum distance to allow node matchings (inclusive), in (potentially rescaled) pixels.

  • scale_factor (tuple[float, ...] | list[float] | None, optional) – If provided, multiply the node locations by the scale factor in each dimension before computing the distance. Useful if the data is not isotropic to ensure that distances are computed in a space that reflects real world distances.

property info: dict[str, Any]

Dictionary of Matcher name and any parameters

compute_mapping(gt_graph: traccuracy._tracking_graph.TrackingGraph, pred_graph: traccuracy._tracking_graph.TrackingGraph) → traccuracy.matchers._matched.Matched

Run the matching on a given set of gt and pred TrackingGraph and returns a Matched object with a new copy of each TrackingGraph

Parameters:
Returns:

Matched data object

Return type:

matched (traccuracy.matchers.Matched)

Raises:

ValueError – gt and pred must be a TrackingGraph object

class traccuracy.matchers.PointSegMatcher[source]

A matcher that constructs a mapping from a set of points to a segmentation array by determining if a point falls within a segmentation label.

Either the predicted data or the ground truth can contain a segmentation array, but not both. The matcher will map many points to a single segmentation label.

property info: dict[str, Any]

Dictionary of Matcher name and any parameters

compute_mapping(gt_graph: traccuracy._tracking_graph.TrackingGraph, pred_graph: traccuracy._tracking_graph.TrackingGraph) → traccuracy.matchers._matched.Matched

Run the matching on a given set of gt and pred TrackingGraph and returns a Matched object with a new copy of each TrackingGraph

Parameters:
Returns:

Matched data object

Return type:

matched (traccuracy.matchers.Matched)

Raises:

ValueError – gt and pred must be a TrackingGraph object