:py:mod:`traccuracy.utils`
==========================

.. py:module:: traccuracy.utils


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


Functions
~~~~~~~~~

.. autoapisummary::

   traccuracy.utils.get_equivalent_skip_edge
   traccuracy.utils.get_corrected_division_graphs_with_delta
   traccuracy.utils.export_graphs_to_geff
   traccuracy.utils.save_results_json



.. py:function:: get_equivalent_skip_edge(skip_other_matched: traccuracy.matchers._matched.Matched, skip_src: collections.abc.Hashable, skip_dst: collections.abc.Hashable, matched_src: collections.abc.Hashable, matched_dst: collections.abc.Hashable) -> list[collections.abc.Hashable]

   Get path `matched_src ->...-> matched_dst` equivalent to `skip_src -> skip_dst`.

   A skip edge `skip_src -> skip_dst` is equivalent to a path connecting `matched_src` and
   `matched_dst` if:

   - `skip_src` is a valid match for `matched_src`,
   - `skip_dst` is a valid match for `matched_dst`,
   - `matched_src` is an ancestor of `matched_dst` (regardless of intervening nodes) AND
   - all nodes on the path `matched_src ->...-> matched_dst` have no valid matches in
       `skip_other_matched`.

   :param skip_other_matched: Matched object mapping
                              skip nodes to other nodes
   :type skip_other_matched: traccuracy.matchers._base.Matched
   :param skip_src: ID of source node of skip edge
   :type skip_src: Hashable
   :param skip_dst: ID of destination node of skip edge
   :type skip_dst: Hashable
   :param matched_src: matched node of skip_src
   :type matched_src: Hashable
   :param matched_dst: matched node of skip_dst
   :type matched_dst: Hashable

   :returns: path from matched_src to matched_dst, or empty list if no such path.
   :rtype: list[Hashable]


.. py:function:: get_corrected_division_graphs_with_delta(matched: traccuracy.matchers._matched.Matched, frame_buffer: int = 0, relax_skip_edges: bool = False) -> tuple[traccuracy._tracking_graph.TrackingGraph, traccuracy._tracking_graph.TrackingGraph]

   Returns copies of graphs with divisions corrected.

   All divisions corrected by a frame_buffer value less than or equal
   to the given frame buffer are marked as `TP_DIV`.

   :param matched: Matched object for set of GT and Pred data.
                   Must be annotated with division events.
   :type matched: traccuracy.matchers._base.Matched
   :param frame_buffer: Maximum frame buffer to use for division correction
   :type frame_buffer: int
   :param relax_skip_edges: If True, will allow divisions that incorporate skip edges from
                            parent to daughter
   :type relax_skip_edges: bool

   :returns:

             Tuple of corrected
                 GT and Pred graphs
   :rtype: tuple[traccuracy.TrackingGraph, traccuracy.TrackingGraph]


.. py:function:: export_graphs_to_geff(out_zarr: str, matched: traccuracy.matchers._matched.Matched, results: list[traccuracy.metrics._results.Results] | list[dict[str, Any]], target_frame_buffer: int = 0) -> None

   Export annotated tracking graphs as geffs along with a summary of traccuracy results

   Output file structure:
   out_zarr.zarr/
   ├── gt.geff
   ├── pred.geff
   └── traccuracy-results.json

   :param out_zarr: Path to output zarr
   :type out_zarr: str
   :param matched: Matched object containing
                   annotated TrackingGraphs
   :type matched: traccuracy.matchers._base.Matched
   :param results: List of Results
                   output by Metric.compute OR results objects as dictionary as returned by `run_metrics`
   :type results: list[traccuracy.metrics._results.Results] | list[dict[str, Any]
   :param target_frame_buffer: If divisions are annotated, target_frame_buffer can
                               be used to run `get_corrected_divisions_with_delta` in order to provide division
                               annotations for a specific frame buffer. Defaults to 0.
   :type target_frame_buffer: int, optional

   :raises ValueError: matched argument must be an instance of `Matched`
   :raises ValueError: results argument must be a list of Results or dictionary objects
   :raises ValueError: Zarr already exists at out_zarr
   :raises ValueError: Requested target frame buffer {target_frame_buffer} exceeds computed "
       "frame buffer {max_frame_buffer}


.. py:function:: save_results_json(results: list[traccuracy.metrics._results.Results] | list[dict[str, Any]], out_path: str) -> None

   Save a list of results to a traccuracy export json

   :param results: List of either
                   results dictionaries or results objects
   :type results: list[traccuracy.metrics._results.Results] | list[dict[str, Any]
   :param out_path: Path to save json file
   :type out_path: str

   :raises ValueError: out_path already exists
   :raises ValueError: results argument must be a list of Results objects or dictionaries
   :raises ValueError: results argument must be a list