:orphan:

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

.. py:module:: traccuracy.metrics._complete_tracks_by_length


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

Classes
~~~~~~~

.. autoapisummary::

   traccuracy.metrics._complete_tracks_by_length.CompleteTracksByLength




.. py:class:: CompleteTracksByLength(max_length: int | None = None, lineages: bool = True, error_type: Literal[basic, ctc] = 'basic')




   Fraction of fully correct tracks as a function of track length.

   This is the CTC-BIO Complete Tracks metric generalized to every track
   length: for each length from 1 to ``max_length`` (in frames), it
   computes the accuracy (number correct / number total) of the ground
   truth track segments that span that many frames. At the maximum length
   this reduces to ``CompleteTracks``.

   Length is measured in frames (time difference), not edge count.
   A segment of length N spans N frames from start to end. For example:

   - A segment of length 1 spans 1 frame (node at t=0 to node at t=1)
   - A segment of length 2 spans 2 frames (node at t=0 to node at t=2)

   Skip edges that span multiple frames are decomposed into individual
   single-frame edges, each carrying the skip edge's correctness. For
   example, a skip edge from t=0 to t=3 contributes three length-1
   segments (t=0->1, t=1->2, t=2->3), and likewise contributes to the
   length-2 and length-3 totals.

   At division points, all branches are included in the same segment -
   a segment is only correct if all branches are correct.

   A segment is counted as correct if:

   - The starting node is a true positive
   - All edges along the path are true positives

   Important counting rules:

   - Isolated nodes (nodes with no outgoing edges) are NOT counted
   - Skip edges are decomposed into single-frame edges, so they
     contribute at every length they span (see above)
   - Tracks shorter than length N still contribute 1 to the total for
     length N (correct iff the entire track is correct)

   This metric helps identify whether tracking errors occur more frequently
   in short or long tracks, providing granular insight into tracking quality
   at different temporal scales.

   :param max_length: Maximum track length in frames to evaluate. The default
                      is None, which uses gt_tracks.end - gt_tracks.start
   :type max_length: int | None
   :param lineages: If True, evaluate on full lineages (connected components).
                    If False, evaluate on tracklets (segments between divisions).
   :param error_type: "basic" or "ctc" error classification scheme

   The compute function returns a results dictionary with three lists,
   each indexed by track length (index 0 = length 1, index 1 = length 2, etc.):

   - ``correct`` - number of correct segments at each length
   - ``total`` - total number of segments at each length
   - ``accuracy`` - correct/total at each length, or np.nan if total is 0


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