traccuracy

package description.

Subpackages

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

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(→ 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]) → list[dict]

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 (Matcher) – instantiated matcher object

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

Returns:

List of dictionaries with one dictionary per Metric object

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 = 'is_tp'

FALSE_POS = 'is_fp'

FALSE_NEG = 'is_fn'

INTERTRACK_EDGE = 'is_intertrack_edge'

WRONG_SEMANTIC = 'is_wrong_semantic'

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!

TRUE_POS = 'is_tp'

FALSE_POS = 'is_fp'

FALSE_NEG = 'is_fn'

NON_SPLIT = 'is_ns'

TP_DIV = 'is_tp_division'

FP_DIV = 'is_fp_division'

FN_DIV = 'is_fn_division'

classmethod has_value(value)

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, segmentation: numpy.ndarray | None = None, frame_key: str = 't', label_key: str = 'segmentation_id', location_keys: tuple[str, Ellipsis] = ('x', 'y'), name: str | None = None)

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.

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

list of str Keys 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

get_location(node_id: Hashable) → list[float]

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

get_nodes_with_flag(flag: NodeFlag) → set[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[Hashable, 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[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[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

get_connected_components() → list[TrackingGraph]

Get a list of TrackingGraphs, each corresponding to one track (i.e., a connected component in the track graph).

Returns:

A list of TrackingGraphs, one for each track.

get_subgraph(nodes: Iterable[Hashable]) → TrackingGraph

Returns a new TrackingGraph with the subgraph defined by the list of nodes

Parameters:

nodes (list) – List of node ids to use in constructing the subgraph

set_flag_on_node(_id: 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 –

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[Hashable, 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. –

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_tracklets(include_division_edges: bool = False) → list[TrackingGraph]

Gets a list of new TrackingGraph 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.