:orphan:

:py:mod:`traccuracy.metrics._divisions`
=======================================

.. py:module:: traccuracy.metrics._divisions

.. autoapi-nested-parse::

   This submodule classifies division errors in tracking graphs

   Each division is classified as one of the following:
   - true positive
   - false positive
   - false negative

   These functions require two `TrackingGraph` objects and a mapper between
   nodes in the two graphs. Divisions are identified as correct if both the parent
   and daughter nodes match between the GT and predicted graph.

   Temporal tolerance for correct divisions is implemented to allow for cases in
   which the exact frame that a division event occurs is somewhat arbitrary due to
   a high frame rate or variable segmentation or detection. Consider the following
   graphs as an example::

       G1
                                   2_4
       1_0 -- 1_1 -- 1_2 -- 1_3 -<
                                   3_4
       G2
                     2_2 -- 2_3 -- 2_4
       1_0 -- 1_1 -<
                     3_2 -- 3_3 -- 3_4

   After classifying basic division errors, we consider all false positive and false
   negative divisions. If a pair of errors occurs within the specified frame buffer,
   the pair is considered a true positive division if the parent nodes and daughter
   nodes match. We determine the "parent node" of the late division, e.g. node 1_3 in
   graph G1, by traversing back along the graph until we find the node in the same frame
   as the parent node of the early division. We repeat the process for finding daughters
   of the early division, by advancing along the graph to find nodes in the same frame
   as the late division daughters.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   traccuracy.metrics._divisions.DivisionMetrics




Attributes
~~~~~~~~~~

.. autoapisummary::

   traccuracy.metrics._divisions.logger


.. py:data:: logger

   

.. py:class:: DivisionMetrics(max_frame_buffer: int = 0)




   Computes division summary metrics with an optional frame tolerance.

   Computes the following metrics:
   - Division Recall
   - Division Precision
   - Division F1 Score (also Branching Correctness)
   - Mitotic Branching Correctness: TP / (TP + FP + FN) as defined by *Ulicna, K.,
   Vallardi, G., Charras, G. & Lowe, A. R. Automated deep lineage tree analysis
   using a Bayesian single cell tracking approach. Frontiers in Computer Science
   3, 734559 (2021).*

   These metrics are written assuming that the ground truth annotations
   are dense. If that is not the case, interpret the numbers carefully.
   Consider eliminating metrics that use the number of false positives.

   :param max_frame_buffer: Maximum value of frame buffer to use in correcting
                            shifted divisions. Divisions will be evaluated for all integer values of frame
                            buffer between 0 and max_frame_buffer
   :type max_frame_buffer: int, optional

   .. py:property:: info
      :type: dict[str, Any]

      Dictionary with Metric name and any parameters

   .. py:method:: compute(matched: traccuracy.matchers._matched.Matched, override_matcher: bool = False, relax_skips_gt: bool = False, relax_skips_pred: bool = False) -> traccuracy.metrics._results.Results

      The compute methods of Metric objects return a Results object populated with results
      and associated metadata

      :param matched: Matched data object to compute metrics on
      :type matched: traccuracy.matchers.Matched
      :param override_matcher: If True, the metric will not validate the matcher type
      :type override_matcher: bool
      :param relax_skips_gt: If True, the metric will check if skips in the ground truth
                             graph have an equivalent multi-edge path in predicted graph
      :type relax_skips_gt: bool
      :param relax_skips_pred: If True, the metric will check if skips in the predicted
                               graph have an equivalent multi-edge path in ground truth graph
      :type relax_skips_pred: bool

      :returns:

                Object containing metric results
                    and associated pipeline metadata
      :rtype: traccuracy.metrics._results.Results