celldetective 1.3.4.post1__py3-none-any.whl → 1.3.6.post1__py3-none-any.whl

celldetective/io.py

@@ -1,30 +1,65 @@
 from natsort import natsorted
+from PyQt5.QtWidgets import QMessageBox
 from glob import glob
 from tifffile import imread, TiffFile
 import numpy as np
 import os
 import pandas as pd
 import napari
+import json
+
 import gc
 from tqdm import tqdm
+import threading
+import concurrent.futures
+
 from csbdeep.utils import normalize_mi_ma
+from csbdeep.io import save_tiff_imagej_compatible
+
 import skimage.io as skio
+from skimage.measure import regionprops_table, label
+
 from scipy.ndimage import zoom
 from btrack.datasets import cell_config
 from magicgui import magicgui
-from csbdeep.io import save_tiff_imagej_compatible
 from pathlib import Path, PurePath
 from shutil import copyfile, rmtree
+
 from celldetective.utils import ConfigSectionMap, extract_experiment_channels, _extract_labels_from_config, get_zenodo_files, download_zenodo_file
-import json
-from skimage.measure import regionprops_table
-from celldetective.utils import _estimate_scale_factor, _extract_channel_indices_from_config, _extract_channel_indices, ConfigSectionMap, _extract_nbr_channels_from_config, _get_img_num_per_channel, normalize_per_channel
-from celldetective.utils import interpolate_nan
-import concurrent.futures
-from tifffile import imwrite
+from celldetective.utils import _estimate_scale_factor, _extract_channel_indices_from_config, _extract_channel_indices, _extract_nbr_channels_from_config, _get_img_num_per_channel, normalize_per_channel
+
 from stardist import fill_label_holes
 
+
 def extract_experiment_from_well(well_path):
+
+	"""
+	Extracts the experiment directory path from a given well directory path.
+
+	Parameters
+	----------
+	well_path : str
+		The file system path to a well directory. The path should end with the well folder, 
+		but it does not need to include a trailing separator.
+
+	Returns
+	-------
+	str
+		The path to the experiment directory, which is assumed to be two levels above the well directory.
+
+	Notes
+	-----
+	- This function expects the well directory to be organized such that the experiment directory is 
+	  two levels above it in the file system hierarchy.
+	- If the input path does not end with a file separator (`os.sep`), one is appended before processing.
+
+	Example
+	-------
+	>>> well_path = "/path/to/experiment/plate/well"
+	>>> extract_experiment_from_well(well_path)
+	'/path/to/experiment'
+	"""
+
 	if not well_path.endswith(os.sep):
 		well_path += os.sep
 	exp_path_blocks = well_path.split(os.sep)[:-2]
@@ -32,6 +67,35 @@ def extract_experiment_from_well(well_path):
 	return experiment
 
 def extract_well_from_position(pos_path):
+
+	"""
+	Extracts the well directory path from a given position directory path.
+
+	Parameters
+	----------
+	pos_path : str
+		The file system path to a position directory. The path should end with the position folder,
+		but it does not need to include a trailing separator.
+
+	Returns
+	-------
+	str
+		The path to the well directory, which is assumed to be two levels above the position directory,
+		with a trailing separator appended.
+
+	Notes
+	-----
+	- This function expects the position directory to be organized such that the well directory is
+	  two levels above it in the file system hierarchy.
+	- If the input path does not end with a file separator (`os.sep`), one is appended before processing.
+
+	Example
+	-------
+	>>> pos_path = "/path/to/experiment/plate/well/position"
+	>>> extract_well_from_position(pos_path)
+	'/path/to/experiment/plate/well/'
+	"""
+
 	if not pos_path.endswith(os.sep):
 		pos_path += os.sep
 	well_path_blocks = pos_path.split(os.sep)[:-2]
@@ -39,14 +103,92 @@ def extract_well_from_position(pos_path):
 	return well_path
 
 def extract_experiment_from_position(pos_path):
-	if not pos_path.endswith(os.sep):
-		pos_path += os.sep
-	exp_path_blocks = pos_path.split(os.sep)[:-3]
+
+	"""
+	Extracts the experiment directory path from a given position directory path.
+
+	Parameters
+	----------
+	pos_path : str
+		The file system path to a position directory. The path should end with the position folder,
+		but it does not need to include a trailing separator.
+
+	Returns
+	-------
+	str
+		The path to the experiment directory, which is assumed to be three levels above the position directory.
+
+	Notes
+	-----
+	- This function expects the position directory to be organized hierarchically such that the experiment directory
+	  is three levels above it in the file system hierarchy.
+	- If the input path does not end with a file separator (`os.sep`), one is appended before processing.
+
+	Example
+	-------
+	>>> pos_path = "/path/to/experiment/plate/well/position"
+	>>> extract_experiment_from_position(pos_path)
+	'/path/to/experiment'
+	"""
+
+	pos_path = pos_path.replace(os.sep, '/')
+	if not pos_path.endswith('/'):
+		pos_path += '/'
+	exp_path_blocks = pos_path.split('/')[:-3]
 	experiment = os.sep.join(exp_path_blocks)
+
 	return experiment
 
 def collect_experiment_metadata(pos_path=None, well_path=None):
 	
+	"""
+	Collects and organizes metadata for an experiment based on a given position or well directory path.
+
+	Parameters
+	----------
+	pos_path : str, optional
+		The file system path to a position directory. If provided, it will be used to extract metadata.
+		This parameter takes precedence over `well_path`.
+	well_path : str, optional
+		The file system path to a well directory. If `pos_path` is not provided, this path will be used to extract metadata.
+
+	Returns
+	-------
+	dict
+		A dictionary containing the following metadata:
+		- `"pos_path"`: The path to the position directory (or `None` if not provided).
+		- `"position"`: The same as `pos_path`.
+		- `"pos_name"`: The name of the position (or `0` if `pos_path` is not provided).
+		- `"well_path"`: The path to the well directory.
+		- `"well_name"`: The name of the well.
+		- `"well_nbr"`: The numerical identifier of the well.
+		- `"experiment"`: The path to the experiment directory.
+		- `"antibody"`: The antibody associated with the well.
+		- `"concentration"`: The concentration associated with the well.
+		- `"cell_type"`: The cell type associated with the well.
+		- `"pharmaceutical_agent"`: The pharmaceutical agent associated with the well.
+
+	Notes
+	-----
+	- At least one of `pos_path` or `well_path` must be provided.
+	- The function determines the experiment path by navigating the directory structure and extracts metadata for the 
+	  corresponding well and position.
+	- The metadata is derived using helper functions like `extract_experiment_from_position`, `extract_well_from_position`,
+	  and `get_experiment_*` family of functions.
+
+	Example
+	-------
+	>>> pos_path = "/path/to/experiment/plate/well/position"
+	>>> metadata = collect_experiment_metadata(pos_path=pos_path)
+	>>> metadata["well_name"]
+	'W1'
+
+	>>> well_path = "/path/to/experiment/plate/well"
+	>>> metadata = collect_experiment_metadata(well_path=well_path)
+	>>> metadata["concentration"]
+	10.0
+	"""
+
 	if pos_path is not None:
 		if not pos_path.endswith(os.sep):
 			pos_path += os.sep
@@ -69,7 +211,15 @@ def collect_experiment_metadata(pos_path=None, well_path=None):
 	antibodies = get_experiment_antibodies(experiment)
 	pharmaceutical_agents = get_experiment_pharmaceutical_agents(experiment)
 	
-	return {"pos_path": pos_path, "position": pos_path, "pos_name": pos_name, "well_path": well_path, "well_name": well_name, "well_nbr": well_nbr, "experiment": experiment, "antibody": antibodies[idx], "concentration": concentrations[idx], "cell_type": cell_types[idx], "pharmaceutical_agent": pharmaceutical_agents[idx]}
+	dico = {"pos_path": pos_path, "position": pos_path, "pos_name": pos_name, "well_path": well_path, "well_name": well_name, "well_nbr": well_nbr, "experiment": experiment, "antibody": antibodies[idx], "concentration": concentrations[idx], "cell_type": cell_types[idx], "pharmaceutical_agent": pharmaceutical_agents[idx]}
+
+	meta = get_experiment_metadata(experiment) # None or dict of metadata
+	if meta is not None:
+		keys = list(meta.keys())
+		for k in keys:
+			dico.update({k: meta[k]})
+	
+	return dico
 
 
 def get_experiment_wells(experiment):
@@ -109,6 +259,38 @@ def get_experiment_wells(experiment):
 
 def get_config(experiment):
 
+	"""
+	Retrieves the path to the configuration file for a given experiment.
+
+	Parameters
+	----------
+	experiment : str
+		The file system path to the experiment directory.
+
+	Returns
+	-------
+	str
+		The full path to the configuration file (`config.ini`) within the experiment directory.
+
+	Raises
+	------
+	AssertionError
+		If the `config.ini` file does not exist in the specified experiment directory.
+
+	Notes
+	-----
+	- The function ensures that the provided experiment path ends with the appropriate file separator (`os.sep`) 
+	  before appending `config.ini` to locate the configuration file.
+	- The configuration file is expected to be named `config.ini` and located at the root of the experiment directory.
+
+	Example
+	-------
+	>>> experiment = "/path/to/experiment"
+	>>> config_path = get_config(experiment)
+	>>> print(config_path)
+	'/path/to/experiment/config.ini'
+	"""
+
 	if not experiment.endswith(os.sep):
 		experiment += os.sep
 
@@ -120,7 +302,42 @@ def get_config(experiment):
 
 def get_spatial_calibration(experiment):
 	
-	
+	"""
+	Retrieves the spatial calibration factor for an experiment.
+
+	Parameters
+	----------
+	experiment : str
+		The file system path to the experiment directory.
+
+	Returns
+	-------
+	float
+		The spatial calibration factor (pixels to micrometers conversion), extracted from the experiment's configuration file.
+
+	Raises
+	------
+	AssertionError
+		If the configuration file (`config.ini`) does not exist in the specified experiment directory.
+	KeyError
+		If the "pxtoum" key is not found under the "MovieSettings" section in the configuration file.
+	ValueError
+		If the retrieved "pxtoum" value cannot be converted to a float.
+
+	Notes
+	-----
+	- The function retrieves the calibration factor by first locating the configuration file for the experiment using `get_config()`.
+	- It expects the configuration file to have a section named `MovieSettings` containing the key `pxtoum`.
+	- This factor defines the conversion from pixels to micrometers for spatial measurements.
+
+	Example
+	-------
+	>>> experiment = "/path/to/experiment"
+	>>> calibration = get_spatial_calibration(experiment)
+	>>> print(calibration)
+	0.325  # pixels-to-micrometers conversion factor
+	"""
+
 	config = get_config(experiment)
 	PxToUm = float(ConfigSectionMap(config, "MovieSettings")["pxtoum"])
 
@@ -129,14 +346,96 @@ def get_spatial_calibration(experiment):
 
 def get_temporal_calibration(experiment):
 	
+	"""
+	Retrieves the temporal calibration factor for an experiment.
+
+	Parameters
+	----------
+	experiment : str
+		The file system path to the experiment directory.
+
+	Returns
+	-------
+	float
+		The temporal calibration factor (frames to minutes conversion), extracted from the experiment's configuration file.
+
+	Raises
+	------
+	AssertionError
+		If the configuration file (`config.ini`) does not exist in the specified experiment directory.
+	KeyError
+		If the "frametomin" key is not found under the "MovieSettings" section in the configuration file.
+	ValueError
+		If the retrieved "frametomin" value cannot be converted to a float.
+
+	Notes
+	-----
+	- The function retrieves the calibration factor by locating the configuration file for the experiment using `get_config()`.
+	- It expects the configuration file to have a section named `MovieSettings` containing the key `frametomin`.
+	- This factor defines the conversion from frames to minutes for temporal measurements.
+
+	Example
+	-------
+	>>> experiment = "/path/to/experiment"
+	>>> calibration = get_temporal_calibration(experiment)
+	>>> print(calibration)
+	0.5  # frames-to-minutes conversion factor
+	"""
+
 	config = get_config(experiment)
 	FrameToMin = float(ConfigSectionMap(config, "MovieSettings")["frametomin"])
 
 	return FrameToMin
 
+def get_experiment_metadata(experiment):
+
+	config = get_config(experiment)
+	metadata = ConfigSectionMap(config, "Metadata")
+	return metadata
+
 
 def get_experiment_concentrations(experiment, dtype=str):
 	
+	"""
+	Retrieves the concentrations associated with each well in an experiment.
+
+	Parameters
+	----------
+	experiment : str
+		The file system path to the experiment directory.
+	dtype : type, optional
+		The data type to which the concentrations should be converted (default is `str`).
+
+	Returns
+	-------
+	numpy.ndarray
+		An array of concentrations for each well, converted to the specified data type.
+
+	Raises
+	------
+	AssertionError
+		If the configuration file (`config.ini`) does not exist in the specified experiment directory.
+	KeyError
+		If the "concentrations" key is not found under the "Labels" section in the configuration file.
+	ValueError
+		If the retrieved concentrations cannot be converted to the specified data type.
+
+	Notes
+	-----
+	- The function retrieves the configuration file using `get_config()` and expects a section `Labels` containing 
+	  a key `concentrations`.
+	- The concentrations are assumed to be comma-separated values.
+	- If the number of wells does not match the number of concentrations, the function generates a default set 
+	  of values ranging from 0 to the number of wells minus 1.
+	- The resulting concentrations are converted to the specified `dtype` before being returned.
+
+	Example
+	-------
+	>>> experiment = "/path/to/experiment"
+	>>> concentrations = get_experiment_concentrations(experiment, dtype=float)
+	>>> print(concentrations)
+	[0.1, 0.2, 0.5, 1.0]
+	"""
 	
 	config = get_config(experiment)
 	wells = get_experiment_wells(experiment)
@@ -150,6 +449,48 @@ def get_experiment_concentrations(experiment, dtype=str):
 
 
 def get_experiment_cell_types(experiment, dtype=str):
+
+	"""
+	Retrieves the cell types associated with each well in an experiment.
+
+	Parameters
+	----------
+	experiment : str
+		The file system path to the experiment directory.
+	dtype : type, optional
+		The data type to which the cell types should be converted (default is `str`).
+
+	Returns
+	-------
+	numpy.ndarray
+		An array of cell types for each well, converted to the specified data type.
+
+	Raises
+	------
+	AssertionError
+		If the configuration file (`config.ini`) does not exist in the specified experiment directory.
+	KeyError
+		If the "cell_types" key is not found under the "Labels" section in the configuration file.
+	ValueError
+		If the retrieved cell types cannot be converted to the specified data type.
+
+	Notes
+	-----
+	- The function retrieves the configuration file using `get_config()` and expects a section `Labels` containing 
+	  a key `cell_types`.
+	- The cell types are assumed to be comma-separated values.
+	- If the number of wells does not match the number of cell types, the function generates a default set 
+	  of values ranging from 0 to the number of wells minus 1.
+	- The resulting cell types are converted to the specified `dtype` before being returned.
+
+	Example
+	-------
+	>>> experiment = "/path/to/experiment"
+	>>> cell_types = get_experiment_cell_types(experiment, dtype=str)
+	>>> print(cell_types)
+	['TypeA', 'TypeB', 'TypeC', 'TypeD']
+	"""
+
 	config = get_config(experiment)
 	wells = get_experiment_wells(experiment)
 	nbr_of_wells = len(wells)
@@ -163,6 +504,44 @@ def get_experiment_cell_types(experiment, dtype=str):
 
 def get_experiment_antibodies(experiment, dtype=str):
 	
+	"""
+	Retrieve the list of antibodies used in an experiment.
+
+	This function extracts antibody labels for the wells in the given experiment
+	based on the configuration file. If the number of wells does not match the
+	number of antibody labels provided in the configuration, it generates a
+	sequence of default numeric labels.
+
+	Parameters
+	----------
+	experiment : str
+		The identifier or name of the experiment to retrieve antibodies for.
+	dtype : type, optional
+		The data type to which the antibody labels should be cast. Default is `str`.
+
+	Returns
+	-------
+	numpy.ndarray
+		An array of antibody labels with the specified data type. If no antibodies
+		are specified or there is a mismatch, numeric labels are generated instead.
+
+	Notes
+	-----
+	- The function assumes the experiment's configuration can be loaded using
+	  `get_config` and that the antibodies are listed under the "Labels" section
+	  with the key `"antibodies"`.
+	- A mismatch between the number of wells and antibody labels will result in
+	  numeric labels generated using `numpy.linspace`.
+
+	Examples
+	--------
+	>>> get_experiment_antibodies("path/to/experiment1")
+	array(['A1', 'A2', 'A3'], dtype='<U2')
+
+	>>> get_experiment_antibodies("path/to/experiment2", dtype=int)
+	array([0, 1, 2])
+	"""
+
 	config = get_config(experiment)
 	wells = get_experiment_wells(experiment)
 	nbr_of_wells = len(wells)
@@ -175,6 +554,48 @@ def get_experiment_antibodies(experiment, dtype=str):
 
 
 def get_experiment_pharmaceutical_agents(experiment, dtype=str):
+	
+	"""
+	Retrieves the antibodies associated with each well in an experiment.
+
+	Parameters
+	----------
+	experiment : str
+		The file system path to the experiment directory.
+	dtype : type, optional
+		The data type to which the antibodies should be converted (default is `str`).
+
+	Returns
+	-------
+	numpy.ndarray
+		An array of antibodies for each well, converted to the specified data type.
+
+	Raises
+	------
+	AssertionError
+		If the configuration file (`config.ini`) does not exist in the specified experiment directory.
+	KeyError
+		If the "antibodies" key is not found under the "Labels" section in the configuration file.
+	ValueError
+		If the retrieved antibody values cannot be converted to the specified data type.
+
+	Notes
+	-----
+	- The function retrieves the configuration file using `get_config()` and expects a section `Labels` containing 
+	  a key `antibodies`.
+	- The antibody names are assumed to be comma-separated values.
+	- If the number of wells does not match the number of antibodies, the function generates a default set 
+	  of values ranging from 0 to the number of wells minus 1.
+	- The resulting antibody names are converted to the specified `dtype` before being returned.
+
+	Example
+	-------
+	>>> experiment = "/path/to/experiment"
+	>>> antibodies = get_experiment_antibodies(experiment, dtype=str)
+	>>> print(antibodies)
+	['AntibodyA', 'AntibodyB', 'AntibodyC', 'AntibodyD']
+	"""
+
 	config = get_config(experiment)
 	wells = get_experiment_wells(experiment)
 	nbr_of_wells = len(wells)
@@ -485,59 +906,61 @@ def get_position_movie_path(pos, prefix=''):
 
 def load_experiment_tables(experiment, population='targets', well_option='*', position_option='*',
 						   return_pos_info=False, load_pickle=False):
+
 	"""
-	Loads and aggregates data tables for specified wells and positions within an experiment,
-	optionally returning position information alongside the aggregated data table.
+	Load tabular data for an experiment, optionally including position-level information.
 
-	This function collects data from tables associated with specific population types across
-	various wells and positions within an experiment. It uses the experiment's configuration
-	to gather metadata such as movie prefix, concentrations, cell types, antibodies, and
-	pharmaceutical agents. Users can specify which wells and positions to include in the
-	aggregation through pattern matching, and whether to include detailed position information
-	in the output.
+	This function retrieves and processes tables associated with positions in an experiment.
+	It supports filtering by wells and positions, and can load either CSV data or pickle files.
 
 	Parameters
 	----------
 	experiment : str
-		The path to the experiment directory.
+		Path to the experiment folder to load data for.
 	population : str, optional
-		The population type to filter the tables by (default is 'targets' among 'targets and "effectors').
-	well_option : str, optional
-		A pattern to specify which wells to include (default is '*', which includes all wells).
-	position_option : str, optional
-		A pattern to specify which positions to include (default is '*', which includes all positions).
+		The population to extract from the position tables (`'targets'` or `'effectors'`). Default is `'targets'`.
+	well_option : str or list, optional
+		Specifies which wells to include. Default is `'*'`, meaning all wells.
+	position_option : str or list, optional
+		Specifies which positions to include within selected wells. Default is `'*'`, meaning all positions.
 	return_pos_info : bool, optional
-		If True, returns a tuple where the first element is the aggregated data table and the
-		second element is detailed position information (default is False).
+		If `True`, also returns a DataFrame containing position-level metadata. Default is `False`.
+	load_pickle : bool, optional
+		If `True`, loads pre-processed pickle files for the positions instead of raw data. Default is `False`.
 
 	Returns
 	-------
-	pandas.DataFrame or (pandas.DataFrame, pandas.DataFrame)
-		If return_pos_info is False, returns a pandas DataFrame aggregating the data from the
-		specified tables. If return_pos_info is True, returns a tuple where the first element
-		is the aggregated data table and the second element is a DataFrame with detailed position
-		information.
-
-	Raises
-	------
-	FileNotFoundError
-		If the experiment directory does not exist or specified files within the directory cannot be found.
-	ValueError
-		If the specified well or position patterns do not match any directories.
+	df : pandas.DataFrame or None
+		A DataFrame containing aggregated data for the specified wells and positions, or `None` if no data is found.
+		The DataFrame includes metadata such as well and position identifiers, concentrations, antibodies, and other
+		experimental parameters.
+	df_pos_info : pandas.DataFrame, optional
+		A DataFrame with metadata for each position, including file paths and experimental details. Returned only
+		if `return_pos_info=True`.
 
 	Notes
 	-----
-	- This function assumes that the naming conventions and directory structure of the experiment
-	  follow a specific format, as outlined in the experiment's configuration file.
-	- The function utilizes several helper functions to extract metadata, interpret well and
-	  position patterns, and load individual position tables. Errors in these helper functions
-	  may propagate up and affect the behavior of this function.
+	- The function assumes the experiment's configuration includes details about movie prefixes, concentrations,
+	  cell types, antibodies, and pharmaceutical agents.
+	- Wells and positions can be filtered using `well_option` and `position_option`, respectively. If filtering
+	  fails or is invalid, those specific wells/positions are skipped.
+	- Position-level metadata is assembled into `df_pos_info` and includes paths to data and movies.
 
 	Examples
 	--------
-	>>> load_experiment_tables('/path/to/experiment', population='targets', well_option='W1', position_option='1-*')
-	# This will load and aggregate tables for the 'targets' population within well 'W1' and positions matching '1-*'.
+	Load all data for an experiment:
+
+	>>> df = load_experiment_tables("path/to/experiment1")
+
+	Load data for specific wells and positions, including position metadata:
 
+	>>> df, df_pos_info = load_experiment_tables(
+	...     "experiment_01", well_option=["A1", "B1"], position_option=[0, 1], return_pos_info=True
+	... )
+
+	Use pickle files for faster loading:
+
+	>>> df = load_experiment_tables("experiment_01", load_pickle=True)
 	"""
 
 	config = get_config(experiment)
@@ -548,6 +971,7 @@ def load_experiment_tables(experiment, population='targets', well_option='*', po
 	cell_types = get_experiment_cell_types(experiment)
 	antibodies = get_experiment_antibodies(experiment)
 	pharmaceutical_agents = get_experiment_pharmaceutical_agents(experiment)
+	metadata = get_experiment_metadata(experiment) # None or dict of metadata
 	well_labels = _extract_labels_from_config(config, len(wells))
 
 	well_indices, position_indices = interpret_wells_and_positions(experiment, well_option, position_option)
@@ -602,15 +1026,23 @@ def load_experiment_tables(experiment, population='targets', well_option='*', po
 				df_pos['antibody'] = well_antibody
 				df_pos['cell_type'] = well_cell_type
 				df_pos['pharmaceutical_agent'] = well_pharmaceutical_agent
+				if metadata is not None:
+					keys = list(metadata.keys())
+					for k in keys:
+						df_pos[k] = metadata[k]
 
 				df.append(df_pos)
 				any_table = True
 
-				df_pos_info.append(
-					{'pos_path': pos_path, 'pos_index': real_pos_index, 'pos_name': pos_name, 'table_path': table,
-					 'stack_path': stack_path,
-					 'well_path': well_path, 'well_index': real_well_index, 'well_name': well_name,
-					 'well_number': well_number, 'well_alias': well_alias})
+				pos_dict = {'pos_path': pos_path, 'pos_index': real_pos_index, 'pos_name': pos_name, 'table_path': table,
+					 'stack_path': stack_path,'well_path': well_path, 'well_index': real_well_index, 'well_name': well_name,
+					 'well_number': well_number, 'well_alias': well_alias}
+				# if metadata is not None:
+				# 	keys = list(metadata.keys())
+				# 	for k in keys:
+				# 		pos_dict.update({k: metadata[k]})
+
+				df_pos_info.append(pos_dict)
 
 				real_pos_index += 1
 
@@ -630,7 +1062,6 @@ def load_experiment_tables(experiment, population='targets', well_option='*', po
 		return df
 
 
-
 def locate_stack(position, prefix='Aligned'):
 
 	"""
@@ -694,35 +1125,52 @@ def locate_stack(position, prefix='Aligned'):
 def locate_labels(position, population='target', frames=None):
 
 	"""
+	Locate and load label images for a given position and population in an experiment.
 
-	Locate and load labels for a specific population.
+	This function retrieves and optionally loads labeled images (e.g., targets or effectors) 
+	for a specified position in an experiment. It supports loading all frames, a specific 
+	frame, or a list of frames.
 
 	Parameters
 	----------
 	position : str
-		The position folder within the well where the stack is located.
+		Path to the position directory containing label images.
 	population : str, optional
-		The population for which to locate the labels.
-		Valid options are 'target' and 'effector'.
-		The default is 'target'.
+		The population to load labels for. Options are `'target'` (or `'targets'`) and 
+		`'effector'` (or `'effectors'`). Default is `'target'`.
+	frames : int, list of int, numpy.ndarray, or None, optional
+		Specifies which frames to load:
+		- `None`: Load all frames (default).
+		- `int`: Load a single frame, identified by its index.
+		- `list` or `numpy.ndarray`: Load multiple specific frames.
 
 	Returns
 	-------
-	labels : ndarray
-		The loaded labels as a NumPy array.
+	numpy.ndarray or list of numpy.ndarray
+		If `frames` is `None` or a single integer, returns a NumPy array of the corresponding 
+		labels. If `frames` is a list or array, returns a list of NumPy arrays for each frame. 
+		If a frame is not found, `None` is returned for that frame.
 
 	Notes
 	-----
-	This function locates and loads the labels for a specific population based on the specified position.
-	It assumes that the labels are stored in a directory named 'labels' or 'labels_effectors'
-	within the specified position, depending on the population.
-	The function loads the labels as a NumPy array.
+	- The function assumes label images are stored in subdirectories named `"labels_targets"` 
+	  or `"labels_effectors"`, with filenames formatted as `####.tif` (e.g., `0001.tif`).
+	- Frame indices are zero-padded to four digits for matching.
+	- If `frames` is invalid or a frame is not found, `None` is returned for that frame.
 
 	Examples
 	--------
-	>>> labels = locate_labels(position, population='target')
-	# Locate and load labels for the target population.
+	Load all label images for a position:
+
+	>>> labels = locate_labels("/path/to/position", population="target")
+
+	Load a single frame (frame index 3):
+
+	>>> label = locate_labels("/path/to/position", population="effector", frames=3)
+
+	Load multiple specific frames:
 
+	>>> labels = locate_labels("/path/to/position", population="target", frames=[0, 1, 2])
 	"""
 
 	if not position.endswith(os.sep):
@@ -791,7 +1239,7 @@ def fix_missing_labels(position, population='target', prefix='Aligned'):
 		position += os.sep
 
 	stack = locate_stack(position, prefix=prefix)
-	template = np.zeros((stack[0].shape[0], stack[0].shape[1]))
+	template = np.zeros((stack[0].shape[0], stack[0].shape[1]),dtype=int)
 	all_frames = np.arange(len(stack))
 
 	if population.lower() == "target" or population.lower() == "targets":
@@ -913,37 +1361,52 @@ def load_tracking_data(position, prefix="Aligned", population="target"):
 
 
 def auto_load_number_of_frames(stack_path):
-
+	
 	"""
+	Automatically determine the number of frames in a TIFF image stack.
 
-	Automatically estimate the number of frames in a stack.
+	This function extracts the number of frames (time slices) from the metadata of a TIFF file 
+	or infers it from the stack dimensions when metadata is unavailable. It is robust to 
+	variations in metadata structure and handles multi-channel images.
 
 	Parameters
 	----------
 	stack_path : str
-		The file path to the stack.
+		Path to the TIFF image stack file.
 
 	Returns
 	-------
 	int or None
-		The estimated number of frames in the stack. Returns None if the number of frames cannot be determined.
+		The number of frames in the image stack. Returns `None` if the path is `None` 
+		or the frame count cannot be determined.
 
 	Notes
 	-----
-	This function attempts to estimate the number of frames in a stack by parsing the image description metadata.
-	It reads the stack file using the TiffFile from the tifffile library.
-	It searches for metadata fields containing information about the number of slices or frames.
-	If the number of slices or frames is found, it returns the estimated length of the movie.
-	If the number of slices or frames cannot be determined, it returns None.
+	- The function attempts to extract the `frames` or `slices` attributes from the 
+	  TIFF metadata, specifically the `ImageDescription` tag.
+	- If metadata extraction fails, the function reads the image stack and infers 
+	  the number of frames based on the stack dimensions.
+	- Multi-channel stacks are handled by assuming the number of channels is specified 
+	  in the metadata under the `channels` attribute.
 
 	Examples
 	--------
-	>>> len_movie = auto_load_number_of_frames(stack_path)
-	# Automatically estimate the number of frames in the stack.
+	Automatically detect the number of frames in a TIFF stack:
 
-	"""
+	>>> frames = auto_load_number_of_frames("experiment_stack.tif")
+	Automatically detected stack length: 120...
+
+	Handle a single-frame TIFF:
 
-	# Try to estimate automatically # frames
+	>>> frames = auto_load_number_of_frames("single_frame_stack.tif")
+	Automatically detected stack length: 1...
+
+	Handle invalid or missing paths gracefully:
+
+	>>> frames = auto_load_number_of_frames(None)
+	>>> print(frames)
+	None
+	"""
 
 	if stack_path is None:
 		return None
@@ -1000,6 +1463,47 @@ def auto_load_number_of_frames(stack_path):
 
 
 def parse_isotropic_radii(string):
+
+	"""
+	Parse a string representing isotropic radii into a structured list.
+
+	This function extracts integer values and ranges (denoted by square brackets) 
+	from a string input and returns them as a list. Single values are stored as integers, 
+	while ranges are represented as lists of two integers.
+
+	Parameters
+	----------
+	string : str
+		The input string containing radii and ranges, separated by commas or spaces. 
+		Ranges should be enclosed in square brackets, e.g., `[1 2]`.
+
+	Returns
+	-------
+	list
+		A list of parsed radii where:
+		- Single integers are included as `int`.
+		- Ranges are included as two-element lists `[start, end]`.
+
+	Examples
+	--------
+	Parse a string with single radii and ranges:
+
+	>>> parse_isotropic_radii("1, [2 3], 4")
+	[1, [2, 3], 4]
+
+	Handle inputs with mixed delimiters:
+
+	>>> parse_isotropic_radii("5 [6 7], 8")
+	[5, [6, 7], 8]
+
+	Notes
+	-----
+	- The function splits the input string by commas or spaces.
+	- It identifies ranges using square brackets and assumes that ranges are always 
+	  two consecutive values.
+	- Non-integer sections of the string are ignored.
+	"""
+
 	sections = re.split(',| ', string)
 	radii = []
 	for k, s in enumerate(sections):
@@ -1061,6 +1565,53 @@ def get_tracking_configs_list(return_path=False):
 
 def interpret_tracking_configuration(config):
 	
+	"""
+	Interpret and resolve the path for a tracking configuration file.
+
+	This function determines the appropriate configuration file path based on the input.
+	If the input is a string representing an existing path or a known configuration name, 
+	it resolves to the correct file path. If the input is invalid or `None`, a default 
+	configuration is returned.
+
+	Parameters
+	----------
+	config : str or None
+		The input configuration, which can be:
+		- A string representing the full path to a configuration file.
+		- A short name of a configuration file without the `.json` extension.
+		- `None` to use a default configuration.
+
+	Returns
+	-------
+	str
+		The resolved path to the configuration file.
+
+	Notes
+	-----
+	- If `config` is a string and the specified path exists, it is returned as-is.
+	- If `config` is a name, the function searches in the `tracking_configs` directory 
+	  within the `celldetective` models folder.
+	- If the file or name is not found, or if `config` is `None`, the function falls 
+	  back to a default configuration using `cell_config()`.
+
+	Examples
+	--------
+	Resolve a full path:
+
+	>>> interpret_tracking_configuration("/path/to/config.json")
+	'/path/to/config.json'
+
+	Resolve a named configuration:
+
+	>>> interpret_tracking_configuration("default_tracking")
+	'/path/to/celldetective/models/tracking_configs/default_tracking.json'
+
+	Handle `None` to return the default configuration:
+
+	>>> interpret_tracking_configuration(None)
+	'/path/to/default/config.json'
+	"""
+
 	if isinstance(config, str):
 		if os.path.exists(config):
 			return config
@@ -1180,6 +1731,61 @@ def get_pair_signal_models_list(return_path=False):
 
 def locate_signal_model(name, path=None, pairs=False):
 
+	"""
+	Locate a signal detection model by name, either locally or from Zenodo.
+
+	This function searches for a signal detection model with the specified name in the local
+	`celldetective` directory. If the model is not found locally, it attempts to download
+	the model from Zenodo.
+
+	Parameters
+	----------
+	name : str
+		The name of the signal detection model to locate.
+	path : str, optional
+		An additional directory path to search for the model. If provided, this directory
+		is also scanned for matching models. Default is `None`.
+	pairs : bool, optional
+		If `True`, searches for paired signal detection models in the `pair_signal_detection`
+		subdirectory. If `False`, searches in the `signal_detection` subdirectory. Default is `False`.
+
+	Returns
+	-------
+	str or None
+		The full path to the located model directory if found, or `None` if the model is not available
+		locally or on Zenodo.
+
+	Notes
+	-----
+	- The function first searches in the `celldetective/models/signal_detection` or 
+	  `celldetective/models/pair_signal_detection` directory based on the `pairs` argument.
+	- If a `path` is specified, it is searched in addition to the default directories.
+	- If the model is not found locally, the function queries Zenodo for the model. If available,
+	  the model is downloaded to the appropriate `celldetective` subdirectory.
+
+	Examples
+	--------
+	Search for a signal detection model locally:
+
+	>>> locate_signal_model("example_model")
+	'path/to/celldetective/models/signal_detection/example_model/'
+
+	Search for a paired signal detection model:
+
+	>>> locate_signal_model("paired_model", pairs=True)
+	'path/to/celldetective/models/pair_signal_detection/paired_model/'
+
+	Include an additional search path:
+
+	>>> locate_signal_model("custom_model", path="/additional/models/")
+	'/additional/models/custom_model/'
+
+	Handle a model available only on Zenodo:
+
+	>>> locate_signal_model("remote_model")
+	'path/to/celldetective/models/signal_detection/remote_model/'
+	"""
+
 	main_dir = os.sep.join([os.path.split(os.path.dirname(os.path.realpath(__file__)))[0], "celldetective"])
 	modelpath = os.sep.join([main_dir, "models", "signal_detection", os.sep])
 	if pairs:
@@ -1206,6 +1812,48 @@ def locate_signal_model(name, path=None, pairs=False):
 	return match
 
 def locate_pair_signal_model(name, path=None):
+
+	"""
+	Locate a pair signal detection model by name.
+
+	This function searches for a pair signal detection model in the default 
+	`celldetective` directory and optionally in an additional user-specified path.
+
+	Parameters
+	----------
+	name : str
+		The name of the pair signal detection model to locate.
+	path : str, optional
+		An additional directory path to search for the model. If provided, this directory 
+		is also scanned for matching models. Default is `None`.
+
+	Returns
+	-------
+	str or None
+		The full path to the located model directory if found, or `None` if no matching 
+		model is located.
+
+	Notes
+	-----
+	- The function first searches in the default `celldetective/models/pair_signal_detection` 
+	  directory.
+	- If a `path` is specified, it is searched in addition to the default directory.
+	- The function prints the search path and model name during execution.
+
+	Examples
+	--------
+	Locate a model in the default directory:
+
+	>>> locate_pair_signal_model("example_model")
+	'path/to/celldetective/models/pair_signal_detection/example_model/'
+
+	Include an additional search directory:
+
+	>>> locate_pair_signal_model("custom_model", path="/additional/models/")
+	'/additional/models/custom_model/'
+	"""
+
+
 	main_dir = os.sep.join([os.path.split(os.path.dirname(os.path.realpath(__file__)))[0], "celldetective"])
 	modelpath = os.sep.join([main_dir, "models", "pair_signal_detection", os.sep])
 	print(f'Looking for {name} in {modelpath}')
@@ -1215,74 +1863,118 @@ def locate_pair_signal_model(name, path=None):
 			path += os.sep
 		models += glob(path + f'*{os.sep}')
 
-def relabel_segmentation(labels, data, properties, column_labels={'track': "track", 'frame': 'frame', 'y': 'y', 'x': 'x', 'label': 'class_id'}, threads=1):
+def relabel_segmentation(labels, df, exclude_nans=True, column_labels={'track': "TRACK_ID", 'frame': 'FRAME', 'y': 'POSITION_Y', 'x': 'POSITION_X', 'label': 'class_id'}, threads=1):
 
 	"""
+	Relabel the segmentation labels with the tracking IDs from the tracks.
 
-	Relabel the segmentation labels based on the provided tracking data and properties.
+	The function reassigns the mask value for each cell with the associated `TRACK_ID`, if it exists
+	in the trajectory table (`df`). If no track uses the cell mask, a new track with a single point
+	is generated on the fly (max of `TRACK_ID` values + i, for i=0 to N such cells). It supports 
+	multithreaded processing for faster execution on large datasets.
 
 	Parameters
 	----------
-	labels : ndarray
-		The original segmentation labels.
-	data : ndarray
-		The tracking data containing information about tracks, frames, y-coordinates, and x-coordinates.
-	properties : ndarray
-		The properties associated with the tracking data.
+	labels : np.ndarray
+		A (TYX) array where each frame contains a 2D segmentation mask. Each unique 
+		non-zero integer represents a labeled object.
+	df : pandas.DataFrame
+		A DataFrame containing tracking information with columns 
+		specified in `column_labels`. Must include at least frame, track ID, and object ID.
+	exclude_nans : bool, optional
+		Whether to exclude rows in `df` with NaN values in the column specified by 
+		`column_labels['label']`. Default is `True`.
 	column_labels : dict, optional
-		A dictionary specifying the column labels for the tracking data. The default is {'track': "track",
-		'frame': 'frame', 'y': 'y', 'x': 'x', 'label': 'class_id'}.
+		A dictionary specifying the column names in `df`. Default is:
+		- `'track'`: Track ID column name (`"TRACK_ID"`)
+		- `'frame'`: Frame column name (`"FRAME"`)
+		- `'y'`: Y-coordinate column name (`"POSITION_Y"`)
+		- `'x'`: X-coordinate column name (`"POSITION_X"`)
+		- `'label'`: Object ID column name (`"class_id"`)
+	threads : int, optional
+		Number of threads to use for multithreaded processing. Default is `1`.
 
 	Returns
 	-------
-	ndarray
-		The relabeled segmentation labels.
+	np.ndarray
+		A new (TYX) array with the same shape as `labels`, where objects are relabeled 
+		according to their tracking identity in `df`.
 
 	Notes
 	-----
-	This function relabels the segmentation labels based on the provided tracking data and properties.
-	It creates a DataFrame from the tracking data and properties, merges them based on the indices, and sorts them by track and frame.
-	Then, it iterates over unique frames in the DataFrame, retrieves the tracks and identities at each frame,
-	and updates the corresponding labels with the new track values.
+	- For frames where labeled objects in `labels` do not match any entries in the `df`,
+	  new track IDs are generated for the unmatched labels.
+	- The relabeling process maintains synchronization across threads using a shared
+	  counter for generating unique track IDs.
 
 	Examples
 	--------
-	>>> relabeled = relabel_segmentation(labels, data, properties, column_labels={'track': "track", 'frame': 'frame',
-	...                                                                 'y': 'y', 'x': 'x', 'label': 'class_id'})
-	# Relabel the segmentation labels based on the provided tracking data and properties.
-	
-	"""
+	Relabel segmentation using tracking data:
 
+	>>> labels = np.random.randint(0, 5, (10, 100, 100))
+	>>> df = pd.DataFrame({
+	...     "TRACK_ID": [1, 2, 1, 2],
+	...     "FRAME": [0, 0, 1, 1],
+	...     "class_id": [1, 2, 1, 2],
+	... })
+	>>> new_labels = relabel_segmentation(labels, df, threads=2)
+	Done.
 
-	n_threads = threads
-	if data.shape[1]==4:
-		df = pd.DataFrame(data,columns=[column_labels['track'],column_labels['frame'],column_labels['y'],column_labels['x']])
-	else:
-		df = pd.DataFrame(data,columns=[column_labels['track'],column_labels['frame'],'z', column_labels['y'],column_labels['x']])
-		df = df.drop(columns=['z'])
+	Use custom column labels and exclude rows with NaNs:
+
+	>>> column_labels = {
+	...     'track': "track_id",
+	...     'frame': "time",
+	...     'label': "object_id"
+	... }
+	>>> new_labels = relabel_segmentation(labels, df, column_labels=column_labels, exclude_nans=True)
+	Done.
+	"""
 
-	df = df.merge(pd.DataFrame(properties),left_index=True, right_index=True)
+	n_threads = threads
 	df = df.sort_values(by=[column_labels['track'],column_labels['frame']])
-	df.loc[df['dummy'],column_labels['label']] = np.nan
+	if exclude_nans:
+		df = df.dropna(subset=column_labels['label'])
 
 	new_labels = np.zeros_like(labels)
+	shared_data = {"s": 0}
 
 	def rewrite_labels(indices):
 
+		all_track_ids = df[column_labels['track']].unique()
+		
 		for t in tqdm(indices):
 
 			f = int(t)
 			cells = df.loc[df[column_labels['frame']] == f, [column_labels['track'], column_labels['label']]].to_numpy()
-			tracks_at_t = cells[:,0]
-			identities = cells[:,1]
+			tracks_at_t = list(cells[:,0])
+			identities = list(cells[:,1])
+
+			labels_at_t = list(np.unique(labels[f]))
+			if 0 in labels_at_t:
+				labels_at_t.remove(0)
+			labels_not_in_df = [lbl for lbl in labels_at_t if lbl not in identities]
+			for lbl in labels_not_in_df:
+				with threading.Lock():  # Synchronize access to `shared_data["s"]`
+					track_id = max(all_track_ids) + shared_data["s"]
+					shared_data["s"] += 1
+				tracks_at_t.append(track_id)
+				identities.append(lbl)
 
 			# exclude NaN
+			tracks_at_t = np.array(tracks_at_t)
+			identities = np.array(identities)
+
 			tracks_at_t = tracks_at_t[identities == identities]
 			identities = identities[identities == identities]
 
 			for k in range(len(identities)):
+
+				# need routine to check values from labels not in class_id of this frame and add new track id
+				
 				loc_i, loc_j = np.where(labels[f] == identities[k])
-				new_labels[f, loc_i, loc_j] = round(tracks_at_t[k])
+				track_id = tracks_at_t[k]
+				new_labels[f, loc_i, loc_j] = round(track_id)
 
 	# Multithreading
 	indices = list(df[column_labels['frame']].unique())
@@ -1296,90 +1988,308 @@ def relabel_segmentation(labels, data, properties, column_labels={'track': "trac
 	return new_labels
 
 
-def control_tracking_btrack(position, prefix="Aligned", population="target", relabel=True, flush_memory=True, threads=1):
+def control_tracks(position, prefix="Aligned", population="target", relabel=True, flush_memory=True, threads=1):
 
 	"""
-	Load the necessary data for visualization of bTrack trajectories in napari.
+	Controls the tracking of cells or objects within a given position by locating the relevant image stack and label data,
+	and then visualizing and managing the tracks in the Napari viewer.
 
 	Parameters
 	----------
 	position : str
-		The path to the position directory.
-	prefix : str, optional
-		The prefix used to identify the movie file. The default is "Aligned".
-	population : str, optional
-		The population type to load, either "target" or "effector". The default is "target".
+		The path to the directory containing the position's data. The function will ensure the path uses forward slashes.
+	
+	prefix : str, optional, default="Aligned"
+		The prefix of the file names for the image stack and labels. This parameter helps locate the relevant data files.
+	
+	population : str, optional, default="target"
+		The population to be tracked, typically either "target" or "effectors". This is used to identify the group of interest for tracking.
+	
+	relabel : bool, optional, default=True
+		If True, will relabel the tracks, potentially assigning new track IDs to the detected objects.
+	
+	flush_memory : bool, optional, default=True
+		If True, will flush memory after processing to free up resources.
+	
+	threads : int, optional, default=1
+		The number of threads to use for processing. This can speed up the task in multi-threaded environments.
 
 	Returns
 	-------
 	None
-		This function displays the data in Napari for visualization and analysis.
-
-	Examples
-	--------
-	>>> control_tracking_btrack("path/to/position", population="target")
-	# Executes napari for visualization of target trajectories.
+		The function performs visualization and management of tracks in the Napari viewer. It does not return any value.
 
+	Notes
+	-----
+	- This function assumes that the necessary data for tracking (stack and labels) are located in the specified position directory.
+	- The `locate_stack_and_labels` function is used to retrieve the image stack and labels from the specified directory.
+	- The tracks are visualized using the `view_tracks_in_napari` function, which handles the display in the Napari viewer.
+	- The function can be used for tracking biological entities (e.g., cells) and their movement across time frames in an image stack.
+	
+	Example
+	-------
+	>>> control_tracks("/path/to/data/position_1", prefix="Aligned", population="target", relabel=True, flush_memory=True, threads=4)
 	"""
+	
+	if not position.endswith(os.sep):
+		position += os.sep
+
+	position = position.replace('\\','/')
+	stack, labels = locate_stack_and_labels(position, prefix=prefix, population=population)
 
-	data, properties, graph, labels, stack = load_napari_data(position, prefix=prefix, population=population)
-	view_on_napari_btrack(data, properties, graph, labels=labels, stack=stack, relabel=relabel,
+	view_tracks_in_napari(position, population, labels=labels, stack=stack, relabel=relabel,
 						  flush_memory=flush_memory, threads=threads)
 
 
-def view_on_napari_btrack(data, properties, graph, stack=None, labels=None, relabel=True, flush_memory=True,
-						  position=None, threads=1):
+def tracks_to_btrack(df, exclude_nans=False):
+	
 	"""
-
-	Visualize btrack data, including stack, labels, points, and tracks, using the napari viewer.
+	Converts a dataframe of tracked objects into the bTrack output format.
+	The function prepares tracking data, properties, and an empty graph structure for further processing.
 
 	Parameters
 	----------
-	data : ndarray
-		The btrack data containing information about tracks.
-	properties : ndarray
-		The properties associated with the btrack data.
-	graph : Graph
-		The btrack graph containing information about track connections.
-	stack : ndarray, optional
-		The stack of images to visualize. The default is None.
-	labels : ndarray, optional
-		The segmentation labels to visualize. The default is None.
-	relabel : bool, optional
-		Specify whether to relabel the segmentation labels using the provided data. The default is True.
+	df : pandas.DataFrame
+		A dataframe containing tracking information. The dataframe must have columns for `TRACK_ID`, 
+		`FRAME`, `POSITION_Y`, `POSITION_X`, and `class_id` (among others).
+
+	exclude_nans : bool, optional, default=False
+		If True, rows with NaN values in the `class_id` column will be excluded from the dataset.
+		If False, the dataframe will retain all rows, including those with NaN in `class_id`.
+
+	Returns
+	-------
+	data : numpy.ndarray
+		A 2D numpy array containing the tracking data with columns `[TRACK_ID, FRAME, z, POSITION_Y, POSITION_X]`.
+		The `z` column is set to zero for all rows.
+
+	properties : dict
+		A dictionary where keys are property names (e.g., 'FRAME', 'state', 'generation', etc.) and values are numpy arrays
+		containing the corresponding values from the dataframe.
 
+	graph : dict
+		An empty dictionary intended to store graph-related information for the tracking data. It can be extended
+		later to represent relationships between different tracking objects.
+	
 	Notes
 	-----
-	This function visualizes btrack data using the napari viewer. It adds the stack, labels, points,
-	and tracks to the viewer for visualization. If `relabel` is True and labels are provided, it calls
-	the `relabel_segmentation` function to relabel the segmentation labels based on the provided data.
+	- The function assumes that the dataframe contains specific columns: `TRACK_ID`, `FRAME`, `POSITION_Y`, `POSITION_X`, 
+	  and `class_id`. These columns are used to construct the tracking data and properties.
+	- The `z` coordinate is set to 0 for all tracks since the function does not process 3D data.
+	- This function is useful for transforming tracking data into a format that can be used by tracking graph algorithms.
+
+	Example
+	-------
+	>>> data, properties, graph = tracks_to_btrack(df, exclude_nans=True)
+	"""
+
+	graph = {}
+	if exclude_nans:
+		df.dropna(subset='class_id',inplace=True)
+
+	df["z"] = 0.
+	data = df[["TRACK_ID","FRAME","z","POSITION_Y","POSITION_X"]].to_numpy()
+	
+	df['dummy'] = False
+	prop_cols = ['FRAME','state','generation','root','parent','dummy','class_id']
+	properties = {}
+	for col in prop_cols:
+		properties.update({col: df[col].to_numpy()})
+	
+	return data, properties, graph
+
+def tracks_to_napari(df, exclude_nans=False):
+	
+	data, properties, graph = tracks_to_btrack(df, exclude_nans=exclude_nans)
+	vertices = data[:, [1,-2,-1]]
+	if data.shape[1]==4:
+		tracks = data
+	else:
+		tracks = data[:,[0,1,3,4]]
+	return vertices, tracks, properties, graph
 
-	Examples
-	--------
-	>>> view_on_napari_btrack(data, properties, graph, stack=stack, labels=labels, relabel=True)
-	# Visualize btrack data, including stack, labels, points, and tracks, using the napari viewer.
 
+def view_tracks_in_napari(position, population, stack=None, labels=None, relabel=True, flush_memory=True, threads=1):
+	
+	"""
+	Updated
 	"""
 
+	df, df_path = get_position_table(position, population=population, return_path=True)
+	if df is None:
+		print('Please compute trajectories first... Abort...')
+		return None
+	shared_data = {"df": df, "path": df_path, "position": position, "population": population, 'selected_frame': None}
+
 	if (labels is not None) * relabel:
 		print('Replacing the cell mask labels with the track ID...')
-		labels = relabel_segmentation(labels, data, properties, threads=threads)
+		labels = relabel_segmentation(labels, df, exclude_nans=True, threads=threads)
 
-	vertices = data[:, [1,-2,-1]]
+	vertices, tracks, properties, graph = tracks_to_napari(df, exclude_nans=True)
 
 	viewer = napari.Viewer()
 	if stack is not None:
 		viewer.add_image(stack, channel_axis=-1, colormap=["gray"] * stack.shape[-1])
 	if labels is not None:
-		viewer.add_labels(labels.astype(int), name='segmentation', opacity=0.4)
+		labels_layer = viewer.add_labels(labels.astype(int), name='segmentation', opacity=0.4)
 	viewer.add_points(vertices, size=4, name='points', opacity=0.3)
-	if data.shape[1]==4:
-		viewer.add_tracks(data, properties=properties, graph=graph, name='tracks')
-	else:
-		viewer.add_tracks(data[:,[0,1,3,4]], properties=properties, graph=graph, name='tracks')     
+	viewer.add_tracks(tracks, properties=properties, graph=graph, name='tracks')     
+
+	def lock_controls(layer, widgets=(), locked=True):
+		qctrl = viewer.window.qt_viewer.controls.widgets[layer]
+		for wdg in widgets:
+			try:
+				getattr(qctrl, wdg).setEnabled(not locked)
+			except:
+				pass
+
+	label_widget_list = ['paint_button', 'erase_button', 'fill_button', 'polygon_button', 'transform_button']
+	lock_controls(viewer.layers['segmentation'], label_widget_list)
+
+	point_widget_list = ['addition_button', 'delete_button', 'select_button', 'transform_button']
+	lock_controls(viewer.layers['points'], point_widget_list)
+
+	track_widget_list = ['transform_button']
+	lock_controls(viewer.layers['tracks'], track_widget_list)
+
+	# Initialize selected frame
+	selected_frame = viewer.dims.current_step[0]
+	shared_data['selected_frame'] = selected_frame
+
+	def export_modifications():
+
+		from celldetective.tracking import write_first_detection_class, clean_trajectories
+		from celldetective.utils import velocity_per_track
+
+		df = shared_data['df']
+		position = shared_data['position']
+		population = shared_data['population']
+		df = velocity_per_track(df, window_size=3, mode='bi')
+		df = write_first_detection_class(df, img_shape=labels[0].shape)
+
+		experiment = extract_experiment_from_position(position)
+		instruction_file = "/".join([experiment,"configs", f"tracking_instructions_{population}.json"])
+		print(f"{instruction_file=}")
+		if os.path.exists(instruction_file):
+			print('Tracking configuration file found...')
+			with open(instruction_file, 'r') as f:
+				instructions = json.load(f)			
+				if 'post_processing_options' in instructions:
+					post_processing_options = instructions['post_processing_options']
+					print(f'Applying the following track postprocessing: {post_processing_options}...')
+					df = clean_trajectories(df.copy(),**post_processing_options)
+		unnamed_cols = [c for c in list(df.columns) if c.startswith('Unnamed')]
+		df = df.drop(unnamed_cols, axis=1)
+		print(f"{list(df.columns)=}")
+		df.to_csv(shared_data['path'], index=False)
+		print('Done...')
+
+	@magicgui(call_button='Export the modified\ntracks...')
+	def export_table_widget():
+		return export_modifications()
+
+	def label_changed(event):
+
+		value = viewer.layers['segmentation'].selected_label
+		if value != 0:
+			selected_frame = viewer.dims.current_step[0]
+			shared_data['selected_frame'] = selected_frame
+
+
+	viewer.layers['segmentation'].events.selected_label.connect(label_changed)
+
+	viewer.window.add_dock_widget(export_table_widget, area='right')
+
+	@labels_layer.mouse_double_click_callbacks.append
+	def on_second_click_of_double_click(layer, event):
+
+		df = shared_data['df']
+		position = shared_data['position']
+		population = shared_data['population']
+
+		frame, x, y = event.position
+		try:
+			value_under = viewer.layers['segmentation'].data[int(frame), int(x), int(y)] #labels[0,int(y),int(x)]
+			if value_under==0:
+				return None
+		except:
+			print('Invalid mask value...')
+			return None
+
+		target_track_id = viewer.layers['segmentation'].selected_label
+
+		msgBox = QMessageBox()
+		msgBox.setIcon(QMessageBox.Question)
+		msgBox.setText(f"Do you want to propagate track {target_track_id} to the cell under the mouse, track {value_under}?")
+		msgBox.setWindowTitle("Info")
+		msgBox.setStandardButtons(QMessageBox.Yes | QMessageBox.No)
+		returnValue = msgBox.exec()
+		if returnValue == QMessageBox.No:
+			return None
+		else:
+
+			if target_track_id not in df['TRACK_ID'].unique() and target_track_id in np.unique(viewer.layers['segmentation'].data[shared_data['selected_frame']]):
+				# the selected cell in frame -1 is not in the table... we can add it to DataFrame
+				current_labelm1 = viewer.layers['segmentation'].data[shared_data['selected_frame']]
+				original_labelm1 = locate_labels(position, population=population, frames=shared_data['selected_frame'])				
+				original_labelm1[current_labelm1!=target_track_id] = 0
+				props = regionprops_table(original_labelm1, intensity_image=None, properties=['centroid', 'label'])
+				props = pd.DataFrame(props)
+				new_cell = props[['centroid-1', 'centroid-0','label']].copy()
+				new_cell.rename(columns={'centroid-1': 'POSITION_X', 'centroid-0': 'POSITION_Y', 'label': 'class_id'},inplace=True)
+				new_cell['FRAME'] = shared_data['selected_frame']
+				new_cell['TRACK_ID'] = target_track_id
+				df = pd.concat([df, new_cell], ignore_index=True)				
+
+			if value_under not in df['TRACK_ID'].unique():
+				# the cell to add is not currently part of DataFrame, need to add measurement
+
+				current_label = viewer.layers['segmentation'].data[int(frame)]
+				original_label = locate_labels(position, population=population, frames=int(frame))
+
+				new_datapoint = {'TRACK_ID': value_under, 'FRAME': frame, 'POSITION_X': np.nan, 'POSITION_Y': np.nan, 'class_id': np.nan}
+				
+				original_label[current_label!=value_under] = 0
+
+				props = regionprops_table(original_label, intensity_image=None, properties=['centroid', 'label'])
+				props = pd.DataFrame(props)
+
+				new_cell = props[['centroid-1', 'centroid-0','label']].copy()
+				new_cell.rename(columns={'centroid-1': 'POSITION_X', 'centroid-0': 'POSITION_Y', 'label': 'class_id'},inplace=True)
+				new_cell['FRAME'] = int(frame)
+				new_cell['TRACK_ID'] = value_under
+				df = pd.concat([df, new_cell], ignore_index=True)
+
+			relabel = np.amax(df['TRACK_ID'].unique()) + 1
+			for f in viewer.layers['segmentation'].data[int(frame):]:
+				if target_track_id!=0:
+					f[np.where(f==target_track_id)] = relabel
+				f[np.where(f==value_under)] = target_track_id
+
+			if target_track_id!=0:
+				df.loc[(df['FRAME']>=frame)&(df['TRACK_ID']==target_track_id),'TRACK_ID'] = relabel
+			df.loc[(df['FRAME']>=frame)&(df['TRACK_ID']==value_under),'TRACK_ID'] = target_track_id
+			df = df.loc[~(df['TRACK_ID']==0),:]
+			df = df.sort_values(by=['TRACK_ID','FRAME'])
+
+			vertices, tracks, properties, graph = tracks_to_napari(df, exclude_nans=True)
+			
+			viewer.layers['tracks'].data = tracks
+			viewer.layers['tracks'].properties = properties
+			viewer.layers['tracks'].graph = graph
+
+			viewer.layers['points'].data = vertices
+
+			viewer.layers['segmentation'].refresh()
+			viewer.layers['tracks'].refresh()
+			viewer.layers['points'].refresh()
+
+		shared_data['df'] = df
+
 	viewer.show(block=True)
 
 	if flush_memory:
+
 		# temporary fix for slight napari memory leak
 		for i in range(10000):
 			try:
@@ -1394,6 +2304,7 @@ def view_on_napari_btrack(data, properties, graph, stack=None, labels=None, rela
 
 
 def load_napari_data(position, prefix="Aligned", population="target", return_stack=True):
+	
 	"""
 	Load the necessary data for visualization in napari.
 
@@ -1417,6 +2328,10 @@ def load_napari_data(position, prefix="Aligned", population="target", return_sta
 	# Load the necessary data for visualization of target trajectories.
 
 	"""
+
+	if not position.endswith(os.sep):
+		position += os.sep
+
 	position = position.replace('\\','/')
 	if population.lower()=="target" or population.lower()=="targets":
 		if os.path.exists(position+os.sep.join(['output','tables','napari_target_trajectories.npy'])):
@@ -1428,6 +2343,7 @@ def load_napari_data(position, prefix="Aligned", population="target", return_sta
 			napari_data = np.load(position+os.sep.join(['output', 'tables', 'napari_effector_trajectories.npy']), allow_pickle=True)
 		else:
 			napari_data = None
+
 	if napari_data is not None:
 		data = napari_data.item()['data']
 		properties = napari_data.item()['properties']
@@ -1444,9 +2360,6 @@ def load_napari_data(position, prefix="Aligned", population="target", return_sta
 	return data, properties, graph, labels, stack
 
 
-from skimage.measure import label
-
-
 def auto_correct_masks(masks, bbox_factor = 1.75, min_area=9, fill_labels=False):
 
 	"""
@@ -1621,7 +2534,7 @@ def control_segmentation_napari(position, prefix='Aligned', population="target",
 			squares = np.array(squares)
 			squares = squares[test_in_frame]
 			nbr_squares = len(squares)
-			print(f"Found {nbr_squares} ROIS")
+			print(f"Found {nbr_squares} ROIs...")
 			if nbr_squares > 0:
 				# deactivate field of view mode
 				fov_export = False
@@ -1710,6 +2623,19 @@ def control_segmentation_napari(position, prefix='Aligned', population="target",
 	viewer.add_labels(labels.astype(int), name='segmentation', opacity=0.4)
 	viewer.window.add_dock_widget(save_widget, area='right')
 	viewer.window.add_dock_widget(export_widget, area='right')
+
+	def lock_controls(layer, widgets=(), locked=True):
+		qctrl = viewer.window.qt_viewer.controls.widgets[layer]
+		for wdg in widgets:
+			try:
+				getattr(qctrl, wdg).setEnabled(not locked)
+			except:
+				pass
+
+	label_widget_list = ['polygon_button', 'transform_button']
+	lock_controls(viewer.layers['segmentation'], label_widget_list)
+
+
 	viewer.show(block=True)
 
 	if flush_memory: