Utilities

napari_relax._interaction_bridge

Simple interaction bridge for coordinating multi-layer lineage interactions.

This module provides a lightweight system for coordinating interactions between Points, Surface, Labels, and Tracks layers in napari-relax.

LayerAdapter

Bases: ABC

Abstract adapter for layer-specific interactions.

__init__(layer, node_to_napari, napari_to_node)

Initialize adapter with mappings between LineageTree nodes and napari indices.

Parameters:

Name	Type	Description	Default
layer	Layer	The napari layer to adapt	required
node_to_napari	dict	Mapping from LineageTree node_id to napari indices	required
napari_to_node	dict	Mapping from napari indices to LineageTree node_id	required

show_only_nodes(node_ids) abstractmethod

Show only the specified nodes, hide all others.

reset_visibility() abstractmethod

Reset all nodes to be visible.

restore_visibility() abstractmethod

Restore all nodes to be visible without affecting selection.

get_node_at_position(position, time)

Get the node ID at the given position and time.

The default implementation returns None; clickable layers override it.

PointsAdapter

Bases: LayerAdapter

Adapter for Points layers.

show_only_nodes(node_ids)

Hide unselected lineages by setting their visibility.

reset_visibility()

Restore original visibility and clear selection.

restore_visibility()

Restore original visibility without affecting selection.

select_nodes(node_ids)

Select nodes without hiding others.

hide_nodes(node_ids)

Hide specific nodes while preserving visibility of others.

get_node_at_position(position, time)

Find the node at the clicked position.

get_node_at_3d_position(position, view_direction, dims_displayed)

Find the node at the clicked position using 3D ray intersection.

SurfaceAdapter

Bases: LayerAdapter

Adapter for Surface layers.

__init__(layer, node_to_vertex_range)

Initialize the surface adapter with vertex range mappings.

The node mappings are read from the linked Points layer.

Parameters:

Name	Type	Description	Default
layer	Surface	The Surface layer to adapt.	required
node_to_vertex_range	dict	Mapping from node ID to (start_vertex_idx, end_vertex_idx) in the surface data.	required

show_only_nodes(node_ids)

Hide unselected lineages by setting their alpha to 0.

hide_nodes(node_ids)

Hide specific nodes by setting their alpha to 0, preserving other visibility.

reset_visibility()

Restore original vertex colors and blending.

restore_visibility()

Restore original vertex colors and blending without affecting selection.

TracksAdapter

Bases: LayerAdapter

Adapter for Tracks layers.

__init__(layer)

Initialize the tracks adapter.

The node mappings are read from the linked Points layer.

Parameters:

Name	Type	Description	Default
layer	Tracks	The Tracks layer to adapt.	required

show_only_nodes(node_ids)

Show only specified tracks.

hide_nodes(node_ids)

Hide specific tracks while preserving visibility of others.

reset_visibility()

Restore original track visibility.

restore_visibility()

Restore original track visibility without affecting selection.

InteractionBridge

Coordinator for multi-layer lineage interactions with state management.

This class discovers related layers through shared metadata, coordinates interactions between them, and maintains state for a specific lineage tree.

discover_layers(viewer, primary_points=None)

Discover and register related layers in the viewer.

Parameters:

Name	Type	Description	Default
viewer	Viewer	The napari viewer instance.	required
primary_points	Points	Specific Points layer to use. If None, the first one with LineageTree metadata is used.	None

Returns:

Type	Description
bool	True if any compatible layers were found.

show_only_lineages(node_ids)

Show only the specified lineages across all registered layers.

show_only_nodes(node_ids)

Show only the specified nodes across all registered layers.

hide_lineages(node_ids_to_hide)

Hide specific lineages while preserving current visibility of other lineages.

highlight_lineages(node_ids)

Highlight the specified lineages. For Points, this selects them without hiding others.

reset_visibility()

Reset visibility across all registered layers.

restore_visibility()

Restore visibility across all registered layers without affecting selection.

find_node_at_position(position, view_direction, dims_displayed)

Find a node at the given position across all clickable layers.

Returns tuple of (layer, node_idx, node_id) if found, None otherwise. Prioritizes: Points > Surface > Tracks

get_registered_layers()

Get list of registered layer types.

update_state(**kwargs)

Save state parameters for this lineage tree.

get_state(key=None)

Get state value(s) for this lineage tree.

restore_state(widget)

Restore widget visibility state from saved state.

get_bridge_for_layer(layer) classmethod

Get the InteractionBridge associated with a layer.

create_bridge_for_points_layer(viewer, points_layer) classmethod

Create and store an InteractionBridge in a Points layer's metadata.

napari_relax._utils

error_image_selection()

Show an error box asking the user to select a Points layer.

custom_error(title, message, informative=None)

Show an error box with a custom message.

Parameters:

Name	Type	Description	Default
title	str	Main text of the box.	required
message	str	Unused, kept for compatibility.	required
informative	str	Additional text shown under the title.	None

error_cell_selection()

Show an error box saying the selected cell cannot be processed.

create_links_and_chains(lT, roots)

Build the links and chain lengths of the trees under some roots.

Similar to the simple tree approximation, mainly used for the tree manipulation app.

Parameters:

Name	Type	Description	Default
lT	LineageTree	The LineageTree.	required
roots	list or set or int	The roots from which the trees are built. All roots of the LineageTree are used if empty.	required

Returns:

Type	Description
dict	links maps each chain start to its end (and each end to its successors); times maps each chain start to its length.

plot_lineages_for_tree_manip(lT, lnks_tms, hiers, nrows=2, figsize=(10, 15), dpi=100, fontsize=40, figure=None, axes=None, **kwargs)

Plot several lineages in a grid of axes, labelled by their root.

Parameters:

Name	Type	Description	Default
lT	LineageTree	The LineageTree to draw.	required
lnks_tms	dict	Graph of each lineage, keyed by plot index.	required
hiers	dict	Node positions of each graph, keyed by plot index.	required
nrows	int	Number of rows of plots, by default 2.	2
figsize	tuple	Figure size in inches, by default (10, 15).	(10, 15)
dpi	int	Figure resolution, by default 100.	100
fontsize	int	Base font size of the labels, by default 40.	40
figure	Figure	Unused, a new figure is always created.	None
axes	Axes	Unused, new axes are always created.	None
**kwargs		Passed to LineageTree.draw_tree_graph.	{}

Returns:

Type	Description
tuple	The figure, the axes, and the mappings from axis to root and from root to axis.

find_pair_with_the_longest_distance(lT)

Find the largest distance between two cells of the dataset.

The distance is measured every 10 timepoints on the convex hull of the cell positions.

Parameters:

Name	Type	Description	Default
lT	LineageTree	The LineageTree.	required

Returns:

Type	Description
float	The length of the longest possible axis.

napari_relax._util_classes.dialog_for_reader

BigDatasetNamesDialog

Bases: QDialog

Dialog box to ask the user if they want to continue using big names.

napari_relax._util_classes.containerize

Containerize

Bases: QWidget

Place a list of widgets in a horizontal or vertical container.

napari_relax._util_classes.custom_colorboxes

ColorBoxLabel

Bases: QWidget

Colormap selector based on napari colormaps.

For matplotlib colormaps, use MplCompatibleColorCombobox.

MplCompatibleColorCombobox

Bases: QWidget

__init__(parent=None, dict_of_cmaps=None)

Create the colormap selector.

Parameters:

Name	Type	Description	Default
parent	QWidget	The parent widget, by default None.	None
dict_of_cmaps	dict[str, Colormap]	Colormaps to offer, in the matplotlib colormap registry format, by default None.	None

colorbox_label

ColorBoxLabel

Bases: QWidget

Colormap selector based on napari colormaps.

For matplotlib colormaps, use MplCompatibleColorCombobox.

mpl_compatible_combobox

MplCompatibleColorCombobox

Bases: QWidget

__init__(parent=None, dict_of_cmaps=None)

Create the colormap selector.

Parameters:

Name	Type	Description	Default
parent	QWidget	The parent widget, by default None.	None
dict_of_cmaps	dict[str, Colormap]	Colormaps to offer, in the matplotlib colormap registry format, by default None.	None

CustomColorStyledDelegate

Bases: QStyledItemDelegate

Colormap item delegate accepting matplotlib colormaps.

Adapted from napari's colormap combobox, which only accepts napari colormaps.

__init__(base_height, dict_of_cmaps=None, **kwargs)

Create the delegate used by the custom colormap combobox.

Parameters:

Name	Type	Description	Default
base_height	int	The height of the widget.	required
dict_of_cmaps	dict[str, Colormap]	Colormaps to offer, in the matplotlib colormap registry format, by default None.	None
**kwargs		Passed to QStyledItemDelegate.	{}

CustomQtColormapComboBox

Bases: QComboBox

__init__(parent=None, dict_of_cmaps=None)

Create the custom colormap combobox.

Parameters:

Name	Type	Description	Default
parent	QWidget	The parent widget, by default None.	None
dict_of_cmaps	dict[str, Colormap]	Colormaps to offer, in the matplotlib colormap registry format, by default None.	None

napari_relax._util_classes.tooltip

napari_relax._util_classes.eventfilter_for_delayed_tooltip

DelayedTooltipEventFilter

Bases: QObject

Event filter that shows tooltips after a delay.

Install it on any QObject with QObject.installEventFilter(DelayedTooltipEventFilter()).

napari_relax._util_classes.viewer_wrapper

QtViewerWrap

Bases: QtViewer

QtViewer embedded in a widget, forwarding file drops to napari.

napari_relax.demo_data

Demo datasets available under File > Open Sample > ReLAX.

Datasets are described in datasets.json and downloaded on first use when they do not ship with the plugin.

load_demo_datasets()

Load demo datasets configuration from JSON file.

save_demo_datasets(datasets)

Save demo datasets configuration to JSON file.

clear_cache(dataset_name=None)

Clear cached demo data.

Parameters:

Name	Type	Description	Default
dataset_name	str	Specific dataset to clear. If None, clears all cached data.	None

ensure_demo_data(dataset_name='demo')

Ensure demo data is available locally, downloading if necessary.

Parameters:

Name	Type	Description	Default
dataset_name	str	Name of the dataset to ensure is available	'demo'

Returns:

Type	Description
Path	Path to the local dataset file

Raises:

Type	Description
RuntimeError	If download fails or dataset is not configured
ValueError	If dataset_name is not found in configuration

get_cached_datasets()

Get information about cached datasets.

load_celegans()

Load the C. elegans demo dataset.

The dataset is downloaded from Zenodo on first use and cached.

Returns:

Type	Description
list of tuple	LayerData tuples for napari.

load_demo()

Load the Parhyale hawaiensis demo dataset.

The file ships with the plugin.

Returns:

Type	Description
list of tuple	LayerData tuples for napari.