API 

celldetective.measure.interpret_track_classification(df: DataFrame, class_attr: str, irreversible_event: bool = False, unique_state: bool = False, transient_event: bool = False, r2_threshold: float = 0.5, percentile_recovery: float = 50, pre_event: str | None = None) → DataFrame[source]

Interpret and classify tracked cells based on their status signals.

Parameters:

df (pandas.DataFrame) – DataFrame containing tracked cell data, including a classification attribute column and other necessary columns.
class_attr (str) – Column name for the classification attribute (e.g., ‘class’) used to determine the state of cells.
irreversible_event (bool, optional) – If True, classifies irreversible events in the dataset (default is False). When set to True, unique_state is ignored.
unique_state (bool, optional) – If True, classifies unique states of cells in the dataset based on a percentile threshold (default is False). This option is ignored if irreversible_event is set to True.
r2_threshold (float, optional) – R-squared threshold used when fitting the model during the classification of irreversible events (default is 0.5).
transient_event (bool, optional) – If True, classifies transient events. Default is False.
percentile_recovery (float, optional) – Percentile threshold for recovery in irreversible classification. Default is 50.
pre_event (str, optional) – Name of a pre-event class to consider. Default is None.

Returns:

DataFrame with updated classifications for cell trajectories:

If irreversible_event is True, it classifies irreversible events using the classify_irreversible_events function.
If unique_state is True, it classifies unique states using the classify_unique_states function.

Return type:

pandas.DataFrame

Raises:

AssertionError – If the ‘TRACK_ID’ column is missing in the input DataFrame.

Notes

The function assumes that the input DataFrame contains a column for tracking cells (TRACK_ID) and possibly a ‘position’ column.
The classification behavior depends on the irreversible_event and unique_state flags:
- When irreversible_event is True, the function classifies events that are considered irreversible.
- When unique_state is True (and irreversible_event is False), it classifies unique states using a 50th percentile threshold.

Example

>>> df = interpret_track_classification(df, 'class', irreversible_event=True, r2_threshold=0.7)

celldetective.measure.local_normalisation(image: ndarray, labels: ndarray, background_intensity: DataFrame, measurement: str = 'intensity_median', operation: str = 'subtract', clip: bool = False) → ndarray[source]

Performs local normalization of an image based on background intensity.

Parameters:

image (ndarray) – The input image to be normalized.
labels (ndarray) – The label image defining cell regions.
background_intensity (pandas.DataFrame) – DataFrame containing background intensity measurements for each cell.
measurement (str, optional) – The name of the measurement column in background_intensity to use. Default is “intensity_median”.
operation (str, optional) – The normalization operation to perform (“subtract” or “divide”). Default is “subtract”.
clip (bool, optional) – Whether to clip the normalized image values to be non-negative. Default is False.

Returns:

The locally normalized image.

Return type:

ndarray

celldetective.measure.measure(stack: ndarray | None = None, labels: ndarray | None = None, trajectories: DataFrame | None = None, channel_names: List[str] | None = None, features: List[str] | None = None, intensity_measurement_radii: int | float | List[float] | None = None, isotropic_operations: List[Literal['mean', 'median', 'average', 'std', 'var', 'nanmedian', 'nanmean', 'nanstd', 'nanvar']] = ['mean'], border_distances: int | float | List[float] | None = None, haralick_options: Dict[str, Any] | None = None, column_labels: Dict[str, str] = {'time': 'FRAME', 'track': 'TRACK_ID', 'x': 'POSITION_X', 'y': 'POSITION_Y'}, clear_previous: bool = False) → DataFrame[source]

Perform measurements on a stack of images or labels.

Parameters:

stack (numpy array, optional) – Stack of images with shape (T, Y, X, C), where T is the number of frames, Y and X are the spatial dimensions, and C is the number of channels. Default is None.
labels (numpy array, optional) – Label stack with shape (T, Y, X) representing cell segmentations. Default is None.
trajectories (pandas DataFrame, optional) – DataFrame of cell trajectories with columns specified in column_labels. Default is None.
channel_names (list, optional) – List of channel names corresponding to the image stack. Default is None.
features (list, optional) – List of features to measure using the measure_features function. Default is None.
intensity_measurement_radii (int, float, or list, optional) – Radius or list of radii specifying the size of the isotropic measurement area for intensity measurements. If a single value is provided, a circular measurement area is used. If a list of values is provided, multiple measurements are performed using ring-shaped measurement areas. Default is None.
isotropic_operations (list, optional) – List of operations to perform on the isotropic intensity values. Default is [‘mean’].
border_distances (int, float, or list, optional) – Distance or list of distances specifying the size of the border region for intensity measurements. If a single value is provided, measurements are performed at a fixed distance from the cell borders. If a list of values is provided, measurements are performed at multiple border distances. Default is None.
haralick_options (dict, optional) – Dictionary of options for Haralick feature measurements. Default is None.
column_labels (dict, optional) – Dictionary containing the column labels for the DataFrame. Default is {‘track’: “TRACK_ID”, ‘time’: ‘FRAME’, ‘x’: ‘POSITION_X’, ‘y’: ‘POSITION_Y’}.
clear_previous (bool, optional) – If True, removes previously computed features from the trajectories DataFrame before measuring. Default is False.

Returns:

DataFrame containing the measured features and intensities.

Return type:

pandas DataFrame

Notes

This function performs measurements on a stack of images or labels. If both stack and labels are provided, measurements are performed on each frame of the stack. The measurements include isotropic intensity values, computed using the measure_isotropic_intensity function, and additional features, computed using the measure_features function. The intensity measurements are performed at the positions specified in the trajectories DataFrame, using the specified intensity_measurement_radii and border_distances. The resulting measurements are combined into a single DataFrame and returned.

Examples

>>> stack = np.random.rand(10, 100, 100, 3)
>>> labels = np.random.randint(0, 2, (10, 100, 100))
>>> trajectories = pd.DataFrame({'TRACK_ID': [1, 2, 3], 'FRAME': [1, 1, 1],
...                                                 'POSITION_X': [10, 20, 30], 'POSITION_Y': [15, 25, 35]})
>>> channel_names = ['channel1', 'channel2', 'channel3']
>>> features = ['area', 'intensity_mean']
>>> intensity_measurement_radii = [5, 10]
>>> border_distances = 2
>>> measurements = measure(stack=stack, labels=labels, trajectories=trajectories, channel_names=channel_names,
...                                                 features=features, intensity_measurement_radii=intensity_measurement_radii,
...                                                 border_distances=border_distances)
# Perform measurements on the stack, labels, and trajectories, computing isotropic intensities and additional features.

celldetective.measure.measure_at_position(pos: str, mode: str, return_measurements: bool = False, threads: int = 1) → DataFrame | None[source]

Executes a measurement script at a specified position directory, optionally returning the measured data.

This function calls an external Python script to perform measurements on data located in a specified position directory. The measurement mode determines the type of analysis performed by the script. The function can either return the path to the resulting measurements table or load and return the measurements as a pandas DataFrame.

Parameters:

pos (str) – The path to the position directory where the measurements should be performed. The path should be a valid directory.
mode (str) – The measurement mode to be used by the script. This determines the type of analysis performed (e.g., ‘tracking’, ‘feature_extraction’).
return_measurements (bool, optional) – If True, the function loads the resulting measurements from a CSV file into a pandas DataFrame and returns it. If False, the function returns None (default is False).
threads (int, optional) – Number of threads to use for parallel processing (default is 1).

Returns:

If return_measurements is True, returns a pandas DataFrame containing the measurements. Otherwise, returns None.

Return type:

pandas.DataFrame or None

celldetective.measure.measure_features(img: ndarray | None, label: ndarray, features: List[str] = ['area', 'intensity_mean'], channels: List[str] | None = None, border_dist: int | float | List[float] | None = None, haralick_options: Dict[str, Any] | None = None, verbose: bool = True, normalisation_list: List[Dict[str, Any]] | None = None, radial_intensity: Any | None = None, radial_channel: Any | None = None, spot_detection: Dict[str, Any] | None = None) → DataFrame[source]

Measure features within segmented regions of an image.

Parameters:

img (ndarray) – The input image as a NumPy array.
label (ndarray) – The segmentation labels corresponding to the image regions.
features (list, optional) – The list of features to measure within the segmented regions. The default is [‘area’, ‘eccentricity’].
channels (list, optional) – The list of channel names in the image. The default is [“brightfield_channel”, “dead_nuclei_channel”, “live_nuclei_channel”].
border_dist (int, float, or list, optional) – The distance(s) in pixels from the edge of each segmented region to measure features. The default is None.
haralick_options (dict, optional) – The options for computing Haralick features. The default is None.
verbose (bool, optional) – If True, warnings will be logged.
normalisation_list (list of dict, optional) – List of normalization operations to apply.
radial_intensity (Any, optional) – Deprecated/Unused parameter.
radial_channel (Any, optional) – Deprecated/Unused parameter.
spot_detection (dict, optional) – Options for spot detection.

Returns:

df_props – A pandas DataFrame containing the measured features for each segmented region.

Return type:

DataFrame

celldetective.measure.measure_isotropic_intensity(positions: DataFrame, img: ndarray, channels: List[str] | None = None, intensity_measurement_radii: int | float | List[float] | Tuple[float, float] | None = None, operations: List[Literal['mean', 'median', 'average', 'std', 'var', 'nanmedian', 'nanmean', 'nanstd', 'nanvar']] = ['mean'], measurement_kernel: ndarray | None = None, pbar: Any | None = None, column_labels: Dict[str, str] = {'time': 'FRAME', 'track': 'TRACK_ID', 'x': 'POSITION_X', 'y': 'POSITION_Y'}, verbose: bool = True) → DataFrame[source]

Measure isotropic intensity values around cell positions in an image.

Parameters:

positions (pandas DataFrame) – DataFrame of cell positions at time ‘t’ containing columns specified in column_labels.
img (numpy array) – Multichannel frame (YXC) at time ‘t’ used for intensity measurement.
channels (list or str, optional) – List of channel names corresponding to the image channels. Default is None.
intensity_measurement_radii (int, list, or tuple) – Radius or list of radii specifying the size of the isotropic measurement area. If a single value is provided, a circular measurement area is used. If a list or tuple of two values is provided, a ring-shaped measurement area is used. Default is None.
operations (list, optional) – List of operations to perform on the intensity values. Default is [‘mean’].
measurement_kernel (numpy array, optional) – Kernel used for intensity measurement. If None, a circular or ring-shaped kernel is generated based on the provided intensity_measurement_radii. Default is None.
pbar (tqdm progress bar, optional) – Progress bar for tracking the measurement process. Default is None.
column_labels (dict, optional) – Dictionary containing the column labels for the DataFrame. Default is {‘track’: “TRACK_ID”, ‘time’: ‘FRAME’, ‘x’: ‘POSITION_X’, ‘y’: ‘POSITION_Y’}.
verbose (bool, optional) – If True, enables verbose output. Default is True.

Returns:

The updated DataFrame positions with additional columns representing the measured intensity values.

Return type:

pandas DataFrame

Notes

This function measures the isotropic intensity values around the cell positions specified in the positions DataFrame using the provided image img. The intensity measurements are performed using circular or ring-shaped measurement areas defined by the intensity_measurement_radii. The measurements are calculated for each channel specified in the channels list. The resulting intensity values are stored in additional columns of the positions DataFrame. The operations parameter allows specifying different operations to be performed on the intensity values, such as ‘mean’, ‘median’, etc. The measurement kernel can be customized by providing the measurement_kernel parameter. If not provided, the measurement kernel is automatically generated based on the intensity_measurement_radii. The progress bar pbar can be used to track the measurement process. The column_labels dictionary is used to specify the column labels for the DataFrame.

Examples

>>> positions = pd.DataFrame({'TRACK_ID': [1, 2, 3], 'FRAME': [1, 1, 1],
...                                                 'POSITION_X': [10, 20, 30], 'POSITION_Y': [15, 25, 35]})
>>> img = np.random.rand(100, 100, 3)
>>> channels = ['channel1', 'channel2', 'channel3']
>>> intensity_measurement_radii = 5
>>> positions = measure_isotropic_intensity(positions, img, channels=channels,
...                                                                                 intensity_measurement_radii=intensity_measurement_radii)
# Measure isotropic intensity values around cell positions in the image.

celldetective.measure.measure_radial_distance_to_center(df: DataFrame, volume: Tuple[int, int] | List[int], column_labels: Dict[str, str] = {'time': 'FRAME', 'track': 'TRACK_ID', 'x': 'POSITION_X', 'y': 'POSITION_Y'}) → DataFrame[source]

Calculates the radial distance of each cell to the center of the image/volume.

Parameters:

df (pandas.DataFrame) – The dataframe containing cell positions.
volume (tuple or list) – The dimensions of the volume (Y, X).
column_labels (dict, optional) – Dictionary mapping internal column names. Default is {“track”: “TRACK_ID”, “time”: “FRAME”, “x”: “POSITION_X”, “y”: “POSITION_Y”}.

Returns:

The dataframe with an added ‘radial_distance’ column.

Return type:

pandas.DataFrame

celldetective.measure.normalise_by_cell(image: ndarray, labels: ndarray, distance: int = 5, model: str = 'median', operation: str = 'subtract', clip: bool = False) → ndarray[source]

Normalizes an image based on the local background around each cell.

Parameters:

image (ndarray) – The input image to be normalized.
labels (ndarray) – The label image defining cell regions.
distance (int, optional) – The distance from the cell boundary to define the local background region. Default is 5.
model (str, optional) – The statistic to compute for the background (“median” or “mean”). Default is “median”.
operation (str, optional) – The normalization operation (“subtract” or “divide”). Default is “subtract”.
clip (bool, optional) – Whether to clip the normalized values. Default is False.

Returns:

The normalized image.

Return type:

ndarray

celldetective.measure.write_first_detection_class(tab: DataFrame, column_labels: Dict[str, str] = {'time': 'FRAME', 'track': 'TRACK_ID', 'x': 'POSITION_X', 'y': 'POSITION_Y'}) → DataFrame[source]

Identifies and records the first detection time and class for each track.

Parameters:

tab (pandas.DataFrame) – The dataframe containing tracking data.
column_labels (dict, optional) – Dictionary mapping internal column names to dataframe column names. Default is {“track”: “TRACK_ID”, “time”: “FRAME”, “x”: “POSITION_X”, “y”: “POSITION_Y”}.

Returns:

The dataframe with added columns ‘class_firstdetection’ and ‘t_firstdetection’.

Return type:

pandas.DataFrame

Signals

Signals Module

This module is dedicated to the extraction, processing, and analysis of biological signals from tracked objects. It includes capabilities for signal measurement, feature computation, and event prediction using machine learning models.

Key Features

Signal Extraction: Retrieves intensity values and other measurements from image channels based on object masks.
Signal Analysis: Computes signal derivatives, smoothing, and other temporal features.
Event Prediction: Uses trained models to detect biological events (e.g., apoptosis, division) from signal time-series.

Main Functions

extract_signals: Extracts raw signal data from images for tracked objects.
predict_signals: Applies pre-trained models to classify signals and detect events.
compute_signal_features: Calculates statistical and temporal features from raw signals.

Dependencies

tensorflow/keras: Required for running event detection models.
scikit-learn: Used for metric calculation and some processing steps.

celldetective.signals.T_MSD(x: ndarray | List[float], y: ndarray | List[float], dt: float) → Tuple[List[float], ndarray][source]

Compute the Time-Averaged Mean Square Displacement (T-MSD) of a 2D trajectory.

Parameters:

x (array_like) – The array of x-coordinates of the trajectory.
y (array_like) – The array of y-coordinates of the trajectory.
dt (float) – The time interval between successive data points in the trajectory.

Returns:

msd (list) – A list containing the Time-Averaged Mean Square Displacement values for different time lags.
timelag (ndarray) – The array representing the time lags corresponding to the calculated MSD values.

Notes

T-MSD is a measure of the average spatial extent explored by a particle over a given time interval.
The input trajectories (x, y) are assumed to be in the same unit of length.
The time interval (dt) should be consistent with the time unit used in the data.

Examples

>>> import numpy as np
>>> x = np.array([1, 2, 4, 7, 11])
>>> y = np.array([0, 3, 5, 8, 10])
>>> dt = 1.0  # Time interval between data points
>>> T_MSD(x, y, dt)
([6.0, 9.0, 4.666666666666667, 1.6666666666666667],
 array([1., 2., 3., 4.]))

celldetective.signals.alpha_msd(t: ndarray | List[float], m: float, alpha: float) → ndarray | float[source]

Function to compute Mean Square Displacement (MSD) with a power-law scaling relationship.

Parameters:

t (array_like) – Time lag values.
m (float) – Scaling factor.
alpha (float) – Exponent representing the scaling relationship between MSD and time.

Returns:

msd – Computed MSD values based on the power-law scaling relationship.

Return type:

ndarray

Examples

>>> import numpy as np
>>> t = np.array([1, 2, 3, 4])
>>> m = 2.0
>>> alpha = 0.5
>>> alpha_msd(t, m, alpha)
array([2.        , 4.        , 6.        , 8.        ])

celldetective.signals.analyze_pair_signals(trajectories_pairs: DataFrame, trajectories_reference: DataFrame, trajectories_neighbors: DataFrame, model: str, interpolate_na: bool = True, selected_signals: List[str] | None = None, model_path: str | None = None, plot_outcome: bool = False, output_dir: str | None = None, column_labels: Dict[str, str] = {'time': 'FRAME', 'track': 'TRACK_ID', 'x': 'POSITION_X', 'y': 'POSITION_Y'}) → DataFrame[source]

Analyzes signals for pairs of cells using a specified model.

Parameters:

trajectories_pairs (pandas.DataFrame) – DataFrame containing pair data.
trajectories_reference (pandas.DataFrame) – DataFrame containing reference population data.
trajectories_neighbors (pandas.DataFrame) – DataFrame containing neighbor population data.
model (str) – Name of the signal model to use.
interpolate_na (bool, optional) – Whether to interpolate NaN values. Default is True.
selected_signals (list of str, optional) – List of signal columns to analyze. Default is None.
model_path (str, optional) – Path to the model directory. Default is None.
plot_outcome (bool, optional) – Whether to interpolate NaN values. Default is True.
output_dir (str, optional) – Directory to save output plots. Default is None.
column_labels (dict, optional) – Dictionary mapping column names.

Returns:

DataFrame with analyzed pair signals and classifications.

Return type:

pandas.DataFrame

celldetective.signals.analyze_pair_signals_at_position(pos: str, model: str, use_gpu: bool = True, populations: List[str] = ['targets', 'effectors']) → None[source]

Analyzes pair signals at a position using a specified model.

Parameters:

pos (str) – Path to the experimental position.
model (str) – Name of the signal model to use.
use_gpu (bool, optional) – Whether to use GPU acceleration. Default is True.
populations (list of str, optional) – List of population names involved in the pair analysis. Default is [“targets”, “effectors”].

Returns:

Results are saved to CSV.

Return type:

None

celldetective.signals.analyze_signals(trajectories: DataFrame, model: str, interpolate_na: bool = True, selected_signals: List[str] | None = None, model_path: str | None = None, column_labels: Dict[str, str] = {'time': 'FRAME', 'track': 'TRACK_ID', 'x': 'POSITION_X', 'y': 'POSITION_Y'}, plot_outcome: bool = False, output_dir: str | None = None) → DataFrame[source]

Analyzes signals from trajectory data using a specified signal detection model and configuration.

This function preprocesses trajectory data, selects specified signals, and applies a pretrained signal detection model to predict classes and times of interest for each trajectory. It supports custom column labeling, interpolation of missing values, and plotting of analysis outcomes.

Parameters:

trajectories (pandas.DataFrame) – DataFrame containing trajectory data with columns for track ID, frame, position, and signals.
model (str) – The name of the signal detection model to be used for analysis.
interpolate_na (bool, optional) – Whether to interpolate missing values in the trajectories (default is True).
selected_signals (list of str, optional) – A list of column names from trajectories representing the signals to be analyzed. If None, signals will be automatically selected based on the model configuration (default is None).
column_labels (dict, optional) – A dictionary mapping the default column names (‘track’, ‘time’, ‘x’, ‘y’) to the corresponding column names in trajectories (default is {‘track’: “TRACK_ID”, ‘time’: ‘FRAME’, ‘x’: ‘POSITION_X’, ‘y’: ‘POSITION_Y’}).
plot_outcome (bool, optional) – If True, generates and saves a plot of the signal analysis outcome (default is False).
output_dir (str, optional) – The directory where the outcome plot will be saved. Required if plot_outcome is True (default is None).
model_path (str, optional) – Path to the model directory. If None, it uses the default model location. Default is None.

Returns:

The input trajectories DataFrame with additional columns for predicted classes, times of interest, and corresponding colors based on status and class.

Return type:

pandas.DataFrame

Raises:

AssertionError – If the model or its configuration file cannot be located.

Notes

The function relies on an external model configuration file (config_input.json) located in the model’s directory.
Signal selection and preprocessing are based on the requirements specified in the model’s configuration.

celldetective.signals.analyze_signals_at_position(pos: str, model: str, mode: str, use_gpu: bool = True, return_table: bool = False) → DataFrame | None[source]

Analyzes signals for a given position directory using a specified model and mode, with an option to use GPU acceleration.

This function executes an external Python script to analyze signals within the specified position directory, applying a predefined model in a specified mode. It supports GPU acceleration for faster processing. Optionally, the function can return the resulting analysis table as a pandas DataFrame.

Parameters:

pos (str) – The file path to the position directory containing the data to be analyzed. The path must be valid and accessible.
model (str) – The name of the model to use for signal analysis.
mode (str) – The operation mode specifying how the analysis should be conducted.
use_gpu (bool, optional) – Specifies whether to use GPU acceleration for the analysis (default is True).
return_table (bool, optional) – If True, the function returns a pandas DataFrame containing the analysis results (default is False).

Returns:

If return_table is True, returns a DataFrame containing the analysis results. Otherwise, returns None.

Return type:

pandas.DataFrame or None

Raises:

AssertionError – If the specified position path does not exist.

Notes

The analysis is performed by an external script (analyze_signals.py) located in a specific directory relative to this function.
The results of the analysis are expected to be saved in the “output/tables” subdirectory within the position directory, following a naming convention based on the analysis mode.

celldetective.signals.columnwise_mean(matrix: ndarray, min_nbr_values: int = 1, projection: Literal['mean', 'median'] = 'mean') → Tuple[ndarray, ndarray][source]

Calculate the column-wise mean and standard deviation of non-NaN elements in the input matrix.

Parameters:

matrix (numpy.ndarray) – The input matrix for which column-wise mean and standard deviation are calculated.
min_nbr_values (int, optional) – The minimum number of non-NaN values required in a column to calculate mean and standard deviation. Default is 1.
projection (str, optional) – The method to calculate the central tendency, either ‘mean’ or ‘median’ (default is ‘mean’).

Returns:

mean_line (numpy.ndarray) – An array containing the column-wise mean of non-NaN elements. Elements with fewer than min_nbr_values non-NaN values are replaced with NaN.
mean_line_std (numpy.ndarray) – An array containing the column-wise standard deviation of non-NaN elements. Elements with fewer than min_nbr_values non-NaN values are replaced with NaN.

Notes

This function calculates the mean and standard deviation of non-NaN elements in each column of the input matrix.
Columns with fewer than min_nbr_values non-zero elements will have NaN as the mean and standard deviation.
NaN values in the input matrix are ignored during calculation.

celldetective.signals.drift_msd(t: float | ndarray, d: float, v: float) → float | ndarray[source]

Calculates the mean squared displacement (MSD) of a particle undergoing diffusion with drift.

The function computes the MSD for a particle that diffuses in a medium with a constant drift velocity. The MSD is given by the formula: MSD = 4Dt + V^2t^2, where D is the diffusion coefficient, V is the drift velocity, and t is the time.

Parameters:

t (float or ndarray) – Time or an array of time points at which to calculate the MSD.
d (float) – Diffusion coefficient of the particle.
v (float) – Drift velocity of the particle.

Returns:

The mean squared displacement of the particle at time t. Returns a single float value if t is a float, or returns an array of MSD values if t is an ndarray.

Return type:

float or ndarray

Examples

>>> drift_msd(t=5, d=1, v=2)
40
>>> drift_msd(t=np.array([1, 2, 3]), d=1, v=2)
array([ 6, 16, 30])

Notes

This formula assumes that the particle undergoes normal diffusion with an additional constant drift component.
The function can be used to model the behavior of particles in systems where both diffusion and directed motion occur.

celldetective.signals.linear_msd(t: ndarray | List[float], m: float) → ndarray | float[source]

Function to compute Mean Square Displacement (MSD) with a linear scaling relationship.

Parameters:

t (array_like) – Time lag values.
m (float) – Linear scaling factor representing the slope of the MSD curve.

Returns:

msd – Computed MSD values based on the linear scaling relationship.

Return type:

ndarray

Examples

>>> import numpy as np
>>> t = np.array([1, 2, 3, 4])
>>> m = 2.0
>>> linear_msd(t, m)
array([2., 4., 6., 8.])

celldetective.signals.mean_signal(df: DataFrame, signal_name: str, class_col: str, time_col: str | float | int | None = None, class_value: int | List[int] = [0], return_matrix: bool = False, forced_max_duration: int | None = None, min_nbr_values: int = 2, conflict_mode: Literal['mean', 'first', 'all'] = 'mean', projection: Literal['mean', 'median'] = 'mean', pairs: bool = False) → Tuple[ndarray, ndarray, ndarray] | Tuple[ndarray, ndarray, ndarray, ndarray][source]

Calculate the mean and standard deviation of a specified signal for tracks of a given class in the input DataFrame.

Parameters:

df (pandas.DataFrame) – Input DataFrame containing tracking data.
signal_name (str) – Name of the signal (column) in the DataFrame for which mean and standard deviation are calculated.
class_col (str) – Name of the column in the DataFrame containing class labels.
time_col (str, optional) – Name of the column in the DataFrame containing time information. Default is None.
class_value (int, optional) – Value representing the class of interest. Default is 0.
return_matrix (bool, optional) – Whether to return the signal matrix along with the mean and standard deviation (default is False).
forced_max_duration (int, optional) – The forced maximum duration of the signal (default is None).
min_nbr_values (int, optional) – The minimum number of values required to calculate the mean (default is 2).
conflict_mode (str, optional) – The method to handle conflicts when multiple values exist for the same time point, either ‘mean’, ‘first’, or ‘all’ (default is ‘mean’).
projection (str, optional) – The method to calculate the central tendency, either ‘mean’ or ‘median’ (default is ‘mean’).
pairs (bool, optional) – Whether the input DataFrame contains pair data (default is False).

Returns:

mean_signal (numpy.ndarray) – An array containing the mean signal values for tracks of the specified class. Tracks with class not equal to class_value are excluded from the calculation.
std_signal (numpy.ndarray) – An array containing the standard deviation of signal values for tracks of the specified class. Tracks with class not equal to class_value are excluded from the calculation.
actual_timeline (numpy.ndarray) – An array representing the time points corresponding to the mean signal values.

Notes

This function calculates the mean and standard deviation of the specified signal for tracks of a given class.
Tracks with class not equal to class_value are excluded from the calculation.
Tracks with missing or NaN values in the specified signal are ignored during calculation.
Tracks are aligned based on their ‘FRAME’ values and the specified time_col (if provided).

celldetective.signals.sliding_msd(x: ndarray | List[float], y: ndarray | List[float], timeline: ndarray | List[float], window: int, mode: Literal['bi', 'forward', 'backward'] = 'bi', n_points_migration: int = 7, n_points_transport: int = 7) → Tuple[ndarray, ndarray][source]

Compute sliding mean square displacement (sMSD) and anomalous exponent (alpha) for a 2D trajectory using a sliding window approach.

Parameters:

x (array_like) – The array of x-coordinates of the trajectory.
y (array_like) – The array of y-coordinates of the trajectory.
timeline (array_like) – The array representing the time points corresponding to the x and y coordinates.
window (int) – The size of the sliding window used for computing local MSD and alpha values.
mode ({'bi', 'forward', 'backward'}, optional) – The sliding window mode: - ‘bi’ (default): Bidirectional sliding window. - ‘forward’: Forward sliding window. - ‘backward’: Backward sliding window.
n_points_migration (int, optional) – The number of points used for fitting the linear function in the MSD calculation.
n_points_transport (int, optional) – The number of points used for fitting the alpha function in the anomalous exponent calculation.

Returns:

s_msd (ndarray) – Sliding Mean Square Displacement values calculated using the sliding window approach.
s_alpha (ndarray) – Sliding anomalous exponent (alpha) values calculated using the sliding window approach.

Raises:

AssertionError – If the window size is not larger than the number of fit points.

Notes

The input trajectories (x, y) are assumed to be in the same unit of length.
The time unit used in the data should be consistent with the time intervals in the timeline array.

Examples

>>> import numpy as np
>>> x = np.array([1, 2, 4, 7, 11, 15, 20])
>>> y = np.array([0, 3, 5, 8, 10, 14, 18])
>>> timeline = np.array([0, 1, 2, 3, 4, 5, 6])
>>> window = 3
>>> s_msd, s_alpha = sliding_msd(x, y, timeline, window, n_points_migration=2, n_points_transport=3)

celldetective.signals.sliding_msd_drift(x: ndarray, y: ndarray, timeline: ndarray, window: int, mode: Literal['bi', 'forward', 'backward'] = 'bi', n_points_migration: int = 7, n_points_transport: int = 7, r2_threshold: float = 0.75) → Tuple[ndarray, ndarray][source]

Computes the sliding mean squared displacement (MSD) with drift for particle trajectories.

This function calculates the diffusion coefficient and drift velocity of particles based on their x and y positions over time. It uses a sliding window approach to estimate the MSD at each point in time, fitting the MSD to the equation MSD = 4Dt + V^2t^2 to extract the diffusion coefficient (D) and drift velocity (V).

Parameters:

x (ndarray) – The x positions of the particle over time.
y (ndarray) – The y positions of the particle over time.
timeline (ndarray) – The time points corresponding to the x and y positions.
window (int) – The size of the sliding window used to calculate the MSD at each point in time.
mode (str, optional) – The mode of sliding window calculation. Options are ‘bi’ for bidirectional, ‘forward’, or ‘backward’. Default is ‘bi’.
n_points_migration (int, optional) – The number of initial points from the calculated MSD to use for fitting the migration model. Default is 7.
n_points_transport (int, optional) – The number of initial points from the calculated MSD to use for fitting the transport model. Default is 7.
r2_threshold (float, optional) – The R-squared threshold used to validate the fit. Default is 0.75.

Returns:

A tuple containing two ndarrays: the estimated diffusion coefficients and drift velocities for each point in time.

Return type:

Raises:

AssertionError – If the window size is not larger than the number of fit points or if the window size is even when mode is ‘bi’.

Notes

The function assumes a uniform time step between each point in the timeline.
The ‘bi’ mode requires an odd-sized window to symmetrically calculate the MSD around each point in time.
The curve fitting is performed using the curve_fit function from scipy.optimize, fitting to the drift_msd model.

Examples

>>> x = np.random.rand(100)
>>> y = np.random.rand(100)
>>> timeline = np.arange(100)
>>> window = 11
>>> diffusion, velocity = sliding_msd_drift(x, y, timeline, window, mode='bi')
# Calculates the diffusion coefficient and drift velocity using a bidirectional sliding window.

celldetective.signals.train_signal_model(config: str) → None[source]

Initiates the training of a signal detection model using a specified configuration file.

This function triggers an external Python script to train a signal detection model. The training configuration, including data paths, model parameters, and training options, are specified in a JSON configuration file. The function asserts the existence of the configuration file before proceeding with the training process.

Parameters:: config (str) – The file path to the JSON configuration file specifying training parameters. This path must be valid and the configuration file must be correctly formatted according to the expectations of the ‘train_signal_model.py’ script.
Raises:: AssertionError – If the specified configuration file does not exist at the given path.

Notes

The external training script ‘train_signal_model.py’ is expected to be located in a predefined directory relative to this function and is responsible for the actual model training process.
The configuration file should include details such as data directories, model architecture specifications, training hyperparameters, and any preprocessing steps required.

Examples

>>> config_path = '/path/to/training_config.json'
>>> train_signal_model(config_path)
# This will execute the 'train_signal_model.py' script using the parameters specified in 'training_config.json'.

Events

Events Module

This module handles the processing of time-to-event data and survival analysis. It is designed to transform tracking data into formats suitable for survival analysis (e.g., Kaplan-Meier estimators) to study event dynamics like cell death or division.

Key Features

Data Transformation: Converts raw tracking and event data into event/censorship indicators and survival times.
Survival Analysis: Wrappers for computing and fitting Kaplan-Meier survival curves.
Censorship Handling: robustly handles left and right censorship in time-series data.

Main Functions

switch_to_events: Core function to convert class and time data into survival analysis format (events vs. censored).
compute_survival: high-level function to compute survival statistics for a specific class of interest from a dataframe.

Dependencies

lifelines: Used for Kaplan-Meier fitting and survival analysis statistics.

celldetective.events.compute_survival(df: DataFrame, class_of_interest: str, t_event: str, t_reference: str | None = None, FrameToMin: float = 1.0, cut_observation_time: float | None = None, pairs: bool = False) → KaplanMeierFitter | None[source]

Computes survival analysis for a specific class of interest within a dataset, returning a fitted Kaplan-Meier survival curve based on event and reference times.

Parameters:

df (pandas.DataFrame) – The dataset containing tracking data, event times, and other relevant columns for survival analysis.
class_of_interest (str) – The name of the column that specifies the class for which survival analysis is to be computed.
t_event (str) – The column indicating the time of the event of interest (e.g., cell death or migration stop).
t_reference (str or None, optional) – The reference column indicating the start or origin time for each track (e.g., detection time). If None, events are not left-censored (default is None).
FrameToMin (float, optional) – Conversion factor to scale the frame time to minutes (default is 1, assuming no scaling).
cut_observation_time (float or None, optional) – A cutoff time to artificially reduce the observation window and exclude late events. If None, uses all available data (default is None).
pairs (bool, optional) – Whether the data represents pairs of cells. If True, grouping is done by ‘REFERENCE_ID’ and ‘NEIGHBOR_ID’. Default is False.

Returns:

ks – A fitted Kaplan-Meier estimator object. If there are no events, returns None.

Return type:

lifelines.KaplanMeierFitter or None

Notes

The function groups the data by ‘position’ and ‘TRACK_ID’, extracting the minimum class_of_interest and t_event values for each track.
If t_reference is provided, the analysis assumes left-censoring and will use t_reference as the origin time for each track.
The function calls switch_to_events to determine the event occurrences and their associated survival times.
A Kaplan-Meier estimator (KaplanMeierFitter) is fitted to the data to compute the survival curve.

Example

>>> ks = compute_survival(df, class_of_interest="class_custom", t_event="time_custom", t_reference="t_firstdetection")
>>> ks.plot_survival_function()

celldetective.events.switch_to_events(classes: Sequence[int], event_times: Sequence[float], max_times: Sequence[float], origin_times: Sequence[float] | None = None, left_censored: bool = True, FrameToMin: float | None = None, cut_observation_time: float | None = None) → Tuple[List[int], List[float]][source]

Converts time-to-event data into a format suitable for survival analysis, optionally adjusting for left censorship and converting time units.

This function processes event data by classifying each event based on whether it occurred or was censored by the end of the observation period. It calculates the survival time for each event, taking into account the possibility of left censorship and the option to convert time units (e.g., from frames to minutes).

Parameters:

classes (array_like) – An array indicating the class of each event (e.g., 0 for event, 1 for non-event, 2 for else).
event_times (array_like) – An array of times at which events occurred. For non-events, this might represent the time of last observation.
max_times (array_like) – An array of maximum observation times for each event.
origin_times (array_like, optional) – An array of origin times for each event. If None, origin times are assumed to be zero, and left_censored is automatically set to False (default is None).
left_censored (bool, optional) – Indicates whether to adjust for left censorship. If True, events with origin times are considered left-censored if the origin time is zero (default is True).
FrameToMin (float, optional) – A conversion factor to transform survival times from frames (or any other unit) to minutes. If None, no conversion is applied (default is None).
cut_observation_time (float or None, optional) – A cutoff time to artificially reduce the observation window and exclude late events. If None, uses all available data (default is None).

Returns:

A tuple containing two lists: events and survival_times. events is a list of binary indicators (1 for event occurrence, 0 for censorship), and survival_times is a list of survival times corresponding to each event or censorship.

Return type:

tuple of lists

Notes

The function assumes that classes, event_times, max_times, and origin_times (if provided) are all arrays of the same length.
This function is particularly useful in preparing time-to-event data for survival analysis models, especially when dealing with censored data and needing to adjust time units.

Examples

>>> classes = [0, 1, 0]
>>> event_times = [5, 10, 15]
>>> max_times = [20, 20, 20]
>>> origin_times = [0, 0, 5]
>>> events, survival_times = switch_to_events(classes, event_times, max_times, origin_times, FrameToMin=0.5)
# This would process the events considering left censorship and convert survival times to minutes.

Neighborhood

Neighborhood Module

This module provides improved algorithms for defining and analyzing local neighborhoods of cells. It supports various definitions of “neighborhood,” including distance-based and contact-based criteria.

Key Features

Distance-Based Neighbors: Identifies neighbors within a specified radius.
Contact-Based Neighbors: Identifies neighbors that are physically touching (based on segmentation masks).
Neighborhood Metrics: Computes statistics about the local environment, such as density or neighbor types.

Main Functions

distance_cut_neighborhood: Main function to compute distance-based neighborhoods for a set of objects.
contact_neighborhood: Computes contact-based neighborhoods using mask adjacency.
compute_attention_weight: Calculates weights based on proximity, useful for weighted neighborhood metrics.

Integrations

The output of this module (neighborhood lists) is often used by relative_measurements.py to compute detailed pair-wise statistics.

celldetective.neighborhood.compute_attention_weight(dist_matrix: ndarray, cut_distance: float, opposite_cell_status: ndarray, opposite_cell_ids: ndarray, axis: int = 1, include_dead_weight: bool = True) → Tuple[ndarray, ndarray][source]

Computes the attention weight for each cell based on its proximity to cells of an opposite type within a specified distance.

This function calculates the attention weight for cells by considering the distance to the cells of an opposite type within a given cutoff distance. It optionally considers only the ‘live’ opposite cells based on their status. The function returns two arrays: one containing the attention weights and another containing the IDs of the closest opposite cells.

Parameters:

dist_matrix (ndarray) – A 2D array representing the distance matrix between cells of two types.
cut_distance (float) – The cutoff distance within which opposite cells will influence the attention weight.
opposite_cell_status (ndarray) – An array indicating the status (e.g., live or dead) of each opposite cell. Only used when include_dead_weight is False.
opposite_cell_ids (ndarray) – An array containing the IDs of the opposite cells.
axis (int, optional) – The axis along which to compute the weights (default is 1). Axis 0 corresponds to rows, and axis 1 corresponds to columns.
include_dead_weight (bool, optional) – If True, includes all opposite cells within the cutoff distance in the weight calculation, regardless of their status. If False, only considers opposite cells that are ‘live’ (default is True).

Returns:

A tuple containing two arrays: weights and closest_opposite. weights is an array of attention weights for each cell, and closest_opposite is an array of the IDs of the closest opposite cells within the cutoff distance.

Return type:

tuple of ndarrays

celldetective.neighborhood.compute_contact_neighborhood_at_position(pos: str, distance: float | List[float], population: List[str] = ['effectors', 'targets'], theta_dist: float | List[float] = 20, img_shape: Tuple[int, int] = (2048, 2048), return_tables: bool = True, clear_neigh: bool = True, event_time_col: str | None = None, neighborhood_kwargs: Dict[str, Any] = {'attention_weight': True, 'compute_cum_sum': False, 'include_dead_weight': True, 'mode': 'two-pop', 'not_status_option': None, 'status': None, 'symmetrize': True}) → Tuple[DataFrame, ...] | None[source]

Computes neighborhood metrics for specified cell populations within a given position, based on distance criteria and additional parameters.

This function assesses the neighborhood interactions between two specified cell populations (or within a single population) at a given position. It computes various neighborhood metrics based on specified distances, considering the entire image or excluding edge regions. The results are optionally cleared of previous neighborhood calculations and can be returned as updated tables.

Parameters:

pos (str) – The path to the position directory where the analysis is to be performed.
distance (float or list of float) – The distance(s) in pixels to define neighborhoods.
population (list of str, optional) – Names of the cell populations to analyze. If a single population is provided, it is used for both populations in the analysis (default is [‘targets’, ‘effectors’]).
theta_dist (float or list of float, optional) – Edge threshold(s) in pixels to exclude cells close to the image boundaries from the analysis. If not provided, defaults to 90% of each specified distance.
img_shape (tuple of int, optional) – The dimensions (height, width) of the images in pixels (default is (2048, 2048)).
return_tables (bool, optional) – If True, returns the updated data tables for both populations (default is False).
clear_neigh (bool, optional) – If True, clears existing neighborhood columns from the data tables before computing new metrics (default is False).
event_time_col (str, optional) – The column name indicating the event time for each cell, required if mean neighborhood metrics are to be computed before events.
neighborhood_kwargs (dict, optional) – Additional keyword arguments for neighborhood computation, including mode, status options, and metrics (default includes mode ‘two-pop’, and symmetrization).

Returns:

If return_tables is True, returns the updated data tables for the specified populations. If only one population is analyzed, both returned data frames will be identical.

Return type:

pandas.DataFrame or (pandas.DataFrame, pandas.DataFrame)

Raises:

AssertionError – If the specified position path does not exist or if the number of distances and edge thresholds do not match.

celldetective.neighborhood.compute_neighborhood_at_position(pos: str, distance: float | List[float], population: str | List[str] = ['targets', 'effectors'], theta_dist: float | List[float] | None = None, img_shape: Tuple[int, int] = (2048, 2048), return_tables: bool = False, clear_neigh: bool = False, event_time_col: str | None = None, neighborhood_kwargs: Dict[str, Any] = {'attention_weight': True, 'compute_cum_sum': False, 'include_dead_weight': True, 'mode': 'two-pop', 'not_status_option': None, 'status': None, 'symmetrize': True}) → DataFrame | Tuple[DataFrame, DataFrame] | None[source]

Computes neighborhood metrics for specified cell populations within a given position, based on distance criteria and additional parameters.

This function assesses the neighborhood interactions between two specified cell populations (or within a single population) at a given position. It computes various neighborhood metrics based on specified distances, considering the entire image or excluding edge regions. The results are optionally cleared of previous neighborhood calculations and can be returned as updated tables.

Parameters:

pos (str) – The path to the position directory where the analysis is to be performed.
distance (float or list of float) – The distance(s) in pixels to define neighborhoods.
population (list of str, optional) – Names of the cell populations to analyze. If a single population is provided, it is used for both populations in the analysis (default is [‘targets’, ‘effectors’]).
theta_dist (float or list of float, optional) – Edge threshold(s) in pixels to exclude cells close to the image boundaries from the analysis. If not provided, defaults to 90% of each specified distance.
img_shape (tuple of int, optional) – The dimensions (height, width) of the images in pixels (default is (2048, 2048)).
return_tables (bool, optional) – If True, returns the updated data tables for both populations (default is False).
clear_neigh (bool, optional) – If True, clears existing neighborhood columns from the data tables before computing new metrics (default is False).
event_time_col (str, optional) – The column name indicating the event time for each cell, required if mean neighborhood metrics are to be computed before events.
neighborhood_kwargs (dict, optional) – Additional keyword arguments for neighborhood computation, including mode, status options, and metrics (default includes mode ‘two-pop’, and symmetrization).

Returns:

If return_tables is True, returns the updated data tables for the specified populations. If only one population is analyzed, both returned data frames will be identical.

Return type:

pandas.DataFrame or (pandas.DataFrame, pandas.DataFrame)

Raises:

AssertionError – If the specified position path does not exist or if the number of distances and edge thresholds do not match.

celldetective.neighborhood.compute_neighborhood_metrics(neigh_table: DataFrame, neigh_col: str, metrics: List[str] = ['inclusive', 'exclusive', 'intermediate'], decompose_by_status: bool = False) → DataFrame[source]

Computes and appends neighborhood metrics to a dataframe based on specified neighborhood characteristics.

This function iterates through a dataframe grouped by either ‘TRACK_ID’ or [‘position’, ‘TRACK_ID’] (if ‘position’ column exists) and computes various neighborhood metrics (inclusive, exclusive, intermediate counts) for each cell. It can also decompose these metrics by cell status (e.g., live or dead) if specified.

Parameters:

neigh_table (pandas.DataFrame) – A dataframe containing neighborhood information for each cell, including position, track ID, frame, and a specified neighborhood column.
neigh_col (str) – The column name in neigh_table that contains neighborhood information (e.g., a list of neighbors with their attributes).
metrics (list of str, optional) – The metrics to be computed from the neighborhood information. Possible values include ‘inclusive’, ‘exclusive’, and ‘intermediate’. Default is [‘inclusive’, ‘exclusive’, ‘intermediate’].
decompose_by_status (bool, optional) – If True, the metrics are computed separately for different statuses (e.g., live or dead) of the neighboring cells. Default is False.

Returns:

The input dataframe with additional columns for each of the specified metrics, and, if decompose_by_status is True, separate metrics for each status.

Return type:

pandas.DataFrame

Notes

‘inclusive’ count refers to the total number of neighbors.
‘exclusive’ count refers to the number of neighbors that are closest.
‘intermediate’ count refers to the sum of weights attributed to neighbors, representing a weighted count.
If decompose_by_status is True, metrics are appended with ‘_s0’ or ‘_s1’ to indicate the status they correspond to.

Examples

>>> neigh_table = pd.DataFrame({
...     'TRACK_ID': [1, 1, 2, 2],
...     'FRAME': [1, 2, 1, 2],
...     'neighborhood_info': [{'weight': 1, 'status': 1, 'closest': 1}, ...]  # example neighborhood info
... })
>>> neigh_col = 'neighborhood_info'
>>> updated_neigh_table = compute_neighborhood_metrics(neigh_table, neigh_col, metrics=['inclusive'], decompose_by_status=True)
# Computes the inclusive count of neighbors for each cell, decomposed by cell status.

celldetective.neighborhood.contact_neighborhood(labelsA: ndarray, labelsB: ndarray | None = None, border: int = 3, connectivity: int = 2) → ndarray[source]

Identifies pairs of cells that are in contact or close proximity.

Parameters:

labelsA (ndarray) – Label image for the first population.
labelsB (ndarray, optional) – Label image for the second population.
border (int, optional) – Border expansion size to check for contact. Default is 3.
connectivity (int, optional) – Connectivity for pixel graph. Default is 2.

Returns:

Array of unique pairs of contacting cell labels.

Return type:

ndarray

celldetective.neighborhood.distance_cut_neighborhood(setA: DataFrame, setB: DataFrame, distance: float | List[float], mode: str = 'two-pop', status: List[str] | None = None, not_status_option: List[bool] | None = None, compute_cum_sum: bool = True, attention_weight: bool = True, symmetrize: bool = True, include_dead_weight: bool = True, column_labels: Dict[str, str] = {'time': 'FRAME', 'track': 'TRACK_ID', 'x': 'POSITION_X', 'y': 'POSITION_Y'}) → Tuple[DataFrame, DataFrame][source]

Match neighbors in set A and B within a circle of radius d.

Parameters:

setA (pandas.DataFrame) – Trajectory or position set A.
setB (pandas.DataFrame) – Trajectory or position set B.
distance (float) – Cut-distance in pixels to match neighboring pairs.
mode (str) – neighboring mode, between ‘two-pop’ (e.g. target-effector) and ‘self’ (target-target or effector-effector).
status (None or status)
not_status_option (str, optional) – A string to specify status options to exclude (default is None).
compute_cum_sum (bool, optional) – Compute cumulated time of presence of neighbours (only if trajectories available for both sets) (default is True).
attention_weight (bool, optional) – Compute the attention weight (how much a cell of set B is shared across cells of set A) (default is True).
symmetrize (bool, optional) – Write in set B the neighborhood of set A (default is True).
include_dead_weight (bool, optional) – Do not count dead cells when establishing attention weight (default is True).
column_labels (dict, optional) – Dictionary specifying column names for ‘track’, ‘time’, ‘x’, and ‘y’. Default is {‘track’: ‘TRACK_ID’, ‘time’: ‘FRAME’, ‘x’: ‘POSITION_X’, ‘y’: ‘POSITION_Y’}.

celldetective.neighborhood.extract_neighborhood_in_pair_table(df: DataFrame, distance: int | None = None, reference_population: str = 'targets', neighbor_population: str = 'effectors', mode: str = 'circle', neighborhood_key: str | None = None, contact_only: bool = True) → DataFrame[source]

Extracts data from a pair table that matches specific neighborhood criteria based on reference and neighbor populations, distance, and mode of neighborhood computation (e.g., circular or contact-based).

Parameters:

df (pandas.DataFrame) – DataFrame containing the pair table, which includes columns for ‘reference_population’, ‘neighbor_population’, and a column for neighborhood status.
distance (int, optional) – Radius in pixels for neighborhood calculation, used only if neighborhood_key is not provided.
reference_population (str, default="targets") – The reference population to consider. Must be either “targets” or “effectors”.
neighbor_population (str, default="effectors") – The neighbor population to consider. Must be either “targets” or “effectors”, used only if neighborhood_key is not provided.
mode (str, default="circle") – Neighborhood computation mode. Options are “circle” for radius-based or “contact” for contact-based neighborhood, used only if neighborhood_key is not provided.
neighborhood_key (str, optional) – A precomputed neighborhood key to identify specific neighborhoods. If provided, this key overrides distance, mode, and neighbor_population.
contact_only (bool, default=True) – If True, only rows indicating contact with the neighbor population (status=1) are kept; if False, both contact (status=1) and no-contact (status=0) rows are included.

Returns:

Filtered DataFrame containing rows that meet the specified neighborhood criteria.

Return type:

pandas.DataFrame

Notes

When neighborhood_key is None, the neighborhood column is generated based on the provided reference_population, neighbor_population, distance, and mode.
The function uses status_<neigh_col> to filter rows based on contact_only criteria.
Ensures that reference_population and neighbor_population are valid inputs and consistent with the neighborhood mode and key.

Example

>>> neighborhood_data = extract_neighborhood_in_pair_table(df, distance=50, reference_population="targets",
                                                                                                                   neighbor_population="effectors", mode="circle")
>>> neighborhood_data.head()

Raises:: AssertionError – If reference_population or neighbor_population is not valid, or if the required neighborhood status column does not exist in df.

celldetective.neighborhood.find_contact_neighbors(labels: ndarray, connectivity: int = 2) → ndarray[source]

Finds touching neighbors in a label image using a pixel graph.

Parameters:

labels (ndarray) – Label image.
connectivity (int, optional) – Connectivity for the pixel graph. Default is 2.

Returns:

Array of adjacent label pairs (touching masks).

Return type:

ndarray

celldetective.neighborhood.mask_contact_neighborhood(setA: DataFrame, setB: DataFrame, labelsA: List[ndarray], labelsB: List[ndarray] | None, distance: float | List[float], mode: str = 'two-pop', status: List[str] | None = None, not_status_option: List[bool] | None = None, compute_cum_sum: bool = True, attention_weight: bool = True, symmetrize: bool = True, include_dead_weight: bool = True, column_labels: Dict[str, str] = {'mask_id': 'class_id', 'time': 'FRAME', 'track': 'TRACK_ID', 'x': 'POSITION_X', 'y': 'POSITION_Y'}) → Tuple[DataFrame, DataFrame][source]

Match neighbors in set A and B within a circle of radius d.

Parameters:

setA (pandas.DataFrame) – Trajectory or position set A.
setB (pandas.DataFrame) – Trajectory or position set B.
labelsA (list of ndarray) – List of label images for set A.
labelsB (list of ndarray) – List of label images for set B.
distance (float) – Cut-distance in pixels to match neighboring pairs.
mode (str, optional) – Neighboring mode, e.g., ‘two-pop’ (default is ‘two-pop’).
status (list, optional) – Status columns to consider (default is None).
not_status_option (str, optional) – A string to specify status options to exclude (default is None).
compute_cum_sum (bool, optional) – Compute cumulated time of presence of neighbours (only if trajectories available for both sets) (default is True).
attention_weight (bool, optional) – Compute the attention weight (how much a cell of set B is shared across cells of set A) (default is True).
symmetrize (bool, optional) – Write in set B the neighborhood of set A (default is True).
include_dead_weight (bool, optional) – Do not count dead cells when establishing attention weight (default is True).
column_labels (dict, optional) – Dictionary specifying column names for ‘track’, ‘time’, ‘x’, ‘y’ and ‘mask_id’. Default is {‘track’: ‘TRACK_ID’, ‘time’: ‘FRAME’, ‘x’: ‘POSITION_X’, ‘y’: ‘POSITION_Y’, ‘mask_id’: ‘class_id’}.

celldetective.neighborhood.mean_neighborhood_after_event(neigh_table: DataFrame, neigh_col: str, event_time_col: str | None, metrics: List[str] = ['inclusive', 'exclusive', 'intermediate']) → DataFrame[source]

Computes the mean neighborhood metrics for each cell track after a specified event time.

This function calculates the mean values of specified neighborhood metrics (inclusive, exclusive, intermediate) for each cell track after the event time. The function requires the neighborhood metrics to have been previously computed and appended to the input dataframe. It operates on grouped data based on position and track ID, handling cases with or without position information.

Parameters:

neigh_table (pandas.DataFrame) – A dataframe containing cell track data with precomputed neighborhood metrics and event time information.
neigh_col (str) – The base name of the neighborhood metric columns in neigh_table.
event_time_col (str or None) – The column name indicating the event time for each cell track. If None, the maximum frame number in the dataframe is used as the event time for all tracks.
metrics (list, optional) – List of metrics to compute. Default is [“inclusive”, “exclusive”, “intermediate”].

Returns:

The input dataframe with added columns for the mean neighborhood metrics before the event for each cell track. The new columns are named as ‘mean_count_{metric}_{neigh_col}_before_event’, where {metric} is one of ‘inclusive’, ‘exclusive’, ‘intermediate’.

Return type:

pandas.DataFrame

celldetective.neighborhood.mean_neighborhood_before_event(neigh_table: DataFrame, neigh_col: str, event_time_col: str | None, metrics: List[str] = ['inclusive', 'exclusive', 'intermediate']) → DataFrame[source]

Computes the mean neighborhood metrics for each cell track before a specified event time.

This function calculates the mean values of specified neighborhood metrics (inclusive, exclusive, intermediate) for each cell track up to and including the frame of an event. The function requires the neighborhood metrics to have been previously computed and appended to the input dataframe. It operates on grouped data based on position and track ID, handling cases with or without position information.

Parameters:

neigh_table (pandas.DataFrame) – A dataframe containing cell track data with precomputed neighborhood metrics and event time information.
neigh_col (str) – The base name of the neighborhood metric columns in neigh_table.
event_time_col (str or None) – The column name indicating the event time for each cell track. If None, the maximum frame number in the dataframe is used as the event time for all tracks.
metrics (list, optional) – List of metrics to compute. Default is [“inclusive”, “exclusive”, “intermediate”].

Returns:

The input dataframe with added columns for the mean neighborhood metrics before the event for each cell track. The new columns are named as ‘mean_count_{metric}_{neigh_col}_before_event’, where {metric} is one of ‘inclusive’, ‘exclusive’, ‘intermediate’.

Return type:

pandas.DataFrame

celldetective.neighborhood.merge_labels(labelsA: ndarray, labelsB: ndarray) → ndarray[source]

Merges two label images into one.

Parameters:

labelsA (ndarray) – First label image.
labelsB (ndarray) – Second label image.

Returns:

Merged label image where non-zero pixels from labelsB overwrite labelsA.

Return type:

ndarray

celldetective.neighborhood.set_live_status(setA: DataFrame, setB: DataFrame, status: List[str] | None, not_status_option: List[bool] | None) → Tuple[DataFrame, DataFrame, List[str] | None][source]

Updates the live status for cells in two datasets based on specified status columns and options.

This function assigns a live status to cells in two datasets (setA and setB) based on the provided status columns and options. If no status column is provided, all cells are marked as live. Otherwise, the function updates the datasets based on the status criteria, potentially inverting the status based on the not_status_option.

Parameters:

setA (pandas.DataFrame) – The first dataset containing trajectory or position information for cells.
setB (pandas.DataFrame) – The second dataset containing trajectory or position information for cells.
status (list or None) – A list containing the names of the columns in setA and setB that classify cells as alive (1) or dead (0). If None, all cells are considered alive. The list should contain exactly two elements.
not_status_option (list) – A list containing boolean values indicating whether to invert the status for setA and setB, respectively. True means the status should be inverted; False means it should not.

Returns:

A tuple containing the updated setA and setB DataFrames, along with the final status column names used to classify cells in each set.

Return type:

celldetective.neighborhood.sign(num: float | int) → int[source]

Returns the sign of a number.

Parameters:: num (float or int) – Input number.
Returns:: -1 if num < 0, else 1.
Return type:: int

Interactions

Relative Measurements Module

This module calculates quantitative metrics describing the relationship between pairs of objects (reference and neighbor). It relies on neighborhood definitions provided by the neighborhood module.

Key Features

Spatial Metrics: Computes relative distance, angle, and orientation between cell pairs.
Temporal Metrics: Calculates relative velocity and interaction duration.
Signal Coupling: Analyzes how signals correlates between measuring pairs.

Main Functions

measure_pairs: Computes instantaneous spatial relationships for identified pairs.
measure_pair_signals_at_position: Extends pair measurements with signal analysis and temporal derivatives.
rel_measure_at_position: Wrapper script to execute relative measurements for an entire position.

Input

Requires pre-computed tracking tables (pkl or csv) containing neighborhood information columns.

celldetective.relative_measurements.expand_pair_table(data: DataFrame) → DataFrame[source]

Expands a pair table by merging reference and neighbor trajectory data from CSV files based on the specified reference and neighbor populations, and their associated positions and frames.

Parameters:: data (pandas.DataFrame) – DataFrame containing the pair table
Returns:: Expanded DataFrame that includes merged reference and neighbor data, sorted by position, reference population, neighbor population, and frame. Rows without values in REFERENCE_ID, NEIGHBOR_ID, reference_population, or neighbor_population are dropped.
Return type:: pandas.DataFrame

Notes

For each unique pair of reference_population and neighbor_population, the function identifies corresponding trajectories CSV files based on the position identifier.
The function reads the trajectories CSV files, prefixes columns with reference_ or neighbor_ to avoid conflicts, and merges data from reference and neighbor tables based on TRACK_ID or ID, and FRAME.
Merges are performed in an outer join manner to retain all rows, regardless of missing values in the target files.
The final DataFrame is sorted and cleaned to ensure only valid pairings are included.

Example

>>> expanded_df = expand_pair_table(pair_table)
>>> expanded_df.head()

Raises:: AssertionError – If reference_population or neighbor_population is not found in the columns of data.

celldetective.relative_measurements.extract_neighborhood_settings(neigh_string: str, population: str = 'targets') → dict[source]

Extract neighborhood settings from a given string.

Parameters:

neigh_string (str) – The string describing the neighborhood settings. Must start with ‘neighborhood’.
population (str, optional) – The population type (‘targets’ by default). Can be either ‘targets’ or ‘effectors’.

Returns:

A dictionary containing the neighborhood protocol with keys:

’reference’str
The reference population.

’neighbor’str
The neighbor population.

’type’str
The type of neighborhood (‘circle’ or ‘contact’).

’distance’float
The distance parameter for the neighborhood.

’description’str
The original neighborhood string.

Return type:

dict

Raises:

AssertionError – If the neigh_string does not start with ‘neighborhood’.

Notes

The function determines the neighbor population based on the given population.
The neighborhood type and distance are extracted from the neigh_string.
The description field in the returned dictionary contains the original neighborhood string.

Examples

>>> extract_neighborhood_settings('neighborhood_self_contact_5_px', 'targets')
{'reference': 'targets', 'neighbor': 'targets', 'type': 'contact', 'distance': 5.0, 'description': 'neighborhood_self_contact_5_px'}

celldetective.relative_measurements.extract_neighborhoods_from_pickles(pos: str, populations: List[str] = ['targets', 'effectors']) → List[dict][source]

Extract neighborhood protocols from pickle files located at a given position.

Parameters:

pos (str) – The base directory path where the pickle files are located.
populations (list of str, optional) – List of populations to extract neighborhoods from. Default is [“targets”, “effectors”].

Returns:

A list of dictionaries, each containing a neighborhood protocol. Each dictionary has the keys:

’reference’str
The reference population (‘targets’ or ‘effectors’).

’neighbor’str
The neighbor population.

’type’str
The type of neighborhood (‘circle’ or ‘contact’).

’distance’float
The distance parameter for the neighborhood.

’description’str
The original neighborhood string.

Return type:

list of dict

Notes

The function checks for the existence of pickle files containing target and effector trajectory data.
If the files exist, it loads the data and extracts columns that start with ‘neighborhood’.
The neighborhood settings are extracted using the extract_neighborhood_settings function.
The function assumes the presence of subdirectories ‘output/tables’ under the provided pos.

Examples

>>> protocols = extract_neighborhoods_from_pickles('/path/to/data')
>>> for protocol in protocols:
>>>         print(protocol)
{'reference': 'targets', 'neighbor': 'targets', 'type': 'contact', 'distance': 5.0, 'description': 'neighborhood_self_contact_5_px'}

celldetective.relative_measurements.measure_pair_signals_at_position(pos: str, neighborhood_protocol: dict, velocity_kwargs: dict = {'mode': 'bi', 'window': 3}) → DataFrame | None[source]

Measures signals and temporal properties for cell pairs at a specific position.

Parameters:

pos (str) – Path to the experimental position.
neighborhood_protocol (dict) – Dictionary containing neighborhood settings.
velocity_kwargs (dict, optional) – Arguments for velocity calculation (window size, mode). Default is {“window”: 3, “mode”: “bi”}.

Returns:

DataFrame containing temporal pair measurements, or None if data is missing.

Return type:

pandas.DataFrame or None

celldetective.relative_measurements.measure_pairs(pos: str, neighborhood_protocol: dict) → DataFrame | None[source]

Measures properties of cell pairs defined by a neighborhood protocol at a specific position.

Parameters:

pos (str) – Path to the experimental position.
neighborhood_protocol (dict) – Dictionary containing neighborhood settings (reference, neighbor, type, distance, etc.).

Returns:

DataFrame containing paired measurements, or None if data is missing.

Return type:

pandas.DataFrame or None

celldetective.relative_measurements.rel_measure_at_position(pos: str) → None[source]

Executes the relative measurement script for a given position.

Parameters:: pos (str) – Path to the experimental position.

celldetective.relative_measurements.timeline_matching(timeline1: ndarray, timeline2: ndarray) → Tuple[ndarray, List[int], List[int]][source]

Match two timelines and create a unified timeline with corresponding indices.

Parameters:

timeline1 (array-like) – The first timeline to be matched.
timeline2 (array-like) – The second timeline to be matched.

Returns:

A tuple containing:

full_timelinenumpy.ndarray
The unified timeline spanning from the minimum to the maximum time point in the input timelines.

index1list of int
The indices of timeline1 in the full_timeline.

index2list of int
The indices of timeline2 in the full_timeline.

Return type:

Examples

>>> timeline1 = [1, 2, 5, 6]
>>> timeline2 = [2, 3, 4, 6]
>>> full_timeline, index1, index2 = timeline_matching(timeline1, timeline2)
>>> print(full_timeline)
[1 2 3 4 5 6]
>>> print(index1)
[0, 1, 4, 5]
>>> print(index2)
[1, 2, 3, 5]

Notes

The function combines the two timelines and generates a continuous range from the minimum to the maximum time point.
It then finds the indices of the original timelines in this unified timeline.
The function assumes that the input timelines consist of integer values.

celldetective.relative_measurements.update_effector_table(df_relative: DataFrame, df_effector: DataFrame) → DataFrame[source]

Updates the effector table to mark effectors that are part of a neighborhood.

Parameters:

df_relative (pandas.DataFrame) – DataFrame containing relative measurements (pairs).
df_effector (pandas.DataFrame) – DataFrame containing effector data.

Returns:

Updated effector DataFrame with ‘group_neighborhood’ column.

Return type:

pandas.DataFrame

Utils

celldetective.utils.io.remove_file_if_exists(file: str | Path)[source]

Remove a file if it exists.

Parameters:: file (str or Path) – Path to the file to remove.

celldetective.utils.io.save_tiff_imagej_compatible(file: str | Path, img: ndarray, axes: str, **imsave_kwargs: Any) → None[source]

Save image in ImageJ-compatible TIFF format. adapted from https://github.com/CSBDeep/CSBDeep/blob/main/csbdeep/utils/utils.py

Parameters:

file (str) – File name
img (numpy.ndarray) – Image
axes (str) – Axes of img
imsave_kwargs (dict, optional) – Keyword arguments for tifffile.imsave()

celldetective.utils.color_mappings.color_from_class(cclass: int, recently_modified: bool = False) → str[source]

Get color based on class.

Parameters:

cclass (int) – Class ID.
recently_modified (bool, optional) – If True, use recently modified color scheme. Default is False.

Returns:

Color string.

Return type:

str

celldetective.utils.color_mappings.color_from_status(status: int, recently_modified: bool = False) → str[source]

Get color based on status.

Parameters:

status (int) – Status code.
recently_modified (bool, optional) – If True, use recently modified color scheme. Default is False.

Returns:

Color string.

Return type:

str

celldetective.utils.data_cleaning.collapse_trajectories_by_status(df: DataFrame, status: str | None = None, projection: str = 'mean', population: str = 'effectors', groupby_columns: List[str] = ['position', 'TRACK_ID']) → DataFrame | None[source]

Collapse trajectories based on status.

Parameters:

df (DataFrame) – Tracking data.
status (str, optional) – Status column name. Default is None.
projection (str, optional) – Projection method (e.g., “mean”). Default is “mean”.
population (str, optional) – Population name. Default is “effectors”.
groupby_columns (list, optional) – Columns to group by. Default is [“position”, “TRACK_ID”].

Returns:

Collapsed dataframe, or None if invalid status.

Return type:

DataFrame or None

celldetective.utils.data_cleaning.extract_cols_from_table_list(tables: List[str], nrows: int = 1) → ndarray[source]

Extracts a unique list of column names from a list of CSV tables.

Parameters:

tables (list of str) – A list of file paths to the CSV tables from which to extract column names.
nrows (int, optional) – The number of rows to read from each table to identify the columns. Default is 1.

Returns:

An array of unique column names found across all the tables.

Return type:

numpy.ndarray

Notes

This function reads only the first nrows rows of each table to improve performance when dealing with large files.
The function ensures that column names are unique by consolidating them using numpy.unique.

Examples

>>> tables = ["table1.csv", "table2.csv"]
>>> extract_cols_from_table_list(tables)
array(['Column1', 'Column2', 'Column3'], dtype='<U8')

celldetective.utils.data_cleaning.extract_identity_col(trajectories: DataFrame) → str | None[source]

Determines the identity column name in a DataFrame of trajectories.

This function checks the provided DataFrame for the presence of a column that can serve as the identity column. It first looks for the column ‘TRACK_ID’. If ‘TRACK_ID’ exists but contains only null values, it checks for the column ‘ID’ instead. If neither column is found, the function returns None and prints a message indicating the issue.

Parameters:: trajectories (pandas.DataFrame) – A DataFrame containing trajectory data. The function assumes that the identity of each trajectory might be stored in either the ‘TRACK_ID’ or ‘ID’ column.
Returns:: The name of the identity column (‘TRACK_ID’ or ‘ID’) if found; otherwise, None.
Return type:: str or None

celldetective.utils.data_cleaning.remove_redundant_features(features: List[str], reference_features: List[str], channel_names: List[str] | None = None) → List[str][source]

Remove redundant features from a list of features based on a reference feature list.

Parameters:

features (list) – The list of features to be filtered.
reference_features (list) – The reference list of features.
channel_names (list or None, optional) – The list of channel names. If provided, it is used to identify and remove redundant intensity features. Default is None.

Returns:

The filtered list of features without redundant entries.

Return type:

Notes

This function removes redundant features from the input list based on a reference list of features. Features that appear in the reference list are removed from the input list. Additionally, if the channel_names parameter is provided, it is used to identify and remove redundant intensity features. Intensity features that have the same mode (e.g., ‘mean’, ‘min’, ‘max’) as any of the channel names in the reference list are also removed.

Examples

>>> features = ['area', 'intensity_mean', 'intensity_max', 'eccentricity']
>>> reference_features = ['area', 'eccentricity']
>>> filtered_features = remove_redundant_features(features, reference_features)
>>> filtered_features
['intensity_mean', 'intensity_max']

>>> channel_names = ['brightfield', 'channel1', 'channel2']
>>> filtered_features = remove_redundant_features(features, reference_features, channel_names)
>>> filtered_features
['area', 'eccentricity']

celldetective.utils.data_cleaning.remove_trajectory_measurements(trajectories: DataFrame, column_labels: Dict[str, str] = {'time': 'FRAME', 'track': 'TRACK_ID', 'x': 'POSITION_X', 'y': 'POSITION_Y'}) → DataFrame[source]

Clear a measurement table, while keeping the tracking information.

Parameters:

trajectories (pandas.DataFrame) – The measurement table where each line is a cell at a timepoint and each column a tracking feature or measurement.
column_labels (dict, optional) – The column labels to use in the output DataFrame. Default is {‘track’: “TRACK_ID”, ‘time’: ‘FRAME’, ‘x’: ‘POSITION_X’, ‘y’: ‘POSITION_Y’}.

Returns:

A filtered DataFrame containing only the tracking columns.

Return type:

pandas.DataFrame

Examples

>>> trajectories_df = pd.DataFrame({
...     'TRACK_ID': [1, 1, 2],
...     'FRAME': [0, 1, 0],
...     'POSITION_X': [100, 105, 200],
...     'POSITION_Y': [150, 155, 250],
...     'area': [10,100,100],  # Additional column to be removed
... })
>>> filtered_df = remove_trajectory_measurements(trajectories_df)
>>> print(filtered_df)
#   pd.DataFrame({
#    'TRACK_ID': [1, 1, 2],
#    'FRAME': [0, 1, 0],
#    'POSITION_X': [100, 105, 200],
#    'POSITION_Y': [150, 155, 250],
#    })

celldetective.utils.data_cleaning.rename_intensity_column(df: DataFrame, channels: List[str] | ndarray) → DataFrame[source]

Rename intensity columns in a DataFrame based on the provided channel names.

Parameters:

df (pandas DataFrame) – The DataFrame containing the intensity columns.
channels (list) – A list of channel names corresponding to the intensity columns.

Returns:

The DataFrame with renamed intensity columns.

Return type:

pandas DataFrame

Notes

This function renames the intensity columns in a DataFrame based on the provided channel names. It searches for columns containing the substring ‘intensity’ in their names and replaces it with the respective channel name. The renaming is performed according to the order of the channels provided in the channels list.

It also applies specific renaming rules for tuple properties: - Center of Mass:

_0 -> _distance

_1 -> _angle

_2 -> _dx

_3 -> _dy

Radial Gradient:
- _0 -> _slope
- _1 -> _intercept
- _2 -> _r2

Examples

>>> data = {'intensity_0': [1, 2, 3], 'intensity_1': [4, 5, 6]}
>>> df = pd.DataFrame(data)
>>> channels = ['channel1', 'channel2']
>>> renamed_df = rename_intensity_column(df, channels)
# Rename the intensity columns in the DataFrame based on the provided channel names.

celldetective.utils.data_cleaning.tracks_to_btrack(df: DataFrame, exclude_nans: bool = False) → Tuple[ndarray, Dict[str, ndarray], Dict[Any, Any]][source]

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:

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

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)

celldetective.utils.data_loaders.get_position_pickle(pos: str, population: str, return_path: bool = False) → DataFrame | None | Tuple[DataFrame | None, str][source]

Retrieves the data table for a specified population at a given position, optionally returning the table’s file path.

This function locates and loads a CSV data table associated with a specific population (e.g., ‘targets’, ‘cells’) from a specified position directory. The position directory should contain an ‘output/tables’ subdirectory where the CSV file named ‘trajectories_{population}.csv’ is expected to be found. If the file exists, it is loaded into a pandas DataFrame; otherwise, None is returned.

Parameters:

pos (str) – The path to the position directory from which to load the data table.
population (str) – The name of the population for which the data table is to be retrieved. This name is used to construct the file name of the CSV file to be loaded.
return_path (bool, optional) – If True, returns a tuple containing the loaded data table (or None) and the path to the CSV file. If False, only the loaded data table (or None) is returned (default is False).

Returns:

If return_path is False, returns the loaded data table as a pandas DataFrame, or None if the table file does not exist. If return_path is True, returns a tuple where the first element is the data table (or None) and the second element is the path to the CSV file.

Return type:

pandas.DataFrame or None, or (pandas.DataFrame or None, str)

Examples

>>> df_pos = get_position_table('/path/to/position', 'targets')
# This will load the 'trajectories_targets.csv' table from the specified position directory into a pandas DataFrame.

>>> df_pos, table_path = get_position_table('/path/to/position', 'targets', return_path=True)
# This will load the 'trajectories_targets.csv' table and also return the path to the CSV file.

celldetective.utils.data_loaders.get_position_table(pos: str, population: str, return_path: bool = False) → DataFrame | None | Tuple[DataFrame | None, str][source]

Retrieves the data table for a specified population at a given position, optionally returning the table’s file path.

This function locates and loads a CSV data table associated with a specific population (e.g., ‘targets’, ‘cells’) from a specified position directory. The position directory should contain an ‘output/tables’ subdirectory where the CSV file named ‘trajectories_{population}.csv’ is expected to be found. If the file exists, it is loaded into a pandas DataFrame; otherwise, None is returned.

Parameters:

pos (str) – The path to the position directory from which to load the data table.
population (str) – The name of the population for which the data table is to be retrieved. This name is used to construct the file name of the CSV file to be loaded.
return_path (bool, optional) – If True, returns a tuple containing the loaded data table (or None) and the path to the CSV file. If False, only the loaded data table (or None) is returned (default is False).

Returns:

If return_path is False, returns the loaded data table as a pandas DataFrame, or None if the table file does not exist. If return_path is True, returns a tuple where the first element is the data table (or None) and the second element is the path to the CSV file.

Return type:

pandas.DataFrame or None, or (pandas.DataFrame or None, str)

Examples

>>> df_pos = get_position_table('/path/to/position', 'targets')
# This will load the 'trajectories_targets.csv' table from the specified position directory into a pandas DataFrame.

>>> df_pos, table_path = get_position_table('/path/to/position', 'targets', return_path=True)
# This will load the 'trajectories_targets.csv' table and also return the path to the CSV file.

celldetective.utils.data_loaders.interpret_tracking_configuration(config: str | None) → str | Any[source]

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:: The resolved path to the configuration file.
Return type:: str

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'

celldetective.utils.data_loaders.load_experiment_tables(experiment: str, population: str = 'targets', well_option: str | List[str] = '*', position_option: str | List[int | str] = '*', return_pos_info: bool = False, load_pickle: bool = False, progress_callback: Callable[[float, float], bool] | None = None) → DataFrame | None | Tuple[DataFrame | None, DataFrame][source]

Load tabular data for an experiment, optionally including position-level information.

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) – Path to the experiment folder to load data for.
population (str, optional) – 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, 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.
progress_callback (callable, optional) – A function to report progress. Should accept a two arguments (well_progress, pos_progress) and return True to continue or False to cancel. Default is None.

Returns:

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

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 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)

celldetective.utils.data_loaders.load_tracking_data(position: str, prefix: str = 'Aligned', population: str = 'target') → Tuple[DataFrame, ndarray, ndarray][source]

Load the tracking data, labels, and stack for a given position and population.

Parameters:

position (str) – The position or directory where the data is located.
prefix (str, optional) – The prefix used in the filenames of the stack images (default is “Aligned”).
population (str, optional) – The population to load the data for. Options are “target” or “effector” (default is “target”).

Returns:

trajectories (DataFrame) – The tracking data loaded as a pandas DataFrame.
labels (ndarray) – The segmentation labels loaded as a numpy ndarray.
stack (ndarray) – The image stack loaded as a numpy ndarray.

Notes

This function loads the tracking data, labels, and stack for a given position and population. It reads the trajectories from the appropriate CSV file based on the specified population. The stack and labels are located using the locate_stack_and_labels function. The resulting tracking data is returned as a pandas DataFrame, and the labels and stack are returned as numpy ndarrays.

Examples

>>> trajectories, labels, stack = load_tracking_data(position, population="target")
# Load the tracking data, labels, and stack for the specified position and target population.

celldetective.utils.dataset_helpers.compute_weights(y: ndarray) → Dict[Any, float][source]

Compute class weights based on the input labels.

Parameters:: y (array-like) – Array of labels.
Returns:: A dictionary containing the computed class weights.
Return type:: dict

Notes

This function calculates the class weights based on the input labels (y) using the “balanced” method. The class weights are computed to address the class imbalance problem, where the weights are inversely proportional to the class frequencies.

The function returns a dictionary (class_weights) where the keys represent the unique classes in y and the values represent the computed weights for each class.

Examples

>>> labels = np.array([0, 1, 0, 1, 1])
>>> weights = compute_weights(labels)
>>> print(weights)
{0: 1.5, 1: 0.75}
# Compute class weights for the binary labels.

>>> labels = np.array([0, 1, 2, 0, 1, 2, 2])
>>> weights = compute_weights(labels)
>>> print(weights)
{0: 1.1666666666666667, 1: 1.1666666666666667, 2: 0.5833333333333334}
# Compute class weights for the multi-class labels.

celldetective.utils.dataset_helpers.split_by_ratio(arr: ndarray, *ratios: float) → List[List[Any]][source]

Split an array into multiple chunks based on given ratios.

Parameters:

arr (array-like) – The input array to be split.
*ratios (float) – Ratios specifying the proportions of each chunk. The sum of ratios should be less than or equal to 1.

Returns:

A list of arrays containing the splits/chunks of the input array.

Return type:

Notes

This function randomly permutes the input array (arr) and then splits it into multiple chunks based on the provided ratios. The ratios determine the relative sizes of the resulting chunks. The sum of the ratios should be less than or equal to 1. The function uses the accumulated ratios to determine the split indices.

The function returns a list of arrays representing the splits of the input array. The number of splits is equal to the number of provided ratios. If there are more ratios than splits, the extra ratios are ignored.

Examples

>>> arr = np.arange(10)
>>> splits = split_by_ratio(arr, 0.6, 0.2, 0.2)
>>> print(len(splits))
3
# Split the array into 3 chunks with ratios 0.6, 0.2, and 0.2.

>>> arr = np.arange(100)
>>> splits = split_by_ratio(arr, 0.5, 0.25)
>>> print([len(split) for split in splits])
[50, 25]
# Split the array into 2 chunks with ratios 0.5 and 0.25.

celldetective.utils.dataset_helpers.train_test_split(data_x: ndarray, data_y1: ndarray, data_class: ndarray | None = None, validation_size: float = 0.25, test_size: float = 0, n_iterations: int = 10) → Dict[str, ndarray][source]

Split the dataset into training, validation, and test sets.

Parameters:

data_x (array-like) – Input features or independent variables.
data_y1 (array-like) – Target variable 1.
data_class (array-like, optional) – Target classification variable (e.g., cell type). Default is None.
validation_size (float, optional) – Proportion of the dataset to include in the validation set. Default is 0.25.
test_size (float, optional) – Proportion of the dataset to include in the test set. Default is 0.
n_iterations (int, optional) – Number of iterations to attempt splitting while ensuring all classes are present in training and validation sets. Default is 10.

Returns:

A dictionary containing the split datasets. Keys: “x_train”, “x_val”, “y1_train”, “y1_val”, “y2_train”, “y2_val”. If test_size > 0, additional keys: “x_test”, “y1_test”, “y2_test”.

Return type:

dict

Notes

This function divides the dataset into training, validation, and test sets based on the specified proportions. It shuffles the data and splits it according to the proportions defined by validation_size and test_size.

The input features (data_x) and target variables (data_y1, data_y2) should be arrays or array-like objects with compatible dimensions.

The function returns a dictionary containing the split datasets. The training set is assigned to “x_train”, “y1_train”, and “y2_train”. The validation set is assigned to “x_val”, “y1_val”, and “y2_val”. If test_size is greater than 0, the test set is assigned to “x_test”, “y1_test”, and “y2_test”.

celldetective.utils.downloaders.download_url_to_file(url: str, dst: str, progress: bool = True) → None[source]

Download object at the given URL to a local path. Thanks to torch, slightly modified, from Cellpose

Parameters:

url (str) – URL of the object to download.
dst (str) – Full path where object will be saved, e.g. /tmp/temporary_file.
progress (bool, optional) – Whether to display a progress bar to stderr. Default is True.

celldetective.utils.downloaders.download_zenodo_file(file: str, output_dir: str) → None[source]

Download a file from Zenodo.

Parameters:

file (str) – Name of the file to download.
output_dir (str) – Directory to save the downloaded file.

celldetective.utils.downloaders.get_zenodo_files(cat: str | None = None) → List[str] | Tuple[List[str], List[str]][source]

Get list of files available on Zenodo.

Parameters:: cat (str, optional) – Category of files to retrieve. Default is None.
Returns:: List of files, or (list of files, list of categories).
Return type:: list or tuple

celldetective.utils.experiment.auto_correct_masks(masks: ndarray, bbox_factor: float = 1.75, min_area: int = 9, fill_labels: bool = False) → ndarray[source]

Auto-correct masks by removing small objects and filling holes.

Parameters:

masks (ndarray) – Input masks.
bbox_factor (float, optional) – Bounding box factor for splitting merged objects. Default is 1.75.
min_area (int, optional) – Minimum area for objects. Default is 9.
fill_labels (bool, optional) – If True, fill holes in labels. Default is False.

Returns:

Corrected masks.

Return type:

ndarray

celldetective.utils.experiment.auto_load_number_of_frames(stack_path: str) → int | None[source]

Automatically load the number of frames from a stack.

Parameters:: stack_path (str) – Path to the stack file.
Returns:: Number of frames, or None if failed.
Return type:: int or None

celldetective.utils.experiment.collect_experiment_metadata(pos_path: str | None = None, well_path: str | None = None) → Dict[str, Any] | None[source]

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:

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.

Return type:

dict

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

celldetective.utils.experiment.control_tracking_table(position: str, calibration: float = 1.0, prefix: str = 'Aligned', population: str = 'target', column_labels: Dict[str, str] = {'frame': 'FRAME', 'label': 'class_id', 'track': 'TRACK_ID', 'x': 'POSITION_X', 'y': 'POSITION_Y'}) → None[source]

Control tracking table by viewing in Napari.

Parameters:

position (str) – Position directory path.
calibration (float, optional) – Spatial calibration factor. Default is 1.
prefix (str, optional) – Prefix of the stack file. Default is “Aligned”.
population (str, optional) – Population name. Default is “target”.
column_labels (dict, optional) – Mapping of column names. Default provided.

celldetective.utils.experiment.extract_experiment_channels(experiment: str | Path) → Tuple[ndarray, ndarray][source]

Extracts channel names and their indices from an experiment project.

Parameters:: experiment (str) – The file system path to the directory of the experiment project.
Returns:: A tuple containing two numpy arrays: channel_names and channel_indices. channel_names includes the names of the channels as specified in the configuration, and channel_indices includes their corresponding indices. Both arrays are ordered according to the channel indices.
Return type:: tuple

Examples

>>> experiment = "path/to/my_experiment"
>>> channels, indices = extract_experiment_channels(experiment)
>>> print(channels)
# array(['brightfield_channel', 'adhesion_channel', 'fitc_channel',
#    'cy5_channel'], dtype='<U19')
>>> print(indices)
# array([0, 1, 2, 3])

celldetective.utils.experiment.extract_experiment_folder_output(experiment_folder: str, destination_folder: str) → None[source]

Copies the output subfolder and associated tables from an experiment folder to a new location, making the experiment folder much lighter by only keeping essential data.

This function takes the path to an experiment folder and a destination folder as input. It creates a copy of the experiment folder at the destination, but only includes the output subfolders and their associated tables for each well and position within the experiment. This operation significantly reduces the size of the experiment data by excluding non-essential files.

The structure of the copied experiment folder is preserved, including the configuration file, well directories, and position directories within each well. Only the ‘output’ subfolder and its ‘tables’ subdirectory are copied for each position.

Parameters:

experiment_folder (str) – The path to the source experiment folder from which to extract data.
destination_folder (str) – The path to the destination folder where the reduced copy of the experiment will be created.

Notes

This function assumes that the structure of the experiment folder is consistent, with wells organized in subdirectories and each containing a position subdirectory. Each position subdirectory should have an ‘output’ folder and a ‘tables’ subfolder within it.
The function also assumes the existence of a configuration file in the root of the experiment folder, which is copied to the root of the destination experiment folder.

Examples

>>> extract_experiment_folder_output('/path/to/experiment_folder', '/path/to/destination_folder')
# This will copy the 'experiment_folder' to 'destination_folder', including only
# the output subfolders and their tables for each well and position.

celldetective.utils.experiment.extract_experiment_from_position(pos_path: str) → str[source]

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:: The path to the experiment directory, which is assumed to be three levels above the position directory.
Return type:: str

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'

celldetective.utils.experiment.extract_experiment_from_well(well_path: str) → str[source]

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:: The path to the experiment directory, which is assumed to be two levels above the well directory.
Return type:: str

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'

celldetective.utils.experiment.extract_position_name(pos: str) → str[source]

Extract the position name from a given position path.

This function takes a position path string, splits it by the OS-specific path separator, filters out any empty components, and extracts the position name, which is the last component of the path.

Parameters:: pos (str) – The position path string, where the position name is the last component.
Returns:: pos_name – The name of the position, extracted from the last component of the path.
Return type:: str

Examples

>>> pos_path = "path/to/position1"
>>> extract_position_name(pos_path)
'position1'

>>> pos_path = "another/path/positionA"
>>> extract_position_name(pos_path)
'positionA'

celldetective.utils.experiment.extract_well_from_position(pos_path: str) → str[source]

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:: The path to the well directory, which is assumed to be two levels above the position directory, with a trailing separator appended.
Return type:: str

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/'

celldetective.utils.experiment.extract_well_name_and_number(well: str) → Tuple[str, int][source]

Extract the well name and number from a given well path.

This function takes a well path string, splits it by the OS-specific path separator, and extracts the well name and number. The well name is the last component of the path, and the well number is derived by removing the ‘W’ prefix and converting the remaining part to an integer.

Parameters:

well (str) – The well path string, where the well name is the last component.

Returns:

well_name (str) – The name of the well, extracted from the last component of the path.
well_number (int) – The well number, obtained by stripping the ‘W’ prefix from the well name and converting the remainder to an integer.

Examples

>>> well_path = "path/to/W23"
>>> extract_well_name_and_number(well_path)
('W23', 23)

>>> well_path = "another/path/W1"
>>> extract_well_name_and_number(well_path)
('W1', 1)

celldetective.utils.experiment.fix_missing_labels(position: str, population: str = 'target', prefix: str = 'Aligned') → None[source]

Create empty label files for missing frames.

Parameters:

position (str) – Position directory path.
population (str, optional) – Population name. Default is “target”.
prefix (str, optional) – Prefix of the stack file. Default is “Aligned”.

celldetective.utils.experiment.get_config(experiment: str | Path) → str[source]

Retrieves the path to the configuration file for a given experiment.

Parameters:: experiment (str) – The file system path to the directory of the experiment project.
Returns:: The full path to the configuration file (config.ini) within the experiment directory.
Return type:: str
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'

celldetective.utils.experiment.get_experiment_antibodies(experiment: str | ~pathlib.Path, dtype: ~typing.Any = <class 'str'>) → ndarray[source]

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:

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.

Return type:

numpy.ndarray

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])

celldetective.utils.experiment.get_experiment_cell_types(experiment: str | ~pathlib.Path, dtype: ~typing.Any = <class 'str'>) → ndarray[source]

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:

An array of cell types for each well, converted to the specified data type.

Return type:

numpy.ndarray

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']

celldetective.utils.experiment.get_experiment_concentrations(experiment: str | ~pathlib.Path, dtype: ~typing.Any = <class 'str'>) → ndarray[source]

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:

An array of concentrations for each well, converted to the specified data type.

Return type:

numpy.ndarray

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]

celldetective.utils.experiment.get_experiment_labels(experiment: str | Path) → Dict[str, Any][source]

Get experiment labels.

Parameters:: experiment (str) – Path to the experiment directory.
Returns:: Dictionary containing labels.
Return type:: dict

celldetective.utils.experiment.get_experiment_metadata(experiment: str | Path) → Dict[str, Any][source]

Get experiment metadata.

Parameters:: experiment (str) – Path to the experiment directory.
Returns:: Dictionary containing metadata.
Return type:: dict

celldetective.utils.experiment.get_experiment_pharmaceutical_agents(experiment: str | ~pathlib.Path, dtype: ~typing.Any = <class 'str'>) → ndarray[source]

Retrieves the pharmaceutical agents 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 agents should be converted (default is str).

Returns:

An array of pharmaceutical agents for each well, converted to the specified data type.

Return type:

numpy.ndarray

Raises:

AssertionError – If the configuration file (config.ini) does not exist in the specified experiment directory.
KeyError – If the “pharmaceutical_agents” key is not found under the “Labels” section in the configuration file.
ValueError – If the retrieved agent 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 pharmaceutical_agents.
The agent names are assumed to be comma-separated values.
If the number of wells does not match the number of agents, the function generates a default set of values ranging from 0 to the number of wells minus 1.
The resulting agent names are converted to the specified dtype before being returned.

Example

>>> experiment = "/path/to/experiment"
>>> agents = get_experiment_pharmaceutical_agents(experiment, dtype=str)
>>> print(agents)
['AgentA', 'AgentB', 'AgentC', 'AgentD']

celldetective.utils.experiment.get_experiment_populations(experiment: str | ~pathlib.Path, dtype: ~typing.Any = <class 'str'>) → List[Any][source]

Get experiment populations.

Parameters:

experiment (str) – Path to the experiment directory.
dtype (type, optional) – Data type for the populations. Default is str.

Returns:

List of populations.

Return type:

celldetective.utils.experiment.get_experiment_wells(experiment: str) → ndarray[source]

Retrieves the list of well directories from a given experiment directory, sorted naturally and returned as a NumPy array of strings.

Parameters:: experiment (str) – The path to the experiment directory from which to retrieve well directories.
Returns:: An array of strings, each representing the full path to a well directory within the specified experiment. The array is empty if no well directories are found.
Return type:: np.ndarray

Notes

The function assumes well directories are prefixed with ‘W’ and uses this to filter directories within the experiment folder.
Natural sorting is applied to the list of wells to ensure that the order is intuitive (e.g., ‘W2’ comes before ‘W10’). This sorting method is especially useful when dealing with numerical sequences that are part of the directory names.

celldetective.utils.experiment.get_position_movie_path(pos: str, prefix: str = '') → str | None[source]

Get the path of the movie file for a given position.

This function constructs the path to a movie file within a given position directory. It searches for TIFF files that match the specified prefix. If multiple matching files are found, the first one is returned.

Parameters:

pos (str) – The directory path for the position.
prefix (str, optional) – The prefix to filter movie files. Defaults to an empty string.

Returns:

stack_path – The path to the first matching movie file, or None if no matching file is found.

Return type:

str or None

Examples

>>> pos_path = "path/to/position1"
>>> get_position_movie_path(pos_path, prefix='experiment_')
'path/to/position1/movie/experiment_001.tif'

>>> pos_path = "another/path/positionA"
>>> get_position_movie_path(pos_path)
'another/path/positionA/movie/001.tif'

>>> pos_path = "nonexistent/path"
>>> get_position_movie_path(pos_path)
None

celldetective.utils.experiment.get_position_table(pos: str, population: str, return_path: bool = False) → DataFrame | None | Tuple[DataFrame | None, str][source]

Retrieves the data table for a specified population at a given position.

Parameters:

pos (str) – Position directory path.
population (str) – Population name.
return_path (bool, optional) – If True, return the path to the table as well. Default is False.

Returns:

The data table, or (table, path) if return_path is True.

Return type:

DataFrame or tuple

celldetective.utils.experiment.get_positions_in_well(well: str) → ndarray[source]

Retrieves the list of position directories within a specified well directory, formatted as a NumPy array of strings.

This function identifies position directories based on their naming convention, which must include a numeric identifier following the well’s name. The well’s name is expected to start with ‘W’ (e.g., ‘W1’), followed by a numeric identifier. Position directories are assumed to be named with this numeric identifier directly after the well identifier, without the ‘W’. For example, positions within well ‘W1’ might be named ‘101’, ‘102’, etc. This function will glob these directories and return their full paths as a NumPy array.

Parameters:: well (str) – The path to the well directory from which to retrieve position directories.
Returns:: An array of strings, each representing the full path to a position directory within the specified well. The array is empty if no position directories are found.
Return type:: np.ndarray

Notes

This function relies on a specific naming convention for wells and positions. It assumes that each well directory is prefixed with ‘W’ followed by a numeric identifier, and position directories are named starting with this numeric identifier directly.

Examples

>>> get_positions_in_well('/path/to/experiment/W1')
# This might return an array like array(['/path/to/experiment/W1/101', '/path/to/experiment/W1/102'])
if position directories '101' and '102' exist within the well 'W1' directory.

celldetective.utils.experiment.get_spatial_calibration(experiment: str | Path) → float[source]

Retrieves the spatial calibration factor for an experiment.

Parameters:

experiment (str) – The file system path to the experiment directory.

Returns:

The spatial calibration factor (pixels to micrometers conversion), extracted from the experiment’s configuration file.

Return type:

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

celldetective.utils.experiment.get_temporal_calibration(experiment: str | Path) → float[source]

Retrieves the temporal calibration factor for an experiment.

Parameters:

experiment (str) – The file system path to the experiment directory.

Returns:

The temporal calibration factor (frames to minutes conversion), extracted from the experiment’s configuration file.

Return type:

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

Interpret well and position options for a given experiment.

This function takes an experiment and well/position options to return the selected wells and positions. It supports selection of all wells or specific wells/positions as specified. The well numbering starts from 0 (i.e., Well 0 is W1 and so on).

Parameters:

experiment (str) – The experiment path containing well information.
well_option (str, int, or list of int) – The well selection option: - ‘*’ : Select all wells. - int : Select a specific well by its index. - list of int : Select multiple wells by their indices.
position_option (str, int, or list of int) – The position selection option: - ‘*’ : Select all positions (returns None). - int : Select a specific position by its index. - list of int : Select multiple positions by their indices.

Returns:

well_indices (numpy.ndarray or list of int) – The indices of the selected wells.
position_indices (numpy.ndarray or list of int or None) – The indices of the selected positions. Returns None if all positions are selected.

Examples

>>> experiment = "path/to/experiment"
>>> interpret_wells_and_positions(experiment, '*', '*')
(array([0, 1, 2, ..., n-1]), None)

>>> interpret_wells_and_positions(experiment, 2, '*')
([2], None)

>>> interpret_wells_and_positions(experiment, [1, 3, 5], 2)
([1, 3, 5], array([2]))

celldetective.utils.experiment.load_tracking_data(position: str, prefix: str = 'Aligned', population: str = 'target') → Tuple[DataFrame, ndarray | Array, ndarray | Array][source]

Load tracking data, labels, and stack.

Parameters:

position (str) – Position directory path.
prefix (str, optional) – Prefix of the stack file. Default is “Aligned”.
population (str, optional) – Population name. Default is “target”.

Returns:

(trajectories, labels, stack).

Return type:

Locate and load labels.

Parameters:

position (str) – Position directory path.
population (str, optional) – Population name (“target” or “effector”). Default is “target”.
frames (int, list, or None, optional) – Frames to load. Default is None (all frames).
lazy (bool, optional) – If True, load lazily using dask. Default is False.

Returns:

Loaded labels.

Return type:

ndarray or dask.array.Array

celldetective.utils.experiment.locate_stack(position: str, prefix: str = 'Aligned', lazy: bool = False) → ndarray | Array[source]

Locate and load an image stack.

Parameters:

position (str) – Position directory path.
prefix (str, optional) – Prefix of the stack file. Default is “Aligned”.
lazy (bool, optional) – If True, load lazily using dask. Default is False.

Returns:

Loaded stack.

Return type:

ndarray or dask.array.Array

celldetective.utils.experiment.locate_stack_and_labels(position: str, prefix: str = 'Aligned', population: str = 'target', lazy: bool = False) → Tuple[ndarray | Array, ndarray | Array][source]

Locate and load both stack and labels.

Parameters:

position (str) – Position directory path.
prefix (str, optional) – Prefix of the stack file. Default is “Aligned”.
population (str, optional) – Population name. Default is “target”.
lazy (bool, optional) – If True, load lazily. Default is False.

Returns:

(stack, labels) as ndarrays or dask arrays.

Return type:

celldetective.utils.experiment.relabel_segmentation(labels: ndarray, df: DataFrame, exclude_nans: bool = True, column_labels: Dict[str, str] = {'frame': 'FRAME', 'label': 'class_id', 'track': 'TRACK_ID', 'x': 'POSITION_X', 'y': 'POSITION_Y'}, threads: int = 1, dialog: Any | None = None) → ndarray[source]

Relabel segmentation based on tracking data.

Parameters:

labels (ndarray) – Label array.
df (DataFrame) – Tracking data.
exclude_nans (bool, optional) – If True, exclude NaN values. Default is True.
column_labels (dict, optional) – Mapping of column names. Default provided.
threads (int, optional) – Number of threads to use. Default is 1.
dialog (QProgressDialog, optional) – Progress dialog to update. Default is None.

Returns:

Relabeled segmentation.

Return type:

ndarray

celldetective.utils.experiment.relabel_segmentation_lazy(labels: Array, df: DataFrame, column_labels: Dict[str, str] = {'frame': 'FRAME', 'label': 'class_id', 'track': 'TRACK_ID'}) → Array[source]

Relabel segmentation lazily using dask.

Parameters:

labels (dask.array.Array) – Label array.
df (DataFrame) – Tracking data.
column_labels (dict, optional) – Mapping of column names. Default provided.

Returns:

Relabeled segmentation.

Return type:

dask.array.Array

celldetective.utils.experiment.tracks_to_btrack(df: DataFrame, exclude_nans: bool = False) → Tuple[ndarray, Dict[str, ndarray], Dict[str, Any]][source]

Converts a dataframe of tracked objects into the bTrack output format.

Parameters:

df (DataFrame) – Tracking data.
exclude_nans (bool, optional) – If True, exclude NaN values. Default is False.

Returns:

(data, properties, graph).

Return type:

celldetective.utils.experiment.tracks_to_napari(df: DataFrame, exclude_nans: bool = False) → Tuple[ndarray, ndarray, Dict[str, ndarray], Dict[str, Any]][source]

Convert tracks to Napari format.

Parameters:

df (DataFrame) – Tracking data.
exclude_nans (bool, optional) – If True, exclude NaN values. Default is False.

Returns:

(vertices, tracks, properties, graph).

Return type:

celldetective.utils.experiment.view_tracks_in_napari(position: str, population: str, stack: ndarray | None = None, labels: ndarray | None = None, relabel: bool = True, flush_memory: bool = True, threads: int = 1, lazy: bool = False, dialog: Any | None = None) → bool | None[source]

View tracks in Napari for a given position and population.

Parameters:

position (str) – Position directory path.
population (str) – Population name.
stack (ndarray, optional) – Image stack. Default is None.
labels (ndarray, optional) – Labels array. Default is None.
relabel (bool, optional) – If True, relabel segmentation. Default is True.
flush_memory (bool, optional) – If True, flush memory. Default is True.
threads (int, optional) – Number of threads. Default is 1.
lazy (bool, optional) – If True, use lazy loading. Default is False.
dialog (QDialog, optional) – Progress dialog. Default is None.

Returns:

True if successful, None if failed.

Return type:

bool or None

celldetective.utils.image_augmenters.augmenter(x: ndarray, y: ndarray, flip: bool = True, gauss_blur: bool = True, noise_option: bool = True, shift: bool = True, channel_extinction: bool = True, extinction_probability: float = 0.1, clip: bool = False, max_sigma_blur: int = 4, apply_noise_probability: float = 0.5, augment_probability: float = 0.9) → Tuple[ndarray, ndarray][source]

Applies a series of augmentation techniques to images and their corresponding masks for deep learning training.

This function randomly applies a set of transformations including flipping, rotation, Gaussian blur, additive noise, shifting, and channel extinction to input images (x) and their masks (y) based on specified probabilities. These augmentations introduce variability in the training dataset, potentially improving model generalization.

Parameters:

x (ndarray) – The input image to be augmented, with dimensions (height, width, channels).
y (ndarray) – The corresponding mask or label image for x, with the same spatial dimensions.
flip (bool, optional) – Whether to randomly flip and rotate the images. Default is True.
gauss_blur (bool, optional) – Whether to apply Gaussian blur to the images. Default is True.
noise_option (bool, optional) – Whether to add random noise to the images. Default is True.
shift (bool, optional) – Whether to randomly shift the images. Default is True.
channel_extinction (bool, optional) – Whether to randomly set entire channels of the image to zero. Default is False.
extinction_probability (float, optional) – The probability of an entire channel being set to zero. Default is 0.1.
clip (bool, optional) – Whether to clip the noise-added images to stay within valid intensity values. Default is False.
max_sigma_blur (int, optional) – The maximum sigma value for Gaussian blur. Default is 4.
apply_noise_probability (float, optional) – The probability of applying noise to the image. Default is 0.5.
augment_probability (float, optional) – The overall probability of applying any augmentation to the image. Default is 0.9.

Returns:

A tuple containing the augmented image and mask (x, y).

Return type:

Raises:

AssertionError – If extinction_probability is not within the range [0, 1].

Notes

The augmentations are applied randomly based on the specified probabilities, allowing for a diverse set of transformed images from the original inputs.
This function is designed to be part of a preprocessing pipeline for training deep learning models, especially in tasks requiring spatial invariance and robustness to noise.

Examples

>>> import numpy as np
>>> x = np.random.rand(128, 128, 3)  # Sample image
>>> y = np.random.randint(2, size=(128, 128))  # Sample binary mask
>>> x_aug, y_aug = augmenter(x, y)
# The returned `x_aug` and `y_aug` are augmented versions of `x` and `y`.

celldetective.utils.image_augmenters.blur(x: ndarray, max_sigma: float = 4.0) → ndarray[source]

Applies a random Gaussian blur to an image.

This function blurs an image by applying a Gaussian filter with a randomly chosen sigma value. The sigma represents the standard deviation for the Gaussian kernel and is selected randomly up to a specified maximum. The blurring is applied while preserving the range of the image’s intensity values and maintaining any zero-valued pixels as they are.

Parameters:

x (ndarray) – The input image to be blurred. The image can have any number of channels, but must be in a format where the channels are the last dimension (YXC format).
max_sigma (float, optional) – The maximum value for the standard deviation of the Gaussian blur. Default is 4.0.

Returns:

The blurred image. The output will have the same shape and type as the input image.

Return type:

ndarray

Notes

The function ensures that zero-valued pixels in the input image remain unchanged after the blurring, which can be important for maintaining masks or other specific regions within the image.
Gaussian blurring is commonly used in image processing to reduce image noise and detail by smoothing.

celldetective.utils.image_augmenters.noise(x: ndarray, apply_probability: float = 0.5, clip_option: bool = False) → ndarray[source]

Applies random noise to each channel of a multichannel image based on a specified probability.

This function introduces various types of random noise to an image. Each channel of the image can be modified independently with different noise models chosen randomly from a predefined list. The application of noise to any given channel is determined by a specified probability, allowing for selective noise addition.

Parameters:

x (ndarray) – The input multichannel image to which noise will be added. The image should be in format with channels as the last dimension (e.g., height x width x channels).
apply_probability (float, optional) – The probability with which noise is applied to each channel of the image. Default is 0.5.
clip_option (bool, optional) – Specifies whether to clip the corrupted data to stay within the valid range after noise addition. If True, the output array will be clipped to the range [0, 1] or [0, 255] depending on the input data type. Default is False.

Returns:

The noised image. This output has the same shape as the input but potentially altered intensity values due to noise addition.

Return type:

ndarray

Notes

The types of noise that can be applied include ‘gaussian’, ‘localvar’, ‘poisson’, and ‘speckle’.
The choice of noise type for each channel is randomized and the noise is only applied if a randomly generated number is less than or equal to apply_probability.
Zero-valued pixels in the input image remain zero in the output to preserve background or masked areas.

Examples

>>> import numpy as np
>>> x = np.random.rand(256, 256, 3)  # Example 3-channel image
>>> noised_image = noise(x)
# The image 'x' may have different types of noise applied to each of its channels with a 50% probability.

celldetective.utils.image_augmenters.random_fliprot(img: ndarray, mask: ndarray) → Tuple[ndarray, ndarray][source]

Randomly flips and rotates an image and its corresponding mask.

This function applies a series of random flips and permutations (rotations) to both the input image and its associated mask, ensuring that any transformations applied to the image are also exactly applied to the mask. The function is designed to handle multi-dimensional images (e.g., multi-channel images in YXC format where channels are last).

Parameters:

img (ndarray) – The input image to be transformed. This array is expected to have dimensions where the channel axis is last.
mask (ndarray) – The mask corresponding to img, to be transformed in the same way as the image.

Returns:

A tuple containing the transformed image and mask.

Return type:

tuple of ndarray

Raises:

AssertionError – If the number of dimensions of the mask exceeds that of the image, indicating incompatible shapes.

celldetective.utils.image_augmenters.random_shift(image: ndarray, mask: ndarray, max_shift_amplitude: float = 0.1) → Tuple[ndarray, ndarray][source]

Randomly shifts an image and its corresponding mask along the X and Y axes.

This function shifts both the image and the mask by a randomly chosen distance up to a maximum percentage of the image’s dimensions, specified by max_shift_amplitude. The shifts are applied independently in both the X and Y directions. This type of augmentation can help improve the robustness of models to positional variations in images.

Parameters:

image (ndarray) – The input image to be shifted. Must be in YXC format (height, width, channels).
mask (ndarray) – The mask corresponding to image, to be shifted in the same way as the image.
max_shift_amplitude (float, optional) – The maximum shift as a fraction of the image’s dimension. Default is 0.1 (10% of the image’s size).

Returns:

A tuple containing the shifted image and mask.

Return type:

tuple of ndarray

Notes

The shift values are chosen randomly within the range defined by the maximum amplitude.
Shifting is performed using the ‘constant’ mode where missing values are filled with zeros (cval=0.0), which may introduce areas of zero-padding along the edges of the shifted images and masks.
This function is designed to support data augmentation for machine learning and image processing tasks, particularly in contexts where spatial invariance is beneficial.

celldetective.utils.image_cleaning.interpolate_nan(img: ndarray, method: str = 'nearest') → ndarray[source]

Interpolate NaN on single channel array 2D

Parameters:

img (ndarray) – Input image.
method (str, optional) – Interpolation method. Default is ‘nearest’.

Returns:

Image with NaNs interpolated.

Return type:

ndarray

celldetective.utils.image_cleaning.interpolate_nan_multichannel(frames: ndarray) → ndarray[source]

Interpolate NaNs in a multichannel image.

Parameters:: frames (ndarray) – Multichannel image (H, W, C).
Returns:: Image with NaNs interpolated.
Return type:: ndarray

celldetective.utils.image_loaders.auto_load_number_of_frames(stack_path: str) → int | None[source]

Automatically determine the number of frames in a TIFF image 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) – Path to the TIFF image stack file.
Returns:: The number of frames in the image stack. Returns None if the path is None or the frame count cannot be determined.
Return type:: int or None

Notes

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

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:

>>> 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("stack.tif")
>>> print(frames)
None

celldetective.utils.image_loaders.fix_missing_labels(position: str, population: str = 'target', prefix: str = 'Aligned') → None[source]

Fix missing label files by creating empty label images for frames that do not have corresponding label files.

This function locates missing label files in a sequence of frames and creates empty labels (filled with zeros) for the frames that are missing. The function works for two types of populations: ‘target’ or ‘effector’.

Parameters:

position (str) – The file path to the folder containing the images/label files. This is the root directory where the label files are expected to be found.
population (str, optional) – Specifies whether to look for ‘target’ or ‘effector’ labels. Accepts ‘target’ or ‘effector’ as valid values. Default is ‘target’.
prefix (str, optional) – The prefix used to locate the image stack (default is ‘Aligned’).

Returns:

The function creates new label files in the corresponding folder for any frames missing label files.

Return type:

None

celldetective.utils.image_loaders.load_frames(img_nums: int | ~typing.List[int] | ~numpy.ndarray, stack_path: str, scale: float | None = None, normalize_input: bool = True, dtype: type = <class 'numpy.float64'>, normalize_kwargs: ~typing.Dict[str, ~typing.Any] = {'percentiles': (0.0, 99.99)}) → ndarray | None[source]

Loads and optionally normalizes and rescales specified frames from a stack located at a given path.

This function reads specified frames from a stack file, applying systematic adjustments to ensure the channel axis is last. It supports optional normalization of the input frames and rescaling. An artificial pixel modification is applied to frames with uniform values to prevent errors during normalization.

Parameters:

img_nums (int or list of int) – The index (or indices) of the image frame(s) to load from the stack.
stack_path (str) – The file path to the stack from which frames are to be loaded.
scale (float, optional) – The scaling factor to apply to the frames. If None, no scaling is applied (default is None).
normalize_input (bool, optional) – Whether to normalize the loaded frames. If True, normalization is applied according to normalize_kwargs (default is True).
dtype (data-type, optional) – The desired data-type for the output frames (default is float).
normalize_kwargs (dict, optional) – Keyword arguments to pass to the normalization function (default is {“percentiles”: (0., 99.99)}).

Returns:

The loaded, and possibly normalized and rescaled, frames as a NumPy array. Returns None if there is an error in loading the frames.

Return type:

ndarray or None

Raises:

Exception – Prints an error message if the specified frames cannot be loaded or if there is a mismatch between the provided experiment channel information and the stack format.

Notes

The function uses scikit-image for reading frames and supports multi-frame TIFF stacks.
Normalization and scaling are optional and can be customized through function parameters.
A workaround is implemented for frames with uniform pixel values to prevent normalization errors by adding a ‘fake’ pixel.

Examples

>>> frames = load_frames([0, 1, 2], '/path/to/stack.tif', scale=0.5, normalize_input=True, dtype=np.uint8)
# Loads the first three frames from '/path/to/stack.tif', normalizes them, rescales by a factor of 0.5,
# and converts them to uint8 data type.

celldetective.utils.image_loaders.load_image_dataset(datasets: List[str], channels: str | List[str], train_spatial_calibration: float | None = None, mask_suffix: str = 'labelled') → Tuple[List[ndarray], List[ndarray], List[str]][source]

Loads image and corresponding mask datasets, optionally applying spatial calibration adjustments.

This function iterates over specified datasets, loading image and mask pairs based on provided channels and adjusting images according to a specified spatial calibration factor. It supports loading images with multiple channels and applies necessary transformations to match the training spatial calibration.

Parameters:

datasets (list of str) – A list of paths to the datasets containing the images and masks.
channels (str or list of str) – The channel(s) to be loaded from the images. If a string is provided, it is converted into a list.
train_spatial_calibration (float, optional) – The spatial calibration (e.g., micrometers per pixel) used during model training. If provided, images will be rescaled to match this calibration. Default is None, indicating no rescaling is applied.
mask_suffix (str, optional) – The suffix used to identify mask files corresponding to the images. Default is ‘labelled’.

Returns:

A tuple containing three lists: X for images, Y for corresponding masks, and files for the original file paths. All lists contain elements corresponding to the loaded samples.

Return type:

tuple of lists

Raises:

AssertionError – If the provided channels argument is not a list or if the number of loaded images does not match the number of loaded masks.

Notes

The function assumes that mask filenames are derived from image filenames by appending a mask_suffix before the file extension.
Spatial calibration adjustment involves rescaling the images and masks to match the train_spatial_calibration.
Only images with a corresponding mask and a valid configuration file specifying channel indices and spatial calibration are loaded.
The image samples must have at least one channel in common with the required channels to be accepted. The missing channels are passed as black frames.

Examples

>>> datasets = ['/path/to/dataset1', '/path/to/dataset2']
>>> channels = ['DAPI', 'GFP']
>>> X, Y, files = load_image_dataset(datasets, channels, train_spatial_calibration=0.65)
# Loads DAPI and GFP channels from specified datasets, rescaling images to match a spatial calibration of 0.65.

Locate and load label images for a given position and population in an experiment.

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) – Path to the position directory containing label images.
population (str, optional) – 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:

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.

Return type:

numpy.ndarray or list of numpy.ndarray or None

Notes

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

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])

celldetective.utils.image_loaders.locate_stack(position: str, prefix: str = 'Aligned') → ndarray[source]

Locate and load a stack of images.

Parameters:

position (str) – The position folder within the well where the stack is located.
prefix (str, optional) – The prefix used to identify the stack. The default is ‘Aligned’.

Returns:

stack – The loaded stack as a NumPy array with shape (T, Y, X, C).

Return type:

ndarray

Raises:

FileNotFoundError – If no stack with the specified prefix is found.

Notes

This function locates and loads a stack of images based on the specified position and prefix. It assumes that the stack is stored in a directory named ‘movie’ within the specified position. The function loads the stack as a NumPy array and reshapes it to (T, Y, X, C) using TIFF metadata (ImageJ or OME-TIFF axes) when available, falling back to shape heuristics otherwise. Both .tif and .ome.tif files are supported.

Examples

>>> stack = locate_stack(position, prefix='Aligned')
# Locate and load a stack of images for further processing.

celldetective.utils.image_loaders.locate_stack_and_labels(position: str, prefix: str = 'Aligned', population: str = 'target') → Tuple[ndarray, ndarray | List[ndarray | None] | None][source]

Locate and load the stack and corresponding segmentation labels.

Parameters:

position (str) – The position or directory path where the stack and labels are located.
prefix (str, optional) – The prefix used to identify the stack. The default is ‘Aligned’.
population (str, optional) – The population for which the segmentation must be located. The default is ‘target’.

Returns:

stack (ndarray) – The loaded stack as a NumPy array.
labels (ndarray) – The loaded segmentation labels as a NumPy array.

Raises:

AssertionError – If no stack with the specified prefix is found or if the shape of the stack and labels do not match.

Notes

This function locates the stack and corresponding segmentation labels based on the specified position and population. It assumes that the stack and labels are stored in separate directories: ‘movie’ for the stack and ‘labels’ or ‘labels_effectors’ for the labels. The function loads the stack and labels as NumPy arrays and performs shape validation.

Examples

>>> stack, labels = locate_stack_and_labels(position, prefix='Aligned', population="target")
# Locate and load the stack and segmentation labels for further processing.

celldetective.utils.image_loaders.zoom_multiframes(frames: ndarray, zoom_factor: float) → ndarray[source]

Applies zooming to each frame (channel) in a multi-frame image.

This function resizes each channel of a multi-frame image independently using a specified zoom factor. The zoom is applied using spline interpolation of the specified order, and the channels are combined back into the original format.

Parameters:

frames (ndarray) – A multi-frame image with dimensions (height, width, channels). The last axis represents different channels.
zoom_factor (float) – The zoom factor to apply to each channel. Values greater than 1 increase the size, and values between 0 and 1 decrease the size.

Returns:

A new multi-frame image with the same number of channels as the input, but with the height and width scaled by the zoom factor.

Return type:

ndarray

Notes

The function uses spline interpolation (order 3) for resizing, which provides smooth results.
prefilter=False is used to prevent additional filtering during the zoom operation.
The function assumes that the input is in height x width x channels format, with channels along the last axis.

celldetective.utils.image_transforms.axes_check_and_normalize(axes: str, length: int | None = None, disallowed: str | None = None, return_allowed: bool = False) → str | Tuple[str, str][source]

adapted from https://github.com/CSBDeep/CSBDeep/blob/main/csbdeep/utils/utils.py S(ample), T(ime), C(hannel), Z, Y, X

Parameters:

axes (str) – The axes string to check and normalize.
length (int, optional) – The expected length of the axes string. Default is None.
disallowed (str, optional) – A string of disallowed axes. Default is None.
return_allowed (bool, optional) – Whether to return the allowed axes string. Default is False.

celldetective.utils.image_transforms.axes_dict(axes: str) → Dict[str, int | None][source]

adapted from https://github.com/CSBDeep/CSBDeep/blob/main/csbdeep/utils/utils.py from axes string to dict

Parameters:: axes (str) – The axes string to convert to a dictionary.

celldetective.utils.image_transforms.consume(iterator: Iterable[Any]) → None[source]

adapted from https://github.com/CSBDeep/CSBDeep/blob/main/csbdeep/utils/utils.py

Parameters:: iterator (iterable) – The iterator to consume.

celldetective.utils.image_transforms.estimate_unreliable_edge(activation_protocol: List[List[Any]] | None = [['gauss', 2], ['std', 4]]) → int | None[source]

Safely estimate the distance to the edge of an image in which the filtered image values can be artefactual.

Parameters:: activation_protocol (list of list, optional) – A list of lists, where each sublist contains a string naming the filter function, followed by its arguments (usually a kernel size). Default is [[‘gauss’, 2], [‘std’, 4]].
Returns:: The sum of the kernel sizes in the activation protocol if the protocol is not empty. Returns None if the activation protocol is empty.
Return type:: int or None

Notes

This function assumes that the second element of each sublist in the activation protocol is a kernel size.

Examples

>>> estimate_unreliable_edge([['gauss', 2], ['std', 4]])
6
>>> estimate_unreliable_edge([])
None

celldetective.utils.image_transforms.mask_edges(binary_mask: ndarray, border_size: int) → ndarray[source]

Mask the edges of a binary mask.

This function sets the edges of a binary mask to False, effectively masking out a border of the specified size.

Parameters:

binary_mask (ndarray) – A 2D binary mask array where the edges will be masked.
border_size (int) – The size of the border to mask (set to False) on all sides.

Returns:

The binary mask with the edges masked out.

Return type:

ndarray

Raises:

ValueError – If border_size is greater than or equal to half of the smallest dimension of binary_mask.

Notes

This function assumes that the input binary_mask is a 2D array. The input mask is converted to a boolean array before masking the edges.

Examples

>>> import numpy as np
>>> binary_mask = np.array([[1, 1, 1, 1, 1],
...                         [1, 1, 1, 1, 1],
...                         [1, 1, 1, 1, 1],
...                         [1, 1, 1, 1, 1],
...                         [1, 1, 1, 1, 1]])
>>> mask_edges(binary_mask, 1)
array([[False, False, False, False, False],
           [False,  True,  True,  True, False],
           [False,  True,  True,  True, False],
           [False,  True,  True,  True, False],
           [False, False, False, False, False]])

celldetective.utils.image_transforms.move_image_axes(x: ndarray, fr: str, to: str, adjust_singletons: bool = False) → ndarray[source]

adapted from https://github.com/CSBDeep/CSBDeep/blob/main/csbdeep/utils/utils.py x: ndarray fr,to: axes string (see axes_dict)

Parameters:

x (ndarray) – Input image.
fr (str) – Source axes.
to (str) – Target axes.
adjust_singletons (bool, optional) – Whether to adjust singleton axes. Default is False.

celldetective.utils.image_transforms.threshold_image(img: ndarray, min_threshold: float, max_threshold: float, foreground_value: float = 255.0, fill_holes: bool = True, edge_exclusion: int | None = None) → ndarray[source]

Threshold the input image to create a binary mask.

Parameters:

img (ndarray) – The input image to be thresholded.
min_threshold (float) – The minimum threshold value.
max_threshold (float) – The maximum threshold value.
foreground_value (float, optional) – The value assigned to foreground pixels in the binary mask. Default is 255.
fill_holes (bool, optional) – Whether to fill holes in the binary mask. If True, the binary mask will be processed to fill any holes. If False, the binary mask will not be modified. Default is True.
edge_exclusion (int, optional) – If provided, border pixels of this width will be masked (set to 0). Default is None.

Returns:

The binary mask after thresholding.

Return type:

ndarray

Notes

This function applies a threshold to the input image to create a binary mask. Pixels with values within the specified threshold range are considered as foreground and assigned the foreground_value, while pixels outside the range are considered as background and assigned 0. If fill_holes is True, the binary mask will be processed to fill any holes using morphological operations.

Examples

>>> image = np.random.rand(256, 256)
>>> binary_mask = threshold_image(image, 0.2, 0.8, foreground_value=1., fill_holes=True)

celldetective.utils.image_transforms.unpad(img: ndarray, pad: int) → ndarray[source]

Remove padding from an image.

This function removes the specified amount of padding from the borders of an image. The padding is assumed to be the same on all sides.

Parameters:

img (ndarray) – The input image from which the padding will be removed.
pad (int) – The amount of padding to remove from each side of the image.

Returns:

The image with the padding removed.

Return type:

ndarray

Raises:

ValueError – If pad is greater than or equal to half of the smallest dimension of img.

See also

numpy.pad: Pads an array.

Notes

This function assumes that the input image is a 2D array.

Examples

>>> import numpy as np
>>> img = np.array([[0, 0, 0, 0, 0],
...                 [0, 1, 1, 1, 0],
...                 [0, 1, 1, 1, 0],
...                 [0, 1, 1, 1, 0],
...                 [0, 0, 0, 0, 0]])
>>> unpad(img, 1)
array([[1, 1, 1],
           [1, 1, 1],
           [1, 1, 1]])

celldetective.utils.mask_cleaning.auto_correct_masks(masks: ndarray, bbox_factor: float = 1.75, min_area: int = 9, fill_labels: bool = False) → ndarray[source]

Correct segmentation masks to ensure consistency and remove anomalies.

This function processes a labeled mask image to correct anomalies and reassign labels. It performs the following operations:

Corrects negative mask values by taking their absolute values.
Identifies and corrects segmented objects with a bounding box area that is disproportionately larger than the actual object area. This indicates potential segmentation errors where separate objects share the same label.
Removes small objects that are considered noise (default threshold is an area of less than 9 pixels).
Reorders the labels so they are consecutive from 1 up to the number of remaining objects (to avoid encoding errors).

Parameters:

masks (np.ndarray) – A 2D array representing the segmented mask image with labeled regions. Each unique value in the array represents a different object or cell.
bbox_factor (float, optional) – A factor on cell area that is compared directly to the bounding box area of the cell, to detect remote cells sharing a same label value. The default is 1.75.
min_area (int, optional) – Discard cells that have an area smaller than this minimum area (px²). The default is 9 (3x3 pixels).
fill_labels (bool, optional) – Fill holes within cell masks automatically. The default is False.

Returns:

clean_labels – A corrected version of the input mask, with anomalies corrected, small objects removed, and labels reordered to be consecutive integers.

Return type:

np.ndarray

Notes

This function is useful for post-processing segmentation outputs to ensure high-quality object detection, particularly in applications such as cell segmentation in microscopy images.
The function assumes that the input masks contain integer labels and that the background is represented by 0.

Examples

>>> masks = np.array([[0, 0, 1, 1], [0, 2, 2, 1], [0, 2, 0, 0]])
>>> corrected_masks = auto_correct_masks(masks)
>>> corrected_masks
array([[0, 0, 1, 1],
           [0, 2, 2, 1],
           [0, 2, 0, 0]])

celldetective.utils.mask_cleaning.fill_label_holes(lbl_img: ndarray, **kwargs: Any) → ndarray[source]

Fill small holes in label image. from https://github.com/stardist/stardist/blob/main/stardist/utils.py

Parameters:

lbl_img (ndarray) – Label image.
**kwargs (dict) – Additional arguments for scipy.ndimage.binary_fill_holes.

Returns:

Label image with filled holes.

Return type:

ndarray

celldetective.utils.mask_cleaning.relabel_segmentation(labels: ndarray, df: DataFrame, exclude_nans: bool = True, column_labels: Dict[str, str] = {'frame': 'FRAME', 'label': 'class_id', 'track': 'TRACK_ID', 'x': 'POSITION_X', 'y': 'POSITION_Y'}, threads: int = 1, progress_callback: Callable[[float], bool] | None = None) → ndarray | None[source]

Relabel the segmentation labels with the tracking IDs from the tracks.

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 (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 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.
progress_callback (callable, optional) – A function to report progress. Should accept a single float argument (0-100) and return True to continue or False to cancel. Default is None.

Returns:

A new (TYX) array with the same shape as labels, where objects are relabeled according to their tracking identity in df.

Return type:

np.ndarray

Notes

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

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.

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.

Generate an instance mask containing the contour of the segmented objects.

This updated version uses a Signed Distance Field (SDF) and Voronoi tessellation approach Generic enough to handle Inner contours, Outer contours, and arbitrary “stripes” (annuli).

Parameters:

label (ndarray) – The instance segmentation labels.
distance (int, float, list, tuple, or str) –
The distance specification.
- Scalar > 0: Inner contour (Erosion) from boundary to ‘distance’ pixels inside. Range [0, distance].
- Scalar < 0: Outer contour (Dilation) from ‘distance’ pixels outside to boundary. Range [distance, 0].
- Tuple/List (a, b): Explicit range in SDF space.
  - Positive values are inside the object.
  - Negative values are outside methods.
  - Example: (5, 10) -> Inner ring 5 to 10px deep.
  - Example: (-10, -5) -> Outer ring 5 to 10px away.
- String “rad1-rad2”: Interpretation for Batch Measurements (Outer Rings).
  - Interpreted as an annular region OUTSIDE the object.
  - ”5-10” -> Range [-10, -5] in SDF space (5 to 10px away).
sdf (ndarray, optional) – Pre-computed Signed Distance Field (dist_in - dist_out). If provided, avoids recomputing EDT.
voronoi_map (ndarray, optional) – Pre-computed Voronoi map of instance labels. Required if sdf is provided and outer contours are needed.

Returns:

border_label – An instance mask containing the contour of the segmented objects. Outer contours preserve instance identity via Voronoi propagation.

Return type:

ndarray

Create a circular patch mask of given dimensions. Adapted from alkasm on https://stackoverflow.com/questions/44865023/how-can-i-create-a-circular-mask-for-a-numpy-array

Parameters:

h (int) – Height of the mask. Prefer odd value.
w (int) – Width of the mask. Prefer odd value.
center (tuple, optional) – Coordinates of the center of the patch. If not provided, the middle of the image is used.
radius (int or float or list, optional) – Radius of the circular patch. If not provided, the smallest distance between the center and image walls is used. If a list is provided, it should contain two elements representing the inner and outer radii of a circular annular patch.

Returns:

Boolean mask where True values represent pixels within the circular patch or annular patch, and False values represent pixels outside.

Return type:

numpy.ndarray

Notes

The function creates a circular patch mask of the given dimensions by determining which pixels fall within the circular patch or annular patch. The circular patch or annular patch is centered at the specified coordinates or at the middle of the image if coordinates are not provided. The radius of the circular patch or annular patch is determined by the provided radius parameter or by the minimum distance between the center and image walls. If an annular patch is desired, the radius parameter should be a list containing the inner and outer radii respectively.

Examples

>>> mask = create_patch_mask(100, 100, center=(50, 50), radius=30)
>>> print(mask)

celldetective.utils.maths.derivative(x: ndarray, timeline: ndarray, window: int, mode: str = 'bi') → ndarray[source]

Compute the derivative of a given array of values with respect to time using a specified numerical differentiation method.

Parameters:

x (array_like) – The input array of values.
timeline (array_like) – The array representing the time points corresponding to the input values.
window (int) – The size of the window used for numerical differentiation. Must be a positive odd integer.
mode ({'bi', 'forward', 'backward'}, optional) – The numerical differentiation method to be used: - ‘bi’ (default): Bidirectional differentiation using a symmetric window. - ‘forward’: Forward differentiation using a one-sided window. - ‘backward’: Backward differentiation using a one-sided window.

Returns:

dxdt – The computed derivative values of the input array with respect to time.

Return type:

ndarray

Raises:

AssertionError – If the window size is not an odd integer and mode is ‘bi’.

Notes

For ‘bi’ mode, the window size must be an odd number.
For ‘forward’ mode, the derivative at the edge points may not be accurate due to the one-sided window.
For ‘backward’ mode, the derivative at the first few points may not be accurate due to the one-sided window.

Examples

>>> import numpy as np
>>> x = np.array([1, 2, 4, 7, 11])
>>> timeline = np.array([0, 1, 2, 3, 4])
>>> window = 3
>>> derivative(x, timeline, window, mode='bi')
array([3., 3., 3.])

>>> derivative(x, timeline, window, mode='forward')
array([1., 2., 3.])

>>> derivative(x, timeline, window, mode='backward')
array([3., 3., 3., 3.])

celldetective.utils.maths.differentiate_per_track(tracks: DataFrame, measurement: str, window_size: int = 3, mode: str = 'bi') → DataFrame[source]

Compute derivate of a measurement per track.

Parameters:

tracks (DataFrame) – Tracking data.
measurement (str) – Measurement column name.
window_size (int, optional) – Window size for differentiation. Default is 3.
mode (str, optional) – Differentiation mode. Default is “bi”.

Returns:

Tracking data with derivative column.

Return type:

DataFrame

celldetective.utils.maths.magnitude_velocity(v_matrix: ndarray) → ndarray[source]

Compute the magnitude of velocity vectors given a matrix representing 2D velocity vectors.

Parameters:: v_matrix (array_like) – The matrix where each row represents a 2D velocity vector with the first column being the x-component and the second column being the y-component.
Returns:: magnitude – The computed magnitudes of the input velocity vectors.
Return type:: ndarray

Notes

If a velocity vector has NaN components, the corresponding magnitude will be NaN.
The function handles NaN values in the input matrix gracefully.

Examples

>>> import numpy as np
>>> v_matrix = np.array([[3, 4],
...                      [2, 2],
...                      [3, 3]])
>>> magnitude_velocity(v_matrix)
array([5., 2.82842712, 4.24264069])

>>> v_matrix_with_nan = np.array([[3, 4],
...                               [np.nan, 2],
...                               [3, np.nan]])
>>> magnitude_velocity(v_matrix_with_nan)
array([5., nan, nan])

celldetective.utils.maths.orientation(v_matrix: ndarray) → ndarray[source]

Compute the orientation angles (in radians) of 2D velocity vectors given a matrix representing velocity vectors.

Parameters:: v_matrix (array_like) – The matrix where each row represents a 2D velocity vector with the first column being the x-component and the second column being the y-component.
Returns:: orientation_array – The computed orientation angles of the input velocity vectors in radians. If a velocity vector has NaN components, the corresponding orientation angle will be NaN.
Return type:: ndarray

Examples

>>> import numpy as np
>>> v_matrix = np.array([[3, 4],
...                      [2, 2],
...                      [-3, -3]])
>>> orientation(v_matrix)
array([0.92729522, 0.78539816, -2.35619449])

>>> v_matrix_with_nan = np.array([[3, 4],
...                               [np.nan, 2],
...                               [3, np.nan]])
>>> orientation(v_matrix_with_nan)
array([0.92729522, nan, nan])

celldetective.utils.maths.safe_log(array: int | float | List | ndarray) → float | ndarray[source]

Safely computes the base-10 logarithm for numeric inputs, handling invalid or non-positive values.

Parameters:

array (int, float, list, or numpy.ndarray) – The input value or array for which to compute the logarithm. Can be a single number (int or float), a list, or a numpy array.

Returns:

If the input is a single numeric value, returns the base-10 logarithm as a float, or np.nan if the value is non-positive.
If the input is a list or numpy array, returns a numpy array with the base-10 logarithm of each element. Invalid or non-positive values are replaced with np.nan.

Return type:

float or numpy.ndarray

Notes

Non-positive values (<= 0) are considered invalid and will result in np.nan.
NaN values in the input array are preserved in the output.
If the input is a list, it is converted to a numpy array for processing.

Examples

>>> safe_log(10)
1.0

>>> safe_log(-5)
nan

>>> safe_log([10, 0, -5, 100])
array([1.0, nan, nan, 2.0])

>>> import numpy as np
>>> safe_log(np.array([1, 10, 100]))
array([0.0, 1.0, 2.0])

celldetective.utils.maths.step_function(t: ndarray | List, t_shift: float, dt: float) → ndarray[source]

Computes a step function using the logistic sigmoid function.

This function calculates the value of a sigmoid function, which is often used to model a step change or transition. The sigmoid function is defined as:

\[f(t) = \frac{1}{1 + \exp{\left( -\frac{t - t_{shift}}{dt} \right)}}\]

where t is the input variable, t_shift is the point of the transition, and dt controls the steepness of the transition.

Parameters:

t (array_like) – The input values for which the step function will be computed.
t_shift (float) – The point in the t domain where the transition occurs.
dt (float) – The parameter that controls the steepness of the transition. Smaller values make the transition steeper, while larger values make it smoother.

Returns:

The computed values of the step function for each value in t.

Return type:

array_like

Examples

>>> import numpy as np
>>> t = np.array([0, 1, 2, 3, 4, 5])
>>> t_shift = 2
>>> dt = 1
>>> step_function(t, t_shift, dt)
array([0.26894142, 0.37754067, 0.5       , 0.62245933, 0.73105858, 0.81757448])

celldetective.utils.maths.velocity(x: ndarray, y: ndarray, timeline: ndarray, window: int, mode: str = 'bi') → ndarray[source]

Compute the velocity vector of a given 2D trajectory represented by arrays of x and y coordinates with respect to time using a specified numerical differentiation method.

Parameters:

x (array_like) – The array of x-coordinates of the trajectory.
y (array_like) – The array of y-coordinates of the trajectory.
timeline (array_like) – The array representing the time points corresponding to the x and y coordinates.
window (int) – The size of the window used for numerical differentiation. Must be a positive odd integer.
mode ({'bi', 'forward', 'backward'}, optional) – The numerical differentiation method to be used: - ‘bi’ (default): Bidirectional differentiation using a symmetric window. - ‘forward’: Forward differentiation using a one-sided window. - ‘backward’: Backward differentiation using a one-sided window.

Returns:

v – The computed velocity vector of the 2D trajectory with respect to time. The first column represents the x-component of velocity, and the second column represents the y-component.

Return type:

ndarray

Raises:

AssertionError – If the window size is not an odd integer and mode is ‘bi’.

Notes

For ‘bi’ mode, the window size must be an odd number.
For ‘forward’ mode, the velocity at the edge points may not be accurate due to the one-sided window.
For ‘backward’ mode, the velocity at the first few points may not be accurate due to the one-sided window.

Examples

>>> import numpy as np
>>> x = np.array([1, 2, 4, 7, 11])
>>> y = np.array([0, 3, 5, 8, 10])
>>> timeline = np.array([0, 1, 2, 3, 4])
>>> window = 3
>>> velocity(x, y, timeline, window, mode='bi')
array([[3., 3.],
           [3., 3.]])

>>> velocity(x, y, timeline, window, mode='forward')
array([[2., 2.],
           [3., 3.]])

>>> velocity(x, y, timeline, window, mode='backward')
array([[3., 3.],
           [3., 3.]])

celldetective.utils.maths.velocity_per_track(tracks: DataFrame, window_size: int = 3, mode: str = 'bi') → DataFrame[source]

Compute velocity per track.

Parameters:

tracks (DataFrame) – Tracking data.
window_size (int, optional) – Window size for differentiation. Default is 3.
mode (str, optional) – Differentiation mode. Default is “bi”.

Returns:

Tracking data with velocity column.

Return type:

DataFrame

celldetective.utils.model_getters.get_pair_signal_models_list(return_path: bool = False) → List[str] | Tuple[List[str], str][source]

Retrieve a list of available signal detection models.

Parameters:: return_path (bool, optional) – If True, also returns the path to the models. Default is False.
Returns:: If return_path is False, returns a list of available signal detection models. If return_path is True, returns a tuple containing the list of models and the path to the models.
Return type:: list or tuple

Notes

This function retrieves the list of available signal detection models by searching for model directories in the predefined model path. The model path is derived from the parent directory of the current script location and the path to the model directory. By default, it returns only the names of the models. If return_path is set to True, it also returns the path to the models.

Examples

>>> models = get_signal_models_list()
# Retrieve a list of available signal detection models.

>>> models, path = get_signal_models_list(return_path=True)
# Retrieve a list of available signal detection models and the path to the models.

celldetective.utils.model_getters.get_segmentation_datasets_list(return_path: bool = False) → List[str] | Tuple[List[str], str][source]

Retrieves a list of available segmentation datasets from both the local ‘celldetective/datasets/segmentation_annotations’ directory and a Zenodo repository, optionally returning the path to the local datasets directory.

This function compiles a list of available segmentation datasets by first identifying datasets stored locally within a specified path related to the script’s directory. It then extends this list with datasets available in a Zenodo repository, ensuring no duplicates are added. The function can return just the list of dataset names or, if specified, also return the path to the local datasets directory.

Parameters:: return_path (bool, optional) – If True, the function returns a tuple containing the list of available dataset names and the path to the local datasets directory. If False, only the list of dataset names is returned (default is False).
Returns:: If return_path is False, returns a list of strings, each string being the name of an available dataset. If return_path is True, returns a tuple where the first element is this list and the second element is a string representing the path to the local datasets directory.
Return type:: list or (list, str)

celldetective.utils.model_getters.get_segmentation_models_list(mode: str = 'targets', return_path: bool = False) → List[str] | Tuple[List[str], str][source]

Get available segmentation models.

Parameters:

mode (str, optional) – Segmentation mode (“targets” or “effectors”). Default is “targets”.
return_path (bool, optional) – If True, return path to models. Default is False.

Returns:

List of models, or (list, path) if return_path is True.

Return type:

list or tuple

celldetective.utils.model_getters.get_signal_datasets_list(return_path: bool = False) → List[str] | Tuple[List[str], str][source]

Retrieves a list of available signal datasets from both the local ‘celldetective/datasets/signal_annotations’ directory and a Zenodo repository, optionally returning the path to the local datasets directory.

This function compiles a list of available signal datasets by first identifying datasets stored locally within a specified path related to the script’s directory. It then extends this list with datasets available in a Zenodo repository, ensuring no duplicates are added. The function can return just the list of dataset names or, if specified, also return the path to the local datasets directory.

Parameters:: return_path (bool, optional) – If True, the function returns a tuple containing the list of available dataset names and the path to the local datasets directory. If False, only the list of dataset names is returned (default is False).
Returns:: If return_path is False, returns a list of strings, each string being the name of an available dataset. If return_path is True, returns a tuple where the first element is this list and the second element is a string representing the path to the local datasets directory.
Return type:: list or (list, str)

celldetective.utils.model_getters.get_signal_models_list(return_path: bool = False) → List[str] | Tuple[List[str], str][source]

Retrieve a list of available signal detection models.

Parameters:: return_path (bool, optional) – If True, also returns the path to the models. Default is False.
Returns:: If return_path is False, returns a list of available signal detection models. If return_path is True, returns a tuple containing the list of models and the path to the models.
Return type:: list or tuple

Notes

This function retrieves the list of available signal detection models by searching for model directories in the predefined model path. The model path is derived from the parent directory of the current script location and the path to the model directory. By default, it returns only the names of the models. If return_path is set to True, it also returns the path to the models.

Examples

>>> models = get_signal_models_list()
# Retrieve a list of available signal detection models.

>>> models, path = get_signal_models_list(return_path=True)
# Retrieve a list of available signal detection models and the path to the models.

celldetective.utils.model_getters.get_tracking_configs_list(return_path: bool = False) → List[str] | Tuple[List[str], str][source]

Retrieve a list of available tracking configurations.

Parameters:: return_path (bool, optional) – If True, also returns the path to the models. Default is False.
Returns:: If return_path is False, returns a list of available tracking configurations. If return_path is True, returns a tuple containing the list of models and the path to the models.
Return type:: list or tuple

Notes

This function retrieves the list of available tracking configurations by searching for model directories in the predefined model path. The model path is derived from the parent directory of the current script location and the path to the model directory. By default, it returns only the names of the models. If return_path is set to True, it also returns the path to the models.

Examples

>>> models = get_tracking_configs_list()
# Retrieve a list of available tracking configurations.

>>> models, path = get_tracking_configs_list(return_path=True)
# Retrieve a list of available tracking configurations.

celldetective.utils.model_loaders.locate_pair_signal_model(name: str, path: str | None = None) → str | None[source]

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:

The full path to the located model directory if found, or None if no matching model is located.

Return type:

str or None

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/'

celldetective.utils.model_loaders.locate_segmentation_dataset(name: str) → str | None[source]

Locates a specified segmentation dataset within the local ‘celldetective/datasets/segmentation_annotations’ directory or downloads it from Zenodo if not found locally.

This function attempts to find a segmentation dataset by name within a predefined directory structure. If the dataset is not found locally, it then tries to locate and download the dataset from Zenodo, placing it into the appropriate category directory within ‘celldetective’. The function prints the search directory path and returns the path to the found or downloaded dataset.

Parameters:: name (str) – The name of the segmentation dataset to locate.
Returns:: The full path to the located or downloaded segmentation dataset directory, or None if the dataset could not be found or downloaded.
Return type:: str or None
Raises:: FileNotFoundError – If the dataset cannot be found locally and also cannot be found or downloaded from Zenodo.

celldetective.utils.model_loaders.locate_segmentation_model(name: str, download: bool = True) → str | None[source]

Locates a specified segmentation model within the local ‘celldetective’ directory or downloads it from Zenodo if not found locally.

This function attempts to find a segmentation model by name within a predefined directory structure starting from the ‘celldetective/models/segmentation*’ path. If the model is not found locally, it then tries to locate and download the model from Zenodo, placing it into the appropriate category directory within ‘celldetective’. The function prints the search directory path and returns the path to the found or downloaded model.

Parameters:

name (str) – The name of the segmentation model to locate.
download (bool, optional) – Whether to download the model from Zenodo if not found locally. Default is True.

Returns:

The full path to the located or downloaded segmentation model directory, or None if the model could not be found or downloaded.

Return type:

str or None

Raises:

FileNotFoundError – If the model cannot be found locally and also cannot be found or downloaded from Zenodo.

celldetective.utils.model_loaders.locate_signal_dataset(name: str) → str | None[source]

Locates a specified signal dataset within the local ‘celldetective/datasets/signal_annotations’ directory or downloads it from Zenodo if not found locally.

This function attempts to find a signal dataset by name within a predefined directory structure. If the dataset is not found locally, it then tries to locate and download the dataset from Zenodo, placing it into the appropriate category directory within ‘celldetective’. The function prints the search directory path and returns the path to the found or downloaded dataset.

Parameters:: name (str) – The name of the signal dataset to locate.
Returns:: The full path to the located or downloaded signal dataset directory, or None if the dataset could not be found or downloaded.
Return type:: str or None
Raises:: FileNotFoundError – If the dataset cannot be found locally and also cannot be found or downloaded from Zenodo.

celldetective.utils.model_loaders.locate_signal_model(name: str, path: str | None = None, pairs: bool = False) → str | None[source]

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:

The full path to the located model directory if found, or None if the model is not available locally or on Zenodo.

Return type:

str or None

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/'

celldetective.utils.normalization.get_stack_normalization_values(stack: ndarray, percentiles: Tuple[float, float] | List[Tuple[float, float]] | None = None, ignore_gray_value: float = 0.0) → List[Tuple[float, float]][source]

Computes the normalization value ranges (minimum and maximum) for each channel in a 4D stack based on specified percentiles.

This function calculates the value ranges for normalizing each channel within a 4-dimensional stack, with dimensions expected to be in the order of Time (T), Y (height), X (width), and Channels (C). The normalization values are determined by the specified percentiles for each channel. An option to ignore a specific gray value during computation is provided, though its effect is not implemented in this snippet.

Parameters:

stack (ndarray) – The input 4D stack with dimensions TYXC from which to calculate normalization values.
percentiles (tuple, list of tuples, optional) – The percentile values (low, high) used to calculate the normalization ranges for each channel. If a single tuple is provided, it is applied to all channels. If a list of tuples is provided, each tuple is applied to the corresponding channel. If None, defaults to (0., 99.99) for each channel.
ignore_gray_value (float, optional) – A gray value to potentially ignore during the calculation. This parameter is provided for interface consistency but is not utilized in the current implementation (default is 0.).

Returns:

A list where each tuple contains the (minimum, maximum) values for normalizing each channel based on the specified percentiles.

Return type:

list of tuples

Raises:

AssertionError – If the input stack does not have 4 dimensions, or if the length of the percentiles list does not match the number of channels in the stack.

Notes

The function assumes the input stack is in TYXC format, where T is the time dimension, Y and X are spatial dimensions, and C is the channel dimension.
Memory management via gc.collect() is employed after calculating normalization values for each channel to mitigate potential memory issues with large datasets.

Examples

>>> stack = np.random.rand(5, 100, 100, 3)  # Example 4D stack with 3 channels
>>> normalization_values = get_stack_normalization_values(stack, percentiles=((1, 99), (2, 98), (0, 100)))
# Calculates normalization ranges for each channel using the specified percentiles.

celldetective.utils.normalization.normalize(frame: ~numpy.ndarray, percentiles: ~typing.Tuple[float, float] = (0.0, 99.99), values: ~typing.Tuple[float, float] | None = None, ignore_gray_value: float | None = 0.0, clip: bool = False, amplification: float | None = None, dtype: ~typing.Any = <class 'float'>) → ndarray[source]

Normalize the intensity values of a frame.

Parameters:

frame (ndarray) – The input frame to be normalized.
percentiles (tuple, optional) – The percentiles used to determine the minimum and maximum values for normalization. Default is (0.0, 99.99).
values (tuple or None, optional) – The specific minimum and maximum values to use for normalization. If None, percentiles are used. Default is None.
ignore_gray_value (float or None, optional) – The gray value to ignore during normalization. If specified, the pixels with this value will not be normalized. Default is 0.0.
clip (bool, optional) – If True, clips the output values to the range [0, 1] or the specified dtype range if dtype is not float. Default is False.
amplification (float, optional) – A factor by which to amplify the intensity values after normalization. If None, no amplification is applied.
dtype (data-type, optional) – The desired data-type for the output normalized frame. The default is float.

Returns:

The normalized frame.

Return type:

ndarray

Notes

This function performs intensity normalization on a frame. It computes the minimum and maximum values for normalization either using the specified values or by calculating percentiles from the frame. The frame is then normalized between the minimum and maximum values using the normalize_mi_ma function. If ignore_gray_value is specified, the pixels with this value will be left unmodified during normalization.

Examples

>>> frame = np.array([[10, 20, 30],
                                          [40, 50, 60],
                                          [70, 80, 90]])
>>> normalized = normalize(frame)
>>> normalized

array([[0. , 0.2, 0.4],: [0.6, 0.8, 1. ], [1.2, 1.4, 1.6]], dtype=float32)

>>> normalized = normalize(frame, percentiles=(10.0, 90.0))
>>> normalized

array([[0.33333334, 0.44444445, 0.5555556 ],: [0.6666667 , 0.7777778 , 0.8888889 ], [1. , 1.1111112 , 1.2222222 ]], dtype=float32)

celldetective.utils.normalization.normalize_mi_ma(x: ~numpy.ndarray, mi: float | ~numpy.ndarray, ma: float | ~numpy.ndarray, clip: bool = False, eps: float = 1e-20, dtype: ~typing.Any | None = <class 'numpy.float32'>) → ndarray[source]

Normalize array between min and max.

Parameters:

x (ndarray) – Input array.
mi (float) – Minimum value.
ma (float) – Maximum value.
clip (bool, optional) – If True, clip values between 0 and 1. Default is False.
eps (float, optional) – Epsilon for numerical stability. Default is 1e-20.
dtype (type, optional) – Data type. Default is np.float32.

Returns:

Normalized array.

Return type:

ndarray

celldetective.utils.normalization.normalize_multichannel(multichannel_frame: ~numpy.ndarray, percentiles: ~typing.Tuple[float, float] | ~typing.List[~typing.Tuple[float, float]] | None = None, values: ~typing.Tuple[float, float] | ~typing.List[~typing.Tuple[float, float]] | None = None, ignore_gray_value: float = 0.0, clip: bool = False, amplification: float | None = None, dtype: ~typing.Any = <class 'float'>) → ndarray[source]

Normalizes a multichannel frame by adjusting the intensity values of each channel based on specified percentiles, direct value ranges, or amplification factors, with options to ignore a specific gray value and to clip the output.

Parameters:

multichannel_frame (ndarray) – The input multichannel image frame to be normalized, expected to be a 3-dimensional array where the last dimension represents the channels.
percentiles (list of tuples or tuple, optional) – Percentile ranges (low, high) for each channel used to scale the intensity values. If a single tuple is provided, it is applied to all channels. If None, the default percentile range of (0., 99.99) is used for each channel.
values (list of tuples or tuple, optional) – Direct value ranges (min, max) for each channel to scale the intensity values. If a single tuple is provided, it is applied to all channels. This parameter overrides percentiles if provided.
ignore_gray_value (float, optional) – A specific gray value to ignore during normalization (default is 0.).
clip (bool, optional) – If True, clips the output values to the range [0, 1] or the specified dtype range if dtype is not float (default is False).
amplification (float, optional) – A factor by which to amplify the intensity values after normalization. If None, no amplification is applied.
dtype (data-type, optional) – The desired data-type for the output normalized frame. The default is float, but other types can be specified to change the range of the output values.

Returns:

The normalized multichannel frame as a 3-dimensional array of the same shape as multichannel_frame.

Return type:

ndarray

Raises:

AssertionError – If the input multichannel_frame does not have 3 dimensions, or if the length of values does not match the number of channels in multichannel_frame.

Notes

This function provides flexibility in normalization by allowing the use of percentile ranges, direct value ranges, or amplification factors.
The function makes a copy of the input frame to avoid altering the original data.
When both percentiles and values are provided, values takes precedence for normalization.

Examples

>>> multichannel_frame = np.random.rand(100, 100, 3)  # Example multichannel frame
>>> normalized_frame = normalize_multichannel(multichannel_frame, percentiles=[(1, 99), (2, 98), (0, 100)])
# Normalizes each channel of the frame using specified percentile ranges.

celldetective.utils.normalization.normalize_per_channel(X: List[ndarray], normalization_percentile_mode: bool | List[bool] = True, normalization_values: List[float] | List[List[float]] = [0.1, 99.99], normalization_clipping: bool | List[bool] = False) → List[ndarray][source]

Applies per-channel normalization to a list of multi-channel images.

This function normalizes each channel of every image in the list X based on either percentile values or fixed min-max values. Optionally, it can also clip the normalized values to stay within the [0, 1] range. The normalization can be applied in a percentile mode, where the lower and upper bounds for normalization are determined based on the specified percentiles of the non-zero values in each channel.

Parameters:

X (list of ndarray) – A list of 3D numpy arrays, where each array represents a multi-channel image with dimensions (height, width, channels).
normalization_percentile_mode (bool or list of bool, optional) – If True (or a list of True values), normalization bounds are determined by percentiles specified in normalization_values for each channel. If False, fixed normalization_values are used directly. Default is True.
normalization_values (list of two floats or list of lists of two floats, optional) – The percentile values [lower, upper] used for normalization in percentile mode, or the fixed min-max values [min, max] for direct normalization. Default is [0.1, 99.99].
normalization_clipping (bool or list of bool, optional) – Determines whether to clip the normalized values to the [0, 1] range for each channel. Default is False.

Returns:

The list of normalized multi-channel images.

Return type:

list of ndarray

Raises:

AssertionError – If the input images do not have a channel dimension, or if the lengths of normalization_values, normalization_clipping, and normalization_percentile_mode do not match the number of channels.

Notes

The normalization is applied in-place, modifying the input list X.
This function is designed to handle multi-channel images commonly used in image processing and computer vision tasks, particularly when different channels require separate normalization strategies.

Examples

>>> X = [np.random.rand(100, 100, 3) for _ in range(5)]  # Example list of 5 RGB images
>>> normalized_X = normalize_per_channel(X)
# Normalizes each channel of each image based on the default percentile values [0.1, 99.99].

celldetective.utils.parsing.config_section_to_dict(path: str | PurePath | Path, section: str) → Dict | None[source]

Parse the config file to extract experiment parameters following https://wiki.python.org/moin/ConfigParserExamples

Parameters:

path (str) – path to the config.ini file
section (str) – name of the section that contains the parameter

Returns:

dict1

Return type:

dictionary

Examples

>>> config = "path/to/config_file.ini"
>>> section = "Channels"
>>> channel_dictionary = config_section_to_dict(config,section)
>>> print(channel_dictionary)
# {'brightfield_channel': '0',
#  'live_nuclei_channel': 'nan',
#  'dead_nuclei_channel': 'nan',
#  'effector_fluo_channel': 'nan',
#  'adhesion_channel': '1',
#  'fluo_channel_1': 'nan',
#  'fluo_channel_2': 'nan',
#  'fitc_channel': '2',
#  'cy5_channel': '3'}

celldetective.utils.parsing.demangle_column_name(name: str) → str[source]

Demangle column name.

Parameters:: name (str) – Column name to demangle.
Returns:: Demangled column name.
Return type:: str

celldetective.utils.parsing.extract_cols_from_query(query: str)[source]

Extract columns from query string.

Parameters:: query (str) – Query string.
Returns:: List of column names.
Return type:: list

celldetective.utils.parsing.parse_isotropic_radii(string: str) → List[int | List[int]][source]

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:: A list of parsed radii where: - Single integers are included as int. - Ranges are included as two-element lists [start, end].
Return type:: list

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.

celldetective.utils.resources.auto_find_gpu()[source]

Automatically detects the presence of GPU devices in the system.

This function checks if any GPU devices are available for use by querying the system’s physical devices. It is a utility function to simplify the process of determining whether GPU-accelerated computing can be leveraged in data processing or model training tasks.

Returns:: True if one or more GPU devices are detected, False otherwise.
Return type:: bool

Notes

The function uses TensorFlow’s list_physical_devices method to query available devices, specifically looking for ‘GPU’ devices.
This function is useful for dynamically adjusting computation strategies based on available hardware resources.

Examples

>>> has_gpu = auto_find_gpu()
>>> print(f"GPU available: {has_gpu}")
# GPU available: True or False based on the system's hardware configuration.

celldetective.utils.stats.test_2samp_generic(data: DataFrame, feature: str | None = None, groupby_cols: str | List[str] | None = None, method: str = 'ks_2samp', *args: Any, **kwargs: Any) → DataFrame[source]

Performs pairwise statistical tests between groups of data, comparing a specified feature using a chosen method.

The function applies two-sample statistical tests, such as the Kolmogorov-Smirnov (KS) test or Cliff’s Delta, to compare distributions of a given feature across groups defined by groupby_cols. It returns the test results in a pivot table format with each group’s pairwise comparison.

Parameters:

data (pandas.DataFrame) – The input dataset containing the feature to be tested.
feature (str) – The name of the column representing the feature to compare between groups.
groupby_cols (list or str) – The column(s) used to group the data. These columns define the groups that will be compared pairwise.
method (str, optional, default="ks_2samp") – The statistical test to use. Options: - “ks_2samp”: Two-sample Kolmogorov-Smirnov test (default). - “cliffs_delta”: Cliff’s Delta for effect size between two distributions.
*args – Additional arguments and keyword arguments for the selected test method.
**kwargs – Additional arguments and keyword arguments for the selected test method.

Returns:

pivot – A pivot table containing the pairwise test results (p-values or effect sizes). The rows and columns represent the unique groups defined by groupby_cols, and the values represent the test result (e.g., p-values or effect sizes) between each group.

Return type:

pandas.DataFrame

Notes

The function compares all unique pairwise combinations of the groups based on groupby_cols.
For the “ks_2samp” method, the test compares the distributions using the Kolmogorov-Smirnov test.
For the “cliffs_delta” method, the function calculates the effect size between two distributions.
The results are returned in a symmetric pivot table where each cell represents the test result for the corresponding group pair.

celldetective.utils.types.is_integer_array(arr: ndarray) → bool[source]

Check if array consists of integers.

Parameters:: arr (ndarray) – Input array.
Returns:: True if all elements are integers, False otherwise.
Return type:: bool

celldetective.utils.types.test_bool_array(array: ndarray) → ndarray[source]

Convert boolean array to integer array if needed.

Parameters:: array (ndarray) – Input array.
Returns:: Integer array if input was boolean, else original array.
Return type:: ndarray

Filters

Image Filters Module

This module provides a collection of image filtering and thresholding functions used throughout Celldetective.

These functions act as building blocks for image preprocessing pipelines, particularly within custom extra_properties measurements and configuration-based image segmentation protocols (e.g. segment_frame_from_thresholds).

Usage in Configuration

Filters are typically specified in configuration dictionaries (e.g., instructions) as a list of lists or tuples, where the first element is the filter name and subsequent elements are arguments.

Example Configuration:

"filters": [
    ["gauss", 2.0],       # Applies gauss_filter(img, 2.0)
    ["subtract", 100],    # Applies subtract_filter(img, 100)
    ["abs"]               # Applies abs_filter(img)
]

This sequence is executed by filter_image, applying each filter to the output of the previous one.

Available Operations

Smoothing/Denoising: gauss, median
Edge/Texture: laplace, variance, std, dog (Difference of Gaussians), log (Laplacian of Gaussian)
Morphological: maximum (dilation), minimum (erosion), tophat (white top-hat)
Arithmetic: subtract, abs, invert, ln (natural log), percentile
Thresholding: otsu, multiotsu, local, niblack, sauvola

Function Naming Convention

Each filter function is named <filter_name>_filter (e.g., gauss_filter). In configuration lists, refer to them by <filter_name> (e.g., "gauss").

celldetective.filters.abs_filter(img: ndarray, *args: Any, **kwargs: Any) → ndarray[source]

Computes the absolute value of the image.

Parameters:

img (ndarray) – The input image.
*kwargs – Unused arguments.

Returns:

The absolute value of the image.

Return type:

ndarray

celldetective.filters.dog_filter(img: ndarray, blob_size: float | None = None, sigma_low: float = 1, sigma_high: float = 2, interpolate: bool = True, *args: Any, **kwargs: Any) → ndarray[source]

Applies a Difference of Gaussians (DoG) filter to the image.

Parameters:

img (ndarray) – The input image.
blob_size (float, optional) – Expected blob size, used to calculate sigmas if provided. Default is None.
sigma_low (float, optional) – Standard deviation for the lower Gaussian. Default is 1.
sigma_high (float, optional) – Standard deviation for the higher Gaussian. Default is 2.
interpolate (bool, optional) – Whether to interpolate NaN values. Default is True.
*kwargs – Additional arguments passed to skimage.filters.difference_of_gaussians.

Returns:

The filtered image.

Return type:

ndarray

celldetective.filters.filter_image(img: ndarray, filters: List[List[Any] | Tuple[Any, ...]] | None = None) → ndarray[source]

Apply one or more image filters to the input image.

Parameters:

img (ndarray) – The input image to be filtered.
filters (list or None, optional) – A list of filters to be applied to the image. Each filter is represented as a tuple or list with the first element being the filter function name (minus the ‘_filter’ extension, as listed in software.filters) and the subsequent elements being the arguments for that filter function. If None, the original image is returned without any filtering applied. Default is None.

Returns:

The filtered image.

Return type:

ndarray

Notes

This function applies a series of image filters to the input image. The filters are specified as a list of tuples, where each tuple contains the name of the filter function and its corresponding arguments. The filters are applied sequentially to the image. If no filters are provided, the original image is returned unchanged.

Examples

>>> image = np.random.rand(256, 256)
>>> filtered_image = filter_image(image, filters=[('gaussian', 3), ('median', 5)])

celldetective.filters.gauss_filter(img: ndarray, sigma: float | Sequence[float], interpolate: bool = True, *args: Any, **kwargs: Any) → ndarray[source]

Applies a Gaussian filter to an image.

Parameters:

img (ndarray) – The input image.
sigma (float or sequence of scalars) – Standard deviation for Gaussian kernel.
interpolate (bool, optional) – Whether to interpolate NaN values before filtering. Default is True.
*kwargs – Additional arguments passed to scipy.ndimage.gaussian_filter.

Returns:

The filtered image.

Return type:

ndarray

celldetective.filters.invert_filter(img: ndarray, value: float = 65535, *args: Any, **kwargs: Any) → ndarray[source]

Inverts the image by subtracting it from a maximum value.

Parameters:

img (ndarray) – The input image.
value (float or int, optional) – The maximum value to subtract the image from. Default is 65535.
*kwargs – Unused arguments.

Returns:

The inverted image.

Return type:

ndarray

celldetective.filters.laplace_filter(img: ~numpy.ndarray, output: ~typing.Any = <class 'float'>, interpolate: bool = True, *args: ~typing.Any, **kwargs: ~typing.Any) → ndarray[source]

Applies a Laplace filter to the image.

Parameters:

img (ndarray) – The input image.
output (type, optional) – The data type of the output. Default is float.
interpolate (bool, optional) – Whether to interpolate NaN values. Default is True.
*kwargs – Additional arguments passed to scipy.ndimage.laplace.

Returns:

The filtered image.

Return type:

ndarray

celldetective.filters.ln_filter(img: ndarray, interpolate: bool = True, *args: Any, **kwargs: Any) → ndarray[source]

Computes the natural logarithm of the image.

Parameters:

img (ndarray) – The input image.
interpolate (bool, optional) – Whether to interpolate NaN values. Default is True.
*kwargs – Unused arguments.

Returns:

The natural logarithm of the image.

Return type:

ndarray

celldetective.filters.local_filter(img: ndarray, *args: Any, **kwargs: Any) → ndarray[source]

Applies local thresholding to the image.

Parameters:

img (ndarray) – The input image.
*kwargs – Additional arguments passed to skimage.filters.threshold_local.

Returns:

The binary image after thresholding (0 or 1, as float).

Return type:

ndarray

celldetective.filters.log_filter(img: ndarray, blob_size: float | None = None, sigma: float = 1, interpolate: bool = True, *args: Any, **kwargs: Any) → ndarray[source]

Applies a Laplacian of Gaussian (LoG) filter to the image.

Parameters:

img (ndarray) – The input image.
blob_size (float, optional) – Expected blob size, used to calculate sigmas if provided. Default is None.
sigma (float, optional) – Standard deviation for the Gaussian kernel. Default is 1.
interpolate (bool, optional) – Whether to interpolate NaN values. Default is True.
*kwargs – Additional arguments passed to scipy.ndimage.gaussian_laplace.

Returns:

The filtered image.

Return type:

ndarray

celldetective.filters.maximum_filter(img: ndarray, size: int, interpolate: bool = True, *args: Any, **kwargs: Any) → ndarray[source]

Applies a maximum filter to an image.

Parameters:

img (ndarray) – The input image.
size (int) – The size of the maximum filter window.
interpolate (bool, optional) – Whether to interpolate NaN values before filtering. Default is True.
*kwargs – Additional arguments passed to scipy.ndimage.maximum_filter.

Returns:

The filtered image.

Return type:

ndarray

celldetective.filters.median_filter(img: ndarray, size: int, interpolate: bool = True, *args: Any, **kwargs: Any) → ndarray[source]

Applies a median filter to an image.

Parameters:

img (ndarray) – The input image.
size (int) – The size of the median filter window.
interpolate (bool, optional) – Whether to interpolate NaN values before filtering. Default is True.
*kwargs – Additional arguments passed to scipy.ndimage.median_filter.

Returns:

The filtered image.

Return type:

ndarray

celldetective.filters.minimum_filter(img: ndarray, size: int, interpolate: bool = True, *args: Any, **kwargs: Any) → ndarray[source]

Applies a minimum filter to an image.

Parameters:

img (ndarray) – The input image.
size (int) – The size of the minimum filter window.
interpolate (bool, optional) – Whether to interpolate NaN values before filtering. Default is True.
*kwargs – Additional arguments passed to scipy.ndimage.minimum_filter.

Returns:

The filtered image.

Return type:

ndarray

celldetective.filters.multiotsu_filter(img: ndarray, classes: int = 3, *args: Any, **kwargs: Any) → ndarray[source]

Applies Multi-Otsu thresholding to the image.

Parameters:

img (ndarray) – The input image.
classes (int, optional) – number of classes to be found. Default is 3.
*kwargs – Unused arguments.

Returns:

The segmented image (regions labeled).

Return type:

ndarray

celldetective.filters.niblack_filter(img: ndarray, *args: Any, **kwargs: Any) → ndarray[source]

Applies Niblack thresholding to the image.

Parameters:

img (ndarray) – The input image.
*kwargs – Additional arguments passed to skimage.filters.threshold_niblack.

Returns:

The binary image after thresholding (0 or 1, as float).

Return type:

ndarray

celldetective.filters.otsu_filter(img: ndarray, *args: Any, **kwargs: Any) → ndarray[source]

Applies Otsu’s thresholding to the image.

Parameters:

img (ndarray) – The input image.
*kwargs – Unused arguments.

Returns:

The binary image after thresholding (0 or 1, as float).

Return type:

ndarray

celldetective.filters.percentile_filter(img: ndarray, percentile: float, size: int, interpolate: bool = True, *args: Any, **kwargs: Any) → ndarray[source]

Applies a percentile filter to an image.

Parameters:

img (ndarray) – The input image.
percentile (float) – The percentile value to calculate.
size (int) – The size of the percentile filter window.
interpolate (bool, optional) – Whether to interpolate NaN values before filtering. Default is True.
*kwargs – Additional arguments passed to scipy.ndimage.percentile_filter.

Returns:

The filtered image.

Return type:

ndarray

celldetective.filters.sauvola_filter(img: ndarray, *args: Any, **kwargs: Any) → ndarray[source]

Applies Sauvola thresholding to the image.

Parameters:

img (ndarray) – The input image.
*kwargs – Additional arguments passed to skimage.filters.threshold_sauvola.

Returns:

The binary image after thresholding (0 or 1, as float).

Return type:

ndarray

celldetective.filters.std_filter(img: ndarray, size: int, interpolate: bool = True, *args: Any) → ndarray[source]

Computes the local standard deviation of the image.

Parameters:

img (ndarray) – The input image.
size (int) – The size of the window over which to compute the standard deviation.
interpolate (bool, optional) – Whether to interpolate NaN values. Default is True.

Returns:

The local standard deviation image.

Return type:

ndarray

celldetective.filters.subtract_filter(img: ndarray, value: float, *args: Any, **kwargs: Any) → ndarray[source]

Subtracts a scalar value from the image.

Parameters:

img (ndarray) – The input image.
value (float) – The value to subtract.
*kwargs – Unused arguments.

Returns:

The image with the value subtracted.

Return type:

ndarray

celldetective.filters.tophat_filter(img: ndarray, size: int, connectivity: int = 4, interpolate: bool = True, *args: Any, **kwargs: Any) → ndarray[source]

Applies a White Top-Hat filter to the image.

Parameters:

img (ndarray) – The input image.
size (int) – The size of the structuring element.
connectivity (int, optional) – The connectivity for determining the neighborhood. Default is 4.
interpolate (bool, optional) – Whether to interpolate NaN values. Default is True.
*kwargs – Additional arguments passed to scipy.ndimage.white_tophat.

Returns:

The filtered image.

Return type:

ndarray

celldetective.filters.variance_filter(img: ndarray, size: int, interpolate: bool = True, *args: Any) → ndarray[source]

Computes the local variance of the image.

Parameters:

img (ndarray) – The input image.
size (int) – The size of the window over which to compute the variance.
interpolate (bool, optional) – Whether to interpolate NaN values. Default is True.

Returns:

The local variance image.

Return type:

ndarray

Extra properties

Extra Properties Module

This module defines custom measurement functions that extend skimage.measure.regionprops.

These functions are designed to be dynamically discovered and applied to single-cell regions during the feature extraction phase. They allow for complex, user-defined measurements that go beyond standard morphological or intensity features (e.g., area of dark regions, specific intensity percentiles).

Function Signature Specification

To be valid, a function in this module must adhere to the following signature:

def my_custom_measurement(regionmask, intensity_image, target_channel='adhesion_channel', **kwargs):
    # ... calculation ...
    return scalar_value

Arguments:

regionmask (ndarray): A binary mask of the object (cell) within its bounding box.
intensity_image (ndarray): The intensity image crop corresponding to the bounding box. Note: Unlike regionprops, this image is not masked (background is not zeroed), allowing for threshold-based analysis within the bounding box.
target_channel (str, optional): The name of the channel being analyzed (e.g., ‘adhesion_channel’).
kwargs: Additional keyword arguments may be passed by the system.

Return Value:

Must return a scalar (float or int).
Returning NaN is permitted and handled.

Code Examples

Here are some simple examples to illustrate the structure:

def area(regionmask, intensity_image, **kwargs):
    return np.sum(regionmask)

def mean_intensity(regionmask, intensity_image, **kwargs):
    # We select only the pixels within the cell mask
    masked_pixels = intensity_image[regionmask]
    return np.mean(masked_pixels)

Naming and Indexing Rules

The name of the function determines the column name in the output measurement table.

Channel Replacement: If the function name contains the substring intensity, it is automatically replaced by the actual channel name being measured.
- Example: intensity_mean -> green_channel_mean
Multi-channel Indexing: Since these functions are often run on multiple channels, avoid using simple digits (0-9) in the function name if they could conflict with channel indexing.
- Bad: measure_ch1
- Good: measure_channel_one

Integration Details

Automatic Discovery: Any function defined in this module is automatically detected and listed in the GUI settings under “Extra features”.
Execution: These functions are called by celldetective.measure.measure_features.

celldetective.extra_properties.area_dark_intensity(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel', fill_holes: bool = True, threshold: float = 0.95) → float[source]

Computes the absolute area within the regionmask where the intensity is below a given threshold.

This function identifies pixels in the region where the intensity is lower than threshold. If fill_holes is True, small enclosed holes in the detected dark regions are filled before computing the total area.

Parameters:

regionmask (ndarray) – A binary mask (2D array) where nonzero values define the region of interest.
intensity_image (ndarray) – A 2D array of the same shape as regionmask, representing the intensity values associated with the region.
target_channel (str, optional) – Name of the intensity channel used for measurement. Defaults to ‘adhesion_channel’.
fill_holes (bool, optional) – If True, fills enclosed holes in the detected dark intensity regions before computing the area. Defaults to True.
threshold (float, optional) – Intensity threshold below which a pixel is considered part of a dark region. Defaults to 0.95.

Returns:

dark_area – The absolute area (number of pixels) where intensity values are below threshold, within the regionmask.

Return type:

Notes

The default threshold for defining “dark” intensity regions is 0.95, but it can be adjusted.
If fill_holes is True, the function applies hole-filling to the detected dark regions using skimage.measure.label and fill_label_holes().
The target_channel parameter tells regionprops to only measure this channel.

celldetective.extra_properties.area_dark_intensity_ninety(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel', fill_holes: bool = True) → float[source]

Computes the area of the region where intensity is below 0.90.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.
target_channel (str, optional) – Target channel name. Default is ‘adhesion_channel’.
fill_holes (bool, optional) – Whether to fill holes in the dark regions. Default is True.

Returns:

Area with intensity below 0.90.

Return type:

celldetective.extra_properties.area_dark_intensity_ninetyfive(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel', fill_holes: bool = True) → float[source]

Computes the area of the region where intensity is below 0.95.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.
target_channel (str, optional) – Target channel name. Default is ‘adhesion_channel’.
fill_holes (bool, optional) – Whether to fill holes in the dark regions. Default is True.

Returns:

Area with intensity below 0.95.

Return type:

celldetective.extra_properties.area_detected_in_intensity(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel') → float[source]

Computes the detected area within the regionmask based on threshold-based segmentation.

The function applies a predefined filtering and thresholding pipeline to the intensity image (normalized adhesion channel) to detect significant regions. The resulting segmented regions are restricted to the regionmask, ensuring that only the relevant area is measured.

Parameters:

regionmask (ndarray) – A binary mask (2D array) where nonzero values define the region of interest.
intensity_image (ndarray) – A 2D array of the same shape as regionmask, representing the intensity values associated with the region.
target_channel (str, optional) – Name of the intensity channel used for measurement. Defaults to ‘adhesion_channel’.

Returns:

detected_area – The total area (number of pixels) detected based on intensity-based segmentation.

Return type:

Notes

The segmentation is performed using segment_frame_from_thresholds() with predefined parameters:
- Thresholding range: [0.02, 1000]
- Filters applied in sequence:
  - “subtract” with value 1 (subtract 1 from intensity values)
  - “abs” (take absolute value of intensities)
  - “gauss” with sigma 0.8 (apply Gauss filter with sigma 0.8)
The segmentation includes hole filling.
The detected regions are converted to a binary mask (lbl > 0).
Any pixels outside the regionmask are excluded from the measurement.

celldetective.extra_properties.fraction_of_area_dark_intensity(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel', fill_holes: bool = True, threshold: float = 0.95) → float[source]

Computes the fraction of the region area where intensity is below a threshold.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.
target_channel (str, optional) – Target channel name. Default is ‘adhesion_channel’.
fill_holes (bool, optional) – Whether to fill holes in the dark regions. Default is True.
threshold (float, optional) – Intensity threshold. Default is 0.95.

Returns:

Fraction of the area with dark intensity.

Return type:

celldetective.extra_properties.fraction_of_area_detected_in_intensity(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel') → float[source]

Computes the fraction of the region area that is detected in the intensity image.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.
target_channel (str, optional) – Target channel name. Default is ‘adhesion_channel’.

Returns:

Fraction of the area detected in the intensity image.

Return type:

celldetective.extra_properties.intensity_center_of_mass_displacement(regionmask: ndarray, intensity_image: ndarray) → Tuple[float, float, float, float][source]

Computes the displacement between the geometric centroid and the intensity-weighted center of mass of a region.

Parameters:

regionmask (ndarray) – A binary mask (2D array) where nonzero values indicate the region of interest.
intensity_image (ndarray) – A 2D array of the same shape as regionmask, representing the intensity values associated with the region.

Returns:

distance (float) – Euclidean distance between the geometric centroid and the intensity-weighted center of mass.
direction_arctan (float) – Angle (in degrees) of displacement from the geometric centroid to the intensity-weighted center of mass, computed using arctan2(delta_y, delta_x).
delta_x (float) – Difference in x-coordinates (intensity-weighted centroid - geometric centroid).
delta_y (float) – Difference in y-coordinates (intensity-weighted centroid - geometric centroid).

Notes

If the intensity_image contains NaN values, it is first processed using interpolate_nan().
Negative intensity values are set to zero to prevent misbehavior in center of mass calculation.
If the intensity image is entirely zero, all outputs are NaN.

celldetective.extra_properties.intensity_center_of_mass_displacement_edge(regionmask: ndarray, intensity_image: ndarray) → Tuple[float, float, float, float][source]

Computes displacement of center of mass relative to the edge of the region.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.

Returns:

(distance, direction_arctan, delta_x, delta_y). Returns (NaN, NaN, NaN, NaN) if calculation fails.

Return type:

celldetective.extra_properties.intensity_median(regionmask: ndarray, intensity_image: ndarray) → float[source]

Computes the median intensity within the region.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.

Returns:

Median intensity.

Return type:

celldetective.extra_properties.intensity_nanmean(regionmask: ndarray, intensity_image: ndarray) → float[source]

Computes the mean intensity within the region, ignoring NaNs.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.

Returns:

Mean intensity, or NaN if the image is all zeros.

Return type:

celldetective.extra_properties.intensity_percentile_fifty(regionmask: ndarray, intensity_image: ndarray) → float[source]

Computes the 50th percentile (median) of intensity within the region.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.

Returns:

50th percentile of intensity.

Return type:

celldetective.extra_properties.intensity_percentile_ninety(regionmask: ndarray, intensity_image: ndarray) → float[source]

Computes the 90th percentile of intensity within the region.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.

Returns:

90th percentile of intensity.

Return type:

celldetective.extra_properties.intensity_percentile_ninety_five(regionmask: ndarray, intensity_image: ndarray) → float[source]

Computes the 95th percentile of intensity within the region.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.

Returns:

95th percentile of intensity.

Return type:

celldetective.extra_properties.intensity_percentile_ninety_nine(regionmask: ndarray, intensity_image: ndarray) → float[source]

Computes the 99th percentile of intensity within the region.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.

Returns:

99th percentile of intensity.

Return type:

celldetective.extra_properties.intensity_percentile_seventy_five(regionmask: ndarray, intensity_image: ndarray) → float[source]

Computes the 75th percentile of intensity within the region.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.

Returns:

75th percentile of intensity.

Return type:

celldetective.extra_properties.intensity_percentile_twenty_five(regionmask: ndarray, intensity_image: ndarray) → float[source]

Computes the 25th percentile of intensity within the region.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.

Returns:

25th percentile of intensity.

Return type:

celldetective.extra_properties.intensity_radial_gradient(regionmask: ndarray, intensity_image: ndarray) → Tuple[float, float, float][source]

Determines whether the intensity follows a radial gradient from the center to the edge of the cell.

The function fits a linear model to the intensity values as a function of distance from the center (computed via the Euclidean distance transform). The slope of the fitted line indicates whether the intensity is higher at the center or at the edges.

Parameters:

regionmask (ndarray) – A binary mask (2D array) where nonzero values define the region of interest.
intensity_image (ndarray) – A 2D array of the same shape as regionmask, representing the intensity values associated with the region.

Returns:

slope (float) – Slope of the fitted linear model.
- If slope > 0: Intensity increases towards the edge.
- If slope < 0: Intensity is higher at the center.
intercept (float) – Intercept of the fitted linear model.
r2 (float) – Coefficient of determination (R²), indicating how well the linear model fits the intensity profile.

Notes

If the intensity_image contains NaN values, they are interpolated using interpolate_nan().
The Euclidean distance transform (distance_transform_edt) is used to compute the distance of each pixel from the edge.
The x-values for the linear fit are reversed so that the origin is at the center.
A warning suppression is applied to ignore messages about poorly conditioned polynomial fits.

celldetective.extra_properties.intensity_std(regionmask: ndarray, intensity_image: ndarray) → float[source]

Computes the standard deviation of intensity within the region.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.

Returns:

Standard deviation of intensity.

Return type:

celldetective.extra_properties.mean_dark_intensity_eight_five_fillhole_false(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel') → float[source]

Computes the mean intensity in dark regions (< 0.85), ignoring NaNs and without hole filling.

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.
target_channel (str, optional) – Target channel name. Default is ‘adhesion_channel’.

Returns:

Mean intensity in dark regions.

Return type:

celldetective.extra_properties.mean_dark_intensity_eighty_five(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel', fill_holes: bool = True) → float[source]

Calculate the mean intensity in a dark subregion below 85, handling NaN values.

Parameters:

regionmask (ndarray) – A binary mask (2D array) where nonzero values define the region of interest.
intensity_image (ndarray) – A 2D array of the same shape as regionmask, representing the intensity values associated with the region.
target_channel (str, optional) – Name of the intensity channel used for measurement. Defaults to ‘adhesion_channel’.
fill_holes (bool, optional) – If True, fills enclosed holes in the detected dark intensity regions before computing the area. Defaults to True.

Returns:

Mean intensity value in the dark subregion.

Return type:

celldetective.extra_properties.mean_dark_intensity_ninety(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel', fill_holes: bool = True) → float[source]

Calculate the mean intensity in a dark subregion below 90, handling NaN values.

Parameters:

regionmask (ndarray) – A binary mask (2D array) where nonzero values define the region of interest.
intensity_image (ndarray) – A 2D array of the same shape as regionmask, representing the intensity values associated with the region.
target_channel (str, optional) – Name of the intensity channel used for measurement. Defaults to ‘adhesion_channel’.
fill_holes (bool, optional) – If True, fills enclosed holes in the detected dark intensity regions before computing the area. Defaults to True.

Returns:

Mean intensity value in the dark subregion.

Return type:

celldetective.extra_properties.mean_dark_intensity_ninety_fillhole_false(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel') → float[source]

Calculate the mean intensity in a dark subregion, handling NaN values.

Parameters:

regionmask (ndarray) – A binary mask (2D array) where nonzero values define the region of interest.
intensity_image (ndarray) – A 2D array of the same shape as regionmask, representing the intensity values associated with the region.
target_channel (str, optional) – Name of the intensity channel used for measurement. Defaults to ‘adhesion_channel’.

Returns:

Mean intensity value in the dark subregion.

Return type:

celldetective.extra_properties.mean_dark_intensity_ninetyfive(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel', fill_holes: bool = True) → float[source]

Calculate the mean intensity in a dark subregion below 95, handling NaN values.

Parameters:

regionmask (ndarray) – A binary mask (2D array) where nonzero values define the region of interest.
intensity_image (ndarray) – A 2D array of the same shape as regionmask, representing the intensity values associated with the region.
target_channel (str, optional) – Name of the intensity channel used for measurement. Defaults to ‘adhesion_channel’.
fill_holes (bool, optional) – If True, fills enclosed holes in the detected dark intensity regions before computing the area. Defaults to True.

Returns:

Mean intensity value in the dark subregion.

Return type:

celldetective.extra_properties.mean_dark_intensity_ninetyfive_fillhole_false(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel') → float[source]

Calculate the mean intensity in a dark subregion below 95, handling NaN values.

Parameters:

regionmask (ndarray) – A binary mask (2D array) where nonzero values define the region of interest.
intensity_image (ndarray) – A 2D array of the same shape as regionmask, representing the intensity values associated with the region.
target_channel (str, optional) – Name of the intensity channel used for measurement. Defaults to ‘adhesion_channel’.

Returns:

Mean intensity value in the dark subregion.

Return type:

celldetective.extra_properties.percentile_five_dark_intensity_ninety(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel') → float[source]

Computes the 5th percentile of intensity in dark regions (< 0.95).

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.
target_channel (str, optional) – Target channel name. Default is ‘adhesion_channel’.

Returns:

5th percentile of intensity in dark regions.

Return type:

celldetective.extra_properties.percentile_ninty_five_dark_intensity_ninety(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel') → float[source]

Computes the 95th percentile of intensity in dark regions (< 0.95).

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.
target_channel (str, optional) – Target channel name. Default is ‘adhesion_channel’.

Returns:

95th percentile of intensity in dark regions.

Return type:

celldetective.extra_properties.percentile_one_dark_intensity_ninety(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel') → float[source]

Computes the 1st percentile of intensity in dark regions (< 0.95).

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.
target_channel (str, optional) – Target channel name. Default is ‘adhesion_channel’.

Returns:

1st percentile of intensity in dark regions.

Return type:

celldetective.extra_properties.percentile_ten_dark_intensity_ninety(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel') → float[source]

Computes the 10th percentile of intensity in dark regions (< 0.95).

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.
target_channel (str, optional) – Target channel name. Default is ‘adhesion_channel’.

Returns:

10th percentile of intensity in dark regions.

Return type:

celldetective.extra_properties.percentile_zero_one_dark_intensity_ninety(regionmask: ndarray, intensity_image: ndarray, target_channel: str = 'adhesion_channel') → float[source]

Computes the 0.1th percentile of intensity in dark regions (< 0.95).

Parameters:

regionmask (ndarray) – Binary mask of the region of interest.
intensity_image (ndarray) – Intensity image.
target_channel (str, optional) – Target channel name. Default is ‘adhesion_channel’.

Returns:

0.1th percentile of intensity in dark regions.

Return type: