Nellie Napari Plugin

nellie_napari

NellieProcessor

NellieProcessor(napari_viewer, nellie, parent=None)

Bases: QWidget

The NellieProcessor class manages the different steps of the Nellie pipeline such as preprocessing, segmentation, mocap marking, tracking, voxel reassignment, and feature extraction. It provides an interface to run each step individually or as part of a full pipeline within a napari viewer.

Attributes:

Name	Type	Description
`nellie`	`object`	Reference to the Nellie instance managing the pipeline.
`viewer`	`Viewer`	Reference to the napari viewer instance.
`im_info_list`	`list of ImInfo or None`	List of ImInfo objects for the selected files. Contains metadata and file information.
`current_im_info`	`ImInfo or None`	The current image's information and metadata object.
`status_label`	`QLabel`	Label displaying the current status of the process.
`status`	`str or None`	The current status of the process (e.g., "preprocessing", "segmentation").
`num_ellipses`	`int`	Counter to manage the ellipsis effect on the status label during execution.
`status_timer`	`QTimer`	Timer that periodically updates the status label during pipeline execution.
`open_dir_button`	`QPushButton`	Button to open the output directory of the current image file.
`run_button`	`QPushButton`	Button to run the full Nellie pipeline.
`preprocess_button`	`QPushButton`	Button to run only the preprocessing step of the pipeline.
`segment_button`	`QPushButton`	Button to run only the segmentation step of the pipeline.
`mocap_button`	`QPushButton`	Button to run only the mocap marking step of the pipeline.
`track_button`	`QPushButton`	Button to run only the tracking step of the pipeline.
`reassign_button`	`QPushButton`	Button to run only the voxel reassignment step of the pipeline.
`feature_export_button`	`QPushButton`	Button to run only the feature extraction step of the pipeline.
`initialized`	`bool`	Flag indicating whether the processor has been initialized.
`pipeline`	`bool`	Flag indicating whether the full pipeline is being run.

Methods:

Name	Description
`set_ui`	Initializes and sets the layout and UI components for the NellieProcessor.
`post_init`	Post-initialization method to load image information and check file existence.
`check_file_existence`	Checks the existence of necessary files for each step of the pipeline and enables/disables buttons accordingly.
`run_nellie`	Runs the entire Nellie pipeline starting from preprocessing to feature extraction.
`run_preprocessing`	Runs the preprocessing step of the Nellie pipeline.
`run_segmentation`	Runs the segmentation step of the Nellie pipeline.
`run_mocap`	Runs the mocap marking step of the pipeline.
`run_tracking`	Runs the tracking step of the pipeline.
`run_reassign`	Runs the voxel reassignment step of the pipeline.
`run_feature_export`	Runs the feature extraction step of the pipeline.
`set_status`	Sets the status to indicate that a process has started, and starts the status update timer.
`update_status`	Updates the status label with the current process and an ellipsis effect while the process is running.
`reset_status`	Resets the status label to indicate that no process is running.
`turn_off_buttons`	Disables all buttons to prevent multiple processes from running simultaneously.
`open_directory`	Opens the output directory where the current image results are saved.

Initialize the NellieProcessor class, setting up the user interface and preparing for running various steps of the pipeline.

Parameters:

Name	Type	Description	Default
`napari_viewer`	`Viewer`	Reference to the napari viewer instance.	required
`nellie`	`object`	Reference to the Nellie instance that manages the pipeline.	required
`parent`	`QWidget`	Optional parent widget (default is None).	`None`

set_ui

set_ui()

Initialize and set the layout and user interface components for the NellieProcessor. This includes the status label, buttons for running individual steps, and the button for running the entire pipeline.

post_init

post_init()

Post-initialization method that checks the state of the selected images. It determines whether the pipeline steps have already been completed and enables/disables the corresponding buttons accordingly.

check_file_existence

check_file_existence()

Check the existence of files required for each step of the pipeline (e.g., preprocessed images, segmented labels). Enables or disables buttons based on the existence of these files.

run_preprocessing

run_preprocessing()

Start the preprocessing step and updates the UI to reflect that preprocessing is running. If the full pipeline is running, it automatically proceeds to segmentation after preprocessing is finished.

run_segmentation

run_segmentation()

Start the segmentation step and updates the UI to reflect that segmentation is running. If the full pipeline is running, it automatically proceeds to mocap marking after segmentation is finished.

run_mocap

run_mocap()

Start the mocap marking step and updates the UI to reflect that mocap marking is running. If the full pipeline is running, it automatically proceeds to tracking after mocap marking is finished.

run_tracking

run_tracking()

Start the tracking step and updates the UI to reflect that tracking is running. If the full pipeline is running, it automatically proceeds to voxel reassignment or feature extraction depending on the settings.

run_reassign

run_reassign()

Start the voxel reassignment step and updates the UI to reflect that voxel reassignment is running. If the full pipeline is running, it automatically proceeds to feature extraction after voxel reassignment is finished.

run_feature_export

run_feature_export()

Start the feature extraction step and updates the UI to reflect that feature extraction is running.

turn_off_pipeline

turn_off_pipeline()

Turn off the pipeline flag to indicate that the full pipeline is no longer running.

run_nellie

run_nellie()

Start the entire Nellie pipeline from preprocessing to feature extraction.

set_status

set_status()

Set the status of the processor to indicate that a process is running, and starts the status update timer.

update_status

update_status()

Update the status label with an ellipsis effect to indicate ongoing processing.

reset_status

reset_status()

Reset the status label to indicate that no process is running.

turn_off_buttons

turn_off_buttons()

Disable all buttons to prevent multiple processes from running simultaneously.

open_directory

open_directory()

Open the output directory of the current image in the system file explorer.

NellieLoader

NellieLoader(napari_viewer, parent=None)

Bases: QTabWidget

The main loader class for managing the different stages of the Nellie pipeline within the napari viewer. This class provides a tabbed interface for file selection, processing, visualization, analysis, and settings management.

Attributes:

Name	Type	Description
`home`	`Home`	The home tab instance, providing an overview of the Nellie pipeline.
`file_select`	`NellieFileSelect`	The file selection tab instance, allowing users to select and validate image files.
`processor`	`NellieProcessor`	The image processing tab instance, where users can process images through the Nellie pipeline.
`visualizer`	`NellieVisualizer`	The visualization tab instance, where processed images can be visualized.
`analyzer`	`NellieAnalysis`	The analysis tab instance, enabling users to analyze processed image data.
`settings`	`Settings`	The settings tab instance, allowing users to configure various settings for the Nellie pipeline.
`home_tab, file_select_tab, processor_tab, visualizer_tab, analysis_tab, settings_tab`	`int`	Integer values representing the index of the respective tabs.
`im_info`	`ImInfo or None`	Contains metadata and information about the selected image file.
`im_info_list`	`list of ImInfo or None`	A list of ImInfo objects when batch processing is enabled (multiple files).

Methods:

Name	Description
`add_tabs`	Adds the individual tabs to the widget.
`reset`	Resets the state of the loader, removing and reinitializing all tabs.
`on_tab_change`	Slot that is triggered when the user changes the tab.
`go_process`	Initializes and enables the processing and visualization tabs for image processing.

Initialize the NellieLoader class, creating instances of the individual tabs for home, file selection, processing, visualization, analysis, and settings.

Parameters:

Name	Type	Description	Default
`napari_viewer`	`Viewer`	Reference to the napari viewer instance.	required
`parent`	`QWidget`	Optional parent widget (default is None).	`None`

on_version_checked

on_version_checked(current_version, latest_version)

Slot called when the version check worker finishes. Update the version info and the Home tab status.

add_tabs

add_tabs()

Add the individual tabs for Home, File validation, Process, Visualize, Analyze, and Settings. Initially disables the Process, Visualize, and Analyze tabs until they are needed.

reset

reset()

Reset the state of the loader, reinitializing all tabs. This method is typically called when the user wants to start a new session with a fresh file selection and settings.

on_tab_change

on_tab_change(index)

Event handler that is triggered when the user changes the active tab. Initializes the Analyze or Visualize tabs if they are selected for the first time, and initializes the Settings tab when selected.

Parameters:

Name	Type	Description	Default
`index`	`int`	The index of the newly selected tab.	required

go_process

go_process()

Prepare the image(s) for processing and visualization. This method is called after a file has been selected and validated. It enables the Process and Visualize tabs and initializes them.

NellieAnalysis

NellieAnalysis(napari_viewer, nellie, parent=None)

Bases: QWidget

A class for analyzing and visualizing multi-dimensional microscopy data using histograms, graphs, and overlays in the napari viewer.

Initialize the NellieAnalysis widget.

Parameters:

Name	Type	Description	Default
`napari_viewer`	`Viewer`	The napari viewer instance.	required
`nellie`	`object`	The main Nellie plugin instance.	required
`parent`	`QWidget`	The parent widget, by default None.	`None`

reset

reset()

Reset internal state so the widget can be reused for a new dataset.

post_init

post_init()

Initialize UI elements and connect them to their event handlers. Must be called once after construction, when 'nellie' and 'viewer' are ready.

set_default_dropdowns

set_default_dropdowns()

Set default values for the hierarchy level and attribute dropdowns.

check_for_adjacency_map

check_for_adjacency_map()

Check whether an adjacency map exists; if not, disable the overlay button.

rewrite_dropdown

rewrite_dropdown()

Update the hierarchy level dropdown based on available data.

export_data

export_data()

Export the current graph data as a CSV file to the graph directory.

save_graph

save_graph()

Save the current graph as a PNG file to the graph directory.

on_hist_change

on_hist_change(event)

Called when histogram ranges or bin count change.

Parameters:

Name	Type	Description	Default
`event`	`Any`	The event that triggered the change (unused).	required

get_index

get_index(layer, event)

Retrieve indices of voxel and mapped features based on mouse position.

Parameters:

Name	Type	Description	Default
`layer`	`Layer`	The layer that was clicked.	required
`event`	`Any`	The mouse event containing the position.	required

overlay

overlay()

Apply an overlay of attribute data onto the image in the napari viewer, using adjacency maps to map higher-level features to voxels.

on_t_change

on_t_change(event)

Called when the current timepoint changes in the viewer.

Parameters:

Name	Type	Description	Default
`event`	`Any`	The event that triggered the change.	required

toggle_match_t

toggle_match_t(state)

Toggle whether to pool across all timepoints or use the current one.

Parameters:

Name	Type	Description	Default
`state`	`int`	The state of the checkbox (Qt.Checked or Qt.Unchecked).	required

toggle_mean_med

toggle_mean_med(state)

Toggle between mean/std view and median/quartiles.

Parameters:

Name	Type	Description	Default
`state`	`int`	The state of the checkbox (Qt.Checked or Qt.Unchecked).	required

get_csvs

get_csvs()

Load all feature CSVs into DataFrames.

on_level_selected

on_level_selected(index)

Called when a hierarchy level is selected from the dropdown.

Parameters:

Name	Type	Description	Default
`index`	`int`	The index of the selected item.	required

on_attr_selected

on_attr_selected(index)

Called when a feature (base attribute) is selected from the dropdown.

Parameters:

Name	Type	Description	Default
`index`	`int`	The index of the selected item.	required

on_form_selected

on_form_selected(index)

Called when a statistic form (mean, std, min, max, ...) is selected.

Parameters:

Name	Type	Description	Default
`index`	`int`	The index of the selected item.	required

get_stats

get_stats()

Compute basic statistics (mean/std or quartiles) for current attribute.

draw_stats

draw_stats()

Draw statistics on the histogram plot.

plot_data

plot_data(title)

Plot the currently selected attribute data as a histogram.

Parameters:

Name	Type	Description	Default
`title`	`str`	The title for the plot.	required

on_log_scale

on_log_scale(state)

Toggle logarithmic scaling for the histogram and refresh.

Parameters:

Name	Type	Description	Default
`state`	`int`	The state of the checkbox (Qt.Checked or Qt.Unchecked).	required

NellieVisualizer

NellieVisualizer(napari_viewer, nellie, parent=None)

Bases: QWidget

The NellieVisualizer class provides an interface for visualizing different stages of the Nellie pipeline, such as raw images, preprocessed images, segmentation labels, mocap markers, and reassigned labels. It also enables track visualization for specific labels and all frame labels using napari.

Initialize the NellieVisualizer class, setting up buttons and layout for opening and visualizing images and tracks.

Parameters:

Name	Type	Description	Default
`napari_viewer`	`Viewer`	Reference to the napari viewer instance.	required
`nellie`	`object`	Reference to the Nellie instance managing the pipeline.	required
`parent`	`QWidget`	Optional parent widget (default is None).	`None`

set_ui

set_ui()

Initialize and set the layout and UI components for the NellieVisualizer. It groups the buttons for image and track visualization into separate sections and arranges them within a vertical layout.

post_init

post_init()

Post-initialization method that sets the image scale based on the image resolution, makes the scale bar visible, and updates button enabled states based on existing files.

check_3d

check_3d()

Ensure that the napari viewer is in 3D display mode if the dataset contains Z-dimension data.

set_scale

set_scale()

Set the scale for image display based on the resolution of the Z, Y, and X dimensions of the image.

open_preprocess_image

open_preprocess_image()

Open and display the preprocessed (Frangi-filtered) image in the napari viewer. Reuses an existing layer if it has already been created.

open_segment_image

open_segment_image()

Open and display the segmentation labels (skeleton relabeled and instance labels) in the napari viewer. Reuses existing layers if they have already been created.

on_track_selected

on_track_selected()

Visualize the tracks for the currently selected label in the napari viewer, based on the active image layer.

track_all

track_all()

Visualize tracks for all labels across frames in the napari viewer, based on the active image layer.

open_mocap_image

open_mocap_image()

Open and display the mocap marker image in the napari viewer. Reuses an existing layer if it has already been created.

open_reassign_image

open_reassign_image()

Open and display the reassigned branch and object labels in the napari viewer. Reuses existing layers if they have already been created.

open_raw

open_raw()

Open and display the raw image in the napari viewer. Reuses an existing layer if it has already been created.

check_file_existence

check_file_existence()

Check for the existence of files related to different steps of the pipeline, enabling or disabling buttons accordingly.

Settings

Settings(napari_viewer, nellie, parent=None)

Bases: QWidget

The Settings class provides a user interface for configuring various options and settings for the Nellie pipeline and visualizations. Users can enable or disable specific processing options, control track visualization settings, and configure voxel visualization parameters.

Initialize the Settings class, setting up the user interface and options for configuring processing and track visualization.

Parameters:

Name	Type	Description	Default
`napari_viewer`	`Viewer`	Reference to the napari viewer instance.	required
`nellie`	`object`	Reference to the Nellie instance that manages the pipeline.	required
`parent`	`QWidget`	Optional parent widget (default is None).	`None`

post_init

post_init()

Post-initialization method that sets the initialized flag to True.

This can be called by the plugin infrastructure once all external components are set up and the Settings widget is fully integrated.

set_ui

set_ui()

Initialize and set the layout and UI components for the Settings class. This includes checkboxes for configuring the processing pipeline and track visualization options, as well as advanced per-step parameters.

to_config

to_config()

Return the current UI state as a SettingsConfig dataclass.

Returns:

Type	Description
`SettingsConfig`	Dataclass capturing the current configuration of the settings widget.

apply_config

apply_config(config)

Apply a SettingsConfig instance to the UI.

Parameters:

Name	Type	Description	Default
`config`	`SettingsConfig`	Configuration to apply to the UI.	required

Home

Home(napari_viewer, nellie, parent=None)

Bases: QWidget

The Home screen for the Nellie application, displayed in the napari viewer. It provides options to start using the application, navigate to the file selection tab, and take screenshots.

Attributes:

Name	Type	Description
`viewer`	`Viewer`	The napari viewer instance.
`nellie`	`object`	Reference to the main Nellie object containing image processing pipelines and functions.
`layout`	`QVBoxLayout`	The vertical layout to organize the widgets on the home screen.
`start_button`	`QPushButton`	Button to start the application and navigate to the file selection tab.
`screenshot_button`	`QPushButton`	Button to take a screenshot of the current napari viewer canvas.

Methods:

Name	Description
`set_update_status`	Updates the label that reports the version / update status.
`screenshot`	Takes a screenshot of the napari viewer and saves it to a specified folder.

Initialize the Home screen with a logo, title, description, and buttons for navigation and screenshot functionality.

Parameters:

Name	Type	Description	Default
`napari_viewer`	`Viewer`	Reference to the napari viewer instance.	required
`nellie`	`object`	Reference to the main Nellie object containing image processing pipelines and functions.	required
`parent`	`QWidget`	Optional parent widget (default is None).	`None`

set_update_status

set_update_status()

Check if the plugin is up to date by comparing the installed version with the latest version on PyPI. If an update is available, it displays a warning to the user.

screenshot

screenshot(checked=False)

Take a screenshot of the napari viewer and saves it as a PNG file in a specified folder.

Parameters:

Name	Type	Description	Default
`checked`	`bool`	Parameter provided by the QPushButton clicked signal. Ignored.	`False`

NellieFileSelect

NellieFileSelect(napari_viewer, nellie, parent=None)

Bases: QWidget

A class for selecting and configuring image files for processing in the Nellie pipeline within the napari viewer.

Attributes:

Name	Type	Description
`viewer`	`Viewer`	The napari viewer instance.
`nellie`	`object`	Reference to the main Nellie object containing image processing pipelines and functions.
`filepath`	`str or None`	The selected file or folder path.
`file_info`	`FileInfo or None`	Stores metadata and shape information about the currently active image file.
`im_info`	`ImInfo or list[ImInfo] or None`	Information object(s) for the image file(s) after confirmation / OME-TIFF creation.
`batch_fileinfo_list`	`list[FileInfo] or None`	List of FileInfo objects when a folder is selected for batch processing.
`filepath_text`	`QLabel`	Text widget displaying the selected file or folder path.
`filepath_button`	`QPushButton`	Button to open the file dialog for selecting an image file.
`folder_button`	`QPushButton`	Button to open the folder dialog for batch processing.
`reset_button`	`QPushButton`	Button to reset the file selection and clear all settings (via nellie.reset()).
`file_shape_text`	`QLabel`	Displays the shape of the selected image file.
`current_order_text`	`QLabel`	Displays the current dimension order (axes) of the image file.
`dim_order_button`	`QLineEdit`	Input field for entering the dimension order of the image.
`dim_t_button, dim_z_button, dim_xy_button`	`QLineEdit`	Input fields for entering the resolution of the time (T), Z, and XY dimensions, respectively.
`channel_button`	`QSpinBox`	Spin box for selecting the channel in the multi-channel image (0-based index).
`start_frame_button, end_frame_button`	`QSpinBox`	Spin boxes for selecting the start and end frame (0-based indices) for temporal range selection.
`confirm_button`	`QPushButton`	Button to confirm the file selection and save the OME-TIFF file(s).
`preview_button`	`QPushButton`	Button to preview the image in the napari viewer.
`process_button`	`QPushButton`	Button to process the selected image file(s) through the Nellie pipeline.

Initialize the NellieFileSelect class.

Parameters:

Name	Type	Description	Default
`napari_viewer`	`Viewer`	Reference to the napari viewer instance.	required
`nellie`	`object`	Reference to the main Nellie object containing image processing pipelines and functions.	required
`parent`	`QWidget`	Optional parent widget (default is None).	`None`

init_ui

init_ui()

Set up the user interface layout with sections for file selection, axes information, dimension resolutions, slice settings, and action buttons.

select_filepath

select_filepath()

Open a file dialog for selecting an image file, validates the selected file, and updates the UI with metadata.

select_folder

select_folder()

Open a folder dialog for selecting a folder for batch processing and initializes FileInfo objects for all files in the folder.

validate_path

validate_path(filepath)

Validate the selected file or folder path and updates the file path attribute. Canceling the dialog is treated as a no-op.

Parameters:

Name	Type	Description	Default
`filepath`	`str`	The file or folder path selected by the user.	required

Returns:

Type	Description
`bool`	True if a valid path was selected, False otherwise.

initialize_single_file

initialize_single_file(metadata_already_loaded=False, reset_overrides=False)

Initialize the FileInfo object for the selected image file, loads metadata, and updates the dimension resolution fields.

Parameters:

Name	Type	Description	Default
`metadata_already_loaded`	`bool`	If True, skip calling find_metadata/load_metadata (used for batch initialization where metadata was already loaded).	`False`
`reset_overrides`	`bool`	If True, clear any user-entered overrides so metadata-derived values are used for the new selection.	`False`

initialize_folder

initialize_folder()

Initialize FileInfo objects for all .tif, .tiff, and .nd2 files in the selected folder and loads their metadata.

Returns:

Type	Description
`bool`	True if at least one compatible file was found and initialized, False otherwise.

on_change

on_change()

Update the user interface elements, including enabling or disabling buttons based on the file metadata and resolution settings.

check_available_dims

check_available_dims()

Check the availability of specific dimensions (T, Z, XY) in the selected file and enables the corresponding input fields for resolutions.

handle_dim_order_changed

handle_dim_order_changed()

Handle changes in the dimension order input field and updates the FileInfo object(s) accordingly.

handle_axes_combo_changed

handle_axes_combo_changed(_text)

Handle axes updates from the combo boxes.

handle_t_changed

handle_t_changed()

Handle changes in the time (T) resolution input field and updates the FileInfo object(s) accordingly.

handle_z_changed

handle_z_changed()

Handle changes in the Z resolution input field and updates the FileInfo object(s) accordingly.

handle_xy_changed

handle_xy_changed()

Handle changes in the XY resolution input field and updates the FileInfo object(s) accordingly.

change_channel

change_channel()

Update the selected channel in the FileInfo object(s) when the channel spin box value is changed.

change_time

change_time()

Update the temporal range in the FileInfo object(s) when the start or end frame spin box values are changed.

on_confirm

on_confirm()

Confirm the file selection, creates ImInfo object(s) for the file(s), and prepares them for processing (creating OME-TIFF files).

on_process

on_process()

Prepare the selected file(s) for processing through the Nellie pipeline by creating ImInfo object(s) and switching to the processing tab.

on_preview

on_preview()

Open a preview of the selected image in the napari viewer, adjusting display settings (e.g., 2D or 3D view) based on the file's dimensionality.