:py:mod:`traccuracy.matchers` ============================= .. py:module:: traccuracy.matchers .. autoapi-nested-parse:: 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 ~~~~~~~ .. autoapisummary:: traccuracy.matchers.CTCMatcher traccuracy.matchers.IOUMatcher traccuracy.matchers.Matched traccuracy.matchers.PointMatcher traccuracy.matchers.PointSegMatcher Functions ~~~~~~~~~ .. autoapisummary:: traccuracy.matchers.get_labels_with_overlap .. py:function:: 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]] Get all labels IDs in gt_frame and res_frame whose bounding boxes overlap, and a metric of pixel overlap (either ``iou`` or ``iogt``). :param gt_frame: ground truth segmentation for a single frame :type gt_frame: np.ndarray :param res_frame: result segmentation for a given frame :type res_frame: np.ndarray :param gt_boxes: ground truth bounding boxes for a single frame :type gt_boxes: np.ndarray :param res_boxes: result bounding boxes for a given frame :type res_boxes: np.ndarray :param gt_labels: ground truth labels for a single frame :type gt_labels: np.ndarray :param res_labels: result labels for a given frame :type res_labels: np.ndarray :param overlap: Choose between intersection-over-ground-truth (``iogt``) or intersection-over-union (``iou``). Defaults to ``iou``. :type overlap: str, optional 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). .. py:class:: CTCMatcher 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. .. py:property:: info :type: dict[str, Any] Dictionary of Matcher name and any parameters .. py:method:: 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 :param gt_graph: Tracking graph object for the gt :type gt_graph: traccuracy.TrackingGraph :param pred_graph: Tracking graph object for the pred :type pred_graph: traccuracy.TrackingGraph :returns: Matched data object :rtype: matched (traccuracy.matchers.Matched) :raises ValueError: gt and pred must be a TrackingGraph object .. py:class:: IOUMatcher(iou_threshold: float = 0.6, one_to_one: bool = False) 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 :param iou_threshold: Minimum IoU value to assign a match. Defaults to 0.6. :type iou_threshold: float, optional :param one_to_one: If True, forces the mapping to be one-to-one by running linear assignment on the thresholded iou array. Default False. :type one_to_one: optional, bool .. py:property:: info :type: dict[str, Any] Dictionary of Matcher name and any parameters .. py:method:: 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 :param gt_graph: Tracking graph object for the gt :type gt_graph: traccuracy.TrackingGraph :param pred_graph: Tracking graph object for the pred :type pred_graph: traccuracy.TrackingGraph :returns: Matched data object :rtype: matched (traccuracy.matchers.Matched) :raises ValueError: gt and pred must be a TrackingGraph object .. py:class:: Matched(gt_graph: traccuracy._tracking_graph.TrackingGraph, pred_graph: traccuracy._tracking_graph.TrackingGraph, mapping: list[tuple[Any, Any]], matcher_info: dict) 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. :ivar gt_pred_map: A dictionary from gt node to list of matched pred nodes :ivar pred_gt_map: A dictionary from pred node to list of matched gt nodes :param gt_graph: Tracking graph object for the gt :type gt_graph: traccuracy.TrackingGraph :param pred_graph: Tracking graph object for the pred :type pred_graph: traccuracy.TrackingGraph :param mapping: List of tuples where each tuple maps a gt node to a pred node :type mapping: list[tuple[Any, Any]] :param matcher_info: Dictionary containing name and parameters from the matcher that generated the mapping :type matcher_info: dict .. py:property:: matching_type :type: str Determines the matching type from gt to pred: one-to-one, one-to-many, many-to-one, many-to-many .. py:method:: get_gt_pred_match(gt_node: collections.abc.Hashable) -> collections.abc.Hashable | None Looks for a single pred node matched to a gt node Assumes the matching is one-to-one :param gt_node: ground truth node :type gt_node: Hashable :returns: Predicted node id if there is a match or none if there is no match :rtype: Hashable | None .. py:method:: get_pred_gt_match(pred_node: collections.abc.Hashable) -> collections.abc.Hashable | None Looks for a single gt node that matches a pred node :param pred_node: predicted node id :type pred_node: Hashable :returns: Ground truth node id if there is a match or none if there is no match :rtype: Hashable | None .. py:method:: get_gt_pred_matches(gt_node: collections.abc.Hashable) -> list[collections.abc.Hashable] Look for predicted node matches to a gt node :param gt_node: Ground truth node id :type gt_node: Hashable :returns: List of matching predicted nodes :rtype: list(Hashable) .. py:method:: get_pred_gt_matches(pred_node: collections.abc.Hashable) -> list[collections.abc.Hashable] Look for gt node matches to a predicted node :param pred_node: Predicted node ID :type pred_node: Hashable :returns: List of matching ground truth nodes :rtype: list(hashable) .. py:class:: PointMatcher(threshold: float, scale_factor: tuple[float, Ellipsis] | list[float] | None = None) 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. :param threshold: The maximum distance to allow node matchings (inclusive), in (potentially rescaled) pixels. :type threshold: float :param scale_factor: 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. :type scale_factor: tuple[float, ...] | list[float] | None, optional .. py:property:: info :type: dict[str, Any] Dictionary of Matcher name and any parameters .. py:method:: 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 :param gt_graph: Tracking graph object for the gt :type gt_graph: traccuracy.TrackingGraph :param pred_graph: Tracking graph object for the pred :type pred_graph: traccuracy.TrackingGraph :returns: Matched data object :rtype: matched (traccuracy.matchers.Matched) :raises ValueError: gt and pred must be a TrackingGraph object .. py:class:: PointSegMatcher 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. .. py:property:: info :type: dict[str, Any] Dictionary of Matcher name and any parameters .. py:method:: 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 :param gt_graph: Tracking graph object for the gt :type gt_graph: traccuracy.TrackingGraph :param pred_graph: Tracking graph object for the pred :type pred_graph: traccuracy.TrackingGraph :returns: Matched data object :rtype: matched (traccuracy.matchers.Matched) :raises ValueError: gt and pred must be a TrackingGraph object