funtracks.utils

Utility functions for funtracks.

detect_zarr_spec_version

detect_zarr_spec_version(store: StoreLike) -> int | None

Detect the zarr specification version of an existing zarr store.

Parameters:

Name	Type	Description	Default
store	StoreLike	The zarr store path or object	required

Returns:

Type	Description
int | None	The zarr spec version (2 or 3) if detectable, None if unknown

ensure_unique_labels

ensure_unique_labels(
    segmentation: ndarray, multiseg: bool = False
) -> np.ndarray

Relabels the segmentation in place to ensure that label ids are unique across time. This means that every detection will have a unique label id. Useful for combining predictions made in each frame independently, or multiple segmentation outputs that repeat label IDs.

Parameters:

Name	Type	Description	Default
segmentation	ndarray	Segmentation with dimensions ([h], t, [z], y, x).	required
multiseg	bool	Flag indicating if the segmentation contains multiple hypotheses in the first dimension. Defaults to False.	False

get_store_path

get_store_path(store) -> Path

Get the filesystem path from a zarr store.

Handles differences between zarr v2 FSStore (.path) and v3 LocalStore (.root).

Parameters:

Name	Type	Description	Default
store		A zarr store object	required

Returns:

Type	Description
Path	The filesystem path of the store

Raises:

Type	Description
ValueError	Cannot determine store path

is_zarr_v3

is_zarr_v3() -> bool

Check if the installed zarr-python version is v3.

Returns:

Type	Description
bool	True if zarr-python v3 is installed, False otherwise.

open_zarr_store

open_zarr_store(path: str | Path)

Open a zarr store with version-appropriate store class.

In zarr-python v3, uses LocalStore. In v2, uses FSStore.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the zarr store	required

Returns:

Type	Description
	Appropriate store object for the installed zarr version

Raises:

Type	Description
FileNotFoundError	Path does not exist

relabel_segmentation_with_track_id

relabel_segmentation_with_track_id(
    solution_nx_graph: DiGraph, segmentation: ndarray
) -> np.ndarray

Relabel a segmentation based on tracking results so that nodes in same track share the same id. IDs do change at division.

Parameters:

Name	Type	Description	Default
solution_nx_graph	DiGraph	Networkx graph with the solution to use for relabeling. Nodes not in graph will be removed from seg. Original segmentation ids have to be stored in the graph so we can map them back.	required
segmentation	ndarray	Original segmentation with dimensions (t, [z], y, x)	required

Returns:

Type	Description
ndarray	np.ndarray: Relabeled segmentation array where nodes in same track share same id with shape (t,[z],y,x)

remove_tilde

remove_tilde(store: StoreLike) -> StoreLike

Remove tilde from a store path/str.

zarr v3 does not recognize the tilde and may write the zarr in the wrong directory.

Parameters:

Name	Type	Description	Default
store	StoreLike	The store path to process	required

Returns:

Type	Description
StoreLike	The store with the tilde expanded

setup_zarr_array

setup_zarr_array(
    store: StoreLike,
    zarr_format: Literal[2, 3] = 2,
    mode: OpenMode = "w",
    **kwargs,
) -> zarr.Array

Set up and return a zarr array for writing.

Parameters:

Name	Type	Description	Default
store	StoreLike	The zarr store path or object	required
zarr_format	Literal[2, 3]	The zarr format version to use (default: 2)	2
mode	OpenMode	The mode to open the array with (default: "w")	'w'
**kwargs		Additional arguments passed to zarr.open_array (shape, dtype, chunks, etc.)	{}

Returns:

Type	Description
Array	The opened zarr array

setup_zarr_group

setup_zarr_group(
    store: StoreLike,
    zarr_format: Literal[2, 3] = 2,
    mode: OpenMode = "a",
) -> zarr.Group

Set up and return a zarr group for writing.

Parameters:

Name	Type	Description	Default
store	StoreLike	The zarr store path or object	required
zarr_format	Literal[2, 3]	The zarr format version to use (default: 2)	2
mode	OpenMode	The mode to open the group with (default: "a" for append)	'a'

Returns:

Type	Description
Group	The opened zarr group