celldetective 1.2.0__py3-none-any.whl → 1.2.2__py3-none-any.whl

celldetective/gui/gui_utils.py

@@ -1,27 +1,98 @@
 import numpy as np
 from PyQt5.QtWidgets import QApplication, QMessageBox, QFrame, QSizePolicy, QWidget, QLineEdit, QListWidget, QVBoxLayout, QComboBox, \
-	QPushButton, QLabel, QHBoxLayout, QCheckBox, QButtonGroup, QRadioButton, QGridLayout, QSpacerItem
-from PyQt5.QtCore import QEvent, Qt, QSize
+	QPushButton, QLabel, QHBoxLayout, QCheckBox, QFileDialog
+from PyQt5.QtCore import Qt, QSize
 from PyQt5.QtGui import QDoubleValidator, QIntValidator
 
+from celldetective.gui import Styles
+from superqt.fonticon import icon
+from fonticon_mdi6 import MDI6
+
 from matplotlib.backends.backend_qt5agg import FigureCanvasQTAgg
 from matplotlib.backends.backend_qt5agg import NavigationToolbar2QT
 import matplotlib.pyplot as plt
 import celldetective.extra_properties as extra_properties
 from inspect import getmembers, isfunction
-from superqt import QLabeledDoubleRangeSlider, QLabeledSlider, QLabeledDoubleSlider
-from superqt.fonticon import icon
-from fonticon_mdi6 import MDI6
-
-from celldetective.io import auto_load_number_of_frames, load_frames
-from celldetective.utils import _extract_channel_indices_from_config
 from celldetective.filters import *
-from celldetective.segmentation import filter_image
-from stardist import fill_label_holes
+from os import sep
+
+
+class QuickSliderLayout(QHBoxLayout):
+	
+	"""
+	A layout class that combines a QLabel and a QSlider in a horizontal box layout.
+
+	This layout provides a convenient way to include a slider with an optional label and configurable 
+	parameters such as range, precision, and step size. It allows for both integer and decimal step values, 
+	making it versatile for different types of input adjustments.
+
+	Parameters
+	----------
+	label : str, optional
+		The label to be displayed next to the slider (default is None).
+	slider : QSlider
+		The slider widget to be added to the layout.
+	layout_ratio : tuple of float, optional
+		Defines the width ratio between the label and the slider in the layout. The first element is the 
+		ratio for the label, and the second is for the slider (default is (0.25, 0.75)).
+	slider_initial_value : int or float, optional
+		The initial value to set for the slider (default is 1).
+	slider_range : tuple of int or float, optional
+		A tuple specifying the minimum and maximum values for the slider (default is (0, 1)).
+	slider_tooltip : str, optional
+		Tooltip text to display when hovering over the slider (default is None).
+	decimal_option : bool, optional
+		If True, the slider allows decimal values with a specified precision (default is True).
+	precision : float, optional
+		The step size for the slider when `decimal_option` is enabled (default is 1.0E-03).
+	
+	Attributes
+	----------
+	qlabel : QLabel
+		The label widget that displays the provided label text (only if `label` is provided).
+	slider : QSlider
+		The slider widget that allows the user to select a value.
+	"""
+
+	def __init__(self, label=None, slider=None, layout_ratio=(0.25,0.75), slider_initial_value=1, slider_range=(0,1), slider_tooltip=None, decimal_option=True, precision=1.0E-03, *args):
+		super().__init__(*args)
+
+		if label is not None and isinstance(label,str):
+			self.qlabel = QLabel(label)
+			self.addWidget(self.qlabel, int(100*layout_ratio[0]))
+
+		self.slider = slider
+		self.slider.setOrientation(1)
+		if decimal_option:
+			self.slider.setSingleStep(precision)
+			self.slider.setTickInterval(precision)
+		else:
+			self.slider.setSingleStep(1)
+			self.slider.setTickInterval(1)
+
+		self.slider.setRange(*slider_range)
+		self.slider.setValue(slider_initial_value)
+		if isinstance(slider_tooltip,str):
+			self.slider.setToolTip(slider_tooltip)
+
+		self.addWidget(self.slider, int(100*layout_ratio[1]))
+
 
 def center_window(window):
+
 	"""
-	Center window in the middle of the screen.
+	Centers the given window in the middle of the screen.
+
+	This function calculates the current screen's geometry and moves the 
+	specified window to the center of the screen. It works by retrieving the 
+	frame geometry of the window, identifying the screen where the cursor is 
+	currently located, and adjusting the window's position to be centrally 
+	aligned on that screen.
+
+	Parameters
+	----------
+	window : QMainWindow or QWidget
+		The window or widget to be centered on the screen.
 	"""
 
 	frameGm = window.frameGeometry()
@@ -30,6 +101,75 @@ def center_window(window):
 	frameGm.moveCenter(centerPoint)
 	window.move(frameGm.topLeft())
 
+class ExportPlotBtn(QPushButton, Styles):
+	
+	"""
+	A custom QPushButton widget for exporting a matplotlib figure.
+
+	This class combines a QPushButton with functionality to export a given matplotlib 
+	figure (`fig`) to an image file. The button includes an icon and a tooltip for easy 
+	user interaction. When clicked, a file dialog is opened allowing the user to specify 
+	the location and file format to save the plot.
+
+	Parameters
+	----------
+	fig : matplotlib.figure.Figure
+		The matplotlib figure object to be exported.
+	export_dir : str, optional
+		The default directory where the file will be saved. If not provided, the current 
+		working directory will be used.
+	*args : tuple
+		Additional positional arguments passed to the parent `QPushButton` constructor.
+	**kwargs : dict
+		Additional keyword arguments passed to the parent `QPushButton` constructor.
+
+	Attributes
+	----------
+	fig : matplotlib.figure.Figure
+		The figure that will be saved when the button is clicked.
+	export_dir : str or None
+		The default directory where the file dialog will initially point when saving the image.
+
+	Methods
+	-------
+	save_plot():
+		Opens a file dialog to choose the file name and location for saving the figure.
+		The figure is then saved in the specified format and location.
+	"""
+
+	def __init__(self, fig, export_dir=None, *args, **kwargs):
+
+		super().__init__()
+
+		self.export_dir = export_dir
+		self.fig = fig
+
+		self.setText('')
+		self.setIcon(icon(MDI6.content_save,color="black"))
+		self.setStyleSheet(self.button_select_all)
+		self.setToolTip('Export figure.')
+		self.setIconSize(QSize(20, 20))
+		self.clicked.connect(self.save_plot)
+	
+	def save_plot(self):
+
+		"""
+		Opens a file dialog for the user to specify the location and name to save the plot.
+
+		If the user selects a file, the figure is saved with tight layout and 300 DPI resolution.
+		Supported formats include PNG, JPG, SVG, and XPM.
+		"""
+
+		if self.export_dir is not None:
+			guess_dir = self.export_dir+sep+'plot.png'
+		else:
+			guess_dir = 'plot.png'
+		fileName, _ = QFileDialog.getSaveFileName(self, 
+			"Save Image", guess_dir, "Images (*.png *.xpm *.jpg *.svg)") #, options=options
+		if fileName:
+			self.fig.tight_layout()
+			self.fig.savefig(fileName, bbox_inches='tight', dpi=300)
+
 
 class QHSeperationLine(QFrame):
 	'''
@@ -323,19 +463,58 @@ class DistanceChoice(QWidget):
 
 
 class ListWidget(QWidget):
+
 	"""
-	Generic list widget.
+	A customizable widget for displaying and managing a list of items, with the 
+	ability to add and remove items interactively.
+
+	This widget is built around a `QListWidget` and allows for initialization with 
+	a set of features. It also provides options to retrieve the items, add new items 
+	using a custom widget, and remove selected items. The items can be parsed and 
+	returned as a list, with support for various data types and formatted input (e.g., 
+	ranges specified with a dash).
+
+	Parameters
+	----------
+	choiceWidget : QWidget
+		A custom widget that is used to add new items to the list.
+	initial_features : list
+		A list of initial items to populate the list widget.
+	dtype : type, optional
+		The data type to cast the list items to. Default is `str`.
+
+	Attributes
+	----------
+	initial_features : list
+		The initial set of features or items displayed in the list.
+	choiceWidget : QWidget
+		The widget used to prompt the user to add new items.
+	dtype : type
+		The data type to convert items into when retrieved from the list.
+	items : list
+		A list to store the current items in the list widget.
+	list_widget : QListWidget
+		The core Qt widget that displays the list of items.
+
+	Methods
+	-------
+	addItem()
+		Opens a new window to add an item to the list using the custom `choiceWidget`.
+	getItems()
+		Retrieves the items from the list widget, parsing ranges (e.g., 'min-max') 
+		into two values, and converts them to the specified `dtype`.
+	removeSel()
+		Removes the currently selected item(s) from the list widget and updates the 
+		internal `items` list accordingly.
 	"""
 
-	def __init__(self, parent_window, choiceWidget, initial_features, dtype=str, channel_names=None):
+	def __init__(self, choiceWidget, initial_features, dtype=str, *args, **kwargs):
 
 		super().__init__()
-		self.parent_window = parent_window
 		self.initial_features = initial_features
 		self.choiceWidget = choiceWidget
 		self.dtype = dtype
 		self.items = []
-		self.channel_names=channel_names
 
 		self.setFixedHeight(80)
 
@@ -347,11 +526,12 @@ class ListWidget(QWidget):
 		main_layout = QVBoxLayout()
 		main_layout.addWidget(self.list_widget)
 		self.setLayout(main_layout)
+		center_window(self)
 
 	def addItem(self):
 
 		"""
-		Add a new item.
+		Opens the custom choiceWidget to add a new item to the list.
 		"""
 
 		self.addItemWindow = self.choiceWidget(self)
@@ -360,7 +540,15 @@ class ListWidget(QWidget):
 	def getItems(self):
 
 		"""
-		Get all the items as a list.
+		Retrieves and returns the items from the list widget.
+
+		This method parses any items that contain a range (formatted as 'min-max') 
+		into a list of two values, and casts all items to the specified `dtype`.
+
+		Returns
+		-------
+		list
+			A list of the items in the list widget, with ranges split into two values.
 		"""
 
 		items = []
@@ -377,11 +565,13 @@ class ListWidget(QWidget):
 		return items
 
 
-
 	def removeSel(self):
-
+		
 		"""
-		Remove selected items.
+		Removes the selected item(s) from the list widget.
+
+		If there are any selected items, they are removed both from the visual list 
+		and the internal `items` list that tracks the current state of the widget.
 		"""
 
 		listItems = self.list_widget.selectedItems()
@@ -424,38 +614,46 @@ class FigureCanvas(QWidget):
 		plt.close(self.fig)
 		super(FigureCanvas, self).closeEvent(event)
 
-
-class QuickSliderLayout(QHBoxLayout):
-	
-	"""docstring for ClassName"""
-	
-	def __init__(self, label=None, slider=None, layout_ratio=(0.25,0.75), slider_initial_value=1, slider_range=(0,1), slider_tooltip=None, decimal_option=True, precision=1.0E-03, *args):
-		super().__init__(*args)
-
-		if label is not None and isinstance(label,str):
-			self.qlabel = QLabel(label)
-			self.addWidget(self.qlabel, int(100*layout_ratio[0]))
-
-		self.slider = slider
-		self.slider.setOrientation(1)
-		if decimal_option:
-			self.slider.setSingleStep(precision)
-			self.slider.setTickInterval(precision)
-		else:
-			self.slider.setSingleStep(1)
-			self.slider.setTickInterval(1)
-
-		self.slider.setRange(*slider_range)
-		self.slider.setValue(slider_initial_value)
-		if isinstance(slider_tooltip,str):
-			self.slider.setToolTip(slider_tooltip)
-
-		self.addWidget(self.slider, int(100*layout_ratio[1]))
-
 class ThresholdLineEdit(QLineEdit):
 	
-	"""docstring for ClassName"""
+	"""
+	A custom QLineEdit widget to manage and validate threshold values.
+
+	This class extends QLineEdit to input and manage threshold values (either float or int), 
+	with optional validation and interaction with connected QPushButtons. The widget can 
+	validate the input and enable/disable buttons based on whether a valid threshold is set.
+
+	Parameters
+	----------
+	init_value : float or int, optional
+		The initial threshold value to display in the input field (default is 2.0).
+	connected_buttons : QPushButton or list of QPushButton, optional
+		QPushButton(s) that should be enabled/disabled based on the validity of the threshold 
+		value (default is None).
+	placeholder : str, optional
+		Placeholder text to show when no value is entered in the input field 
+		(default is 'px > thresh are masked').
+	value_type : str, optional
+		Specifies the type of threshold value, either 'float' or 'int' (default is 'float').
+
+	Methods
+	-------
+	enable_btn():
+		Enables or disables connected QPushButtons based on the validity of the threshold value.
+	set_threshold(value):
+		Sets the input field to the given threshold value.
+	get_threshold(show_warning=True):
+		Retrieves the current threshold value from the input field, returning it as a float or int.
+		If invalid, optionally displays a warning dialog.
+
+	Example
+	-------
+	>>> threshold_input = ThresholdLineEdit(init_value=5, value_type='int')
+	>>> print(threshold_input.get_threshold())
+	5
+	"""
 	
+
 	def __init__(self, init_value=2.0, connected_buttons=None, placeholder='px > thresh are masked',value_type='float',*args):
 		super().__init__(*args)
 
@@ -472,11 +670,17 @@ class ThresholdLineEdit(QLineEdit):
 
 		if self.connected_buttons is not None:
 			self.textChanged.connect(self.enable_btn)
-		print("init value of ",self.init_value," for threshold LE")
 		self.set_threshold(self.init_value)
 
 	def enable_btn(self):
 
+		"""
+		Enable or disable connected QPushButtons based on the threshold value.
+
+		If the current threshold value is valid, the connected buttons will be enabled.
+		If the value is invalid or empty, the buttons will be disabled.
+		"""
+
 		thresh = self.get_threshold(show_warning=False)
 		if isinstance(self.connected_buttons, QPushButton):
 			cbs = [self.connected_buttons]
@@ -492,6 +696,15 @@ class ThresholdLineEdit(QLineEdit):
 
 	def set_threshold(self, value):
 
+		"""
+		Set the input field to the specified threshold value.
+
+		Parameters
+		----------
+		value : float or int
+			The value to set in the input field.
+		"""
+
 		try:
 			self.setText(str(value).replace('.',','))
 		except:
@@ -499,6 +712,23 @@ class ThresholdLineEdit(QLineEdit):
 
 	def get_threshold(self, show_warning=True):
 		
+		"""
+		Retrieve the current threshold value from the input field.
+
+		Converts the value to a float or int based on the `value_type` attribute. If the value
+		is invalid and `show_warning` is True, a warning dialog is shown.
+
+		Parameters
+		----------
+		show_warning : bool, optional
+			If True, show a warning dialog if the value is invalid (default is True).
+
+		Returns
+		-------
+		float or int or None
+			The threshold value as a float or int, or None if the value is invalid.
+		"""
+
 		try:
 			if self.value_type=='float':
 				thresh = float(self.text().replace(',','.'))
@@ -517,176 +747,6 @@ class ThresholdLineEdit(QLineEdit):
 
 		return thresh
 
-# class BackgroundFitCorrectionLayout(QGridLayout):
-	
-# 	"""docstring for ClassName"""
-	
-# 	def __init__(self, parent=None, *args):
-# 		super().__init__(*args)
-
-# 		self.parent = parent
-# 		self.channel_names = self.parent.channel_names # check this
-
-# 		self.setContentsMargins(15,15,15,15)
-# 		self.generate_widgets()
-# 		self.add_to_layout()
-
-# 	def generate_widgets(self):
-
-# 		self.channel_lbl = QLabel('Channel: ')
-# 		self.channels_cb = QComboBox()
-# 		self.channels_cb.addItems(self.channel_names)
-		
-# 		self.thresh_lbl = QLabel('Threshold: ')
-# 		self.thresh_lbl.setToolTip('Threshold on the STD-filtered image.\nPixel values above the threshold are\nconsidered as non-background and are\nmasked prior to background estimation.')
-# 		self.threshold_viewer_btn = QPushButton()
-# 		self.threshold_viewer_btn.setIcon(icon(MDI6.image_check, color="k"))
-# 		self.threshold_viewer_btn.setStyleSheet(self.parent.parent.parent.button_select_all)
-# 		self.threshold_viewer_btn.clicked.connect(self.set_threshold_graphically)
-
-# 		self.model_lbl = QLabel('Model: ')
-# 		self.models_cb = QComboBox()
-# 		self.models_cb.addItems(['Paraboloid', 'Place'])
-		
-# 		self.operation_lbl = QLabel('Operation: ')
-# 		self.operation_group = QButtonGroup()
-# 		self.subtract_btn = QRadioButton('Subtract')
-# 		self.divide_btn = QRadioButton('Divide')
-# 		self.subtract_btn.toggled.connect(self.activate_clipping_options)
-# 		self.divide_btn.toggled.connect(self.activate_clipping_options)
-
-# 		self.operation_group.addButton(self.subtract_btn)
-# 		self.operation_group.addButton(self.divide_btn)
-
-# 		self.clip_group = QButtonGroup()
-# 		self.clip_btn = QRadioButton('Clip')
-# 		self.clip_not_btn = QRadioButton('Do not clip')
-
-# 		self.clip_group.addButton(self.clip_btn)
-# 		self.clip_group.addButton(self.clip_not_btn)
-
-# 		self.corrected_stack_viewer = QPushButton("")
-# 		self.corrected_stack_viewer.setStyleSheet(self.parent.parent.parent.button_select_all)
-# 		self.corrected_stack_viewer.setIcon(icon(MDI6.eye_outline, color="black"))
-# 		self.corrected_stack_viewer.setToolTip("View corrected image")
-# 		self.corrected_stack_viewer.setIconSize(QSize(20, 20))
-
-# 		self.add_correction_btn = QPushButton('Add correction')
-# 		self.add_correction_btn.setStyleSheet(self.parent.parent.parent.button_style_sheet_2)
-# 		self.add_correction_btn.setIcon(icon(MDI6.plus, color="#1565c0"))
-# 		self.add_correction_btn.setToolTip('Add correction.')
-# 		self.add_correction_btn.setIconSize(QSize(25, 25))
-# 		self.add_correction_btn.clicked.connect(self.add_instructions_to_parent_list)
-
-# 		self.threshold_le = ThresholdLineEdit(init_value=2, connected_buttons=[self.threshold_viewer_btn,
-# 																			   self.corrected_stack_viewer,
-# 																			   self.add_correction_btn
-# 																			   ])
-
-# 	def add_to_layout(self):
-		
-# 		channel_layout = QHBoxLayout()
-# 		channel_layout.addWidget(self.channel_lbl, 25)
-# 		channel_layout.addWidget(self.channels_cb, 75)
-# 		self.addLayout(channel_layout, 0, 0, 1, 3)
-
-# 		threshold_layout = QHBoxLayout()
-# 		threshold_layout.addWidget(self.thresh_lbl, 25)
-# 		threshold_layout.addWidget(self.threshold_le, 70)
-# 		threshold_layout.addWidget(self.threshold_viewer_btn, 5)
-# 		self.addLayout(threshold_layout, 1, 0, 1, 3)
-
-# 		model_layout = QHBoxLayout()
-# 		model_layout.addWidget(self.model_lbl, 25)
-# 		model_layout.addWidget(self.models_cb, 75)
-# 		self.addLayout(model_layout, 2, 0, 1, 3)
-
-# 		operation_layout = QHBoxLayout()
-# 		operation_layout.addWidget(self.operation_lbl, 25)
-# 		operation_layout.addWidget(self.subtract_btn, 75//2, alignment=Qt.AlignCenter)
-# 		operation_layout.addWidget(self.divide_btn, 75//2, alignment=Qt.AlignCenter)
-# 		self.addLayout(operation_layout, 3, 0, 1, 3)
-
-# 		clip_layout = QHBoxLayout()
-# 		clip_layout.addWidget(QLabel(''), 25)
-# 		clip_layout.addWidget(self.clip_btn, 75//4, alignment=Qt.AlignCenter)
-# 		clip_layout.addWidget(self.clip_not_btn, 75//4, alignment=Qt.AlignCenter)
-# 		clip_layout.addWidget(QLabel(''), 75//2)
-# 		self.addLayout(clip_layout, 4, 0, 1, 3)
-
-# 		self.addWidget(self.corrected_stack_viewer, 4, 2, 1, 1)
-# 		self.addWidget(self.add_correction_btn, 5, 0, 1, 3)
-
-# 		self.subtract_btn.click()
-# 		self.clip_not_btn.click()
-
-# 		verticalSpacer = QSpacerItem(20, 40, QSizePolicy.Minimum, QSizePolicy.Expanding)
-# 		self.addItem(verticalSpacer, 5, 0, 1, 3)
-
-# 	def add_instructions_to_parent_list(self):
-
-# 		self.generate_instructions()
-# 		self.parent.background_correction.append(self.instructions)
-# 		correction_description = ""
-# 		for index, (key, value) in enumerate(self.instructions.items()):
-# 			if index > 0:
-# 				correction_description += ", "
-# 			correction_description += str(key) + " : " + str(value)
-# 		self.parent.normalisation_list.addItem(correction_description)
-
-# 	def generate_instructions(self):
-
-# 		if self.subtract_btn.isChecked():
-# 			operation = "subtract"
-# 		else:
-# 			operation = "divide"
-# 			clip = None
-
-# 		if self.clip_btn.isChecked() and self.subtract_btn.isChecked():
-# 			clip = True
-# 		else:
-# 			clip = False
-
-# 		self.instructions = {
-# 					  "target_channel": self.channels_cb.currentText(),
-# 					  "correction_type": "fit",
-# 					  "threshold_on_std": self.threshold_le.get_threshold(),
-# 					  "operation": operation,
-# 					  "clip": clip
-# 					 }
-
-# 	def activate_clipping_options(self):
-		
-# 		if self.subtract_btn.isChecked():
-# 			self.clip_btn.setEnabled(True)
-# 			self.clip_not_btn.setEnabled(True)
-
-# 		else:
-# 			self.clip_btn.setEnabled(False)
-# 			self.clip_not_btn.setEnabled(False)		
-
-# 	def set_target_channel(self):
-
-# 		channel_indices = _extract_channel_indices_from_config(self.parent.parent.exp_config, [self.channels_cb.currentText()])
-# 		self.target_channel = channel_indices[0]
-
-# 	def set_threshold_graphically(self):
-
-# 		self.parent.locate_image()
-# 		self.set_target_channel()
-# 		thresh = self.threshold_le.get_threshold()
-
-# 		if self.parent.current_stack is not None and thresh is not None:
-# 			self.viewer = ThresholdedStackVisualizer(initial_threshold=thresh,
-# 													 parent_le = self.threshold_le,
-# 													 preprocessing=[['gauss',2],["std",4]],
-# 													 stack_path=self.parent.current_stack,
-# 													 n_channels=len(self.channel_names),
-# 													 target_channel=self.target_channel,
-# 													 window_title='Set the exclusion threshold',
-# 													 )
-# 			self.viewer.show()
-
 
 def color_from_status(status, recently_modified=False):
 	if not recently_modified:
@@ -708,19 +768,40 @@ def color_from_status(status, recently_modified=False):
 		else:
 			return 'k'
 
-def color_from_state(state, recently_modified=False):
+def color_from_state(state):
+
+	"""
+	Generate a color map based on unique values in the provided state array.
+
+	This function creates a mapping between the unique values found in the `state` array 
+	and colors from the `tab10` colormap in Matplotlib. A special condition is applied 
+	to the value `99`, which is assigned the color black ('k').
+
+	Parameters
+	----------
+	state : array-like
+		An array or list of state values to be used for generating the color map.
+
+	Returns
+	-------
+	dict
+		A dictionary where the keys are the unique state values from the `state` array, 
+		and the values are the corresponding colors from Matplotlib's `tab10` colormap.
+		The value `99` is mapped to the color black ('k').
+	
+	Notes
+	-----
+	- Matplotlib's `tab10` colormap is used for values other than `99`.
+	"""
+
 	unique_values = np.unique(state)
 	color_map={}
 	for value in unique_values:
 		color_map[value] = plt.cm.tab10(value)
 		if value == 99:
 			color_map[value] = 'k'
-	# colors = plt.cm.tab10(len(unique_values))
-	# color_map = dict(zip(unique_values, colors))
-	# print(color_map)
-	return color_map
-
 
+	return color_map
 
 
 def color_from_class(cclass, recently_modified=False):
@@ -771,3 +852,97 @@ class ChannelChoice(QWidget):
 		filtername = self.combo_box.currentText()
 		self.parent_window.list_widget.addItems([filtername])
 		self.close()
+
+def help_generic(tree):
+
+	"""
+	Interactively traverse a decision tree to provide user guidance based on a nested dictionary structure.
+
+	This function takes a nested dictionary representing a decision tree and guides the user through
+	it step-by-step by displaying messages for user input using the `generic_msg()` function. 
+	At each step, the user selects a key that corresponds to a further step in the tree, until a 
+	final suggestion (leaf node) is reached.
+
+	Parameters
+	----------
+	tree : dict
+		A dictionary where keys represent options and values represent either further steps (as dictionaries)
+		or a final suggestion (leaf nodes).
+
+	Returns
+	-------
+	any
+		The final suggestion or outcome after traversing the decision tree.
+
+	Example
+	-------
+	>>> decision_tree = {
+	...     'Start': {
+	...         'Option 1': {
+	...             'Sub-option 1': 'Final suggestion 1',
+	...             'Sub-option 2': 'Final suggestion 2'
+	...         },
+	...         'Option 2': 'Final suggestion 3'
+	...     }
+	... }
+	>>> result = help_generic(decision_tree)
+	# The function prompts the user to choose between "Option 1" or "Option 2", 
+	# and then proceeds through the tree based on the user's choices.
+	"""
+
+	output = generic_msg(list(tree.keys())[0])
+	while output is not None:
+		tree = tree[list(tree.keys())[0]][output]
+		if isinstance(tree,dict):
+			output = generic_msg(list(tree.keys())[0])
+		else:
+			# return the final suggestion
+			output = None
+	return tree
+
+def generic_msg(text):
+	
+	"""
+	Display a message box with a question and capture the user's response.
+
+	This function creates a message box with a `Yes`, `No`, and `Cancel` option, 
+	displaying the provided `text` as the question. It returns the user's selection as a string.
+
+	Parameters
+	----------
+	text : str
+		The message or question to display in the message box.
+
+	Returns
+	-------
+	str or None
+		The user's response: "yes" if Yes is selected, "no" if No is selected, 
+		and `None` if Cancel is selected or the dialog is closed.
+
+	Example
+	-------
+	>>> response = generic_msg("Would you like to continue?")
+	>>> if response == "yes":
+	...     print("User chose Yes")
+	... elif response == "no":
+	...     print("User chose No")
+	... else:
+	...     print("User cancelled the action")
+	
+	Notes
+	-----
+	- The message box displays a window with three options: Yes, No, and Cancel.
+	"""
+
+	msgBox = QMessageBox()
+	msgBox.setIcon(QMessageBox.Question)
+	msgBox.setText(text)
+	msgBox.setWindowTitle("Question")
+	msgBox.setStandardButtons(QMessageBox.Yes | QMessageBox.No | QMessageBox.Cancel)
+	returnValue = msgBox.exec()
+	if returnValue == QMessageBox.Yes:
+		return "yes"
+	elif returnValue == QMessageBox.No:
+		return "no"
+	else:
+		return None