spacr 0.4.60__py3-none-any.whl → 0.9.0__py3-none-any.whl

spacr/timelapse.py

@@ -7,9 +7,9 @@ from IPython.display import display
 from IPython.display import Image as ipyimage
 import trackpy as tp
 from btrack import datasets as btrack_datasets
-from skimage.measure import regionprops
+from skimage.measure import regionprops, regionprops_table
 from scipy.signal import find_peaks
-from scipy.optimize import curve_fit
+from scipy.optimize import curve_fit, linear_sum_assignment
 from scipy.integrate import trapz
 import matplotlib.pyplot as plt
 
@@ -255,7 +255,7 @@ def _relabel_masks_based_on_tracks(masks, tracks, mode='btrack'):
 
     return relabeled_masks
 
-def _prepare_for_tracking(mask_array):
+def _prepare_for_tracking_v1(mask_array):
     """
     Prepare the mask array for object tracking.
 
@@ -286,6 +286,105 @@ def _prepare_for_tracking(mask_array):
             })
     return pd.DataFrame(frames)
 
+def _prepare_for_tracking_v1(mask_array):
+    frames = []
+    for t, frame in enumerate(mask_array):
+        props = regionprops_table(
+            frame,
+            properties=('label', 'centroid-0', 'centroid-1', 'area',
+                        'bbox-0', 'bbox-1', 'bbox-2', 'bbox-3',
+                        'eccentricity')
+        )
+        df = pd.DataFrame(props)
+        df = df.rename(columns={
+            'centroid-0': 'y', 'centroid-1': 'x', 'area': 'mass',
+            'label': 'original_label'
+        })
+        df['frame'] = t
+        frames.append(df[['frame','y','x','mass','original_label',
+                          'bbox-0','bbox-1','bbox-2','bbox-3','eccentricity']])
+    return pd.concat(frames, ignore_index=True)
+
+def _prepare_for_tracking(mask_array):
+    frames = []
+    for t, frame in enumerate(mask_array):
+        props = regionprops_table(
+            frame,
+            properties=('label', 'centroid', 'area', 'bbox', 'eccentricity')
+        )
+        df = pd.DataFrame(props)
+        df = df.rename(columns={
+            'centroid-0': 'y',
+            'centroid-1': 'x',
+            'area':       'mass',
+            'label':      'original_label'
+        })
+        df['frame'] = t
+        frames.append(df[['frame','y','x','mass','original_label',
+                          'bbox-0','bbox-1','bbox-2','bbox-3','eccentricity']])
+    return pd.concat(frames, ignore_index=True)
+
+def _track_by_iou(masks, iou_threshold=0.1):
+    """
+    Build a track table by linking masks frame→frame via IoU.
+    Returns a DataFrame with columns [frame, original_label, track_id].
+    """
+    n_frames = masks.shape[0]
+    # 1) initialize: every label in frame 0 starts its own track
+    labels0 = np.unique(masks[0])[1:]
+    next_track = 1
+    track_map = {}  # (frame,label) -> track_id
+    for L in labels0:
+        track_map[(0, L)] = next_track
+        next_track += 1
+
+    # 2) iterate through frames
+    for t in range(1, n_frames):
+        prev, curr = masks[t-1], masks[t]
+        matches = link_by_iou(prev, curr, iou_threshold=iou_threshold)
+        used_curr = set()
+        # a) assign matched labels to existing tracks
+        for L_prev, L_curr in matches:
+            tid = track_map[(t-1, L_prev)]
+            track_map[(t, L_curr)] = tid
+            used_curr.add(L_curr)
+        # b) any label in curr not matched → new track
+        for L in np.unique(curr)[1:]:
+            if L not in used_curr:
+                track_map[(t, L)] = next_track
+                next_track += 1
+
+    # 3) flatten into DataFrame
+    records = []
+    for (frame, label), tid in track_map.items():
+        records.append({'frame': frame, 'original_label': label, 'track_id': tid})
+    return pd.DataFrame(records)
+
+def link_by_iou(mask_prev, mask_next, iou_threshold=0.1):
+    # Get labels
+    labels_prev = np.unique(mask_prev)[1:]
+    labels_next = np.unique(mask_next)[1:]
+    # Precompute masks as boolean
+    bool_prev = {L: mask_prev==L for L in labels_prev}
+    bool_next = {L: mask_next==L for L in labels_next}
+    # Cost matrix = 1 - IoU
+    cost = np.ones((len(labels_prev), len(labels_next)), dtype=float)
+    for i, L1 in enumerate(labels_prev):
+        m1 = bool_prev[L1]
+        for j, L2 in enumerate(labels_next):
+            m2 = bool_next[L2]
+            inter = np.logical_and(m1, m2).sum()
+            union = np.logical_or(m1, m2).sum()
+            if union > 0:
+                cost[i, j] = 1 - inter/union
+    # Solve assignment
+    row_ind, col_ind = linear_sum_assignment(cost)
+    matches = []
+    for i, j in zip(row_ind, col_ind):
+        if cost[i,j] <= 1 - iou_threshold:
+            matches.append((labels_prev[i], labels_next[j]))
+    return matches
+
 def _find_optimal_search_range(features, initial_search_range=500, increment=10, max_attempts=49, memory=3):
     """
     Find the optimal search range for linking features.
@@ -336,7 +435,94 @@ def _remove_objects_from_first_frame(masks, percentage=10):
             masks[0][first_frame == label] = 0
         return masks
 
-def _facilitate_trackin_with_adaptive_removal(masks, search_range=500, max_attempts=100, memory=3):
+def _track_by_iou(masks, iou_threshold=0.1):
+    """
+    Build a track table by linking masks frame→frame via IoU.
+    Returns a DataFrame with columns [frame, original_label, track_id].
+    """
+    n_frames = masks.shape[0]
+    # 1) initialize: every label in frame 0 starts its own track
+    labels0 = np.unique(masks[0])[1:]
+    next_track = 1
+    track_map = {}  # (frame,label) -> track_id
+    for L in labels0:
+        track_map[(0, L)] = next_track
+        next_track += 1
+
+    # 2) iterate through frames
+    for t in range(1, n_frames):
+        prev, curr = masks[t-1], masks[t]
+        matches = link_by_iou(prev, curr, iou_threshold=iou_threshold)
+        used_curr = set()
+        # a) assign matched labels to existing tracks
+        for L_prev, L_curr in matches:
+            tid = track_map[(t-1, L_prev)]
+            track_map[(t, L_curr)] = tid
+            used_curr.add(L_curr)
+        # b) any label in curr not matched → new track
+        for L in np.unique(curr)[1:]:
+            if L not in used_curr:
+                track_map[(t, L)] = next_track
+                next_track += 1
+
+    # 3) flatten into DataFrame
+    records = []
+    for (frame, label), tid in track_map.items():
+        records.append({'frame': frame, 'original_label': label, 'track_id': tid})
+    return pd.DataFrame(records)
+
+
+def _facilitate_trackin_with_adaptive_removal(masks, search_range=None, max_attempts=5, memory=3, min_mass=50, track_by_iou=False):
+    """
+    Facilitates object tracking with deterministic initial filtering and
+    trackpy’s constant-velocity prediction.
+
+    Args:
+        masks (np.ndarray): integer‐labeled masks (frames × H × W).
+        search_range (int|None): max displacement; if None, auto‐computed.
+        max_attempts (int): how many times to retry with smaller search_range.
+        memory (int): trackpy memory parameter.
+        min_mass (float): drop any object in frame 0 with area < min_mass.
+
+    Returns:
+        masks, features_df, tracks_df
+
+    Raises:
+        RuntimeError if linking fails after max_attempts.
+    """
+    # 1) initial features & filter frame 0 by area
+    features = _prepare_for_tracking(masks)
+    f0 = features[features['frame'] == 0]
+    valid = f0.loc[f0['mass'] >= min_mass, 'original_label'].unique()
+    masks[0] = np.where(np.isin(masks[0], valid), masks[0], 0)
+
+    # 2) recompute features on filtered masks
+    features = _prepare_for_tracking(masks)
+
+    # 3) default search_range = 2×sqrt(99th‑pct area)
+    if search_range is None:
+        a99 = f0['mass'].quantile(0.99)
+        search_range = max(1, int(2 * np.sqrt(a99)))
+
+    # 4) attempt linking, shrinking search_range on failure
+    for attempt in range(1, max_attempts + 1):
+        try:
+            if track_by_iou:
+                tracks_df = _track_by_iou(masks, iou_threshold=0.1)
+            else:
+                tracks_df = tp.link_df(features,search_range=search_range, memory=memory, predict=True)
+                print(f"Linked on attempt {attempt} with search_range={search_range}")
+            return masks, features, tracks_df
+
+        except Exception as e:
+            search_range = max(1, int(search_range * 0.8))
+            print(f"Attempt {attempt} failed ({e}); reducing search_range to {search_range}")
+
+    raise RuntimeError(
+        f"Failed to track after {max_attempts} attempts; last search_range={search_range}"
+    )
+
+def _facilitate_trackin_with_adaptive_removal_v1(masks, search_range=500, max_attempts=100, memory=3):
     """
     Facilitates object tracking with adaptive removal.
 
@@ -376,7 +562,7 @@ def _facilitate_trackin_with_adaptive_removal(masks, search_range=500, max_attem
     print(f"Failed to track objects after {max_attempts} attempts. Consider adjusting parameters.")
     return None, None, None
 
-def _trackpy_track_cells(src, name, batch_filenames, object_type, masks, timelapse_displacement, timelapse_memory, timelapse_remove_transient, plot, save, mode):
+def _trackpy_track_cells(src, name, batch_filenames, object_type, masks, timelapse_displacement, timelapse_memory, timelapse_remove_transient, plot, save, mode, track_by_iou):
         """
         Track cells using the Trackpy library.
 
@@ -409,7 +595,7 @@ def _trackpy_track_cells(src, name, batch_filenames, object_type, masks, timelap
             if timelapse_displacement is None:
                 timelapse_displacement = 50
 
-        masks, features, tracks_df = _facilitate_trackin_with_adaptive_removal(masks, search_range=timelapse_displacement, max_attempts=100, memory=timelapse_memory)
+        masks, features, tracks_df = _facilitate_trackin_with_adaptive_removal(masks, search_range=timelapse_displacement, max_attempts=100, memory=timelapse_memory, track_by_iou=track_by_iou)
 
         tracks_df['particle'] += 1
 

spacr/utils.py

@@ -1,5 +1,4 @@
 import os, re, sqlite3, torch, torchvision, random, string, shutil, cv2, tarfile, glob, psutil, platform, gzip, subprocess, time, requests, ast, traceback
-
 import numpy as np
 import pandas as pd
 from cellpose import models as cp_models
@@ -11,7 +10,7 @@ import skimage.measure as measure
 from skimage.transform import resize as resizescikit
 from skimage.morphology import dilation, square
 from skimage.measure import find_contours
-from skimage.segmentation import clear_border
+from skimage.segmentation import clear_border, find_boundaries
 from scipy.stats import pearsonr
 
 from collections import defaultdict, OrderedDict
@@ -432,7 +431,7 @@ def close_multiprocessing_processes():
 
 def check_mask_folder(src,mask_fldr):
     
-    mask_folder = os.path.join(src,'norm_channel_stack',mask_fldr)
+    mask_folder = os.path.join(src,'masks',mask_fldr)
     stack_folder = os.path.join(src,'stack')
 
     if not os.path.exists(mask_folder):
@@ -554,7 +553,7 @@ def _get_cellpose_batch_size():
     except Exception as e:
         return 8
 
-def _extract_filename_metadata(filenames, src, regular_expression, metadata_type='cellvoyager', pick_slice=False, skip_mode='01'):
+def _extract_filename_metadata(filenames, src, regular_expression, metadata_type='cellvoyager'):
     
     images_by_key = defaultdict(list)
 
@@ -568,33 +567,38 @@ def _extract_filename_metadata(filenames, src, regular_expression, metadata_type
                     plate = os.path.basename(src)
 
                 well = match.group('wellID')
-                field = match.group('fieldID')
-                channel = match.group('chanID')
-                mode = None
-
                 if well[0].isdigit():
                     well = str(_safe_int_convert(well))
+                
+                field = match.group('fieldID')
                 if field[0].isdigit():
                     field = str(_safe_int_convert(field))
+                    
+                channel = match.group('chanID')
                 if channel[0].isdigit():
                     channel = str(_safe_int_convert(channel))
-
+                    
+                if 'timeID' in match.groupdict():
+                    timeID = match.group('timeID')
+                    if timeID[0].isdigit():
+                        timeID = str(_safe_int_convert(timeID))
+                else:
+                    timeID = None
+                        
+                if 'sliceID' in match.groupdict():
+                    sliceID = match.group('sliceID')
+                    if sliceID[0].isdigit():
+                        sliceID = str(_safe_int_convert(sliceID))
+                else:
+                    sliceID = None
+                    
                 if metadata_type =='cq1':
                     orig_wellID = wellID
                     wellID = _convert_cq1_well_id(wellID)
                     print(f'Converted Well ID: {orig_wellID} to {wellID}', end='\r', flush=True)
 
-                if pick_slice:
-                    try:
-                        mode = match.group('AID')
-                    except IndexError:
-                        sliceid = '00'
-
-                    if mode == skip_mode:
-                        continue
-                        
-                key = (plate, well, field, channel, mode)
-                file_path = os.path.join(src, filename)  # Store the full path
+                key = (plate, well, field, channel, timeID, sliceID)
+                file_path = os.path.join(src, filename)
                 images_by_key[key].append(file_path)
                 
             except IndexError:
@@ -1262,9 +1266,9 @@ def _pivot_counts_table(db_path):
     
 def _get_cellpose_channels(src, nucleus_channel, pathogen_channel, cell_channel):
 
-    cell_mask_path = os.path.join(src, 'norm_channel_stack', 'cell_mask_stack')
-    nucleus_mask_path = os.path.join(src, 'norm_channel_stack', 'nucleus_mask_stack')
-    pathogen_mask_path = os.path.join(src, 'norm_channel_stack', 'pathogen_mask_stack')
+    cell_mask_path = os.path.join(src, 'masks', 'cell_mask_stack')
+    nucleus_mask_path = os.path.join(src, 'masks', 'nucleus_mask_stack')
+    pathogen_mask_path = os.path.join(src, 'masks', 'pathogen_mask_stack')
 
 
     if os.path.exists(cell_mask_path) or os.path.exists(nucleus_mask_path) or os.path.exists(pathogen_mask_path):
@@ -3084,17 +3088,19 @@ def _object_filter(df, object_type, size_range, intensity_range, mask_chans, mas
     return df
 
 def _get_regex(metadata_type, img_format, custom_regex=None):
+    
+    print(f"Image_format: {img_format}")
 
     if img_format == None:
-        img_format == '.tif'
+        img_format == 'tif'
     if metadata_type == 'cellvoyager':
-        regex = f'(?P<plateID>.*)_(?P<wellID>.*)_T(?P<timeID>.*)F(?P<fieldID>.*)L(?P<laserID>..)A(?P<AID>..)Z(?P<sliceID>.*)C(?P<chanID>.*){img_format}'
+        regex = f"(?P<plateID>.*)_(?P<wellID>.*)_T(?P<timeID>.*)F(?P<fieldID>.*)L(?P<laserID>..)A(?P<AID>..)Z(?P<sliceID>.*)C(?P<chanID>.*).{img_format}"
     elif metadata_type == 'cq1':
-        regex = f'W(?P<wellID>.*)F(?P<fieldID>.*)T(?P<timeID>.*)Z(?P<sliceID>.*)C(?P<chanID>.*){img_format}'
+        regex = f"W(?P<wellID>.*)F(?P<fieldID>.*)T(?P<timeID>.*)Z(?P<sliceID>.*)C(?P<chanID>.*).{img_format}"
     elif metadata_type == 'auto':
-        regex = f'(?P<plateID>.*)_(?P<wellID>.*)_T(?P<timeID>.*)F(?P<fieldID>.*)L(?P<laserID>.*)C(?P<chanID>.*).tif'     
+        regex = f"(?P<plateID>.*)_(?P<wellID>.*)_T(?P<timeID>.*)F(?P<fieldID>.*)L(?P<laserID>.*)C(?P<chanID>.*).tif"     
     elif metadata_type == 'custom':
-        regex = f'({custom_regex}){img_format}'
+        regex = f"({custom_regex}){img_format}"
         
     print(f'regex mode:{metadata_type} regex:{regex}')
     return regex
@@ -3279,15 +3285,6 @@ class SaliencyMapGenerator:
         return fig
     
     def percentile_normalize(self, img, lower_percentile=2, upper_percentile=98):
-        """
-        Normalize each channel of the image to the given percentiles.
-        Args:
-            img: Input image as numpy array with shape (H, W, C)
-            lower_percentile: Lower percentile for normalization (default 2)
-            upper_percentile: Upper percentile for normalization (default 98)
-        Returns:
-            img: Normalized image
-        """
         img_normalized = np.zeros_like(img)
 
         for c in range(img.shape[2]):  # Iterate over each channel
@@ -3297,7 +3294,6 @@ class SaliencyMapGenerator:
 
         return img_normalized
 
-
 class GradCAMGenerator:
     def __init__(self, model, target_layer, cam_type='gradcam'):
         self.model = model
@@ -3402,15 +3398,6 @@ class GradCAMGenerator:
         return fig
     
     def percentile_normalize(self, img, lower_percentile=2, upper_percentile=98):
-        """
-        Normalize each channel of the image to the given percentiles.
-        Args:
-            img: Input image as numpy array with shape (H, W, C)
-            lower_percentile: Lower percentile for normalization (default 2)
-            upper_percentile: Upper percentile for normalization (default 98)
-        Returns:
-            img: Normalized image
-        """
         img_normalized = np.zeros_like(img)
 
         for c in range(img.shape[2]):  # Iterate over each channel
@@ -4522,6 +4509,76 @@ def _merge_cells_based_on_parasite_overlap(parasite_mask, cell_mask, nuclei_mask
     relabeled_cell_mask, _ = label(cell_mask, return_num=True)
     return relabeled_cell_mask.astype(np.uint16)
 
+def _merge_cells_without_nucleus(adj_cell_mask: np.ndarray, nuclei_mask: np.ndarray):
+    """
+    Relabel any cell that lacks a nucleus to the ID of an adjacent
+    cell that *does* contain a nucleus.
+
+    Parameters
+    ----------
+    adj_cell_mask : np.ndarray
+        Labelled (0 = background) cell mask after all other merging steps.
+    nuclei_mask : np.ndarray
+        Labelled (0 = background) nuclei mask.
+
+    Returns
+    -------
+    np.ndarray
+        Updated cell mask with nucleus-free cells merged into
+        neighbouring nucleus-bearing cells.
+    """
+    out = adj_cell_mask.copy()
+
+    # ----------------------------------------------------------------- #
+    # 1 — Identify which cell IDs contain a nucleus
+    nuc_labels = np.unique(nuclei_mask[nuclei_mask > 0])
+
+    cells_with_nuc = set()
+    for nuc_id in nuc_labels:
+        labels, counts = np.unique(adj_cell_mask[nuclei_mask == nuc_id],
+                                   return_counts=True)
+
+        # drop background (label 0) from *both* arrays
+        keep = labels > 0
+        labels = labels[keep]
+        counts = counts[keep]
+
+        if labels.size:                     # at least one non-zero overlap
+            cells_with_nuc.add(labels[np.argmax(counts)])
+
+    # ----------------------------------------------------------------- #
+    # 2 — Build an adjacency map between neighbouring cell IDs
+    # ----------------------------------------------------------------- #
+    boundaries = find_boundaries(adj_cell_mask, mode="thick")
+    adj_map = defaultdict(set)
+
+    ys, xs = np.where(boundaries)
+    h, w = adj_cell_mask.shape
+    for y, x in zip(ys, xs):
+        src = adj_cell_mask[y, x]
+        if src == 0:
+            continue
+        for dy in (-1, 0, 1):
+            for dx in (-1, 0, 1):
+                ny, nx = y + dy, x + dx
+                if 0 <= ny < h and 0 <= nx < w:
+                    dst = adj_cell_mask[ny, nx]
+                    if dst != 0 and dst != src:
+                        adj_map[src].add(dst)
+
+    # ----------------------------------------------------------------- #
+    # 3 — Relabel nucleus-free cells that touch nucleus-bearing neighbours
+    # ----------------------------------------------------------------- #
+    cells_no_nuc = set(np.unique(adj_cell_mask)) - {0} - cells_with_nuc
+    for cell_id in cells_no_nuc:
+        neighbours = adj_map.get(cell_id, set()) & cells_with_nuc
+        if neighbours:
+            # Choose the first nucleus-bearing neighbour deterministically
+            target = sorted(neighbours)[0]
+            out[out == cell_id] = target
+
+    return out.astype(np.uint16)
+
 def adjust_cell_masks(parasite_folder, cell_folder, nuclei_folder, overlap_threshold=5, perimeter_threshold=30):
 
     """
@@ -4556,12 +4613,12 @@ def adjust_cell_masks(parasite_folder, cell_folder, nuclei_folder, overlap_thres
         parasite_mask = np.load(parasite_path, allow_pickle=True)
         cell_mask = np.load(cell_path, allow_pickle=True)
         nuclei_mask = np.load(nuclei_path, allow_pickle=True)
+        
         # Merge and relabel cells
         merged_cell_mask = _merge_cells_based_on_parasite_overlap(parasite_mask, cell_mask, nuclei_mask, overlap_threshold, perimeter_threshold)
         
-        # Force 16 bit
-        #merged_cell_mask = merged_cell_mask.astype(np.uint16)
-        
+        #merged_cell_mask = _merge_cells_without_nucleus(merged_cell_mask, nuclei_mask)
+    
         # Overwrite the original cell mask file with the merged result
         np.save(cell_path, merged_cell_mask)
 
@@ -4698,10 +4755,10 @@ def get_ml_results_paths(src, model_type='xgboost', channel_of_interest=1):
     elif isinstance(channel_of_interest, int):
         feature_string = f"channel_{channel_of_interest}"
 
-    elif channel_of_interest is 'morphology':
+    elif channel_of_interest == 'morphology':
         feature_string = 'morphology'
 
-    elif channel_of_interest is None:
+    elif channel_of_interest == None:
         feature_string = 'all_features'
     else:
         raise ValueError(f"Unsupported channel_of_interest: {channel_of_interest}. Supported values are 'int', 'list', 'None', or 'morphology'.")
@@ -4851,7 +4908,7 @@ def correct_masks(src):
 
     from .io import _load_and_concatenate_arrays
 
-    cell_path = os.path.join(src,'norm_channel_stack', 'cell_mask_stack')
+    cell_path = os.path.join(src,'masks', 'cell_mask_stack')
     convert_and_relabel_masks(cell_path)
     _load_and_concatenate_arrays(src, [0,1,2,3], 1, 0, 2)
 
@@ -5115,13 +5172,46 @@ def correct_metadata_column_names(df):
 
 def control_filelist(folder, mode='columnID', values=['01','02']):
     files = os.listdir(folder)
-    if mode is 'columnID':
+    if mode == 'columnID':
         filtered_files = [file for file in files if file.split('_')[1][1:] in values]
-    if mode is 'rowID':
+    if mode == 'rowID':
         filtered_files = [file for file in files if file.split('_')[1][:1] in values]
     return filtered_files
     
 def rename_columns_in_db(db_path):
+    # map old column names → new names
+    rename_map = {
+        'row':      'rowID',
+        'column':   'columnID',
+        'col':      'columnID',
+        'plate':    'plateID',
+        'field':    'fieldID',
+        'channel':  'chanID',
+    }
+
+    con = sqlite3.connect(db_path)
+    cur = con.cursor()
+
+    # 1) get all user tables
+    cur.execute("SELECT name FROM sqlite_master WHERE type='table';")
+    tables = [row[0] for row in cur.fetchall()]
+
+    for table in tables:
+        # 2) get column names only
+        cur.execute(f"PRAGMA table_info(`{table}`);")
+        cols = [row[1] for row in cur.fetchall()]
+
+        # 3) for each old→new, if the old exists and new does not, rename it
+        for old, new in rename_map.items():
+            if old in cols and new not in cols:
+                sql = f"ALTER TABLE `{table}` RENAME COLUMN `{old}` TO `{new}`;"
+                cur.execute(sql)
+                print(f"Renamed `{table}`.`{old}` → `{new}`")
+
+    con.commit()
+    con.close()    
+
+def rename_columns_in_db_v1(db_path):
     with sqlite3.connect(db_path) as conn:
         cursor = conn.cursor()
         
@@ -5204,7 +5294,7 @@ def delete_intermedeate_files(settings):
     path_orig = os.path.join(settings['src'], 'orig')
     path_stack = os.path.join(settings['src'], 'stack')
     merged_stack = os.path.join(settings['src'], 'merged')
-    path_norm_chan_stack = os.path.join(settings['src'], 'norm_channel_stack')
+    path_norm_chan_stack = os.path.join(settings['src'], 'masks')
     path_1 = os.path.join(settings['src'], '1')
     path_2 = os.path.join(settings['src'], '2')
     path_3 = os.path.join(settings['src'], '3')
@@ -5491,3 +5581,37 @@ def correct_metadata(df):
         df = df.rename(columns={'field_name': 'fieldID'})
     
     return df
+
+def remove_outliers_by_group(df, group_col, value_col, method='iqr', threshold=1.5):
+    """
+    Removes outliers from `value_col` within each group defined by `group_col`.
+
+    Parameters:
+        df (pd.DataFrame): The input DataFrame.
+        group_col (str): Column name to group by.
+        value_col (str): Column containing values to check for outliers.
+        method (str): 'iqr' or 'zscore'.
+        threshold (float): Threshold multiplier for IQR (default 1.5) or z-score.
+
+    Returns:
+        pd.DataFrame: A DataFrame with outliers removed.
+    """
+    def iqr_filter(subdf):
+        q1 = subdf[value_col].quantile(0.25)
+        q3 = subdf[value_col].quantile(0.75)
+        iqr = q3 - q1
+        lower = q1 - threshold * iqr
+        upper = q3 + threshold * iqr
+        return subdf[(subdf[value_col] >= lower) & (subdf[value_col] <= upper)]
+
+    def zscore_filter(subdf):
+        mean = subdf[value_col].mean()
+        std = subdf[value_col].std()
+        return subdf[(subdf[value_col] - mean).abs() <= threshold * std]
+
+    if method == 'iqr':
+        return df.groupby(group_col, group_keys=False).apply(iqr_filter)
+    elif method == 'zscore':
+        return df.groupby(group_col, group_keys=False).apply(zscore_filter)
+    else:
+        raise ValueError("method must be 'iqr' or 'zscore'")