masster 0.5.1__py3-none-any.whl → 0.5.4__py3-none-any.whl

masster/study/merge.py

@@ -1,6 +1,6 @@
 """
 Unified merge module for the Study class.
-Supports multiple merge methods: 'kd', 'qt', 'kd-nowarp', 'kd_chunked', 'qt_chunked'
+Supports multiple merge methods: 'kd', 'qt', 'kd_chunked', 'qt_chunked'
 """
 
 import time
@@ -12,6 +12,7 @@ import pyopenms as oms
 import polars as pl
 from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor, as_completed
 from concurrent.futures.process import BrokenProcessPool
+from scipy.spatial import cKDTree
 from masster.study.defaults import merge_defaults
 
 
@@ -115,47 +116,6 @@ def _process_kd_chunk_parallel(chunk_data):
     return chunk_start_idx, consensus_features
 
 
-def _deserialize_consensus_features(consensus_features):
-    """
-    Deserialize consensus features back into an OpenMS ConsensusMap.
-    
-    Args:
-        consensus_features: List of serialized consensus feature dictionaries
-        
-    Returns:
-        OpenMS ConsensusMap object
-    """
-    import pyopenms as oms
-    
-    consensus_map = oms.ConsensusMap()
-    
-    for feature_data in consensus_features:
-        consensus_feature = oms.ConsensusFeature()
-        consensus_feature.setRT(float(feature_data['rt']))
-        consensus_feature.setMZ(float(feature_data['mz']))
-        consensus_feature.setIntensity(float(feature_data['intensity']))
-        consensus_feature.setQuality(float(feature_data['quality']))
-        consensus_feature.setUniqueId(int(feature_data['unique_id']))
-        
-        # Reconstruct feature handles (simplified approach)
-        feature_handles = []
-        for handle_data in feature_data['features']:
-            feature_handle = oms.FeatureHandle()
-            feature_handle.setUniqueId(int(handle_data['unique_id']))
-            feature_handle.setMapIndex(int(handle_data['map_index']))
-            feature_handles.append(feature_handle)
-        
-        # Set the feature list - properly add feature handles back to consensus feature
-        if feature_handles:
-            # Add each feature handle to the consensus feature using the correct OpenMS API
-            for feature_handle in feature_handles:
-                consensus_feature.getFeatureList().append(feature_handle)
-        
-        consensus_map.push_back(consensus_feature)
-    
-    return consensus_map
-
-
 def _process_qt_chunk_parallel(chunk_data):
     """
     Process a single QT chunk in parallel by reconstructing FeatureMaps from features_df slice.
@@ -222,7 +182,8 @@ def _process_qt_chunk_parallel(chunk_data):
     chunk_params.setValue("distance_MZ:unit", "Da")
     chunk_params.setValue("ignore_charge", "true")
     chunk_params.setValue("nr_partitions", params_dict['nr_partitions'])
-    
+   
+
     grouper.setParameters(chunk_params)
     grouper.group(chunk_maps, chunk_consensus_map)
     
@@ -251,29 +212,6 @@ def _process_qt_chunk_parallel(chunk_data):
     return chunk_start_idx, consensus_features
 
 
-def _serialize_feature_map(feature_map):
-    """
-    Serialize a FeatureMap to a list of dictionaries for multiprocessing.
-    
-    Args:
-        feature_map: OpenMS FeatureMap object
-        
-    Returns:
-        List of feature dictionaries
-    """
-    features_data = []
-    for feature in feature_map:
-        feature_data = {
-            'rt': feature.getRT(),
-            'mz': feature.getMZ(), 
-            'intensity': feature.getIntensity(),
-            'charge': feature.getCharge(),
-            'unique_id': feature.getUniqueId()
-        }
-        features_data.append(feature_data)
-    return features_data
-
-
 def merge(study, **kwargs) -> None:
     """
     Group features across samples into consensus features using various algorithms.
@@ -285,74 +223,155 @@ def merge(study, **kwargs) -> None:
     ----------
     **kwargs : dict
         Parameters from merge_defaults class:
-        - method : str, default 'quality'
-          Merge algorithm: 'sensitivity', 'qt', 'nowarp', 'kd_chunked', 'qt_chunked', 'quality'
-        - min_samples : int, default 10  
+        - method : str, default 'kd'
+          Merge algorithm: 'kd', 'qt', 'kd_chunked', 'qt_chunked'
+        - min_samples : int, default 2  
           Minimum number of samples for consensus feature
-        - rt_tol : float, default 2.0
+        - rt_tol : float, default 5.0
           RT tolerance in seconds
         - mz_tol : float, default 0.01
           m/z tolerance in Da (Daltons) for all methods
         - chunk_size : int, default 500
-          Chunk size for 'chunked' method
-        - threads : int, default 1
-          Number of parallel processes for chunked methods (kd_chunked, qt_chunked)
-        - nr_partitions : int, default 500
+          Chunk size for chunked methods
+        - dechunking : str, default 'hierarchical'
+          Cross-chunk merging algorithm: 'hierarchical', 'kdtree', 'qt', 'none'
+        - threads : int, default None
+          Number of parallel processes for chunked methods (None=sequential)
+        - nr_partitions : int, default 1000
           Number of partitions in m/z dimension for KD algorithms
-        - min_rel_cc_size : float, default 0.3
-          Minimum relative connected component size for conflict resolution
-        - max_pairwise_log_fc : float, default 0.5
-          Maximum pairwise log fold change for conflict resolution
+        - min_rel_cc_size : float, default 0.1
+          Minimum relative connected component size for conflict resolution (chunked only)
+        - max_pairwise_log_fc : float, default -1.0
+          Maximum pairwise log fold change for conflict resolution (chunked only)
         - max_nr_conflicts : int, default 0
-          Maximum number of conflicts allowed in consensus feature
+          Maximum number of conflicts allowed in consensus feature (chunked only)
         - link_ms2 : bool, default True
           Whether to link MS2 spectra to consensus features
-
-    Algorithm Guidelines
-    -------------------
-    - Quality: KD with post-processing quality control to reduce oversegmentation (RECOMMENDED DEFAULT)
-      Includes RT tolerance optimization, secondary clustering, and quality filtering
-    - Sensitivity: Best raw sensitivity, O(n log n), maximum feature detection
-    - QT: Thorough but slow O(n²), good for <1000 samples  
-    - NoWarp: Memory efficient KD without RT warping for large datasets
-    - KD-Chunked: Memory-optimized KD algorithm for very large datasets (>5000 samples)
-      Uses optimized partitioning for better memory management while maintaining
-      full cross-sample consensus feature detection. Supports parallel processing.
-    - QT-Chunked: Memory-optimized QT algorithm for very large datasets (>5000 samples)
-      Uses QT clustering in first stage with optimized cross-chunk consensus building.
-      Supports parallel processing.
+        - extract_ms1 : bool, default True
+          Whether to extract MS1 spectra for consensus features
+
+    Algorithm Selection Guide
+    ------------------------
+    Choose your merge method based on dataset size and performance requirements:
+
+    **KD (K-D Tree)** - *Recommended Default*
+        - Fast O(n log n) algorithm with RT warping
+        - Best balance of speed, accuracy, and memory usage
+        - Suitable for most dataset sizes (50 - 5,000 samples)
+        - Uses spatial partitioning for efficient feature matching
+
+    **QT (Quality Threshold)**
+        - Thorough O(n²) clustering algorithm  
+        - Most accurate but slowest method
+        - Recommended for small datasets (<1,000 samples)
+        - Guarantees quality threshold constraints
+
+    **KD-Chunked** - *For Large Datasets*
+        - Memory-optimized KD algorithm for very large datasets (>5,000 samples)
+        - Processes data in chunks with cross-chunk consensus building
+        - Supports parallel processing with threads parameter
+        - Maintains high feature recovery through hierarchical dechunking
+
+    **QT-Chunked** - *For Large Datasets with Maximum Accuracy*
+        - Memory-optimized QT algorithm for very large datasets (>5,000 samples)
+        - Uses QT clustering within chunks, then cross-chunk consensus
+        - Slowest but most thorough for large datasets
+        - Best when accuracy is more important than speed
+
+    Cross-Chunk Merging (Dechunking) Methods
+    ----------------------------------------
+    For chunked methods, choose dechunking algorithm based on your priorities:
+
+    **Hierarchical** - *Recommended Default*
+        - Priority-based merging starting from high sample count features
+        - Achieves ~97% feature recovery vs original ~10% recovery
+        - Best overall balance of recovery and accuracy
+
+    **KDTree** - *High Sample Feature Preservation*
+        - Spatial indexing approach optimized for frequent features
+        - ~95% high sample count feature recovery
+        - Best for preserving features present in many samples
+
+    Performance Guidelines
+    ---------------------
+    - **Small datasets (≤1,000 samples)**: Use 'qt' for maximum accuracy
+    - **Medium datasets (1,000-5,000 samples)**: Use 'kd' (default)
+    - **Large datasets (>5,000 samples)**: Use 'kd_chunked' or 'qt_chunked'
+    - **Memory constrained**: Use chunked methods with smaller chunk_size
+    - **Time constrained**: Use 'kd' or 'kd_chunked' with hierarchical dechunking
 
     Parallel Processing
     ------------------
-    For kd_chunked and qt_chunked methods, use threads > 1 to enable parallel processing
-    of chunk alignments. This can significantly reduce processing time for large datasets
-    by processing multiple chunks simultaneously in separate processes.
-    
-    Example:
-        study.merge(method='kd_chunked', threads=4, chunk_size=200)
+    Chunked methods support parallel processing:
+    - Set threads=N (where N is number of CPU cores to use)
+    - Recommended: threads=4 to 8 for most systems
+    - Each chunk is processed independently in parallel
+    - Significantly reduces processing time for large datasets
+
+    Tolerance Settings
+    -----------------
+    - **rt_tol**: RT tolerance in seconds (typical range: 1-10s)
+      - Smaller values: more specific, may fragment features
+      - Larger values: more permissive, may merge distinct features
+    - **mz_tol**: m/z tolerance in Daltons (typical range: 0.005-0.05 Da)
+      - High-resolution MS: 0.005-0.01 Da
+      - Lower resolution MS: 0.01-0.05 Da
+
+    Examples
+    --------
+    Basic usage with default KD algorithm:
+        study.merge()
+
+    High-accuracy small dataset:
+        study.merge(method='qt', rt_tol=2.0, mz_tol=0.005, min_samples=5)
+
+    Large dataset with parallel processing:
+        study.merge(method='kd_chunked', threads=8, chunk_size=500, 
+                   dechunking='hierarchical')
+
+    Custom tolerances for specific instrument:
+        study.merge(method='kd', rt_tol=1.5, mz_tol=0.01, min_samples=10)
+
+    Notes
+    -----
+    - Features must be loaded before merging (study.load_features())
+    - Results are stored in study.consensus_df and study.consensus_mapping_df
+    - Merge parameters are saved to study history for reproducibility
+    - MS2 spectra are automatically linked when link_ms2=True
+    - Adduct relationships are identified and stored after merging
     """
     start_time = time.time()
     
     # Initialize with defaults and override with kwargs
-    params = merge_defaults()
-    
-    # Filter and apply only valid parameters
-    valid_params = set(params.list_parameters())
+    params = merge_defaults()    
+    
+    # Handle 'params' keyword argument specifically (like merge does)
+    if 'params' in kwargs:
+        provided_params = kwargs.pop('params')
+        if isinstance(provided_params, merge_defaults):
+            params = provided_params
+            study.logger.debug("Using provided merge_defaults parameters from 'params' argument")
+        else:
+            study.logger.warning("'params' argument is not an merge_defaults instance, ignoring")
+
+    # Process remaining kwargs
     for key, value in kwargs.items():
-        if key in valid_params:
-            setattr(params, key, value)
+        if isinstance(value, merge_defaults):
+            params = value
+            study.logger.debug("Using provided merge_defaults parameters")
         else:
-            study.logger.warning(f"Unknown parameter '{key}' ignored")
-    
+            if hasattr(params, key):
+                if params.set(key, value, validate=True):
+                    study.logger.debug(f"Updated parameter {key} = {value}")
+                else:
+                    study.logger.warning(
+                        f"Failed to set parameter {key} = {value} (validation failed)",
+                    )
+            else:
+                study.logger.warning(f"Unknown parameter '{key}' ignored")
+
     # Backward compatibility: Map old method names to new names
     method_mapping = {
-        'kd': 'sensitivity',
-        'kd-nowarp': 'nowarp', 
-        'kd_nowarp': 'nowarp',
-        'kd-strict': 'quality',
-        'kd_strict': 'quality',
-        'kdstrict': 'quality',
-        'chunked': 'kd_chunked',  # Map old 'chunked' to 'kd_chunked'
         'qtchunked': 'qt_chunked',  # QT chunked variants
         'qt-chunked': 'qt_chunked',
         'kdchunked': 'kd_chunked',  # KD chunked variants 
@@ -365,18 +384,28 @@ def merge(study, **kwargs) -> None:
         study.logger.info(f"Method '{old_method}' is deprecated. Using '{params.method}' instead.")
     
     # Validate method
-    if params.method not in ['sensitivity', 'qt', 'nowarp', 'kd_chunked', 'qt_chunked', 'quality']:
-        raise ValueError(f"Invalid method '{params.method}'. Must be one of: ['sensitivity', 'qt', 'nowarp', 'kd_chunked', 'qt_chunked', 'quality']")
-    
+    if params.method not in ['kd', 'qt', 'kd_chunked', 'qt_chunked']:
+        raise ValueError(f"Invalid method '{params.method}'. Must be one of: ['kd', 'qt', 'kd_chunked', 'qt_chunked']")
+   
     # Check if chunked method is advisable for large datasets
     num_samples = len(study.samples_df) if hasattr(study, 'samples_df') and study.samples_df is not None else 0
+    if num_samples == 0:
+        raise ValueError("No samples loaded in study. Load features before merging.")
+    if params.method == 'kd' and num_samples > params.chunk_size:
+        params.method = 'kd_chunked'
+        study.logger.info(
+            f"Switching to chunked method for large dataset ({num_samples} samples > chunk_size {params.chunk_size})"
+        )
+    if params.method == 'qt' and num_samples > params.chunk_size:
+        params.method = 'qt_chunked'
+        study.logger.info(
+            f"Switching to chunked method for large dataset ({num_samples} samples > chunk_size {params.chunk_size})"
+        )
+
     if num_samples > 500:
-        chunked_methods = {'kd_chunked', 'qt_chunked'}
-        if params.method not in chunked_methods:
+        if params.method not in {'kd_chunked', 'qt_chunked'}:
             study.logger.warning(
-                f"Large dataset detected ({num_samples} samples > 500). "
-                f"For better performance and memory efficiency, consider using a chunked method: "
-                f"'kd_chunked' or 'qt_chunked' instead of '{params.method}'"
+                f"Large dataset detected ({num_samples} samples > 500). Consider dropping chunk_size to 500 to use chunked methods."
             )
     
     # Persist last used params for diagnostics
@@ -403,8 +432,10 @@ def merge(study, **kwargs) -> None:
         f"Merge: {params.method}, samples={params.min_samples}, rt_tol={params.rt_tol}s, mz_tol={params.mz_tol}Da"
     )
     
-    # Initialize
-    _reset_consensus_data(study)
+    # Initialize    
+    study.consensus_df = pl.DataFrame()
+    study.consensus_ms2 = pl.DataFrame()
+    study.consensus_mapping_df = pl.DataFrame()
 
     # Cache adducts for performance (avoid repeated _get_adducts() calls)
     cached_adducts_df = None
@@ -424,7 +455,7 @@ def merge(study, **kwargs) -> None:
     cached_valid_adducts.add("?")
     
     # Route to algorithm implementation  
-    if params.method == 'sensitivity':
+    if params.method == 'kd':
         consensus_map = _merge_kd(study, params)
         # Extract consensus features
         _extract_consensus_features(study, consensus_map, params.min_samples, cached_adducts_df, cached_valid_adducts)
@@ -432,13 +463,6 @@ def merge(study, **kwargs) -> None:
         consensus_map = _merge_qt(study, params)
         # Extract consensus features
         _extract_consensus_features(study, consensus_map, params.min_samples, cached_adducts_df, cached_valid_adducts)
-    elif params.method == 'nowarp':
-        consensus_map = _merge_kd_nowarp(study, params)
-        # Extract consensus features
-        _extract_consensus_features(study, consensus_map, params.min_samples, cached_adducts_df, cached_valid_adducts)
-    elif params.method == 'quality':
-        consensus_map = _merge_kd_strict(study, params)
-        # Note: _merge_kd_strict handles both consensus_df and consensus_mapping_df directly
     elif params.method == 'kd_chunked':
         consensus_map = _merge_kd_chunked(study, params, cached_adducts_df, cached_valid_adducts)
         # Note: _merge_kd_chunked populates consensus_df directly, no need to extract
@@ -446,19 +470,23 @@ def merge(study, **kwargs) -> None:
         consensus_map = _merge_qt_chunked(study, params, cached_adducts_df, cached_valid_adducts)
         # Note: _merge_qt_chunked populates consensus_df directly, no need to extract
     
-    # Enhanced post-clustering to merge over-segmented features (for qt and kd methods)
-    if params.method in ['qt', 'sensitivity', 'qt_chunked', 'kd_chunked', 'quality']:
-        _consensus_cleanup(study, params.rt_tol, params.mz_tol)
+    # Enhanced post-clustering to merge over-segmented features (for non-chunked methods)
+    # Chunked methods already perform their own cross-chunk consensus building
+    if params.method in ['qt', 'kd']:
+        __consensus_cleanup(study, params.rt_tol, params.mz_tol)
     
     # Perform adduct grouping
     _perform_adduct_grouping(study, params.rt_tol, params.mz_tol)
     
     # Identify coeluting consensus features by mass shifts and update adduct information
-    _identify_adduct_by_mass_shift(study, params.rt_tol, cached_adducts_df)
+    __identify_adduct_by_mass_shift(study, params.rt_tol, cached_adducts_df)
+    
+    # Post-processing for chunked methods: merge partial consensus features
+    if params.method in ['qt_chunked', 'kd_chunked']:
+        _merge_partial_consensus_features(study, params.rt_tol, params.mz_tol)
     
-    # Link MS2 if requested
-    if params.link_ms2:
-        _finalize_merge(study, params.link_ms2, params.min_samples)
+    # Finalize merge: filter by min_samples and add isotope/MS2 data
+    __finalize_merge(study, params.link_ms2, params.extract_ms1, params.min_samples)
     
     # Log completion without the misleading feature count
     elapsed = time.time() - start_time
@@ -494,10 +522,6 @@ def _merge_kd(study, params: merge_defaults) -> oms.ConsensusMap:
     params_oms.setValue("warp:mz_tol", params.mz_tol)
     params_oms.setValue("link:rt_tol", params.rt_tol)
     params_oms.setValue("link:mz_tol", params.mz_tol)
-    #params_oms.setValue("link:min_rel_cc_size", params.min_rel_cc_size)
-    #params_oms.setValue("link:max_pairwise_log_fc", params.max_pairwise_log_fc)
-    #params_oms.setValue("link:max_nr_conflicts", params.max_nr_conflicts)
-    #params_oms.setValue("link:charge_merging", "With_charge_zero") THIS LEADS TO A CRASH
     
     grouper.setParameters(params_oms)
     grouper.group(temp_feature_maps, consensus_map)
@@ -505,92 +529,6 @@ def _merge_kd(study, params: merge_defaults) -> oms.ConsensusMap:
     return consensus_map
 
 
-def _generate_feature_maps_from_samples(study):
-    """
-    Generate feature maps using Study-level features_df instead of Sample-level loading.
-    This uses the study's existing features_df which is already loaded.
-    
-    Args:
-        study: Study object containing features_df
-    
-    Returns:
-        list: List of temporary FeatureMap objects built from Study-level data
-    """
-    import pyopenms as oms
-    
-    temp_feature_maps = []
-    
-    study.logger.info(f"Building feature maps using Study-level features_df from {len(study.samples_df)} samples")
-    
-    # Use the features_df from the study that's already loaded
-    if not hasattr(study, 'features_df') or study.features_df is None or study.features_df.is_empty():
-        study.logger.warning("No features_df available - features must be loaded first")
-        return temp_feature_maps
-    
-    # Group features by sample
-    study.logger.info(f"Processing {len(study.features_df)} features grouped by sample")
-    
-    # Get unique sample names/indices
-    if 'sample_uid' in study.features_df.columns:
-        sample_groups = study.features_df.group_by('sample_uid')
-        study.logger.debug("Grouping features by 'sample_uid' column")
-    elif 'sample_id' in study.features_df.columns:
-        sample_groups = study.features_df.group_by('sample_id')
-        study.logger.debug("Grouping features by 'sample_id' column")
-    elif 'sample' in study.features_df.columns:
-        sample_groups = study.features_df.group_by('sample')
-        study.logger.debug("Grouping features by 'sample' column")
-    else:
-        study.logger.warning("No sample grouping column found in features_df")
-        study.logger.info(f"Available columns: {study.features_df.columns}")
-        return temp_feature_maps
-    
-    # Process each sample group
-    processed_samples = 0
-    for sample_key, sample_features in sample_groups:
-        try:
-            feature_map = oms.FeatureMap()
-            feature_count = 0
-            
-            # Build features from this sample's features
-            for row in sample_features.iter_rows(named=True):
-                try:
-                    feature = oms.Feature()
-                    
-                    # Set feature properties
-                    if row.get("feature_id") is not None:
-                        feature.setUniqueId(int(row["feature_id"]))
-                    if row.get("mz") is not None:
-                        feature.setMZ(float(row["mz"]))
-                    if row.get("rt") is not None:
-                        feature.setRT(float(row["rt"]))
-                    if row.get("inty") is not None:
-                        feature.setIntensity(float(row["inty"]))
-                    if row.get("quality") is not None:
-                        feature.setOverallQuality(float(row["quality"]))
-                    if row.get("charge") is not None:
-                        feature.setCharge(int(row["charge"]))
-                    
-                    feature_map.push_back(feature)
-                    feature_count += 1
-                    
-                except (ValueError, TypeError) as e:
-                    study.logger.warning(f"Skipping feature in sample {sample_key} due to conversion error: {e}")
-                    continue
-            
-            temp_feature_maps.append(feature_map)
-            processed_samples += 1
-            study.logger.debug(f"Built feature map for sample {sample_key} with {feature_count} features")
-            
-        except Exception as e:
-            study.logger.warning(f"Failed to process sample group {sample_key}: {e}")
-            # Add empty feature map for failed samples to maintain sample order
-            temp_feature_maps.append(oms.FeatureMap())
-    
-    study.logger.info(f"Generated {len(temp_feature_maps)} feature maps from {processed_samples} samples using Study-level features_df")
-    return temp_feature_maps
-
-
 def _generate_feature_maps_on_demand(study):
     """
     Generate feature maps on-demand using Sample-level _load_ms1() for merge operations.
@@ -610,9 +548,9 @@ def _generate_feature_maps_on_demand(study):
     use_sample_loading = True  # Default to Sample-level loading as requested
     
     # Use Sample-level loading if requested and samples_df is available
-    if use_sample_loading and hasattr(study, 'samples_df') and study.samples_df is not None and len(study.samples_df) > 0:
-        study.logger.debug("Building feature maps using Sample-level _load_ms1() instead of features_df")
-        return _generate_feature_maps_from_samples(study)
+    #if use_sample_loading and hasattr(study, 'samples_df') and study.samples_df is not None and len(study.samples_df) > 0:
+    #    study.logger.debug("Building feature maps using Sample-level _load_ms1() instead of features_df")
+    #    return _generate_feature_maps_from_samples(study)
     
     # Fallback to original features_df approach
     if study.features_df is None or len(study.features_df) == 0:
@@ -750,9 +688,6 @@ def _merge_qt(study, params: merge_defaults) -> oms.ConsensusMap:
     params_oms.setValue("distance_MZ:max_difference", params.mz_tol)
     params_oms.setValue("distance_MZ:unit", "Da")  # QT now uses Da like all other methods
     params_oms.setValue("ignore_charge", "true")
-    #params_oms.setValue("min_rel_cc_size", params.min_rel_cc_size)
-    #params_oms.setValue("max_pairwise_log_fc", params.max_pairwise_log_fc)
-    #params_oms.setValue("max_nr_conflicts", params.max_nr_conflicts)
     params_oms.setValue("nr_partitions", params.nr_partitions)
 
     grouper.setParameters(params_oms)
@@ -761,534 +696,6 @@ def _merge_qt(study, params: merge_defaults) -> oms.ConsensusMap:
     return consensus_map
 
 
-def _merge_kd_strict(study, params: merge_defaults) -> oms.ConsensusMap:
-    """
-    Quality merge: Standard KD algorithm with post-processing quality control.
-    
-    This method combines the sensitivity of KD clustering with post-processing steps
-    to reduce oversegmentation while maintaining high-quality consensus features.
-    This is the recommended default method.
-    
-    Post-processing features:
-    1. RT tolerance optimization (optional)
-    2. Secondary clustering for close features
-    3. Sample overlap validation
-    4. RT spread quality filtering
-    5. Chromatographic coherence validation
-    
-    Additional parameters supported in params:
-    - optimize_rt_tol: bool - Enable RT tolerance optimization
-    - rt_tol_range: tuple - RT tolerance range for optimization (min, max)
-    - secondary_merge_rt_tol: float - Secondary merge RT tolerance (default: 0.5s)
-    - secondary_merge_mz_tol: float - Secondary merge m/z tolerance (default: 0.005)
-    - min_sample_overlap: float - Minimum sample overlap for merging (0.0-1.0, default: 0.8)
-    - max_rt_spread: float - Maximum RT spread allowed (default: 2x rt_tol)
-    - min_coherence: float - Minimum chromatographic coherence (default: 0.0, disabled)
-    """
-    
-    # Check for RT tolerance optimization
-    optimize_rt_tol = getattr(params, 'optimize_rt_tol', False)
-    
-    if optimize_rt_tol:
-        # Optimize RT tolerance first
-        optimal_rt_tol = _optimize_rt_tolerance(study, params)
-        study.logger.info(f"RT tolerance optimization: {params.rt_tol}s → {optimal_rt_tol}s")
-        # Create modified params with optimal RT tolerance
-        import copy
-        optimized_params = copy.deepcopy(params)
-        optimized_params.rt_tol = optimal_rt_tol
-    else:
-        optimized_params = params
-    
-    # Phase 1: Standard KD clustering
-    study.logger.debug("Initial KD clustering")
-    consensus_map = _merge_kd(study, optimized_params)
-    
-    # Phase 2: Post-processing quality control
-    study.logger.debug("Post-processing quality control")
-    consensus_map = _apply_kd_strict_postprocessing(study, consensus_map, optimized_params)
-    
-    return consensus_map
-
-
-def _optimize_rt_tolerance(study, params: merge_defaults) -> float:
-    """
-    Optimize RT tolerance by testing different values and measuring oversegmentation.
-    
-    Args:
-        study: Study object
-        params: Merge parameters
-        
-    Returns:
-        Optimal RT tolerance value
-    """
-    rt_tol_range = getattr(params, 'rt_tol_range', (0.8, 2.0))
-    rt_tol_steps = getattr(params, 'rt_tol_steps', 5)
-    
-    study.logger.info(f"Optimizing RT tolerance in range {rt_tol_range} with {rt_tol_steps} steps")
-    
-    # Generate test values
-    test_rt_tols = [rt_tol_range[0] + i * (rt_tol_range[1] - rt_tol_range[0]) / (rt_tol_steps - 1) 
-                    for i in range(rt_tol_steps)]
-    
-    best_rt_tol = params.rt_tol
-    best_score = float('inf')
-    
-    # Store original features for restoration
-    original_consensus_df = getattr(study, 'consensus_df', pl.DataFrame())
-    original_consensus_mapping_df = getattr(study, 'consensus_mapping_df', pl.DataFrame())
-    
-    for test_rt_tol in test_rt_tols:
-        try:
-            # Create test parameters
-            import copy
-            test_params = copy.deepcopy(params)
-            test_params.rt_tol = test_rt_tol
-            
-            # Run KD merge with test parameters
-            test_consensus_map = _merge_kd(study, test_params)
-            
-            # Extract consensus features temporarily for analysis
-            _extract_consensus_features(study, test_consensus_map, test_params.min_samples)
-            
-            if len(study.consensus_df) == 0:
-                continue
-            
-            # Calculate oversegmentation metrics
-            oversegmentation_score = _calculate_oversegmentation_score(study, test_rt_tol)
-            
-            study.logger.debug(f"RT tol {test_rt_tol:.1f}s: {len(study.consensus_df)} features, score: {oversegmentation_score:.3f}")
-            
-            # Lower score is better (less oversegmentation)
-            if oversegmentation_score < best_score:
-                best_score = oversegmentation_score
-                best_rt_tol = test_rt_tol
-                
-        except Exception as e:
-            study.logger.warning(f"RT tolerance optimization failed for {test_rt_tol}s: {e}")
-            continue
-    
-    # Restore original consensus data
-    study.consensus_df = original_consensus_df
-    study.consensus_mapping_df = original_consensus_mapping_df
-    
-    study.logger.info(f"Optimal RT tolerance: {best_rt_tol:.1f}s (score: {best_score:.3f})")
-    return best_rt_tol
-
-
-def _calculate_oversegmentation_score(study, rt_tol: float) -> float:
-    """
-    Calculate oversegmentation score based on feature density and RT spread metrics.
-    Lower scores indicate less oversegmentation.
-    
-    Args:
-        study: Study object
-        rt_tol: RT tolerance used
-        
-    Returns:
-        Oversegmentation score (lower = better)
-    """
-    if len(study.consensus_df) == 0:
-        return float('inf')
-    
-    # Metric 1: Feature density (features per RT second)
-    rt_range = study.consensus_df['rt'].max() - study.consensus_df['rt'].min()
-    if rt_range <= 0:
-        return float('inf')
-    
-    feature_density = len(study.consensus_df) / rt_range
-    
-    # Metric 2: Average RT spread relative to tolerance
-    rt_spreads = (study.consensus_df['rt_max'] - study.consensus_df['rt_min'])
-    avg_rt_spread_ratio = rt_spreads.mean() / rt_tol if rt_tol > 0 else float('inf')
-    
-    # Metric 3: Proportion of features with low sample counts (indicates fragmentation)
-    low_sample_features = len(study.consensus_df.filter(pl.col('number_samples') <= 5))
-    low_sample_ratio = low_sample_features / len(study.consensus_df)
-    
-    # Metric 4: Number of features with excessive RT spread
-    excessive_spread_features = len(rt_spreads.filter(rt_spreads > rt_tol * 2))
-    excessive_spread_ratio = excessive_spread_features / len(study.consensus_df)
-    
-    # Combined score (weighted combination)
-    oversegmentation_score = (
-        0.4 * (feature_density / 10.0) +  # Normalize to reasonable scale
-        0.3 * avg_rt_spread_ratio +
-        0.2 * low_sample_ratio +
-        0.1 * excessive_spread_ratio
-    )
-    
-    return oversegmentation_score
-
-
-def _apply_kd_strict_postprocessing(study, consensus_map: oms.ConsensusMap, params: merge_defaults) -> oms.ConsensusMap:
-    """
-    Apply post-processing quality control to KD consensus map.
-    
-    Args:
-        consensus_map: Initial consensus map from KD
-        params: Merge parameters with kd-strict options
-        
-    Returns:
-        Processed consensus map with reduced oversegmentation
-    """
-    if consensus_map.size() == 0:
-        study.logger.warning("Empty consensus map provided to post-processing")
-        return consensus_map
-    
-    study.logger.debug(f"Post-processing {consensus_map.size()} initial consensus features")
-    
-    # Step 1: Extract initial consensus features
-    original_min_samples = params.min_samples
-    params.min_samples = 1  # Extract all features initially
-    
-    _extract_consensus_features(study, consensus_map, params.min_samples)
-    initial_feature_count = len(study.consensus_df)
-    
-    if initial_feature_count == 0:
-        study.logger.warning("No consensus features extracted for post-processing")
-        params.min_samples = original_min_samples
-        return consensus_map
-    
-    # Step 2: Secondary clustering for close features
-    secondary_merge_rt_tol = getattr(params, 'secondary_merge_rt_tol', 0.5)
-    secondary_merge_mz_tol = getattr(params, 'secondary_merge_mz_tol', 0.005)
-    
-    study.logger.debug(f"Secondary clustering with RT≤{secondary_merge_rt_tol}s, m/z≤{secondary_merge_mz_tol}")
-    merged_features = _perform_secondary_clustering(study, secondary_merge_rt_tol, secondary_merge_mz_tol)
-    
-    # Step 3: Sample overlap validation
-    min_sample_overlap = getattr(params, 'min_sample_overlap', 0.8)
-    if min_sample_overlap > 0:
-        study.logger.debug(f"Sample overlap validation (threshold: {min_sample_overlap})")
-        merged_features = _validate_sample_overlap(study, merged_features, min_sample_overlap)
-    
-    # Step 4: RT spread quality filtering
-    if params.rt_tol is not None:
-        max_rt_spread = getattr(params, 'max_rt_spread', params.rt_tol * 2)
-        if max_rt_spread is not None:
-            study.logger.debug(f"RT spread filtering (max: {max_rt_spread:.1f}s)")
-            merged_features = _filter_rt_spread(study, merged_features, max_rt_spread)
-        else:
-            study.logger.debug("Skipping RT spread filtering - max_rt_spread is None")
-    else:
-        study.logger.debug("Skipping RT spread filtering - rt_tol is None")
-    
-    # Step 5: Chromatographic coherence filtering (optional)
-    min_coherence = getattr(params, 'min_coherence', 0.0)
-    if min_coherence > 0:
-        study.logger.debug(f"Chromatographic coherence filtering (min: {min_coherence})")
-        merged_features = _filter_coherence(study, merged_features, min_coherence)
-    
-    # Step 6: Rebuild consensus_df with filtered features and preserve mapping
-    original_mapping_df = study.consensus_mapping_df.clone()  # Save original mapping
-    study.consensus_df = pl.DataFrame(merged_features, strict=False)
-    
-    # Step 7: Apply original min_samples filter
-    params.min_samples = original_min_samples
-    if params.min_samples > 1:
-        l1 = len(study.consensus_df)
-        study.consensus_df = study.consensus_df.filter(
-            pl.col("number_samples") >= params.min_samples
-        )
-        filtered_count = l1 - len(study.consensus_df)
-        if filtered_count > 0:
-            study.logger.debug(f"Filtered {filtered_count} features below min_samples threshold ({params.min_samples})")
-    
-    # Step 8: Update consensus_mapping_df to match final consensus_df
-    if len(study.consensus_df) > 0 and len(original_mapping_df) > 0:
-        valid_consensus_ids = set(study.consensus_df['consensus_uid'].to_list())
-        study.consensus_mapping_df = original_mapping_df.filter(
-            pl.col('consensus_uid').is_in(list(valid_consensus_ids))
-        )
-    else:
-        study.consensus_mapping_df = pl.DataFrame()
-    
-    final_feature_count = len(study.consensus_df)
-    reduction_pct = ((initial_feature_count - final_feature_count) / initial_feature_count * 100) if initial_feature_count > 0 else 0
-    
-    study.logger.info(f"Consensus cleanup complete: {initial_feature_count} → {final_feature_count} features ({reduction_pct:.1f}% reduction)")
-    
-    # Create a new consensus map for compatibility (the processed data is in consensus_df)
-    processed_consensus_map = oms.ConsensusMap()
-    return processed_consensus_map
-
-
-def _perform_secondary_clustering(study, rt_tol: float, mz_tol: float) -> list:
-    """
-    Perform secondary clustering to merge very close features.
-    
-    Args:
-        rt_tol: RT tolerance for secondary clustering
-        mz_tol: m/z tolerance for secondary clustering
-        
-    Returns:
-        List of merged consensus feature dictionaries
-    """
-    if len(study.consensus_df) == 0:
-        return []
-    
-    # Convert consensus_df to list of dictionaries for clustering
-    consensus_features = []
-    for i, row in enumerate(study.consensus_df.iter_rows(named=True)):
-        consensus_features.append(dict(row))
-    
-    # Use Union-Find for efficient clustering
-    class UnionFind:
-        def __init__(study, n):
-            study.parent = list(range(n))
-            study.rank = [0] * n
-        
-        def find(study, x):
-            if study.parent[x] != x:
-                study.parent[x] = study.find(study.parent[x])
-            return study.parent[x]
-        
-        def union(study, x, y):
-            px, py = study.find(x), study.find(y)
-            if px == py:
-                return
-            if study.rank[px] < study.rank[py]:
-                px, py = py, px
-            study.parent[py] = px
-            if study.rank[px] == study.rank[py]:
-                study.rank[px] += 1
-    
-    n_features = len(consensus_features)
-    uf = UnionFind(n_features)
-    
-    # Find features to merge based on proximity
-    merge_count = 0
-    for i in range(n_features):
-        for j in range(i + 1, n_features):
-            feat_i = consensus_features[i]
-            feat_j = consensus_features[j]
-            
-            rt_diff = abs(feat_i['rt'] - feat_j['rt'])
-            mz_diff = abs(feat_i['mz'] - feat_j['mz'])
-            
-            if rt_diff <= rt_tol and mz_diff <= mz_tol:
-                uf.union(i, j)
-                merge_count += 1
-    
-    # Group features by their root
-    groups_by_root = defaultdict(list)
-    for i in range(n_features):
-        root = uf.find(i)
-        groups_by_root[root].append(consensus_features[i])
-    
-    # Merge features within each group
-    merged_features = []
-    for group in groups_by_root.values():
-        if len(group) == 1:
-            # Single feature - keep as is
-            merged_features.append(group[0])
-        else:
-            # Multiple features - merge them
-            merged_feature = _merge_feature_group(group)
-            merged_features.append(merged_feature)
-    
-    study.logger.debug(f"Secondary clustering: {n_features} → {len(merged_features)} features ({n_features - len(merged_features)} merged)")
-    return merged_features
-
-
-def _merge_feature_group(feature_group: list) -> dict:
-    """
-    Merge a group of similar consensus features into one.
-    
-    Args:
-        feature_group: List of consensus feature dictionaries to merge
-        
-    Returns:
-        Merged consensus feature dictionary
-    """
-    if not feature_group:
-        return {}
-    
-    if len(feature_group) == 1:
-        return feature_group[0]
-    
-    # Use the feature with highest sample count as base
-    base_feature = max(feature_group, key=lambda f: f.get('number_samples', 0))
-    merged = base_feature.copy()
-    
-    # Aggregate numeric statistics
-    rt_values = [f['rt'] for f in feature_group if f.get('rt') is not None]
-    mz_values = [f['mz'] for f in feature_group if f.get('mz') is not None]
-    sample_counts = [f.get('number_samples', 0) for f in feature_group]
-    intensities = [f.get('inty_mean', 0) for f in feature_group if f.get('inty_mean') is not None]
-    
-    # Update merged feature statistics
-    if rt_values:
-        merged['rt'] = float(np.mean(rt_values))
-        merged['rt_min'] = min([f.get('rt_min', f['rt']) for f in feature_group])
-        merged['rt_max'] = max([f.get('rt_max', f['rt']) for f in feature_group])
-        merged['rt_mean'] = float(np.mean(rt_values))
-    
-    if mz_values:
-        merged['mz'] = float(np.mean(mz_values))
-        merged['mz_min'] = min([f.get('mz_min', f['mz']) for f in feature_group])
-        merged['mz_max'] = max([f.get('mz_max', f['mz']) for f in feature_group])
-        merged['mz_mean'] = float(np.mean(mz_values))
-    
-    # Use maximum sample count (features might be detected in overlapping but different samples)
-    merged['number_samples'] = max(sample_counts)
-    
-    # Use weighted average intensity (by sample count)
-    if intensities and sample_counts:
-        total_weight = sum(sample_counts)
-        if total_weight > 0:
-            weighted_intensity = sum(inty * count for inty, count in zip(intensities, sample_counts)) / total_weight
-            merged['inty_mean'] = float(weighted_intensity)
-    
-    # Aggregate chromatographic quality metrics if available
-    coherence_values = [f.get('chrom_coherence_mean', 0) for f in feature_group if f.get('chrom_coherence_mean') is not None]
-    prominence_values = [f.get('chrom_prominence_mean', 0) for f in feature_group if f.get('chrom_prominence_mean') is not None]
-    
-    if coherence_values:
-        merged['chrom_coherence_mean'] = float(np.mean(coherence_values))
-    if prominence_values:
-        merged['chrom_prominence_mean'] = float(np.mean(prominence_values))
-    
-    # Merge MS2 counts
-    ms2_counts = [f.get('number_ms2', 0) for f in feature_group]
-    merged['number_ms2'] = sum(ms2_counts)
-    
-    # Keep the best quality score
-    quality_scores = [f.get('quality', 1.0) for f in feature_group if f.get('quality') is not None]
-    if quality_scores:
-        merged['quality'] = max(quality_scores)
-    
-    return merged
-
-
-def _validate_sample_overlap(study, features: list, min_overlap: float) -> list:
-    """
-    Validate that merged features have sufficient sample overlap.
-    
-    Args:
-        features: List of consensus feature dictionaries
-        min_overlap: Minimum sample overlap ratio (0.0-1.0)
-        
-    Returns:
-        List of validated features
-    """
-    # This is a placeholder for sample overlap validation
-    # Implementation would require access to which samples each feature appears in
-    # For now, we'll use a simple heuristic based on feature statistics
-    
-    validated_features = []
-    for feature in features:
-        # Simple validation based on RT spread and sample count ratio
-        rt_spread = feature.get('rt_max', feature['rt']) - feature.get('rt_min', feature['rt'])
-        sample_count = feature.get('number_samples', 1)
-        
-        # Features with very tight RT spread and high sample counts are more reliable
-        if rt_spread <= 2.0 or sample_count >= 10:  # More permissive validation
-            validated_features.append(feature)
-        else:
-            # Could implement more sophisticated sample overlap checking here
-            validated_features.append(feature)  # Keep for now
-    
-    return validated_features
-
-
-def _filter_rt_spread(study, features: list, max_rt_spread: float) -> list:
-    """
-    Filter out features with excessive RT spread.
-    
-    Args:
-        features: List of consensus feature dictionaries
-        max_rt_spread: Maximum allowed RT spread in seconds
-        
-    Returns:
-        List of filtered features
-    """
-    filtered_features = []
-    filtered_count = 0
-    
-    for feature in features:
-        rt_min = feature.get('rt_min', feature['rt'])
-        rt_max = feature.get('rt_max', feature['rt'])
-        rt_spread = rt_max - rt_min
-        
-        if rt_spread <= max_rt_spread:
-            filtered_features.append(feature)
-        else:
-            filtered_count += 1
-    
-    if filtered_count > 0:
-        study.logger.debug(f"Filtered {filtered_count} features with excessive RT spread (>{max_rt_spread:.1f}s)")
-    
-    return filtered_features
-
-
-def _filter_coherence(study, features: list, min_coherence: float) -> list:
-    """
-    Filter out features with low chromatographic coherence.
-    
-    Args:
-        features: List of consensus feature dictionaries
-        min_coherence: Minimum chromatographic coherence score
-        
-    Returns:
-        List of filtered features
-    """
-    filtered_features = []
-    filtered_count = 0
-    
-    for feature in features:
-        coherence = feature.get('chrom_coherence_mean', 1.0)  # Default to high coherence if missing
-        
-        if coherence >= min_coherence:
-            filtered_features.append(feature)
-        else:
-            filtered_count += 1
-    
-    if filtered_count > 0:
-        study.logger.debug(f"Filtered {filtered_count} features with low coherence (<{min_coherence})")
-    
-    return filtered_features
-
-
-def _merge_kd_nowarp(study, params: merge_defaults) -> oms.ConsensusMap:
-    """KD-tree based merge without RT warping"""
-    
-    # Generate temporary feature maps on-demand from features_df
-    temp_feature_maps = _generate_feature_maps_on_demand(study)
-    
-    consensus_map = oms.ConsensusMap()
-    file_descriptions = consensus_map.getColumnHeaders()
-    
-    for i, feature_map in enumerate(temp_feature_maps):
-        file_description = file_descriptions.get(i, oms.ColumnHeader())
-        file_description.filename = study.samples_df.row(i, named=True)["sample_name"]
-        file_description.size = feature_map.size()
-        file_description.unique_id = feature_map.getUniqueId()
-        file_descriptions[i] = file_description
-    
-    consensus_map.setColumnHeaders(file_descriptions)
-    
-    # Configure KD algorithm with warping disabled for memory efficiency
-    grouper = oms.FeatureGroupingAlgorithmKD()
-    params_oms = grouper.getParameters()
-    
-    params_oms.setValue("mz_unit", "Da")
-    params_oms.setValue("nr_partitions", params.nr_partitions)
-    params_oms.setValue("warp:enabled", "false")  # Disabled for memory efficiency
-    params_oms.setValue("link:rt_tol", params.rt_tol)
-    params_oms.setValue("link:mz_tol", params.mz_tol)
-    params_oms.setValue("link:min_rel_cc_size", params.min_rel_cc_size)
-    params_oms.setValue("link:max_pairwise_log_fc", params.max_pairwise_log_fc)
-    params_oms.setValue("link:max_nr_conflicts", params.max_nr_conflicts)
-    #params_oms.setValue("link:charge_merging", "Any")
-    
-    grouper.setParameters(params_oms)
-    grouper.group(temp_feature_maps, consensus_map)
-    
-    return consensus_map
-
-
 def _merge_kd_chunked(study, params: merge_defaults, cached_adducts_df=None, cached_valid_adducts=None) -> oms.ConsensusMap:
     """KD-based chunked merge with proper cross-chunk consensus building and optional parallel processing"""
     
@@ -1462,7 +869,7 @@ def _merge_kd_chunked(study, params: merge_defaults, cached_adducts_df=None, cac
     
     # Merge chunk results with proper cross-chunk consensus building  
     # _merge_chunk_results now handles both ConsensusMap objects (sequential) and serialized data (parallel)
-    _merge_chunk_results(study, chunk_consensus_maps, params, cached_adducts_df, cached_valid_adducts)
+    _dechunk_results(study, chunk_consensus_maps, params, cached_adducts_df, cached_valid_adducts)
     
     # Return a dummy consensus map for compatibility (consensus features are stored in study.consensus_df)
     consensus_map = oms.ConsensusMap()
@@ -1637,14 +1044,14 @@ def _merge_qt_chunked(study, params: merge_defaults, cached_adducts_df=None, cac
     
     # Merge chunk results with proper cross-chunk consensus building  
     # _merge_chunk_results now handles both ConsensusMap objects (sequential) and serialized data (parallel)
-    _merge_chunk_results(study, chunk_consensus_maps, params, cached_adducts_df, cached_valid_adducts)
+    _dechunk_results(study, chunk_consensus_maps, params, cached_adducts_df, cached_valid_adducts)
     
     # Return a dummy consensus map for compatibility (consensus features are stored in study.consensus_df)
     consensus_map = oms.ConsensusMap()
     return consensus_map
 
 
-def _merge_chunk_results(study, chunk_consensus_maps: list, params: merge_defaults, cached_adducts_df=None, cached_valid_adducts=None) -> None:
+def _dechunk_results(study, chunk_consensus_maps: list, params: merge_defaults, cached_adducts_df=None, cached_valid_adducts=None) -> None:
     """
     Scalable aggregation of chunk consensus maps into final consensus_df.
     
@@ -1672,7 +1079,7 @@ def _merge_chunk_results(study, chunk_consensus_maps: list, params: merge_defaul
         for row in study.features_df.iter_rows(named=True)
     }
     
-    features_lookup = _optimized_feature_lookup(study, study.features_df)
+    features_lookup = __merge_feature_lookup(study, study.features_df)
     
     # Extract all consensus features from chunks with their feature_uids
     all_chunk_consensus = []
@@ -1705,7 +1112,10 @@ def _merge_chunk_results(study, chunk_consensus_maps: list, params: merge_defaul
                     if feature_data:
                         feature_uids.append(feature_uid)
                         feature_data_list.append(feature_data)
-                        sample_uids.append(chunk_start_idx + feature_handle.getMapIndex() + 1)
+                        
+                        # Use feature_uid to lookup actual sample_uid instead of chunk position
+                        actual_sample_uid = feature_data['sample_uid']
+                        sample_uids.append(actual_sample_uid)
 
                 if not feature_data_list:
                     # No retrievable feature metadata (possible stale map reference) -> skip
@@ -1725,13 +1135,6 @@ def _merge_chunk_results(study, chunk_consensus_maps: list, params: merge_defaul
         
         # Process the consensus features (now all in serialized format)
         for consensus_feature_data in consensus_features_data:
-            # ACCEPT ALL consensus features (size >=1) here.
-            # Reason: A feature that is globally present in many samples can still
-            # appear only once inside a given sample chunk. Early filtering at
-            # size>=2 causes irreversible loss and underestimates the final
-            # consensus count (observed ~296 vs 950 for KD). We defer filtering
-            # strictly to the final global min_samples.
-            
             # For parallel processing, feature data is already extracted
             if isinstance(chunk_data, list):
                 # Extract feature_uids and data from serialized format for parallel processing
@@ -1749,11 +1152,14 @@ def _merge_chunk_results(study, chunk_consensus_maps: list, params: merge_defaul
                     if feature_data:
                         feature_uids.append(feature_uid)
                         feature_data_list.append(feature_data)
-                        sample_uids.append(chunk_start_idx + handle_data['map_index'] + 1)
+                        
+                        # Use feature_uid to lookup actual sample_uid instead of chunk position
+                        actual_sample_uid = feature_data['sample_uid']
+                        sample_uids.append(actual_sample_uid)
                 
                 if not feature_data_list:
                     continue
-                    
+                
                 # Get RT/MZ from consensus feature data
                 consensus_rt = consensus_feature_data['rt']
                 consensus_mz = consensus_feature_data['mz']
@@ -1818,163 +1224,301 @@ def _merge_chunk_results(study, chunk_consensus_maps: list, params: merge_defaul
         study.consensus_mapping_df = pl.DataFrame()
         return
     
-    # Perform cross-chunk clustering using optimized spatial indexing
-    def _cluster_chunk_consensus(chunk_consensus_list: list, rt_tol: float, mz_tol: float) -> list:
-        """Cluster chunk consensus features using interval overlap (no over-relaxation).
-
-        A union is formed if either centroids are within tolerance OR their RT / m/z
-        intervals (expanded by tolerance) overlap, and they originate from different chunks.
+    # CROSS-CHUNK DECHUNKING ALGORITHMS
+    # Multiple algorithms available for combining chunk results
+    
+    class HierarchicalAnchorMerger:
+        """
+        Hierarchical Anchor Merger: Comprehensive cross-chunk feature preservation.
+        Uses Union-Find clustering for transitive matching across multiple chunks.
         """
-        if not chunk_consensus_list:
-            return []
-
-        n_features = len(chunk_consensus_list)
-
-        # Spatial bins using strict tolerances (improves candidate reduction without recall loss)
-        rt_bin_size = rt_tol if rt_tol > 0 else 1.0
-        mz_bin_size = mz_tol if mz_tol > 0 else 0.01
-        features_by_bin = defaultdict(list)
-
-        for i, cf in enumerate(chunk_consensus_list):
-            rt_bin = int(cf['rt'] / rt_bin_size)
-            mz_bin = int(cf['mz'] / mz_bin_size)
-            features_by_bin[(rt_bin, mz_bin)].append(i)
-
-        class UF:
-            def __init__(study, n):
-                study.p = list(range(n))
-                study.r = [0]*n
-            def find(study, x):
-                if study.p[x] != x:
-                    study.p[x] = study.find(study.p[x])
-                return study.p[x]
-            def union(study, a,b):
-                pa, pb = study.find(a), study.find(b)
-                if pa == pb:
-                    return
-                if study.r[pa] < study.r[pb]:
-                    pa, pb = pb, pa
-                study.p[pb] = pa
-                if study.r[pa] == study.r[pb]:
-                    study.r[pa] += 1
-
-        uf = UF(n_features)
-        checked = set()
-        for (rtb, mzb), idxs in features_by_bin.items():
-            for dr in (-1,0,1):
-                for dm in (-1,0,1):
-                    neigh = (rtb+dr, mzb+dm)
-                    if neigh not in features_by_bin:
+        def __init__(self, rt_tol: float, mz_tol: float):
+            self.rt_tol = rt_tol
+            self.mz_tol = mz_tol
+            
+        def merge(self, chunk_consensus_list: list) -> list:
+            """Fixed hierarchical merging with union-find clustering for complete feature preservation"""
+            if not chunk_consensus_list:
+                return []
+            
+            study.logger.debug(f"FIXED HierarchicalAnchorMerger: processing {len(chunk_consensus_list)} chunk features")
+            
+            # Union-Find data structure for transitive clustering
+            class UnionFind:
+                def __init__(self, n):
+                    self.parent = list(range(n))
+                    self.rank = [0] * n
+                    
+                def find(self, x):
+                    if self.parent[x] != x:
+                        self.parent[x] = self.find(self.parent[x])  # Path compression
+                    return self.parent[x]
+                    
+                def union(self, x, y):
+                    px, py = self.find(x), self.find(y)
+                    if px == py:
+                        return False  # Already in same component
+                    # Union by rank for balanced trees
+                    if self.rank[px] < self.rank[py]:
+                        px, py = py, px
+                    self.parent[py] = px
+                    if self.rank[px] == self.rank[py]:
+                        self.rank[px] += 1
+                    return True  # Union was performed
+            
+            n_features = len(chunk_consensus_list)
+            uf = UnionFind(n_features)
+            merges_made = 0
+            
+            # Optimized cross-chunk feature matching using KD-tree spatial indexing
+            
+            # Proper dimensional scaling for RT vs m/z
+            rt_scale = 1.0    # RT in seconds (1-30 min range)
+            mz_scale = 100.0  # m/z in Da (100-1000 range) - scale to match RT magnitude
+            
+            # Build spatial index with scaled coordinates
+            points = np.array([[f['rt'] * rt_scale, f['mz'] * mz_scale] for f in chunk_consensus_list])
+            tree = cKDTree(points, balanced_tree=True, compact_nodes=True)
+            
+            # Calculate proper Euclidean radius in scaled space
+            scaled_rt_tol = self.rt_tol * rt_scale
+            scaled_mz_tol = self.mz_tol * mz_scale  
+            radius = np.sqrt(scaled_rt_tol**2 + scaled_mz_tol**2)
+            
+            # Efficient neighbor search for feature matching
+            for i in range(n_features):
+                feature_i = chunk_consensus_list[i]
+                chunk_i = feature_i.get('chunk_idx', -1)
+                
+                # Query spatial index for nearby features
+                neighbor_indices = tree.query_ball_point(points[i], r=radius, p=2)
+                
+                for j in neighbor_indices:
+                    if i >= j:  # Skip duplicates and self
                         continue
-                    for i in idxs:
-                        for j in features_by_bin[neigh]:
-                            if i >= j:
-                                continue
-                            pair = (i,j)
-                            if pair in checked:
-                                continue
-                            checked.add(pair)
-                            a = chunk_consensus_list[i]
-                            b = chunk_consensus_list[j]
-                            if a['chunk_idx'] == b['chunk_idx']:
-                                continue
-                            
-                            # Primary check: centroid distance (strict)
-                            centroid_close = (abs(a['rt']-b['rt']) <= rt_tol and abs(a['mz']-b['mz']) <= mz_tol)
-                            
-                            # Secondary check: interval overlap (more conservative)
-                            # Only allow interval overlap if centroids are reasonably close (within 2x tolerance)
-                            centroids_reasonable = (abs(a['rt']-b['rt']) <= 2 * rt_tol and abs(a['mz']-b['mz']) <= 2 * mz_tol)
-                            if centroids_reasonable:
-                                rt_overlap = (a['rt_min'] - rt_tol/2) <= (b['rt_max'] + rt_tol/2) and (b['rt_min'] - rt_tol/2) <= (a['rt_max'] + rt_tol/2)
-                                mz_overlap = (a['mz_min'] - mz_tol/2) <= (b['mz_max'] + mz_tol/2) and (b['mz_min'] - mz_tol/2) <= (a['mz_max'] + mz_tol/2)
-                            else:
-                                rt_overlap = mz_overlap = False
-                            
-                            if centroid_close or (rt_overlap and mz_overlap):
-                                uf.union(i,j)
-
-        groups_by_root = defaultdict(list)
-        for i in range(n_features):
-            groups_by_root[uf.find(i)].append(chunk_consensus_list[i])
-        return list(groups_by_root.values())
-    # (Obsolete relaxed + centroid stitching code removed.)
-
-    # --- Stage 1: initial cross-chunk clustering of chunk consensus features ---
-    initial_groups = _cluster_chunk_consensus(all_chunk_consensus, params.rt_tol, params.mz_tol)
-
-    # --- Stage 2: centroid refinement (lightweight second pass) ---
-    def _refine_groups(groups: list, rt_tol: float, mz_tol: float) -> list:
-        """Refine groups by clustering group centroids (single-link) under same tolerances.
-
-        This reconciles borderline splits left after interval-overlap clustering without
-        re-introducing broad over-merging. Works on group centroids only (low cost).
+                        
+                    feature_j = chunk_consensus_list[j]
+                    chunk_j = feature_j.get('chunk_idx', -1)
+                    
+                    # Skip features from same chunk (already clustered within chunk)
+                    if chunk_i == chunk_j:
+                        continue
+                    
+                    # Verify with precise original tolerances (more accurate than scaled)
+                    rt_diff = abs(feature_i['rt'] - feature_j['rt'])
+                    mz_diff = abs(feature_i['mz'] - feature_j['mz'])
+                    
+                    if rt_diff <= self.rt_tol and mz_diff <= self.mz_tol:
+                        if uf.union(i, j):  # Merge if not already connected
+                            merges_made += 1
+            
+            study.logger.debug(f"FIXED HierarchicalAnchorMerger: made {merges_made} cross-chunk merges")
+            
+            # Group features by their connected component
+            clusters = {}
+            for i in range(n_features):
+                root = uf.find(i)
+                if root not in clusters:
+                    clusters[root] = []
+                clusters[root].append(chunk_consensus_list[i])
+            
+            # Merge each cluster into a single consensus feature
+            result = []
+            for cluster_features in clusters.values():
+                merged = self._merge_cluster(cluster_features)
+                result.append(merged)
+            
+            study.logger.debug(f"FIXED HierarchicalAnchorMerger: output {len(result)} merged features (from {n_features} inputs)")
+            
+            # VERIFICATION: Ensure we haven't lost features
+            if len(result) > len(chunk_consensus_list):
+                study.logger.warning(f"FIXED HierarchicalAnchorMerger: More outputs than inputs ({len(result)} > {n_features})")
+            
+            return result
+            
+        def _merge_cluster(self, cluster: list) -> dict:
+            """Merge cluster using sample-weighted consensus with robust error handling"""
+            if len(cluster) == 1:
+                return cluster[0]  # No merging needed for single feature
+                
+            # Calculate weights robustly to prevent division by zero
+            weights = []
+            for c in cluster:
+                sample_count = c.get('sample_count', 0)
+                # Use minimum weight of 1 to prevent zero weights
+                weights.append(max(sample_count, 1))
+            
+            total_weight = sum(weights)
+            # Fallback for edge cases
+            if total_weight == 0:
+                total_weight = len(cluster)
+                weights = [1] * len(cluster)
+            
+            # Weighted consensus for RT/mz coordinates
+            merged = {
+                'consensus_id': cluster[0]['consensus_id'],  # Use first feature's ID
+                'chunk_indices': [c.get('chunk_idx', 0) for c in cluster],
+                'mz': sum(c['mz'] * w for c, w in zip(cluster, weights)) / total_weight,
+                'rt': sum(c['rt'] * w for c, w in zip(cluster, weights)) / total_weight,
+                'intensity': sum(c.get('intensity', 0) for c in cluster),
+                'quality': sum(c.get('quality', 1) * w for c, w in zip(cluster, weights)) / total_weight,
+                'feature_uids': [],
+                'feature_data_list': [],
+                'sample_uids': [],
+                'sample_count': 0
+            }
+            
+            # Aggregate all features and samples from all chunks
+            all_feature_uids = []
+            all_feature_data = []
+            all_sample_uids = []
+            
+            for chunk in cluster:
+                # Collect feature UIDs
+                chunk_feature_uids = chunk.get('feature_uids', [])
+                all_feature_uids.extend(chunk_feature_uids)
+                
+                # Collect feature data
+                chunk_feature_data = chunk.get('feature_data_list', [])
+                all_feature_data.extend(chunk_feature_data)
+                
+                # Collect sample UIDs
+                chunk_sample_uids = chunk.get('sample_uids', [])
+                all_sample_uids.extend(chunk_sample_uids)
+            
+            # Remove duplicates properly and count unique samples
+            merged['feature_uids'] = list(set(all_feature_uids))
+            merged['feature_data_list'] = all_feature_data  # Keep all feature data
+            merged['sample_uids'] = list(set(all_sample_uids))  # Unique sample UIDs only
+            merged['sample_count'] = len(merged['sample_uids'])  # Count of unique samples
+            
+            return merged
+    
+    class KDTreeSpatialMerger:
         """
-        if len(groups) <= 1:
-            return groups
-        # Build centroid list
-        centroids = []  # (idx, rt, mz)
-        for gi, g in enumerate(groups):
-            if not g:
-                continue
-            rt_vals = [cf['rt'] for cf in g]
-            mz_vals = [cf['mz'] for cf in g]
-            if not rt_vals or not mz_vals:
-                continue
-            centroids.append((gi, float(np.mean(rt_vals)), float(np.mean(mz_vals))))
-        if len(centroids) <= 1:
-            return groups
-
-        # Spatial binning for centroid clustering
-        rt_bin = rt_tol if rt_tol > 0 else 1.0
-        mz_bin = mz_tol if mz_tol > 0 else 0.01
-        bins = defaultdict(list)
-        for idx, rt_c, mz_c in centroids:
-            bins[(int(rt_c/rt_bin), int(mz_c/mz_bin))].append((idx, rt_c, mz_c))
-
-        # Union-Find over group indices
-        parent = list(range(len(groups)))
-        rank = [0]*len(groups)
-        def find(x):
-            if parent[x] != x:
-                parent[x] = find(parent[x])
-            return parent[x]
-        def union(a,b):
-            pa, pb = find(a), find(b)
-            if pa == pb:
-                return
-            if rank[pa] < rank[pb]:
-                pa, pb = pb, pa
-            parent[pb] = pa
-            if rank[pa] == rank[pb]:
-                rank[pa] += 1
-
-        checked = set()
-        for (rb, mb), items in bins.items():
-            for dr in (-1,0,1):
-                for dm in (-1,0,1):
-                    neigh_key = (rb+dr, mb+dm)
-                    if neigh_key not in bins:
+        KD-Tree Spatial Merger: Optimized for high-sample features.
+        """
+        def __init__(self, rt_tol: float, mz_tol: float):
+            self.rt_tol = rt_tol
+            self.mz_tol = mz_tol
+            
+        def merge(self, chunk_consensus_list: list) -> list:
+            """KD-tree based spatial merging"""
+            if not chunk_consensus_list:
+                return []
+                
+            try:
+                from scipy.spatial import cKDTree
+                import numpy as np
+            except ImportError:
+                # Fallback to simple clustering if scipy not available
+                return self._fallback_merge(chunk_consensus_list)
+                
+            # Build spatial index
+            points = np.array([[c['rt'], c['mz']] for c in chunk_consensus_list])
+            tree = cKDTree(points)
+            
+            # Scale tolerances for KD-tree query
+            rt_scale = 1.0 / self.rt_tol if self.rt_tol > 0 else 1.0
+            mz_scale = 1.0 / self.mz_tol if self.mz_tol > 0 else 1.0
+            scaled_points = points * np.array([rt_scale, mz_scale])
+            scaled_tree = cKDTree(scaled_points)
+            
+            clusters = []
+            used = set()
+            
+            # Priority processing for high-sample features
+            high_sample_indices = [i for i, c in enumerate(chunk_consensus_list) if c['sample_count'] >= 100]
+            remaining_indices = [i for i in range(len(chunk_consensus_list)) if i not in high_sample_indices]
+            
+            for idx in high_sample_indices + remaining_indices:
+                if idx in used:
+                    continue
+                    
+                # Find neighbors in scaled space
+                neighbors = scaled_tree.query_ball_point(scaled_points[idx], r=1.0)
+                cluster_indices = [i for i in neighbors if i not in used and i != idx]
+                cluster_indices.append(idx)
+                
+                if cluster_indices:
+                    cluster = [chunk_consensus_list[i] for i in cluster_indices]
+                    clusters.append(self._merge_cluster(cluster))
+                    used.update(cluster_indices)
+                    
+            return clusters
+            
+        def _fallback_merge(self, chunk_consensus_list: list) -> list:
+            """Simple distance-based fallback when scipy unavailable"""
+            clusters = []
+            used = set()
+            
+            for i, anchor in enumerate(chunk_consensus_list):
+                if i in used:
+                    continue
+                    
+                cluster = [anchor]
+                used.add(i)
+                
+                for j, candidate in enumerate(chunk_consensus_list):
+                    if j in used or j == i:
                         continue
-                    for (gi, rt_i, mz_i) in items:
-                        for (gj, rt_j, mz_j) in bins[neigh_key]:
-                            if gi >= gj:
-                                continue
-                            pair = (gi, gj)
-                            if pair in checked:
-                                continue
-                            checked.add(pair)
-                            if abs(rt_i-rt_j) <= rt_tol and abs(mz_i-mz_j) <= mz_tol:
-                                union(gi, gj)
-
-        merged = defaultdict(list)
-        for gi, g in enumerate(groups):
-            merged[find(gi)].extend(g)
-        return list(merged.values())
-
-    refined_groups = _refine_groups(initial_groups, params.rt_tol, params.mz_tol)
-
-    # --- Stage 3: build final consensus feature metadata and mapping ---
+                        
+                    rt_diff = abs(candidate['rt'] - anchor['rt'])
+                    mz_diff = abs(candidate['mz'] - anchor['mz'])
+                    
+                    if rt_diff <= self.rt_tol and mz_diff <= self.mz_tol:
+                        cluster.append(candidate)
+                        used.add(j)
+                
+                clusters.append(self._merge_cluster(cluster))
+                
+            return clusters
+            
+        def _merge_cluster(self, cluster: list) -> dict:
+            """Merge cluster with intensity-weighted consensus"""
+            if len(cluster) == 1:
+                return cluster[0]
+                
+            # Weight by intensity for spatial accuracy
+            total_intensity = sum(c['intensity'] for c in cluster)
+            
+            merged = {
+                'consensus_id': cluster[0]['consensus_id'],
+                'chunk_indices': [c['chunk_idx'] for c in cluster],
+                'mz': sum(c['mz'] * c['intensity'] for c in cluster) / total_intensity,
+                'rt': sum(c['rt'] * c['intensity'] for c in cluster) / total_intensity,
+                'intensity': total_intensity,
+                'quality': sum(c['quality'] for c in cluster) / len(cluster),
+                'feature_uids': [],
+                'feature_data_list': [],
+                'sample_uids': [],
+                'sample_count': 0
+            }
+            
+            # Aggregate features
+            for chunk in cluster:
+                merged['feature_uids'].extend(chunk['feature_uids'])
+                merged['feature_data_list'].extend(chunk['feature_data_list'])
+                merged['sample_uids'].extend(chunk['sample_uids'])
+                
+            merged['feature_uids'] = list(set(merged['feature_uids']))
+            merged['sample_count'] = len(set(merged['sample_uids']))
+            
+            return merged
+    # SELECT DECHUNKING ALGORITHM BASED ON PARAMETER
+    if params.dechunking == "hierarchical":
+        merger = HierarchicalAnchorMerger(params.rt_tol, params.mz_tol)
+        final_consensus = merger.merge(all_chunk_consensus)
+    elif params.dechunking == "kdtree":
+        merger = KDTreeSpatialMerger(params.rt_tol, params.mz_tol)
+        final_consensus = merger.merge(all_chunk_consensus)
+    else:
+        raise ValueError(f"Invalid dechunking method '{params.dechunking}'. Must be one of: ['hierarchical', 'kdtree']")
+
+    # --- Stage 1: Cross-chunk clustering using selected dechunking algorithm ---
+    # New algorithms return final consensus features, no further refinement needed
+    # Convert each merged consensus feature to a "group" of one feature for compatibility
+    refined_groups = [[feature] for feature in final_consensus]
     consensus_metadata = []
     consensus_mapping_list = []
     consensus_uid_counter = 0
@@ -2011,7 +1555,6 @@ def _merge_chunk_results(study, chunk_consensus_maps: list, params: merge_defaul
 
         number_samples = len(sample_uids_acc)
         
-        # NOTE: Don't filter by min_samples here - let _finalize_merge handle it
         # This allows proper cross-chunk consensus building before final filtering
 
         metadata = _calculate_consensus_statistics(
@@ -2028,13 +1571,29 @@ def _merge_chunk_results(study, chunk_consensus_maps: list, params: merge_defaul
             cached_valid_adducts=cached_valid_adducts,
         )
         
-        # Validate RT spread doesn't exceed tolerance (with some flexibility for chunked merge)
+        # Validate RT and m/z spread don't exceed tolerance limits
         rt_spread = metadata.get('rt_max', 0) - metadata.get('rt_min', 0)
-        max_allowed_spread = params.rt_tol * 2  # Allow 2x tolerance for chunked method
+        mz_spread = metadata.get('mz_max', 0) - metadata.get('mz_min', 0)
+        max_allowed_rt_spread = params.rt_tol * 2  # Allow 2x tolerance for chunked method
+        max_allowed_mz_spread = params.mz_tol * 2  # Enforce strict m/z spread limit
+        
+        skip_feature = False
+        skip_reason = ""
         
-        if rt_spread > max_allowed_spread:
-            # Skip consensus features with excessive RT spread
-            study.logger.debug(f"Skipping consensus feature {consensus_uid_counter} with RT spread {rt_spread:.3f}s > {max_allowed_spread:.3f}s")
+        if rt_spread > max_allowed_rt_spread:
+            skip_feature = True
+            skip_reason = f"RT spread {rt_spread:.3f}s > {max_allowed_rt_spread:.3f}s"
+            
+        if mz_spread > max_allowed_mz_spread:
+            skip_feature = True
+            if skip_reason:
+                skip_reason += f" AND m/z spread {mz_spread:.4f} Da > {max_allowed_mz_spread:.4f} Da"
+            else:
+                skip_reason = f"m/z spread {mz_spread:.4f} Da > {max_allowed_mz_spread:.4f} Da"
+        
+        if skip_feature:
+            # Skip consensus features with excessive spread
+            study.logger.debug(f"Skipping consensus feature {consensus_uid_counter}: {skip_reason}")
             consensus_uid_counter += 1
             continue
             
@@ -2043,6 +1602,7 @@ def _merge_chunk_results(study, chunk_consensus_maps: list, params: merge_defaul
         # Build mapping rows (deduplicated)
         for fid, fd in feature_data_acc.items():
             samp_uid = fd.get('sample_uid') or fd.get('sample_id') or fd.get('sample')
+                                 
             # If absent we attempt to derive from original group sample_uids pairing
             # but most feature_data rows should include sample_uid already.
             if samp_uid is None:
@@ -2238,80 +1798,6 @@ def _calculate_consensus_statistics(study_obj, consensus_uid: int, feature_data_
     }
 
 
-def _cluster_consensus_features(features: list, rt_tol: float, mz_tol: float) -> list:
-    """
-    Cluster consensus features from different chunks based on RT and m/z similarity.
-    
-    Args:
-        features: List of feature dictionaries with 'mz', 'rt', 'id' keys
-        rt_tol: RT tolerance in seconds
-        mz_tol: m/z tolerance in Da
-        
-    Returns:
-        List of groups, where each group is a list of feature dictionaries
-    """
-    if not features:
-        return []
-    
-    # Use Union-Find for efficient clustering
-    class UnionFind:
-        def __init__(study, n):
-            study.parent = list(range(n))
-            study.rank = [0] * n
-        
-        def find(study, x):
-            if study.parent[x] != x:
-                study.parent[x] = study.find(study.parent[x])
-            return study.parent[x]
-        
-        def union(study, x, y):
-            px, py = study.find(x), study.find(y)
-            if px == py:
-                return
-            if study.rank[px] < study.rank[py]:
-                px, py = py, px
-            study.parent[py] = px
-            if study.rank[px] == study.rank[py]:
-                study.rank[px] += 1
-    
-    n_features = len(features)
-    uf = UnionFind(n_features)
-    
-    # Build distance matrix and cluster features within tolerance
-    for i in range(n_features):
-        for j in range(i + 1, n_features):
-            feat_i = features[i]
-            feat_j = features[j]
-            
-            # Skip if features are from the same chunk (they're already processed)
-            if feat_i['chunk_idx'] == feat_j['chunk_idx']:
-                continue
-            
-            mz_diff = abs(feat_i['mz'] - feat_j['mz'])
-            rt_diff = abs(feat_i['rt'] - feat_j['rt'])
-            
-            # Cluster if within tolerance
-            if mz_diff <= mz_tol and rt_diff <= rt_tol:
-                uf.union(i, j)
-    
-    # Extract groups
-    groups_by_root = {}
-    for i in range(n_features):
-        root = uf.find(i)
-        if root not in groups_by_root:
-            groups_by_root[root] = []
-        groups_by_root[root].append(features[i])
-    
-    return list(groups_by_root.values())
-
-
-def _reset_consensus_data(study):
-    """Reset consensus-related DataFrames at the start of merge."""
-    study.consensus_df = pl.DataFrame()
-    study.consensus_ms2 = pl.DataFrame()
-    study.consensus_mapping_df = pl.DataFrame()
-
-
 def _extract_consensus_features(study, consensus_map, min_samples, cached_adducts_df=None, cached_valid_adducts=None):
     """Extract consensus features and build metadata."""
     # create a dict to map uid to feature_uid using study.features_df
@@ -2324,7 +1810,7 @@ def _extract_consensus_features(study, consensus_map, min_samples, cached_adduct
     study.logger.debug(f"Found {imax} feature groups by clustering.")
 
     # Pre-build fast lookup tables for features_df data using optimized approach
-    features_lookup = _optimized_feature_lookup(study, study.features_df)
+    features_lookup = __merge_feature_lookup(study, study.features_df)
 
     # create a list to store the consensus mapping
     consensus_mapping = []
@@ -2752,7 +2238,11 @@ def _extract_consensus_features(study, consensus_map, min_samples, cached_adduct
         pl.col("consensus_uid").is_in(study.consensus_df["consensus_uid"].to_list()),
     )
 
-    study.consensus_map = consensus_map
+    # Log final counts
+    study.logger.info(
+        f"Extracted {len(study.consensus_df)} consensus features with "
+        f"at least {min_samples} samples."
+    )
 
 
 def _perform_adduct_grouping(study, rt_tol, mz_tol):
@@ -2775,7 +2265,7 @@ def _perform_adduct_grouping(study, rt_tol, mz_tol):
             )
 
         # Use optimized adduct grouping
-        adduct_group_list, adduct_of_list = _optimized_adduct_grouping(
+        adduct_group_list, adduct_of_list = __merge_adduct_grouping(
             study, consensus_data, rt_tol, mz_tol
         )
 
@@ -2802,70 +2292,186 @@ def _count_tight_clusters(study, mz_tol: float = 0.04, rt_tol: float = 0.3) -> i
     if len(study.consensus_df) < 2:
         return 0
     
-    # Extract consensus feature data
-    consensus_data = []
-    for row in study.consensus_df.iter_rows(named=True):
-        consensus_data.append({
-            'consensus_uid': row['consensus_uid'],
-            'mz': row['mz'], 
-            'rt': row['rt']
-        })
-    
-    # Build spatial index using bins
-    rt_bin_size = rt_tol / 2
-    mz_bin_size = mz_tol / 2
-    
-    bins = defaultdict(list)
-    for feature in consensus_data:
-        rt_bin = int(feature['rt'] / rt_bin_size)
-        mz_bin = int(feature['mz'] / mz_bin_size)
-        bins[(rt_bin, mz_bin)].append(feature)
+    # Extract consensus feature coordinates efficiently
+    feature_coords = study.consensus_df.select([
+        pl.col("consensus_uid"),
+        pl.col("mz"),
+        pl.col("rt")
+    ]).to_numpy()
     
-    processed_features = set()
+    n_features = len(feature_coords)
+    processed = [False] * n_features
     tight_clusters_count = 0
     
-    for bin_key, bin_features in bins.items():
-        if len(bin_features) < 2:
+    # Use vectorized distance calculations for efficiency
+    for i in range(n_features):
+        if processed[i]:
             continue
             
-        # Check neighboring bins for additional features
-        rt_bin, mz_bin = bin_key
-        all_nearby_features = list(bin_features)
-        
-        # Check 8 neighboring bins
-        for drt in [-1, 0, 1]:
-            for dmz in [-1, 0, 1]:
-                if drt == 0 and dmz == 0:
-                    continue
-                neighbor_key = (rt_bin + drt, mz_bin + dmz)
-                if neighbor_key in bins:
-                    all_nearby_features.extend(bins[neighbor_key])
+        # Find all features within tolerance of feature i
+        cluster_members = [i]
+        rt_i, mz_i = feature_coords[i][2], feature_coords[i][1]
         
-        # Filter to features within actual tolerances and not yet processed
-        valid_cluster_features = []
-        for feature in all_nearby_features:
-            if feature['consensus_uid'] in processed_features:
+        for j in range(i + 1, n_features):
+            if processed[j]:
                 continue
                 
-            # Check if this feature is within tolerances of any bin feature
-            for bin_feature in bin_features:
-                rt_diff = abs(feature['rt'] - bin_feature['rt'])
-                mz_diff = abs(feature['mz'] - bin_feature['mz'])
-                
-                if rt_diff <= rt_tol and mz_diff <= mz_tol:
-                    valid_cluster_features.append(feature)
-                    break
+            rt_j, mz_j = feature_coords[j][2], feature_coords[j][1]
+            
+            if abs(rt_i - rt_j) <= rt_tol and abs(mz_i - mz_j) <= mz_tol:
+                cluster_members.append(j)
         
-        # Count as tight cluster if we have multiple features
-        if len(valid_cluster_features) >= 2:
+        # Mark cluster as tight if it has 2+ members
+        if len(cluster_members) >= 2:
             tight_clusters_count += 1
-            for feature in valid_cluster_features:
-                processed_features.add(feature['consensus_uid'])
+            for idx in cluster_members:
+                processed[idx] = True
     
     return tight_clusters_count
 
 
-def _consensus_cleanup(study, rt_tol, mz_tol):
+def _merge_partial_consensus_features(study, rt_tol, mz_tol):
+    """
+    Merge partial consensus features that likely represent the same compound but were
+    split across chunks. This is specifically for chunked methods.
+    """
+    if len(study.consensus_df) == 0:
+        return
+        
+    initial_count = len(study.consensus_df)
+    study.logger.debug(f"Post-processing chunked results: merging partial consensus features from {initial_count} features")
+    
+    # Convert to list of dictionaries for easier processing
+    consensus_features = []
+    for row in study.consensus_df.iter_rows(named=True):
+        consensus_features.append({
+            'consensus_uid': row['consensus_uid'],
+            'rt': row['rt'],
+            'mz': row['mz'],
+            'number_samples': row.get('number_samples', 0),
+            'inty_mean': row.get('inty_mean', 0.0)
+        })
+    
+    # Use Union-Find to group features that should be merged
+    class UnionFind:
+        def __init__(self, n):
+            self.parent = list(range(n))
+            
+        def find(self, x):
+            if self.parent[x] != x:
+                self.parent[x] = self.find(self.parent[x])
+            return self.parent[x]
+            
+        def union(self, x, y):
+            px, py = self.find(x), self.find(y)
+            if px != py:
+                self.parent[py] = px
+    
+    n_features = len(consensus_features)
+    uf = UnionFind(n_features)
+    
+    # Find features that should be merged using original tolerances
+    for i in range(n_features):
+        for j in range(i + 1, n_features):
+            feature_a = consensus_features[i]
+            feature_b = consensus_features[j]
+            
+            rt_diff = abs(feature_a['rt'] - feature_b['rt'])
+            mz_diff = abs(feature_a['mz'] - feature_b['mz'])
+            
+            # Merge if within tolerance
+            if rt_diff <= rt_tol and mz_diff <= mz_tol:
+                uf.union(i, j)
+    
+    # Group features by their root
+    groups = {}
+    for i, feature in enumerate(consensus_features):
+        root = uf.find(i)
+        if root not in groups:
+            groups[root] = []
+        groups[root].append(consensus_features[i])
+    
+    # Create merged features
+    merged_features = []
+    merged_mapping_data = []
+    uids_to_remove = set()
+    
+    for group in groups.values():
+        if len(group) < 2:
+            # Single feature, keep as is
+            continue
+        else:
+            # Multiple features, merge them
+            # Find best representative feature (highest sample count, then intensity)
+            best_feature = max(group, key=lambda x: (x['number_samples'], x['inty_mean']))
+            
+            # Calculate merged properties
+            total_samples = sum(f['number_samples'] for f in group)
+            weighted_rt = sum(f['rt'] * f['number_samples'] for f in group) / total_samples if total_samples > 0 else best_feature['rt']
+            weighted_mz = sum(f['mz'] * f['number_samples'] for f in group) / total_samples if total_samples > 0 else best_feature['mz']
+            mean_intensity = sum(f['inty_mean'] * f['number_samples'] for f in group) / total_samples if total_samples > 0 else best_feature['inty_mean']
+            
+            # Keep the best feature's UID but update its properties
+            merged_features.append({
+                'consensus_uid': best_feature['consensus_uid'],
+                'rt': weighted_rt,
+                'mz': weighted_mz,
+                'number_samples': total_samples,
+                'inty_mean': mean_intensity
+            })
+            
+            # Mark other features for removal
+            for f in group:
+                if f['consensus_uid'] != best_feature['consensus_uid']:
+                    uids_to_remove.add(f['consensus_uid'])
+    
+    if merged_features:
+        study.logger.debug(f"Merging {len(merged_features)} groups of partial consensus features")
+        
+        # Update consensus_df with merged features
+        for merged_feature in merged_features:
+            study.consensus_df = study.consensus_df.with_columns([
+                pl.when(pl.col('consensus_uid') == merged_feature['consensus_uid'])
+                .then(pl.lit(merged_feature['rt']))
+                .otherwise(pl.col('rt'))
+                .alias('rt'),
+                
+                pl.when(pl.col('consensus_uid') == merged_feature['consensus_uid'])
+                .then(pl.lit(merged_feature['mz']))
+                .otherwise(pl.col('mz'))
+                .alias('mz'),
+                
+                pl.when(pl.col('consensus_uid') == merged_feature['consensus_uid'])
+                .then(pl.lit(merged_feature['number_samples']))
+                .otherwise(pl.col('number_samples'))
+                .alias('number_samples'),
+                
+                pl.when(pl.col('consensus_uid') == merged_feature['consensus_uid'])
+                .then(pl.lit(merged_feature['inty_mean']))
+                .otherwise(pl.col('inty_mean'))
+                .alias('inty_mean')
+            ])
+        
+        # Remove duplicate features
+        if uids_to_remove:
+            study.consensus_df = study.consensus_df.filter(
+                ~pl.col('consensus_uid').is_in(list(uids_to_remove))
+            )
+            
+            # Also update consensus_mapping_df - reassign mappings from removed UIDs
+            if hasattr(study, 'consensus_mapping_df') and not study.consensus_mapping_df.is_empty():
+                study.consensus_mapping_df = study.consensus_mapping_df.with_columns(
+                    pl.when(pl.col('consensus_uid').is_in(list(uids_to_remove)))
+                    .then(pl.lit(None))  # Will be handled by subsequent operations
+                    .otherwise(pl.col('consensus_uid'))
+                    .alias('consensus_uid')
+                )
+        
+        final_count = len(study.consensus_df)
+        study.logger.debug(f"Partial consensus merging: {initial_count} → {final_count} features")
+
+
+def __consensus_cleanup(study, rt_tol, mz_tol):
     """
     Consensus cleanup to merge over-segmented consensus features and remove isotopic features.
     
@@ -3091,7 +2697,7 @@ def _consensus_cleanup(study, rt_tol, mz_tol):
         study.logger.debug(f"Consensus cleanup complete: {initial_count} → {final_count} features ({total_reduction_pct:.1f}% total reduction)")
 
 
-def _identify_adduct_by_mass_shift(study, rt_tol, cached_adducts_df=None):
+def __identify_adduct_by_mass_shift(study, rt_tol, cached_adducts_df=None):
     """
     Identify coeluting consensus features by characteristic mass shifts between adducts
     and update their adduct information accordingly.
@@ -3378,7 +2984,7 @@ def _identify_adduct_by_mass_shift(study, rt_tol, cached_adducts_df=None):
         study.logger.debug("No consensus features updated based on mass shift analysis")
 
 
-def _finalize_merge(study, link_ms2, min_samples):
+def __finalize_merge(study, link_ms2, extract_ms1, min_samples):
     """Complete the merge process with final calculations and cleanup."""
     import polars as pl
     
@@ -3438,12 +3044,13 @@ def _finalize_merge(study, link_ms2, min_samples):
         )
 
     # add iso data from raw files.
-    study.find_iso()
     if link_ms2:
         study.find_ms2()
+    if extract_ms1:
+        study.find_iso()
 
 
-def _optimized_feature_lookup(study_obj, features_df):
+def __merge_feature_lookup(study_obj, features_df):
     """
     Optimized feature lookup creation using Polars operations.
     """
@@ -3452,7 +3059,7 @@ def _optimized_feature_lookup(study_obj, features_df):
     
     # Use Polars select for faster conversion
     feature_columns = [
-        "feature_uid", "rt", "mz", "rt_start", "rt_end", "rt_delta", 
+        "feature_uid", "sample_uid", "rt", "mz", "rt_start", "rt_end", "rt_delta", 
         "mz_start", "mz_end", "inty", "chrom_coherence", "chrom_prominence", 
         "chrom_prominence_scaled", "chrom_height_scaled", "iso", "charge", 
         "ms2_scans", "adduct", "adduct_mass"
@@ -3476,12 +3083,12 @@ def _optimized_feature_lookup(study_obj, features_df):
     return features_lookup
 
 
-def _optimized_adduct_grouping(study_obj, consensus_data, rt_tol, mz_tol):
+def __merge_adduct_grouping(study, consensus_data, rt_tol, mz_tol):
     """
     Optimized O(n log n) adduct grouping using spatial indexing.
     
     Args:
-        study_obj: Study object with logger
+        study: Study object with logger
         consensus_data: List of consensus feature dictionaries
         rt_tol: RT tolerance in minutes
         mz_tol: m/z tolerance in Da
@@ -3494,9 +3101,9 @@ def _optimized_adduct_grouping(study_obj, consensus_data, rt_tol, mz_tol):
     
     n_features = len(consensus_data)
     if n_features > 10000:
-        study_obj.logger.info(f"Adduct grouping for {n_features} consensus features...")
+        study.logger.info(f"Adduct grouping for {n_features} consensus features...")
     else:
-        study_obj.logger.debug(f"Adduct grouping for {n_features} consensus features...")
+        study.logger.debug(f"Adduct grouping for {n_features} consensus features...")
     
     # Build spatial index using RT and neutral mass as coordinates
     features_by_mass = defaultdict(list)
@@ -3567,14 +3174,14 @@ def _optimized_adduct_grouping(study_obj, consensus_data, rt_tol, mz_tol):
     groups_by_root = defaultdict(list)
     for i, (uid, rt, mass, inty, adduct, _) in enumerate(valid_features):
         root = uf.find(i)
-        groups_by_root[root].append((uid, rt, mass, inty, adduct))
+        groups_by_root[root].append(valid_features[i])
     
     groups = {}
     group_id = 1
     assigned_groups = {}
     
     for group_members in groups_by_root.values():
-        member_uids = [uid for uid, _, _, _, _ in group_members]
+        member_uids = [uid for uid, _, _, _, _, _ in group_members]
         
         for uid in member_uids:
             assigned_groups[uid] = group_id
@@ -3632,8 +3239,8 @@ def _optimized_adduct_grouping(study_obj, consensus_data, rt_tol, mz_tol):
         adduct_of_list.append(adduct_of)
     
     if n_features > 10000:
-        study_obj.logger.info("Adduct grouping completed.")
+        study.logger.info("Adduct grouping completed.")
     else:
-        study_obj.logger.debug("Adduct grouping completed.")
+        study.logger.debug("Adduct grouping completed.")
 
     return adduct_group_list, adduct_of_list