funtracks.data_model.tracks

Tracks

Tracks(
    graph: DiGraph,
    segmentation: ndarray | None = None,
    time_attr: str | None = None,
    pos_attr: str
    | tuple[str, ...]
    | list[str]
    | None = None,
    tracklet_attr: str | None = None,
    lineage_attr: str | None = None,
    scale: list[float] | None = None,
    ndim: int | None = None,
    features: FeatureDict | None = None,
)

A set of tracks consisting of a graph and an optional segmentation.

The graph nodes represent detections and must have a time attribute and position attribute. Edges in the graph represent links across time.

Attributes:

Name	Type	Description
graph	DiGraph	A graph with nodes representing detections and and edges representing links across time.
segmentation	ndarray | None	An optional segmentation that accompanies the tracking graph. If a segmentation is provided, the node ids in the graph must match the segmentation labels.
features	FeatureDict	Dictionary of features tracked on graph nodes/edges.
annotators	AnnotatorRegistry	List of annotators that compute features.
scale	list[float] | None	How much to scale each dimension by, including time.
ndim	int	Number of dimensions (3 for 2D+time, 4 for 3D+time).

Initialize a Tracks object.

Parameters:

Name	Type	Description	Default
graph	DiGraph	NetworkX directed graph with nodes as detections and edges as links.	required
segmentation	ndarray | None	Optional segmentation array where labels match node IDs. Required for computing region properties (area, etc.).	None
time_attr	str | None	Graph attribute name for time. Defaults to "time" if None.	None
pos_attr	str | tuple[str, ...] | list[str] | None	Graph attribute name(s) for position. Can be: - Single string for one attribute containing position array - List/tuple of strings for multi-axis (one attribute per axis) Defaults to "pos" if None.	None
tracklet_attr	str | None	Graph attribute name for tracklet/track IDs. Defaults to "track_id" if None.	None
lineage_attr	str | None	Graph attribute name for lineage IDs. Defaults to "lineage_id" if None.	None
scale	list[float] | None	Scaling factors for each dimension (including time). If None, all dimensions scaled by 1.0.	None
ndim	int | None	Number of dimensions (3 for 2D+time, 4 for 3D+time). If None, inferred from segmentation or scale.	None
features	FeatureDict | None	Pre-built FeatureDict with feature definitions. If provided, time_attr/pos_attr/tracklet_attr are ignored. Assumes that all features in the dict already exist on the graph (will be activated but not recomputed). If None, core computed features (pos, area, track_id) are auto-detected by checking if they exist on the graph.	None

delete

delete(directory: Path)

Delete the tracks in the given directory. Also deletes the directory.

Parameters:

Name	Type	Description	Default
directory	Path	Directory containing tracks to be deleted	required

disable_features

disable_features(feature_keys: list[str]) -> None

Disable multiple features from computation.

Removes features from annotators and FeatureDict.

Parameters:

Name	Type	Description	Default
feature_keys	list[str]	List of feature keys to disable	required

Raises:

Type	Description
KeyError	If any feature is not available (raised by annotators)

enable_features

enable_features(
    feature_keys: list[str], recompute: bool = True
) -> None

Enable multiple features for computation efficiently.

Adds features to annotators and FeatureDict, optionally computes their values.

Parameters:

Name	Type	Description	Default
feature_keys	list[str]	List of feature keys to enable	required
recompute	bool	If True, compute feature values. If False, assume values already exist in graph and just register the feature.	True

Raises:

Type	Description
KeyError	If any feature is not available (raised by annotators)

get_area

get_area(node: Node) -> int | None

Get the area/volume of a given node. Raises a KeyError if the node is not in the graph. Returns None if the given node does not have an Area attribute.

.. deprecated:: 1.0 get_area will be removed in funtracks v2.0. Use get_node_attr(node, "area") instead.

Parameters:

Name	Type	Description	Default
node	Node	The node id to get the area/volume for	required

Returns:

Name	Type	Description
int	int | None	The area/volume of the node

get_areas

get_areas(nodes: Iterable[Node]) -> Sequence[int | None]

Get the area/volume of a given node. Raises a KeyError if the node is not in the graph. Returns None if the given node does not have an Area attribute.

.. deprecated:: 1.0 get_areas will be removed in funtracks v2.0. Use get_nodes_attr(nodes, "area") instead.

Parameters:

Name	Type	Description	Default
node	Node	The node id to get the area/volume for	required

Returns:

Name	Type	Description
int	Sequence[int | None]	The area/volume of the node

get_available_features

get_available_features() -> dict[str, Feature]

Get all features that can be computed across all annotators.

Returns:

Type	Description
dict[str, Feature]	Dictionary mapping feature keys to Feature definitions

get_iou

get_iou(edge: Edge)

Get the IoU value for the given edge.

.. deprecated:: 1.0 get_iou will be removed in funtracks v2.0. Use get_edge_attr(edge, "iou") instead.

Parameters:

Name	Type	Description	Default
edge	Edge	An edge to get the IoU value for.	required

Returns:

Type	Description
	The IoU value for the edge.

get_ious

get_ious(edges: Iterable[Edge])

Get the IoU values for the given edges.

.. deprecated:: 1.0 get_ious will be removed in funtracks v2.0. Use get_edges_attr(edges, "iou") instead.

Parameters:

Name	Type	Description	Default
edges	Iterable[Edge]	An iterable of edges to get IoU values for.	required

Returns:

Type	Description
	The IoU values for the edges.

get_pixels

get_pixels(node: Node) -> tuple[np.ndarray, ...] | None

Get the pixels corresponding to each node in the nodes list.

Parameters:

Name	Type	Description	Default
node	Node	A node to get the pixels for.	required

Returns:

Type	Description
tuple[ndarray, ...] | None	tuple[np.ndarray, ...] | None: A tuple representing the pixels for the input
tuple[ndarray, ...] | None	node, or None if the segmentation is None. The tuple will have length equal
tuple[ndarray, ...] | None	to the number of segmentation dimensions, and can be used to index the
tuple[ndarray, ...] | None	segmentation.

get_positions

get_positions(
    nodes: Iterable[Node], incl_time: bool = False
) -> np.ndarray

Get the positions of nodes in the graph. Optionally include the time frame as the first dimension. Raises an error if any of the nodes are not in the graph.

Parameters:

Name	Type	Description	Default
node	Iterable[Node]	The node ids in the graph to get the positions of	required
incl_time	bool	If true, include the time as the first element of each position array. Defaults to False.	False

Returns:

Type	Description
ndarray	np.ndarray: A N x ndim numpy array holding the positions, where N is the number of nodes passed in

get_time

get_time(node: Node) -> int

Get the time frame of a given node. Raises an error if the node is not in the graph.

Parameters:

Name	Type	Description	Default
node	Any	The node id to get the time frame for	required

Returns:

Name	Type	Description
int	int	The time frame that the node is in

load

load(
    directory: Path, seg_required=False, solution=False
) -> Tracks

Load a Tracks object from the given directory. Looks for files in the format generated by Tracks.save. Args: directory (Path): The directory containing tracks to load seg_required (bool, optional): If true, raises a FileNotFoundError if the segmentation file is not present in the directory. Defaults to False. Returns: Tracks: A tracks object loaded from the given directory

notify_annotators

notify_annotators(action: BasicAction) -> None

Notify annotators about an action so they can recompute affected features.

Delegates to the annotator registry which broadcasts to all annotators. The action contains all necessary information about which elements to update.

Parameters:

Name	Type	Description	Default
action	BasicAction	The action that triggered this notification	required

save

save(directory: Path)

Save the tracks to the given directory. Currently, saves the graph as a json file in networkx node link data format, saves the segmentation as a numpy npz file, and saves the time and position attributes and scale information in an attributes json file. Args: directory (Path): The directory to save the tracks in.

set_pixels

set_pixels(pixels: tuple[ndarray, ...], value: int) -> None

Set the given pixels in the segmentation to the given value.

Parameters:

Name	Type	Description	Default
pixels	Iterable[tuple[ndarray]]	The pixels that should be set, formatted like the output of np.nonzero (each element of the tuple represents one dimension, containing an array of indices in that dimension). Can be used to directly index the segmentation.	required
value	Iterable[int | None]	The value to set each pixel to	required

set_positions

set_positions(
    nodes: Iterable[Node],
    positions: ndarray,
    incl_time: bool = False,
)

Set the location of nodes in the graph. Optionally include the time frame as the first dimension. Raises an error if any of the nodes are not in the graph.

Parameters:

Name	Type	Description	Default
nodes	Iterable[node]	The node ids in the graph to set the location of.	required
positions	ndarray	An (ndim, num_nodes) shape array of positions to set.	required
incl_time	bool	If true, include the time as the first column of the position array. Defaults to False.	False

set_time

set_time(node: Any, time: int)

Set the time frame of a given node. Raises an error if the node is not in the graph.

Parameters:

Name	Type	Description	Default
node	Any	The node id to set the time frame for	required
time	int	The time to set	required