traccuracy

Subpackages

• traccuracy.loaders
• traccuracy.matchers
• traccuracy.metrics
• traccuracy.track_errors

Submodules

• traccuracy.utils

Package Contents

Classes

EdgeFlag	An enum containing standard flags that are used to
NodeFlag	An enum containing standard flags that are used to annotate the nodes
TrackingGraph	A directed graph representing a tracking solution where edges go forward in time.

Functions

run_metrics(→ tuple[list[dict], ...)

Compute given metrics on data using the given matcher.

traccuracy.run_metrics(gt_data: traccuracy._tracking_graph.TrackingGraph, pred_data: traccuracy._tracking_graph.TrackingGraph, matcher: traccuracy.matchers._base.Matcher, metrics: list[traccuracy.metrics._base.Metric], relax_skips_gt: bool = False, relax_skips_pred: bool = False) → tuple[list[dict], traccuracy.matchers._matched.Matched]

Compute given metrics on data using the given matcher.

The returned result dictionary will contain all metrics computed by the given Metric classes, as well as general summary numbers e.g. false positive/false negative detection and edge counts.

Parameters:

• gt_data (traccuracy.TrackingGraph) – ground truth graph and optionally segmentation

• pred_data (traccuracy.TrackingGraph) – predicted graph and optionally segmentation

• matcher (traccuracy.matchers._base.Matcher) – instantiated matcher object

• metrics (List[traccuracy.metrics._base.Metric]) – list of instantiated metrics objects to compute

• relax_skips_gt (bool) – If True, the metric will check if skips in the ground truth graph have an equivalent multi-edge path in predicted graph

• relax_skips_pred (bool) – If True, the metric will check if skips in the predicted graph have an equivalent multi-edge path in ground truth graph

Returns:

List of dictionaries with one dictionary per Metric object Matched: Matched data which includes annotated graphs

Return type:

List[Dict]

class traccuracy.EdgeFlag

An enum containing standard flags that are used to annotate the edges of a TrackingGraph. If a graph already has annotations using these strings before becoming a TrackingGraph, this will likely ruin metrics computation!

TRUE_POS = 'tp'

CTC_FALSE_POS = 'ctc_fp'

CTC_FALSE_NEG = 'ctc_fn'

INTERTRACK_EDGE = 'intertrack_edge'

WRONG_SEMANTIC = 'wrong_semantic'

FALSE_POS = 'fp'

FALSE_NEG = 'fn'

SKIP_FALSE_POS = 'skip_fp'

SKIP_FALSE_NEG = 'skip_fn'

SKIP_TRUE_POS = 'skip_tp'

class traccuracy.NodeFlag

An enum containing standard flags that are used to annotate the nodes of a TrackingGraph. Note that the user specified frame and location attributes are also valid node attributes that will be stored on the graph and should not overlap with these values. Additionally, if a graph already has annotations using these strings before becoming a TrackingGraph, this will likely ruin metrics computation!

CTC_TRUE_POS = 'ctc_tp'

CTC_FALSE_POS = 'ctc_fp'

CTC_FALSE_NEG = 'ctc_fn'

NON_SPLIT = 'ns'

TP_DIV = 'tp_division'

TP_DIV_SKIP = 'tp_division_skip'

FP_DIV = 'fp_division'

FN_DIV = 'fn_division'

WC_DIV = 'wrong_child_division'

TRUE_POS = 'tp'

FALSE_POS = 'fp'

FALSE_NEG = 'fn'

MIN_BUFFER_CORRECT = 'min_buffer_correct'

MIN_BUFFER_CORRECT_SKIP = 'min_buffer_correct_skip'

classmethod has_value(value: str) → bool

Check if a value is one of the enum’s values. This can be used to check if other graph annotation strings are colliding with our reserved strings.

Parameters:

value – Check if the enum contains this value.

Returns:

True if the value is already in the enum’s values,

false otherwise

Return type:

bool

class traccuracy.TrackingGraph(graph: networkx.DiGraph[collections.abc.Hashable], segmentation: numpy.ndarray | None = None, frame_key: str = 't', label_key: str | None = 'segmentation_id', location_keys: str | tuple[str, Ellipsis] | None = None, name: str | None = None, validate: bool = True)

A directed graph representing a tracking solution where edges go forward in time.

Nodes represent cell detections and edges represent links between detections in the same track. Nodes in the graph must have an attribute that represents time frame (default to ‘t’) and location (defaults to ‘x’ and ‘y’). As in networkx, every cell must have a unique id, but these can be of any (hashable) type.

Edges typically connect nodes across consecutive frames, but gap closing or frame skipping edges are valid, which connect nodes in frame t to nodes in frames beyond t+1.

We provide common functions for accessing parts of the track graph, for example all nodes in a certain frame, or all previous or next edges for a given node. Additional functionality can be accessed by querying the stored networkx graph with native networkx functions.

Currently it is assumed that the structure of the networkx graph as well as the time frame and location of each node is not mutated after construction, although non-spatiotemporal attributes of nodes and edges can be modified freely.

start_frame

int, the first frame with a node in the graph

end_frame

int, the end of the span of frames containing nodes (one frame after the last frame that contains a node)

nodes_by_frame

dict of int -> node_id Maps from frames to all node ids in that frame

frame_key

str The name of the node attribute that corresponds to the frame of the node. Defaults to “t”.

location_keys

tuple of str | str | None Key(s) used to access the location of the cell in space.

property nodes: networkx.classes.reportviews.NodeView

Get all the nodes in the graph, along with their attributes.

Returns:

Provides set-like operations on the nodes as well as node attribute lookup.

Return type:

NodeView

property edges: networkx.classes.reportviews.OutEdgeView

Get all the edges in the graph, along with their attributes.

Returns:

Provides set-like operations on the edge-tuples as well as edge attribute

lookup.

Return type:

OutEdgeView

clear_annotations() → None

Resets a TrackingGraph by removing all traccuracy related annotations from the networkx graph

Also resets any attributes on the TrackingGraph that are related to annotations

get_location(node_id: collections.abc.Hashable) → list[float] | tuple[float] | numpy.ndarray

Get the spatial location of the node with node_id using self.location_keys.

Parameters:

node_id (hashable) – The node_id to get the location of

Returns:

A list of location values in the same order as self.location_keys

Return type:

list of float

Raises:

ValueError if location keys were not provided –

get_nodes_with_flag(flag: NodeFlag) → set[collections.abc.Hashable]

Get all nodes with specified NodeFlag set to True.

Parameters:

flag (traccuracy.NodeFlag) – the node flag to query for

Returns:

An iterable of node_ids which have the given flag

and the value is True.

Return type:

(List(hashable))

get_edges_with_flag(flag: EdgeFlag) → set[tuple[collections.abc.Hashable, collections.abc.Hashable]]

Get all edges with specified EdgeFlag set to True.

Parameters:

flag (traccuracy.EdgeFlag) – the edge flag to query for

Returns:

An iterable of edge ids which have the given flag

and the value is True.

Return type:

(List(hashable))

get_divisions() → list[collections.abc.Hashable]

Get all nodes that have at least two edges pointing to the next time frame

Returns:

a list of node ids for nodes that have more than one child

Return type:

list of hashable

get_merges() → list[collections.abc.Hashable]

Get all nodes that have at least two incoming edges from the previous time frame

Returns:

a list of node ids for nodes that have more than one parent

Return type:

list of hashable

set_flag_on_node(_id: collections.abc.Hashable, flag: NodeFlag, value: bool = True) → None

Set an attribute flag for a single node. If the id is not found in the graph, a KeyError will be raised. If the flag already exists, the existing value will be overwritten.

Parameters:

• _id (Hashable) – The node id on which to set the flag.

• flag (traccuracy.NodeFlag) – The node flag to set. Must be of type NodeFlag - you may not not pass strings, even if they are included in the NodeFlag enum values.

• value (bool, optional) – Flags can only be set to True or False. Defaults to True.

Raises:

• KeyError if the provided id is not in the graph. –

• ValueError if the provided flag is not a NodeFlag –

remove_flag_from_node(_id: collections.abc.Hashable, flag: NodeFlag) → None

Removes a flag from a node

Parameters:

• _id (Hashable) – The node id for which to discard the flag.

• flag (NodeFlag) – The node flag to discard. Must be of type NodeFlag - you may not not pass strings, even if they are included in the NodeFlag enum values.

Raises:

KeyError if the flag is not present on the node. –

set_flag_on_all_nodes(flag: NodeFlag, value: bool = True) → None

Set an attribute flag for all nodes in the graph. If the flag already exists, the existing values will be overwritten.

Parameters:

• flag (traccuracy.NodeFlag) – The node flag to set. Must be of type NodeFlag - you may not not pass strings, even if they are included in the NodeFlag enum values.

• value (bool, optional) – Flags can only be set to True or False. Defaults to True.

Raises:

ValueError if the provided flag is not a NodeFlag. –

set_flag_on_edge(_id: tuple[collections.abc.Hashable, collections.abc.Hashable], flag: EdgeFlag, value: bool = True) → None

Set an attribute flag for an edge. If the flag already exists, the existing value will be overwritten.

Parameters:

• ids (tuple[Hashable]) – The edge id or list of edge ids to set the attribute for. Edge ids are a 2-tuple of node ids.

• flag (traccuracy.EdgeFlag) – The edge flag to set. Must be of type EdgeFlag - you may not pass strings, even if they are included in the EdgeFlag enum values.

• value (bool) – Flags can only be set to True or False. Defaults to True.

Raises:

KeyError if edge with _id not in graph. –

remove_flag_from_edge(_id: tuple[collections.abc.Hashable, collections.abc.Hashable], flag: EdgeFlag) → None

Removes flag from a given edge

Parameters:

• ids (tuple[Hashable]) – The edge id or list of edge ids to discard the attribute for. Edge ids are a 2-tuple of node ids.

• flag (traccuracy.EdgeFlag) – The edge flag to discard. Must be of type EdgeFlag - you may not pass strings, even if they are included in the EdgeFlag enum values.

Raises:

• KeyError if edge with _id not in graph. –

• KeyError if flag not present on edge –

set_flag_on_all_edges(flag: EdgeFlag, value: bool = True) → None

Set an attribute flag for all edges in the graph. If the flag already exists, the existing values will be overwritten.

Parameters:

• flag (traccuracy.EdgeFlag) – The edge flag to set. Must be of type EdgeFlag - you may not not pass strings, even if they are included in the EdgeFlag enum values.

• value (bool, optional) – Flags can only be set to True or False. Defaults to True.

Raises:

ValueError if the provided flag is not an EdgeFlag. –

get_lineages() → list[networkx.DiGraph]

Gets a list of new nx.DiGraph objects containing all lineages of the current graph.

Lineage is defined as all connected components.

get_tracklets(include_division_edges: bool = False) → list[networkx.DiGraph]

Gets a list of new nx.DiGraph objects containing all tracklets of the current graph.

Tracklet is defined as all connected components between divisions (daughter to next parent). Tracklets can also start or end with a non-dividing cell.

Parameters:

include_division_edges (bool, optional) – If True, include edges at division.

get_skip_edges() → set[tuple[collections.abc.Hashable, collections.abc.Hashable]]

Get all edges that skip one or more frames.

Returns:

A set of edges that skip one or more frames.

Each edge is represented as a tuple of (source_node, target_node).

Return type:

set of tuples

is_skip_edge(edge: tuple[collections.abc.Hashable, collections.abc.Hashable]) → bool