API Reference

This section documents the main classes and functions in the mitotnt package.

`MitoSegmenter`

Scans a directory for subfolders matching a given pattern (e.g., "frame_000", "frame_001"), stores metadata about the dataset, and records pixel resolution information.

Parameters:

data_path (str) –

Path to the root directory containing frame subfolders of raw tif.
pattern (str, default: 'frame' ) –

Substring pattern used to identify frame folders (default is "frame").
xy_pxl_size (float, default: 1.0 ) –

Pixel size in the x–y plane, in microns (default is 1.0).
z_pxl_size (float, default: 1.0 ) –

Pixel size in the z axis, in microns (default is 1.0).

Attributes:	`data_path` (`str`) – Path to the root data directory. `list_of_folders` (`list of str`) – Sorted list of frame-level subfolders matching the given pattern. `num_frames` (`int`) – Number of frames detected in the dataset. `xy_pxl_size` (`float`) – Pixel resolution in the x–y plane. `z_pxl_size` (`float`) – Pixel resolution in the z axis.

`run_mitograph_cpu`

Run MitoGraph on each frame of the dataset using CPU in parallel with a progress bar.

Parameters:	`overwrite` (`bool`, default: `False` ) – Whether to overwrite existing MitoGraph outputs (default is False). `extra_params` (`str`, default: `''` ) – Additional MitoGraph parameters (default is ""). `max_workers` (`int`, default: `4` ) – Number of threads to use in parallel (default is 4).

Returns:	`None` – The MitoGraph outputs are written to each frame subfolder containing `.tif`.

`visualize_segmented_data`

Create ChimeraX script to visualize the segmented mitochondrial surface and the raw microscopy data. This is critical to evaluate the quality of mitochondria segmentation.

Parameters:	`frames` (`list of int`, default: `None` ) – The frames to visualize (default is [0, -1], the first and last frames).

Returns:	`None` – check_mitograph.cxc is saved and can be opened in ChimeraX for visualization.

`SkeletonizedMito`

This class stores metadata and skeletonized graph representations of mitochondria extracted from raw segmentation results produced by MitoSegmenter. It provides access to frame-level information and graph structures that can later be used for tracking.

Parameters:	`mito_segmenter` (`MitoSegmenter`) – Object that contains metadata.

Attributes:

data_path (str) –

Path to the directory containing the segmented mitochondrial data.
list_of_folders (list of str) –

List of frame-level folders containing segmentation outputs.
num_frames (int) –

Total number of frames in the dataset.
xy_pxl_size (float) –

Pixel size in the x–y plane (microns).
z_pxl_size (float) –

Pixel size in the z axis (microns).
save_path (str) –

Path to where processed mitochondrial data will be saved.
full_graphs (list or None) –

Frame-wise full graphs with all nodes. None until computed.
segment_nodes (list or None) –

Nodes for each mitochondrial segment (branch). None until computed.
simple_graphs (list or None) –

Frame-wise simple graphs (full_graphs where degree-2 nodes are substituted by edges). None until computed.
local_simple_graphs (list or None) –

Simple graphs restricted to the local neighborhood of each node. They are used for computing topology cost when tracking. None until computed.

`extract_graphs`

Extract the graph representations of the previously segmented mitochondria used for tracking.

Parameters:	`overwrite` (`bool`, default: `False` ) – Whether to overwrite existing graphs (default is False). `node_gap_size` (`int`, default: `0` ) – Number of nodes to skip when generating the full graphs (default is 0, keep all).

Returns:	`None` – The computed graphs and segment nodes are stored internally as `SkeletonizedMito` attributes.

`NetworkTracker`

This class provides functionality to track skeletonized mitochondria in time-lapse imaging data. It uses distance and graph-based score to link mitochondrial nodes frame-to-frame and reconstruct trajectories under configurable tracking constraints.

Parameters:

segmented_mito (SkeletonizedMito) –

Pre-processed mitochondrial data with skeletonized structures.
frame_interval (float, default: None ) –

Time between consecutive frames, in seconds (default is 1.0).
start_frame (int, default: 0 ) –

Index of the first frame to include in tracking (default is 0).
end_frame (int, default: None ) –

Index of the last frame to include in tracking. If None, uses the total number of frames from segmented_mito (default is None).
tracking_interval (int, default: 1 ) –

The frame number difference for the two frames to be tracked (default is 1 so track every frame).
cutoff_num_neighbor (int, default: 10 ) –

Maximum number of nearest neighbors to consider when making node assignments across frames (default is 10).
cutoff_speed (float, default: None ) –

Maximum allowed speed of mitochondria (microns/frame interval). If None, no speed cutoff is applied (default is None).
graph_matching_depth (int, default: 2 ) –

Depth of neighborhood considered for graph matching (default is 2).
dist_exponent (int, default: 1 ) –

Exponent applied to spatial distance when computing costs (default is 1).
top_exponent (int, default: 1 ) –

Exponent applied to topological distance when computing costs (default is 1).
min_track_size (int, default: 4 ) –

Minimum number of frames required for a valid track (default is 4).
max_gap_size (int, default: 3 ) –

Maximum number of consecutive missing frames allowed when performing gap closing tracks.
block_size_factor (float, default: 1.0 ) –

Values less than 1 allows using sliding blocks of cost matrix during gap closing to prevent memory overflow due to large number of tracks. (default is 1, close all tracks at the same time).

Attributes:

segmented_mito (SkeletonizedMito) –

Reference to the input mitochondrial skeleton data.
start_frame (int) –

First frame index used for tracking.
end_frame (int) –

Last frame index used for tracking.
frame_interval (float) –

Time between frames.
tracking_interval (int) –

Step size in frames when tracking.
cutoff_num_neighbor (int) –

Maxium number of neighbors to consider.
cutoff_speed (float) –

Speed threshold for tracking.
graph_matching_depth (int) –

Graph depth used in matching.
dist_exponent (int) –

Distance exponent in matching cost.
top_exponent (int) –

Topology exponent in matching cost.
min_track_size (int) –

Minimum valid trajectory length.
max_gap_size (int) –

Maximum number of frames for an allowed gap.
block_size_factor (float) –

Factor for using sliding cost blocks during gap closing.

`reload_results`

Same as run() except reload previously saved results into TrackedMito.

Returns:

object –
TrackedMito object with network tracking results and metadata. TrackedMito.node_tracks contains tabular data with each tracked node at one frame as rows and the following columns:
- frame_id (int): the frame number.
- frame_node_id (int): node id with frame-wise indexing.
- unique_node_id (int): node id shared by all the nodes in the same track at different frames. Each track is uniquely indexed throughout the whole trajectory. This contains the tracking information.
- frame_seg_id (int): segment id for each mitochondrial segment (between non-degree-2 nodes) with frame-wise indexing.
- frame_frag_id (int): fragment id for each mitochondrial fragment (connected component) with frame-wise indexing.
- connected_unique_node_id (str): space-delimited unique_node_id for tracked neigboring nodes in the graph. Note that the topology may be different from static graphs due to absence of untracked nodes.
- x, y, z: coordinates for the node.
- intensity, width: pixel intensity and tubular width for the node from MitoGraph.

`run`

Perform frame-to-frame tracking of mitochondria using the parameters declared in NetworkTracker.

Returns:

object –
TrackedMito object with network tracking results and metadata. TrackedMito.node_tracks contains tabular data with each tracked node at one frame as rows and the following columns:
- frame_id (int): the frame number.
- frame_node_id (int): node id with frame-wise indexing.
- unique_node_id (int): node id shared by all the nodes in the same track at different frames. Each track is uniquely indexed throughout the whole trajectory. This contains the tracking information.
- frame_seg_id (int): segment id for each mitochondrial segment (between non-degree-2 nodes) with frame-wise indexing.
- frame_frag_id (int): fragment id for each mitochondrial fragment (connected component) with frame-wise indexing.
- connected_unique_node_id (str): space-delimited unique_node_id for tracked neigboring nodes in the graph. Note that the topology may be different from static graphs due to absence of untracked nodes.
- x, y, z: coordinates for the node.
- intensity, width: pixel intensity and tubular width for the node from MitoGraph.

`TrackedMito`

This class stores the results of mitochondrial tracking based on skeletonized network representations.It also adds features such as diffusivity and remodeling events.

Parameters:

segmented_mito (SkeletonizedMito) –

Pre-processed mitochondrial data with skeletonized structures.
frame_interval (float) –

Time between consecutive frames, in seconds.
start_frame (int) –

Index of the first frame used for tracking.
end_frame (int) –

Index of the last frame used for tracking.
tracking_interval (int) –

The frame number difference for the two frames to be tracked.
node_tracks (DataFrame) –

Table of tracked nodes across frames.
linked_nodes (ndarray) –

Array describing frame-to-frame node linkages produced by the tracking algorithm.

Attributes:

data_path (str) –

Path to the directory containing the original segmented data.
save_path (str) –

Path where tracking results are stored.
list_of_folders (list of str) –

Frame-level segmentation folders.
num_frames (int) –

Total number of frames in the dataset.
xy_pxl_size (float) –

Pixel resolution in the x–y plane (microns).
z_pxl_size (float) –

Pixel resolution in the z axis (microns).
full_graphs (list) –

Frame-wise full skeleton graphs of mitochondria.
segment_nodes (list) –

Nodes of individual mitochondrial segments.
simple_graphs (list) –

Simplified skeleton graphs for each frame.
local_simple_graphs (list) –

Simplified skeleton graphs restricted to local neighborhoods for each node.
start_frame (int) –

First frame index used for tracking.
end_frame (int) –

Last frame index used for tracking.
frame_interval (float) –

Time between frames.
tracking_interval (int) –

Step size in frames for linking nodes.
node_tracks (DataFrame) –

Computed from NetworkTracker.run(). Tabular data with each tracked node at one frame as a row, and columns include 'frame_id', 'frame_node_id', 'unique_node_id', 'frame_seg_id', 'frame_frag_id', 'connected_unique_node_id', 'x', 'y', 'z', 'intensity', 'width'.
linked_nodes (ndarray) –

Computed from NetworkTracker.run(). Array of node linkages between frames.
remodeling_events (dict or None) –

Placeholder for detected mitochondrial remodeling events (e.g., fusion, fission). None until computed.
node_diffusivity (DataFrame or None) –

Placeholder for diffusivity metrics at the node level. None until computed.
segment_diffusivity (DataFrame or None) –

Placeholder for diffusivity metrics at the segment level. None until computed.
fragment_diffusivity (DataFrame or None) –

Placeholder for diffusivity metrics at the fragment level. None until computed.

`compute_fragment_diffusivity`

Compute fragment-level diffusivity from tracked mitochondrial trajectories.

For each fragment in selected center frames, this method aggregates node-level displacements into fragment-averaged displacements, computes time-averaged mean squared displacement (TA-MSD), and estimates diffusivity coefficients using a linear least-squares fit of MSD vs. lag time.

Parameters:

max_tau (int, default: 5 ) –

Maximum time lag (in frames) for MSD calculation (default is 5).
tracked_ratio (float, default: 0.5 ) –

Minimum fraction of fragment nodes that must be tracked at a given lag for the fragment displacement to be considered (default is 0.3).
half_win_size (int, default: 10 ) –

Half-width of the temporal window (in frames) around each center frame used for displacement calculations (default is 10).
selected_frames (list of int, default: None ) –

Specific frame indices to use as centers for fragment diffusivity analysis. If None, frames are auto-selected at intervals of 2 * half_win_size across the dataset.

Returns:

None –

Results are stored in the attribute self.fragment_diffusivity as a pandas DataFrame and written to fragment_diffusivity.csv. Each row is a tracked fragment with the following columns:

- ``center_frame_id`` (int): Center frame used for the analysis.
- ``seg_id`` (int): Fragment identifier within the frame.
- ``diffusivity`` (float): Estimated diffusivity coefficient D.
- ``msd`` (float): Fitted mean squared displacement per frame.
- ``r_squared`` (float): Goodness of fit (R²) for the linear regression.
- ``num_points`` (int): Number of time lags included in the fit.

`compute_mitochondria_diffusivity`

Wrapper to compute mitochondrial diffusivity at one or more structural levels: nodes, segments, or fragments.

Parameters:

levels (list of strings, default: None ) –

Structural levels at which to compute diffusivity. Choose from any combination of "node", "segment", "fragment" (default is ["node", "segment", "fragment"]).
max_tau (int, default: 5 ) –

Maximum time lag (in frames) for MSD calculation (default=5).
tracked_ratio (float, default: 0.3 ) –

Minimum fraction of nodes tracked at a given lag (default=0.3). Used only for segment and fragment diffusivity.
half_win_size (int, default: 10 ) –

Half-width of the temporal window (in frames) around each center frame used for displacement calculations (default=10). Used only for segment and fragment diffusivity.
selected_frames (list of int, default: None ) –

Specific frame indices to use as centers for analysis. If None, frames are auto-selected at intervals of 2 * half_win_size across the dataset. Used only for segment and fragment diffusivity.

Returns:

None –

Results are stored in class attributes and written to CSV files.

For node diffusivity, each row is a tracked node with the following columns: - unique_node_id (int): unique node track ID from TrackedMito.node_tracks - diffusivity (float): Estimated diffusivity coefficient D. - msd (float): Fitted mean squared displacement per frame. - r_squared (float): Goodness of fit (R²) for the linear regression. - num_points (int): Number of time lags included in the fit.

For segment/fragment diffusivity, each row is a tracked segment/fragment with the following columns: - center_frame_id (int): Center frame used for the analysis. - seg_id/frag_id (int): Segment identifier within the frame. - diffusivity (float): Estimated diffusivity coefficient D. - msd (float): Fitted mean squared displacement per frame. - r_squared (float): Goodness of fit (R²) for the linear regression. - num_points (int): Number of time lags included in the fit.

`compute_node_diffusivity`

Compute node-level diffusivity from tracked mitochondrial trajectories.

For each tracked node, the time-averaged mean squared displacement (TA-MSD) is calculated over time lags up to max_tau. A linear least-squares fit of MSD vs. lag time is then used to estimate the diffusivity coefficient (D), assuming 3D diffusion (MSD = 6Dt).

Parameters:	`max_tau` (`int`, default: `5` ) – Maximum time lag (in frames) used to compute TA-MSD (default is 5).

Returns:

None –
Results are stored in the attribute self.node_diffusivity as a pandas DataFrame and written to node_diffusivity.csv. Each row is a tracked node with the following columns:
- unique_node_id (int): Unique node track ID from TrackedMito.node_tracks
- diffusivity (float): Estimated diffusivity coefficient D.
- msd (float): Fitted mean squared displacement per frame.
- r_squared (float): Goodness of fit (R²) for the linear regression.
- num_points (int): Number of time lags included in the fit.

`compute_segment_diffusivity`

Compute segment-level diffusivity from tracked mitochondrial trajectories.

For each segment in selected center frames, this method aggregates node-level displacements into segment-averaged displacements, computes time-averaged mean squared displacement (TA-MSD), and estimates diffusivity coefficients using a linear least-squares fit of MSD vs. lag time.

Parameters:

max_tau (int, default: 5 ) –

Maximum time lag (in frames) for MSD calculation (default is 5).
tracked_ratio (float, default: 0.3 ) –

Minimum fraction of segment nodes that must be tracked at a given lag for the segment displacement to be considered (default is 0.3).
half_win_size (int, default: 10 ) –

Half-width of the temporal window (in frames) around each center frame used for displacement calculations (default is 10).
selected_frames (list of int, default: None ) –

Specific frame indices to use as centers for segment diffusivity analysis. If None, frames are auto-selected at intervals of 2 * half_win_size across the dataset.

Returns:

None –

Results are stored in the attribute self.segment_diffusivity as a pandas DataFrame and written to segment_diffusivity.csv. Each row is a tracked segment with the following columns:

- ``center_frame_id`` (int): Center frame used for the analysis.
- ``seg_id`` (int): Segment identifier within the frame.
- ``diffusivity`` (float): Estimated diffusivity coefficient D.
- ``msd`` (float): Fitted mean squared displacement per frame.
- ``r_squared`` (float): Goodness of fit (R²) for the linear regression.
- ``num_points`` (int): Number of time lags included in the fit.

`detect_fusion_fission`

Detect mitochondrial fusion and fission events.

Scans tracked mitochondrial nodes across frames to identify topological remodeling events (fusion and fission). A sliding temporal window is applied to ensure that events are stable over multiple frames and not due to transient noise.

Parameters:

start_frame (int, default: None ) –

First frame index to analyze. If None, defaults to previous start_frame + half_win_size.
end_frame (int, default: None ) –

Last frame index to analyze. If None, defaults to previous end_frame - half_win_size.
tracking_interval (int, default: None ) –

Frame step size for event detection. If None, defaults to the object's tracking_interval.
half_win_size (int, default: 4 ) –

Half-width of the temporal window (in frames) used to confirm events (default is 4).
min_tracked_frames (int, default: 2 ) –

Minimum number of consecutive frames a node must be tracked to be considered in event detection (default is 2).

Returns:	`None` – Results updated to `remodeling_events` attribute as a pandas DataFrame and written to `remodeling_events.csv`. Each row is a detected fusion or fission event, with the following columns: 'type', 'frame_id', 'frame_id_before', 'frame_id_after', 'node_id_before', 'node_id_after', 'frag_id_before','frag_id_after', 'unique_node_id'.

`Visualizer`

Prepare ChimeraX files for visualizing tracking.

Parameters:	`tracked_mito` (`TrackedMito`) – Contains segmented mitochondria and network tracking results.

Attributes:

tracked_mito (TrackedMito) –

Reference to the input TrackedMito object.
visual_path (str) –

Path to the directory where visualization scripts are saved (default is TrackedMito.save_path + 'visualization/').
visual_data_path (str) –

Path to the directory where intermediate visualization data is saved (default is TrackedMito.save_path + 'visualization/data/').

`generate_chimerax_skeleton`

Export mitochondrial network skeletons to ChimeraX BILD format.

Generates .bild files representing mitochondrial skeleton graphs for a specified frame range. Each skeleton is rendered as cylinders (edges) and spheres (nodes), which can be directly loaded into ChimeraX for 3D visualization.

Parameters:

start_frame (int, default: 0 ) –

Index of the first frame to export (default is 0).
end_frame (int, default: 5 ) –

Index of the last frame to export (default is 5).
skeleton_colors (list of str, default: None ) –

List of colors (ChimeraX color names or abbreviations) used for rendering skeletons. Each color is applied sequentially across frames. If None, defaults to blue for current frame and red for next frame.
skeleton_size (float, default: 0.03 ) –

Cylinder radius for skeleton edges (default is 0.03).
node_size (float, default: 0.03 ) –

Sphere radius for nodes (default is 0.03).

Returns:	`None` – BILD files are written to the directory `self.visual_data_path`.

`generate_tracking_arrows`

Export tracking arrows between frames to ChimeraX BILD format.

Generates .bild files that visualize temporal linkages of tracked mitochondrial nodes as arrows between consecutive frames. Each arrow connects the coordinate of a node in frame t to its linked node in frame t + tracking_interval.

Parameters:

start_frame (int, default: 0 ) –

Index of the first frame to export arrows for (default is 0).
end_frame (int, default: 5 ) –

Index of the last frame to export arrows for (default is 5).
arrow_color (str, default: 'black' ) –

Color of the arrows (ChimeraX color name or abbreviation, default is 'black').
arrow_size (float, default: 0.03 ) –

Radius of arrow shafts (default is 0.03). Arrowheads are scaled proportionally.

Returns:	`None` – BILD files are written to the directory `self.visual_data_path`.

`map_mitochondria_fragment_motility`

Map fragment-level mitochondrial motility (diffusivity) to 3D visualization.

For each selected frame, fragment-level diffusivity values are extracted from self.tracked_mito.fragment_diffusivity and mapped onto the skeleton graph. Each fragment is rendered by coloring its constituent nodes, represented as spheres, with colors reflecting normalized diffusivity values. The output is exported in ChimeraX BILD format for visualization.

Parameters:	`node_size` (`float`, default: `0.3` ) – Radius of spheres used to represent fragment nodes (default is 0.3). `selected_frames` (`list of int`, default: `None` ) – Frame indices to visualize. Must be explicitly provided.

Returns:	`None` – `.bild` files are written to the directory `self.visual_path`.

`map_mitochondria_motility`

Wrapper to map mitochondrial motility (diffusivity) to 3D visualization at one or more structural levels: nodes, segments, or fragments.

Parameters:

levels (list of strings, default: None ) –

Structural levels at which to map motility. Choose from any combination of "node", "segment", "fragment" (default is ["node", "segment", "fragment"]).
node_size (float, default: 0.3 ) –

Radius of spheres used to represent nodes (default=0.3).
selected_frames (list of int, default: None ) –

Frame indices to visualize. Must be explicitly provided.

Returns:	`None` – `.bild` visualization files are written to `self.visual_path`.

`map_mitochondria_node_motility`

Map node-level mitochondrial motility (diffusivity) to 3D visualization.

For each selected frame, node-level diffusivity values are extracted from self.tracked_mito.node_diffusivity and mapped onto the skeleton graph. Nodes are rendered as spheres with colors representing normalized diffusivity. The output is exported in ChimeraX BILD format for visualization.

Parameters:	`node_size` (`float`, default: `0.3` ) – Radius of spheres used to represent nodes (default is 0.3). `selected_frames` (`list of int`, default: `None` ) – Frame indices to visualize. Must be explicitly provided.

Returns:	`None` – `.bild` files are written to the directory `self.visual_path`.

`map_mitochondria_segment_motility`

Map segment-level mitochondrial motility (diffusivity) to 3D visualization.

For each selected frame, segment-level diffusivity values are extracted from self.tracked_mito.segment_diffusivity and mapped onto the skeleton graph. Each segment is rendered by coloring its constituent nodes, represented as spheres, with colors reflecting normalized diffusivity values. The output is exported in ChimeraX BILD format for visualization.

Parameters:	`node_size` (`float`, default: `0.3` ) – Radius of spheres used to represent segment nodes (default is 0.3). `selected_frames` (`list of int`, default: `None` ) – Frame indices to visualize. Must be explicitly provided.

Returns:	`None` – `.bild` files are written to the directory `self.visual_path`.

`visualize_tracking`

Generate a ChimeraX command script for visualizing mitochondrial tracking.

Creates a .cxc script that loads skeletons, arrows, and optional TIFF volumes into ChimeraX for side-by-side visualization of tracked mitochondrial networks. Skeletons can be displayed either as constructed ChimeraX BILD skeletons or as raw Mitograph VTK files.

Parameters:

start_frame (int, default: 0 ) –

Index of the first frame to visualize (default is 0).
end_frame (int, default: 5 ) –

Index of the last frame to visualize (default is 5).
show_tif (bool, default: True ) –

If True, include raw TIFF volumes in the visualization (default is True).
tif_colors (list of str, default: None ) –

List of two ChimeraX color names for rendering consecutive TIFF frames. If None, defaults to ['deep sky blue', 'tomato'].
threshold_level (str, default: '' ) –

Threshold setting for volume rendering (default is '', use ChimeraX defaults).
use_chimerax_skeleton (bool, default: True ) –

If True, load skeletons exported in ChimeraX BILD format. If False, load original Mitograph VTK skeletons (default is True).
skeleton_colors (list of str, default: None ) –

List of two ChimeraX color names for consecutive skeletons. If None, defaults to blue for current frame and red for next frame.

Returns:	`None` – A ChimeraX command script `visualize_tracking.cxc` is written to `self.visual_path`.