masster 0.2.4__py3-none-any.whl → 0.3.0__py3-none-any.whl

masster/sample/helpers.py

@@ -1,364 +1,833 @@
-from __future__ import annotations
-
-import polars as pl
-
-import numpy as np
-
-# Parameters removed - using hardcoded defaults
-
-
-def get_dda_stats(self):
-    # filter self.scans_df with mslevel 1
-    ms1 = self.scans_df.filter(pl.col("ms_level") == 1)
-    return ms1
-
-
-# TODO
-
-
-def get_feature(self, feature_uid):
-    # get the feature with feature_uid == feature_uid
-    feature = self.features_df.filter(pl.col("feature_uid") == feature_uid)
-    if len(feature) == 0:
-        self.logger.warning(f"Feature {feature_uid} not found.")
-        return None
-    else:
-        return feature.row(0, named=True)
-
-
-def _get_scan_uids(self, scans=None, verbose=True):
-    if scans is None:
-        # fromuids scan all get_dfans
-        scans_uids = self.scans_df.get_column("scan_uid").to_list()
-    elif isinstance(scans, list):
-        # if scans is a list, ensure all elements are valid scan_uids
-        scans_uids = [
-            s for s in scans if s in self.scans_df.get_column("scan_uid").to_list()
-        ]
-        if verbose and not scans_uids:
-            self.logger.error("No valid scan_uids provided.")
-
-    return scans_uids
-
-
-def _get_feature_uids(self, features=None, verbose=True):
-    if features is None:
-        # fromuids scan all get_dfans
-        feature_uids = self.features_df.get_column("feature_uid").to_list()
-    elif isinstance(features, list):
-        # if features is a list, ensure all elements are valid feature_uids
-        feature_uids = [
-            f
-            for f in features
-            if f in self.features_df.get_column("feature_uid").to_list()
-        ]
-        if verbose and not feature_uids:
-            self.logger.error("No valid feature_uids provided.")
-
-    return feature_uids
-
-
-def get_scan(self, scans: list | None = None, verbose=True):
-    scan_uids = self._get_scan_uids(scans, verbose=False)
-    if not scan_uids:
-        if verbose:
-            self.logger.warning("No valid scan_uids provided.")
-        return None
-
-    scan = self.scans_df.filter(pl.col("scan_uid").is_in(scan_uids))
-    return scan
-
-
-def find_closest_scan(
-    self,
-    rt,
-    prec_mz=None,
-    mz_tol=0.01,
-):
-    """
-    Find the closest scan based on retention time (rt), applying additional filtering on precursor m/z (prec_mz) if provided.
-    Parameters:
-        rt (float): The target retention time to find the closest scan.
-        prec_mz (float, optional): The precursor m/z value used to filter scans. If given, only scans with ms_level 2 are considered
-                                    and filtered to include only those within mz_tol of prec_mz.
-        mz_tol (float, optional): The tolerance to apply when filtering scans by precursor m/z. Defaults to 0.01.
-    Returns:
-        dict or None: A dictionary representing the closest scan if a matching scan is found;
-                        otherwise, returns None.
-    Notes:
-        - If the scans_df attribute is None, the function prints an error message and returns None.
-        - When prec_mz is provided, it filters scans where ms_level equals 2 and the precursor m/z is within the given mz_tol range.
-        - If prec_mz is not provided, scans with ms_level equal to 1 are considered.
-        - The function calculates the absolute difference between each scan's rt and the given rt, sorting the scans by this difference.
-        - If no scans match the criteria, an error message is printed before returning None.
-    """
-    # check if scans_df is None
-    if self.scans_df is None:
-        self.logger.warning("No scans found.")
-        return None
-    if prec_mz is not None:
-        ms_level = 2
-        scans = self.scans_df.filter(pl.col("ms_level") == ms_level)
-        # find all scans with prec_mz within mz_tol of prec_mz
-        scans = scans.filter(pl.col("prec_mz") > prec_mz - mz_tol)
-        scans = scans.filter(pl.col("prec_mz") < prec_mz + mz_tol)
-        # sort by distance to rt
-        scans = scans.with_columns((pl.col("rt") - rt).abs().alias("rt_diff"))
-        scans = scans.sort("rt_diff")
-        # return the closest scan
-        if len(scans) > 0:
-            scan = scans[0]
-        else:
-            self.logger.warning(
-                f"No scans found with prec_mz {prec_mz} within {mz_tol} of rt {rt}.",
-            )
-            return None
-    else:
-        mslevel = 1
-        scans = self.scans_df.filter(pl.col("ms_level") == mslevel)
-        # sort by distance to rt
-        scans = scans.with_columns((pl.col("rt") - rt).abs().alias("rt_diff"))
-        scans = scans.sort("rt_diff")
-        # return the closest scan
-        if len(scans) > 0:
-            scan = scans[0]
-        else:
-            self.logger.warning(
-                f"No scans found with ms_level {mslevel} within {mz_tol} of rt {rt}.",
-            )
-            return None
-    # convert to dict
-
-    return scan.row(0, named=True)
-
-
-# TODO the variables here do not follow the rest (mz, rt being tuples, etc.)
-
-
-def filter_features(
-    self,
-    inplace=False,
-    mz=None,
-    rt=None,
-    coherence=None,
-    inty=None,
-    rt_delta=None,
-    iso=None,
-    iso_of=None,
-    has_MS2=None,
-    prominence_scaled=None,
-    height_scaled=None,
-    prominence=None,
-    height=None,
-):
-    # remove all features with coherence < coherence
-    if self.features_df is None:
-        # self.logger.info("No features found. R")
-        return
-    feats = self.features_df.clone()
-    if coherence is not None:
-        has_coherence = "chrom_coherence" in self.features_df.columns
-        if not has_coherence:
-            self.logger.warning("No coherence data found in features.")
-        else:
-            # record len for logging
-            feats_len_before_filter = len(feats)
-            if isinstance(coherence, tuple) and len(coherence) == 2:
-                min_coherence, max_coherence = coherence
-                feats = feats.filter(
-                    (pl.col("chrom_coherence") >= min_coherence)
-                    & (pl.col("chrom_coherence") <= max_coherence),
-                )
-            else:
-                feats = feats.filter(pl.col("chrom_coherence") >= coherence)
-            self.logger.debug(
-                f"Filtered features by coherence. Features removed: {feats_len_before_filter - len(feats)}",
-            )
-
-    if mz is not None:
-        feats_len_before_filter = len(feats)
-        if isinstance(mz, tuple) and len(mz) == 2:
-            min_mz, max_mz = mz
-            feats = feats.filter((pl.col("mz") >= min_mz) & (pl.col("mz") <= max_mz))
-        else:
-            feats = feats.filter(pl.col("mz") >= mz)
-        self.logger.debug(
-            f"Filtered features by mz. Features removed: {feats_len_before_filter - len(feats)}",
-        )
-
-    if rt is not None:
-        feats_len_before_filter = len(feats)
-        if isinstance(rt, tuple) and len(rt) == 2:
-            min_rt, max_rt = rt
-            feats = feats.filter((pl.col("rt") >= min_rt) & (pl.col("rt") <= max_rt))
-        else:
-            feats = feats.filter(pl.col("rt") >= rt)
-        self.logger.debug(
-            f"Filtered features by rt. Features removed: {feats_len_before_filter - len(feats)}",
-        )
-
-    if inty is not None:
-        feats_len_before_filter = len(feats)
-        if isinstance(inty, tuple) and len(inty) == 2:
-            min_inty, max_inty = inty
-            feats = feats.filter(
-                (pl.col("inty") >= min_inty) & (pl.col("inty") <= max_inty),
-            )
-        else:
-            feats = feats.filter(pl.col("inty") >= inty)
-        self.logger.debug(
-            f"Filtered features by intensity. Features removed: {feats_len_before_filter - len(feats)}",
-        )
-
-    if rt_delta is not None:
-        feats_len_before_filter = len(feats)
-        if "rt_delta" not in feats.columns:
-            self.logger.warning("No rt_delta data found in features.")
-            return
-        if isinstance(rt_delta, tuple) and len(rt_delta) == 2:
-            min_rt_delta, max_rt_delta = rt_delta
-            feats = feats.filter(
-                (pl.col("rt_delta") >= min_rt_delta)
-                & (pl.col("rt_delta") <= max_rt_delta),
-            )
-        else:
-            feats = feats.filter(pl.col("rt_delta") >= rt_delta)
-        self.logger.debug(
-            f"Filtered features by rt_delta. Features removed: {feats_len_before_filter - len(feats)}",
-        )
-
-    if iso is not None:
-        feats_len_before_filter = len(feats)
-        if isinstance(iso, tuple) and len(iso) == 2:
-            min_iso, max_iso = iso
-            feats = feats.filter(
-                (pl.col("iso") >= min_iso) & (pl.col("iso") <= max_iso),
-            )
-        else:
-            feats = feats.filter(pl.col("iso") == iso)
-        self.logger.debug(
-            f"Filtered features by iso. Features removed: {feats_len_before_filter - len(feats)}",
-        )
-
-    if iso_of is not None:
-        feats_len_before_filter = len(feats)
-        if isinstance(iso_of, tuple) and len(iso_of) == 2:
-            min_iso_of, max_iso_of = iso_of
-            feats = feats.filter(
-                (pl.col("iso_of") >= min_iso_of) & (pl.col("iso_of") <= max_iso_of),
-            )
-        else:
-            feats = feats.filter(pl.col("iso_of") == iso_of)
-        self.logger.debug(
-            f"Filtered features by iso_of. Features removed: {feats_len_before_filter - len(feats)}",
-        )
-
-    if has_MS2 is not None:
-        feats_len_before_filter = len(feats)
-        if has_MS2:
-            feats = feats.filter(pl.col("ms2_scans").is_not_null())
-        else:
-            feats = feats.filter(pl.col("ms2_scans").is_null())
-        self.logger.debug(
-            f"Filtered features by MS2 presence. Features removed: {feats_len_before_filter - len(feats)}",
-        )
-
-    if prominence_scaled is not None:
-        feats_len_before_filter = len(feats)
-        if isinstance(prominence_scaled, tuple) and len(prominence_scaled) == 2:
-            min_prominence_scaled, max_prominence_scaled = prominence_scaled
-            feats = feats.filter(
-                (pl.col("chrom_prominence_scaled") >= min_prominence_scaled)
-                & (pl.col("chrom_prominence_scaled") <= max_prominence_scaled),
-            )
-        else:
-            feats = feats.filter(pl.col("chrom_prominence_scaled") >= prominence_scaled)
-        self.logger.debug(
-            f"Filtered features by prominence_scaled. Features removed: {feats_len_before_filter - len(feats)}",
-        )
-
-    if height_scaled is not None:
-        feats_len_before_filter = len(feats)
-        if isinstance(height_scaled, tuple) and len(height_scaled) == 2:
-            min_height_scaled, max_height_scaled = height_scaled
-            feats = feats.filter(
-                (pl.col("chrom_height_scaled") >= min_height_scaled)
-                & (pl.col("chrom_height_scaled") <= max_height_scaled),
-            )
-        else:
-            feats = feats.filter(pl.col("chrom_height_scaled") >= height_scaled)
-        self.logger.debug(
-            f"Filtered features by height_scaled. Features removed: {feats_len_before_filter - len(feats)}",
-        )
-
-    if prominence is not None:
-        feats_len_before_filter = len(feats)
-        if isinstance(prominence, tuple) and len(prominence) == 2:
-            min_prominence, max_prominence = prominence
-            feats = feats.filter(
-                (pl.col("chrom_prominence") >= min_prominence)
-                & (pl.col("chrom_prominence") <= max_prominence),
-            )
-        else:
-            feats = feats.filter(pl.col("chrom_prominence") >= prominence)
-        self.logger.debug(
-            f"Filtered features by prominence. Features removed: {feats_len_before_filter - len(feats)}",
-        )
-
-    if height is not None:
-        feats_len_before_filter = len(feats)
-        # Check if chrom_height column exists, if not use chrom_height_scaled
-        height_col = (
-            "chrom_height" if "chrom_height" in feats.columns else "chrom_height_scaled"
-        )
-        if isinstance(height, tuple) and len(height) == 2:
-            min_height, max_height = height
-            feats = feats.filter(
-                (pl.col(height_col) >= min_height) & (pl.col(height_col) <= max_height),
-            )
-        else:
-            feats = feats.filter(pl.col(height_col) >= height)
-        self.logger.debug(
-            f"Filtered features by {height_col}. Features removed: {feats_len_before_filter - len(feats)}",
-        )
-
-    self.logger.info(f"Filtered features. Features left: {len(feats)}")
-    if inplace:
-        self.features_df = feats
-    else:
-        return feats
-
-
-def _delete_ms2(self):
-    """
-    Unlinks MS2 spectra from features in the dataset.
-    This method removes the association between MS2 spectra and features in the features dataframe by setting
-    the 'ms2_scans' and 'ms2_specs' columns to None. It also updates the scans dataframe to remove the feature
-    id (feature_uid) association for the linked MS2 spectra.
-    Parameters:
-    Returns:
-        None
-    Side Effects:
-        Updates self.features_df by setting 'ms2_scans' and 'ms2_specs' columns to None. Also, updates self.scans_df
-        by resetting the 'feature_uid' column for linked MS2 spectra.
-    """
-    if self.features_df is None:
-        # self.logger.warning("No features found.")
-        return
-
-    self.logger.debug("Unlinking MS2 spectra from features...")
-
-    # Set ms2_scans and ms2_specs to None using Polars syntax
-    self.features_df = self.features_df.with_columns([
-        pl.lit(None).alias("ms2_scans"),
-        pl.lit(None).alias("ms2_specs"),
-    ])
-
-    # Update scans_df to remove feature_uid association for linked MS2 spectra
-    self.scans_df = self.scans_df.with_columns(
-        pl.when(pl.col("ms_level") == 2)
-        .then(None)
-        .otherwise(pl.col("feature_uid"))
-        .alias("feature_uid"),
-    )
-    self.logger.info("MS2 spectra unlinked from features.")
+from __future__ import annotations
+
+import polars as pl
+
+
+# Parameters removed - using hardcoded defaults
+
+
+def _estimate_memory_usage(self):
+    """
+    Estimate the memory usage of all dataframes in the Sample object.
+    
+    Returns:
+        dict: A dictionary containing memory usage estimates for each dataframe
+              and the total memory usage in bytes and MB.
+    """
+    memory_usage = {}
+    total_bytes = 0
+    
+    # Check features_df
+    if self.features_df is not None and len(self.features_df) > 0:
+        features_bytes = self.features_df.estimated_size()
+        memory_usage['features_df'] = {
+            'rows': len(self.features_df),
+            'columns': len(self.features_df.columns),
+            'bytes': features_bytes,
+            'mb': features_bytes / (1024 * 1024)
+        }
+        total_bytes += features_bytes
+    else:
+        memory_usage['features_df'] = {'rows': 0, 'columns': 0, 'bytes': 0, 'mb': 0}
+    
+    # Check scans_df
+    if self.scans_df is not None and len(self.scans_df) > 0:
+        scans_bytes = self.scans_df.estimated_size()
+        memory_usage['scans_df'] = {
+            'rows': len(self.scans_df),
+            'columns': len(self.scans_df.columns),
+            'bytes': scans_bytes,
+            'mb': scans_bytes / (1024 * 1024)
+        }
+        total_bytes += scans_bytes
+    else:
+        memory_usage['scans_df'] = {'rows': 0, 'columns': 0, 'bytes': 0, 'mb': 0}
+    
+    # Check ms1_df
+    if self.ms1_df is not None and len(self.ms1_df) > 0:
+        ms1_bytes = self.ms1_df.estimated_size()
+        memory_usage['ms1_df'] = {
+            'rows': len(self.ms1_df),
+            'columns': len(self.ms1_df.columns),
+            'bytes': ms1_bytes,
+            'mb': ms1_bytes / (1024 * 1024)
+        }
+        total_bytes += ms1_bytes
+    else:
+        memory_usage['ms1_df'] = {'rows': 0, 'columns': 0, 'bytes': 0, 'mb': 0}
+    
+    # Check chrom_df
+    if self.chrom_df is not None and len(self.chrom_df) > 0:
+        chrom_bytes = self.chrom_df.estimated_size()
+        memory_usage['chrom_df'] = {
+            'rows': len(self.chrom_df),
+            'columns': len(self.chrom_df.columns),
+            'bytes': chrom_bytes,
+            'mb': chrom_bytes / (1024 * 1024)
+        }
+        total_bytes += chrom_bytes
+    else:
+        memory_usage['chrom_df'] = {'rows': 0, 'columns': 0, 'bytes': 0, 'mb': 0}
+    
+    # Add total memory usage
+    memory_usage['total'] = {
+        'bytes': total_bytes,
+        'mb': total_bytes / (1024 * 1024),
+        'gb': total_bytes / (1024 * 1024 * 1024)
+    }
+    
+    # Log the memory usage summary
+    if hasattr(self, 'logger'):
+        self.logger.debug(f"Total DataFrame memory usage: {memory_usage['total']['mb']:.2f} MB")
+        for df_name, stats in memory_usage.items():
+            if df_name != 'total' and stats['bytes'] > 0:
+                self.logger.debug(f"{df_name}: {stats['rows']} rows, {stats['mb']:.2f} MB")
+    
+    return memory_usage['total']['mb']
+
+
+def get_dda_stats(self):
+    # filter self.scans_df with mslevel 1
+    ms1 = self.scans_df.filter(pl.col("ms_level") == 1)
+    return ms1
+
+
+# TODO
+
+
+def get_feature(self, feature_uid):
+    # get the feature with feature_uid == feature_uid
+    feature = self.features_df.filter(pl.col("feature_uid") == feature_uid)
+    if len(feature) == 0:
+        self.logger.warning(f"Feature {feature_uid} not found.")
+        return None
+    else:
+        return feature.row(0, named=True)
+
+
+def _get_scan_uids(self, scans=None, verbose=True):
+    if scans is None:
+        # fromuids scan all get_dfans
+        scans_uids = self.scans_df.get_column("scan_uid").to_list()
+    elif isinstance(scans, list):
+        # if scans is a list, ensure all elements are valid scan_uids
+        scans_uids = [s for s in scans if s in self.scans_df.get_column("scan_uid").to_list()]
+        if verbose and not scans_uids:
+            self.logger.error("No valid scan_uids provided.")
+
+    return scans_uids
+
+
+def _get_feature_uids(self, features=None, verbose=True):
+    """
+    Get feature UIDs from various input types.
+    
+    Parameters:
+        features: Can be one of the following:
+            - None: Returns all feature UIDs from self.features_df
+            - list: Returns the list if all elements are valid feature UIDs
+            - polars.DataFrame: Extracts unique values from 'feature_uid' or 'feature_id' column
+            - pandas.DataFrame: Extracts unique values from 'feature_uid' or 'feature_id' column
+        verbose (bool): Whether to log errors for invalid inputs
+    
+    Returns:
+        list: List of feature UIDs
+    """
+    if features is None:
+        # Get all feature UIDs from self.features_df
+        if self.features_df is None:
+            if verbose:
+                self.logger.warning("No features_df available.")
+            return []
+        feature_uids = self.features_df.get_column("feature_uid").to_list()
+    elif isinstance(features, list):
+        # If features is a list, ensure all elements are valid feature_uids
+        if self.features_df is None:
+            if verbose:
+                self.logger.warning("No features_df available to validate feature UIDs.")
+            return []
+        
+        valid_feature_uids = self.features_df.get_column("feature_uid").to_list()
+        feature_uids = [f for f in features if f in valid_feature_uids]
+        if verbose and not feature_uids:
+            self.logger.error("No valid feature_uids provided.")
+    else:
+        # Handle polars and pandas DataFrames
+        try:
+            # Check if it's a polars DataFrame
+            if hasattr(features, 'columns') and hasattr(features, 'get_column'):
+                # Polars DataFrame
+                feature_column = None
+                if 'feature_uid' in features.columns:
+                    feature_column = 'feature_uid'
+                elif 'feature_id' in features.columns:
+                    feature_column = 'feature_id'
+                
+                if feature_column is None:
+                    if verbose:
+                        self.logger.error("No 'feature_uid' or 'feature_id' column found in polars DataFrame.")
+                    return []
+                
+                # Get unique values from the column
+                feature_uids = features.get_column(feature_column).unique().to_list()
+                
+            # Check if it's a pandas DataFrame
+            elif hasattr(features, 'columns') and hasattr(features, 'iloc'):
+                # Pandas DataFrame
+                import pandas as pd
+                if not isinstance(features, pd.DataFrame):
+                    if verbose:
+                        self.logger.error("Invalid input type. Expected None, list, polars DataFrame, or pandas DataFrame.")
+                    return []
+                
+                feature_column = None
+                if 'feature_uid' in features.columns:
+                    feature_column = 'feature_uid'
+                elif 'feature_id' in features.columns:
+                    feature_column = 'feature_id'
+                
+                if feature_column is None:
+                    if verbose:
+                        self.logger.error("No 'feature_uid' or 'feature_id' column found in pandas DataFrame.")
+                    return []
+                
+                # Get unique values from the column
+                feature_uids = features[feature_column].unique().tolist()
+                
+            else:
+                if verbose:
+                    self.logger.error("Invalid input type. Expected None, list, polars DataFrame, or pandas DataFrame.")
+                return []
+                
+        except Exception as e:
+            if verbose:
+                self.logger.error(f"Error processing DataFrame input: {e}")
+            return []
+
+    return feature_uids
+
+
+def get_scan(self, scans: list | None = None, verbose=True):
+    scan_uids = self._get_scan_uids(scans, verbose=False)
+    if not scan_uids:
+        if verbose:
+            self.logger.warning("No valid scan_uids provided.")
+        return None
+
+    scan = self.scans_df.filter(pl.col("scan_uid").is_in(scan_uids))
+    return scan
+
+
+def select_closest_scan(
+    self,
+    rt,
+    prec_mz=None,
+    mz_tol=0.01,
+):
+    """
+    Select the closest scan based on retention time (rt), applying additional filtering on precursor m/z (prec_mz) if provided.
+    Parameters:
+        rt (float): The target retention time to find the closest scan.
+        prec_mz (float, optional): The precursor m/z value used to filter scans. If given, only scans with ms_level 2 are considered
+                                    and filtered to include only those within mz_tol of prec_mz.
+        mz_tol (float, optional): The tolerance to apply when filtering scans by precursor m/z. Defaults to 0.01.
+    Returns:
+        polars.DataFrame or None: A DataFrame slice containing the closest scan if a matching scan is found;
+                                  otherwise, returns None.
+    Notes:
+        - If the scans_df attribute is None, the function prints an error message and returns None.
+        - When prec_mz is provided, it filters scans where ms_level equals 2 and the precursor m/z is within the given mz_tol range.
+        - If prec_mz is not provided, scans with ms_level equal to 1 are considered.
+        - The function calculates the absolute difference between each scan's rt and the given rt, sorting the scans by this difference.
+        - If no scans match the criteria, an error message is printed before returning None.
+    """
+    # check if scans_df is None
+    if self.scans_df is None:
+        self.logger.warning("No scans found.")
+        return None
+    if prec_mz is not None:
+        ms_level = 2
+        scans = self.scans_df.filter(pl.col("ms_level") == ms_level)
+        # find all scans with prec_mz within mz_tol of prec_mz
+        scans = scans.filter(pl.col("prec_mz") > prec_mz - mz_tol)
+        scans = scans.filter(pl.col("prec_mz") < prec_mz + mz_tol)
+        # sort by distance to rt
+        scans = scans.with_columns((pl.col("rt") - rt).abs().alias("rt_diff"))
+        scans = scans.sort("rt_diff")
+        # return the closest scan
+        if len(scans) > 0:
+            scan = scans.slice(0, 1)
+        else:
+            self.logger.warning(
+                f"No scans found with prec_mz {prec_mz} within {mz_tol} of rt {rt}.",
+            )
+            return None
+    else:
+        mslevel = 1
+        scans = self.scans_df.filter(pl.col("ms_level") == mslevel)
+        # sort by distance to rt
+        scans = scans.with_columns((pl.col("rt") - rt).abs().alias("rt_diff"))
+        scans = scans.sort("rt_diff")
+        # return the closest scan
+        if len(scans) > 0:
+            scan = scans.slice(0, 1)
+        else:
+            self.logger.warning(
+                f"No scans found with ms_level {mslevel} within {mz_tol} of rt {rt}.",
+            )
+            return None
+    # return scans_df slice
+
+    return scan
+
+
+# TODO the variables here do not follow the rest (mz, rt being tuples, etc.)
+
+
+def select(
+    self,
+    mz=None,
+    rt=None,
+    coherence=None,
+    inty=None,
+    rt_delta=None,
+    iso=None,
+    iso_of=None,
+    has_MS2=None,
+    prominence_scaled=None,
+    height_scaled=None,
+    prominence=None,
+    height=None,
+):
+    """
+    Select features based on specified criteria and return the filtered DataFrame.
+    
+    Parameters:
+        mz: m/z range filter (tuple for range, single value for minimum)
+        rt: retention time range filter (tuple for range, single value for minimum)
+        coherence: chromatogram coherence filter (tuple for range, single value for minimum)
+        inty: intensity filter (tuple for range, single value for minimum)
+        rt_delta: retention time delta filter (tuple for range, single value for minimum)
+        iso: isotope number filter (tuple for range, single value for exact match)
+        iso_of: isotope parent filter (tuple for range, single value for exact match)
+        has_MS2: filter for features with/without MS2 spectra (bool)
+        prominence_scaled: scaled prominence filter (tuple for range, single value for minimum)
+        height_scaled: scaled height filter (tuple for range, single value for minimum)
+        prominence: prominence filter (tuple for range, single value for minimum)
+        height: height filter (tuple for range, single value for minimum)
+    
+    Returns:
+        polars.DataFrame: Filtered features DataFrame
+    """
+    # remove all features with coherence < coherence
+    if self.features_df is None:
+        # self.logger.info("No features found. R")
+        return
+    feats = self.features_df.clone()
+    if coherence is not None:
+        has_coherence = "chrom_coherence" in self.features_df.columns
+        if not has_coherence:
+            self.logger.warning("No coherence data found in features.")
+        else:
+            # record len for logging
+            feats_len_before_filter = len(feats)
+            if isinstance(coherence, tuple) and len(coherence) == 2:
+                min_coherence, max_coherence = coherence
+                feats = feats.filter(
+                    (pl.col("chrom_coherence") >= min_coherence) & (pl.col("chrom_coherence") <= max_coherence),
+                )
+            else:
+                feats = feats.filter(pl.col("chrom_coherence") >= coherence)
+            self.logger.debug(
+                f"Selected features by coherence. Features removed: {feats_len_before_filter - len(feats)}",
+            )
+
+    if mz is not None:
+        feats_len_before_filter = len(feats)
+        if isinstance(mz, tuple) and len(mz) == 2:
+            min_mz, max_mz = mz
+            feats = feats.filter((pl.col("mz") >= min_mz) & (pl.col("mz") <= max_mz))
+        else:
+            feats = feats.filter(pl.col("mz") >= mz)
+        self.logger.debug(
+            f"Selected features by mz. Features removed: {feats_len_before_filter - len(feats)}",
+        )
+
+    if rt is not None:
+        feats_len_before_filter = len(feats)
+        if isinstance(rt, tuple) and len(rt) == 2:
+            min_rt, max_rt = rt
+            feats = feats.filter((pl.col("rt") >= min_rt) & (pl.col("rt") <= max_rt))
+        else:
+            feats = feats.filter(pl.col("rt") >= rt)
+        self.logger.debug(
+            f"Selected features by rt. Features removed: {feats_len_before_filter - len(feats)}",
+        )
+
+    if inty is not None:
+        feats_len_before_filter = len(feats)
+        if isinstance(inty, tuple) and len(inty) == 2:
+            min_inty, max_inty = inty
+            feats = feats.filter(
+                (pl.col("inty") >= min_inty) & (pl.col("inty") <= max_inty),
+            )
+        else:
+            feats = feats.filter(pl.col("inty") >= inty)
+        self.logger.debug(
+            f"Selected features by intensity. Features removed: {feats_len_before_filter - len(feats)}",
+        )
+
+    if rt_delta is not None:
+        feats_len_before_filter = len(feats)
+        if "rt_delta" not in feats.columns:
+            self.logger.warning("No rt_delta data found in features.")
+            return
+        if isinstance(rt_delta, tuple) and len(rt_delta) == 2:
+            min_rt_delta, max_rt_delta = rt_delta
+            feats = feats.filter(
+                (pl.col("rt_delta") >= min_rt_delta) & (pl.col("rt_delta") <= max_rt_delta),
+            )
+        else:
+            feats = feats.filter(pl.col("rt_delta") >= rt_delta)
+        self.logger.debug(
+            f"Selected features by rt_delta. Features removed: {feats_len_before_filter - len(feats)}",
+        )
+
+    if iso is not None:
+        feats_len_before_filter = len(feats)
+        if isinstance(iso, tuple) and len(iso) == 2:
+            min_iso, max_iso = iso
+            feats = feats.filter(
+                (pl.col("iso") >= min_iso) & (pl.col("iso") <= max_iso),
+            )
+        else:
+            feats = feats.filter(pl.col("iso") == iso)
+        self.logger.debug(
+            f"Selected features by iso. Features removed: {feats_len_before_filter - len(feats)}",
+        )
+
+    if iso_of is not None:
+        feats_len_before_filter = len(feats)
+        if isinstance(iso_of, tuple) and len(iso_of) == 2:
+            min_iso_of, max_iso_of = iso_of
+            feats = feats.filter(
+                (pl.col("iso_of") >= min_iso_of) & (pl.col("iso_of") <= max_iso_of),
+            )
+        else:
+            feats = feats.filter(pl.col("iso_of") == iso_of)
+        self.logger.debug(
+            f"Selected features by iso_of. Features removed: {feats_len_before_filter - len(feats)}",
+        )
+
+    if has_MS2 is not None:
+        feats_len_before_filter = len(feats)
+        if has_MS2:
+            feats = feats.filter(pl.col("ms2_scans").is_not_null())
+        else:
+            feats = feats.filter(pl.col("ms2_scans").is_null())
+        self.logger.debug(
+            f"Selected features by MS2 presence. Features removed: {feats_len_before_filter - len(feats)}",
+        )
+
+    if prominence_scaled is not None:
+        feats_len_before_filter = len(feats)
+        if isinstance(prominence_scaled, tuple) and len(prominence_scaled) == 2:
+            min_prominence_scaled, max_prominence_scaled = prominence_scaled
+            feats = feats.filter(
+                (pl.col("chrom_prominence_scaled") >= min_prominence_scaled)
+                & (pl.col("chrom_prominence_scaled") <= max_prominence_scaled),
+            )
+        else:
+            feats = feats.filter(pl.col("chrom_prominence_scaled") >= prominence_scaled)
+        self.logger.debug(
+            f"Selected features by prominence_scaled. Features removed: {feats_len_before_filter - len(feats)}",
+        )
+
+    if height_scaled is not None:
+        feats_len_before_filter = len(feats)
+        if isinstance(height_scaled, tuple) and len(height_scaled) == 2:
+            min_height_scaled, max_height_scaled = height_scaled
+            feats = feats.filter(
+                (pl.col("chrom_height_scaled") >= min_height_scaled)
+                & (pl.col("chrom_height_scaled") <= max_height_scaled),
+            )
+        else:
+            feats = feats.filter(pl.col("chrom_height_scaled") >= height_scaled)
+        self.logger.debug(
+            f"Selected features by height_scaled. Features removed: {feats_len_before_filter - len(feats)}",
+        )
+
+    if prominence is not None:
+        feats_len_before_filter = len(feats)
+        if isinstance(prominence, tuple) and len(prominence) == 2:
+            min_prominence, max_prominence = prominence
+            feats = feats.filter(
+                (pl.col("chrom_prominence") >= min_prominence) & (pl.col("chrom_prominence") <= max_prominence),
+            )
+        else:
+            feats = feats.filter(pl.col("chrom_prominence") >= prominence)
+        self.logger.debug(
+            f"Selected features by prominence. Features removed: {feats_len_before_filter - len(feats)}",
+        )
+
+    if height is not None:
+        feats_len_before_filter = len(feats)
+        # Check if chrom_height column exists, if not use chrom_height_scaled
+        height_col = "chrom_height" if "chrom_height" in feats.columns else "chrom_height_scaled"
+        if isinstance(height, tuple) and len(height) == 2:
+            min_height, max_height = height
+            feats = feats.filter(
+                (pl.col(height_col) >= min_height) & (pl.col(height_col) <= max_height),
+            )
+        else:
+            feats = feats.filter(pl.col(height_col) >= height)
+        self.logger.debug(
+            f"Selected features by {height_col}. Features removed: {feats_len_before_filter - len(feats)}",
+        )
+    if len(feats) == 0:
+        self.logger.warning("No features remaining after applying selection criteria.")
+    else:
+        self.logger.info(f"Selected features. Features remaining: {len(feats)}")
+    return feats
+
+
+
+
+def _features_sync(self):
+    """
+    Synchronizes the OpenMS FeatureMap and features_df by removing features that exist in one 
+    but not the other, using feature_id for mapping between them.
+    
+    This function ensures that:
+    - Features in the FeatureMap that don't have corresponding entries in features_df are removed
+    - Features in features_df that don't have corresponding entries in the FeatureMap are removed
+    
+    Returns:
+        None
+        
+    Side Effects:
+        Updates self.features (OpenMS FeatureMap) by creating a new FeatureMap with synchronized features
+        Updates self.features_df by filtering to only include features present in the FeatureMap
+        
+    Note:
+        Uses feature_id as the mapping key. feature_id contains OpenMS unique IDs that correspond
+        to the unique IDs of features in the FeatureMap.
+    """
+    if self.features_df is None or self.features is None:
+        self.logger.warning("Cannot sync: features_df or FeatureMap is None.")
+        return
+    
+    try:
+        # Import pyopenms
+        import pyopenms as oms
+        
+        # Get feature_ids from features_df
+        df_feature_ids = set(self.features_df.get_column("feature_id").to_list())
+        
+        # Get feature unique IDs from FeatureMap
+        feature_map_ids = set()
+        for i in range(self.features.size()):
+            feature = self.features[i]
+            unique_id = str(feature.getUniqueId())  # Convert to string to match DataFrame
+            feature_map_ids.add(unique_id)
+        
+        # Find features that exist in both
+        common_feature_ids = df_feature_ids & feature_map_ids
+        
+        # Safety check: log error and exit if no features are matching
+        if not common_feature_ids:
+            self.logger.error(
+                f"No matching features found between FeatureMap and features_df. "
+                f"FeatureMap has {len(feature_map_ids)} features, "
+                f"features_df has {len(df_feature_ids)} features. "
+                f"Cannot synchronize - this indicates a data inconsistency. Exiting without changes."
+            )
+            return
+        
+        # Create new synchronized FeatureMap with only common features
+        synced_feature_map = oms.FeatureMap()
+        for i in range(self.features.size()):
+            feature = self.features[i]
+            unique_id = str(feature.getUniqueId())
+            if unique_id in common_feature_ids:
+                synced_feature_map.push_back(feature)
+        
+        # Filter features_df to only include features that exist in FeatureMap
+        synced_features_df = self.features_df.filter(
+            pl.col("feature_id").is_in(list(common_feature_ids))
+        )
+        
+        # Update the objects
+        original_map_size = self.features.size()
+        original_df_size = len(self.features_df)
+        
+        self.features = synced_feature_map
+        self.features_df = synced_features_df
+        
+        # Log the synchronization results
+        map_removed = original_map_size - self.features.size()
+        df_removed = original_df_size - len(self.features_df)
+
+        # only log if features were removed
+        if map_removed > 0 or df_removed > 0:
+            self.logger.info(
+                f"Features synchronized. FeatureMap: {original_map_size} -> {self.features.size()} "
+                f"({map_removed} removed), DataFrame: {original_df_size} -> {len(self.features_df)} "
+                f"({df_removed} removed)"
+            )
+        else:
+            self.logger.debug(
+                f"Features synchronized. FeatureMap: {original_map_size} -> {self.features.size()} "
+                f"({map_removed} removed), DataFrame: {original_df_size} -> {len(self.features_df)} "
+                f"({df_removed} removed)"
+            )
+        
+    except ImportError:
+        self.logger.warning("PyOpenMS not available, cannot sync FeatureMap")
+    except Exception as e:
+        self.logger.error(f"Error during feature synchronization: {e}")
+
+
+def features_delete(self, features: list|None=None):
+    """
+    Delete features from both self.features_df and self.features based on a list of feature UIDs.
+    
+    Parameters:
+        features (list, optional): List of feature UIDs to delete. If None, all features will be deleted.
+    
+    Returns:
+        None
+        
+    Side Effects:
+        Updates self.features_df by removing specified features.
+        Updates self.features (OpenMS FeatureMap) by creating a new FeatureMap with only the remaining features.
+        Updates self.scans_df by removing feature_uid associations for deleted features.
+        
+    Note:
+        The function preserves all OpenMS FeatureMap information by creating a new FeatureMap
+        containing only the features that should remain after deletion.
+    """
+    if self.features_df is None:
+        self.logger.warning("No features found.")
+        return
+    
+    # Get the feature UIDs to delete
+    feature_uids_to_delete = self._get_feature_uids(features=features, verbose=True)
+    
+    if not feature_uids_to_delete:
+        self.logger.warning("No valid feature UIDs provided for deletion.")
+        return
+    
+    original_count = len(self.features_df)
+    
+    # Update features_df by filtering out the features to delete
+    self.features_df = self.features_df.filter(
+        ~pl.col("feature_uid").is_in(feature_uids_to_delete)
+    )
+    
+    # Update the OpenMS FeatureMap by creating a new one with only features to keep
+    if self.features is not None:
+        try:
+            # Import pyopenms
+            import pyopenms as oms
+            
+            # Create new FeatureMap with only features to keep
+            filtered_map = oms.FeatureMap()
+            
+            # Get the feature UIDs that should remain after deletion
+            remaining_feature_uids = self.features_df.get_column("feature_uid").to_list()
+            
+            # Iterate through existing features and keep only those not in deletion list
+            for i in range(self.features.size()):
+                feature = self.features[i]
+                # Since feature UIDs in DataFrame are sequential (0, 1, 2, ...) and correspond to indices
+                # we can check if the current index is in the remaining UIDs
+                if i in remaining_feature_uids:
+                    filtered_map.push_back(feature)
+            
+            # Replace the original FeatureMap with the filtered one
+            self.features = filtered_map
+            self.logger.debug(f"OpenMS FeatureMap updated with {filtered_map.size()} remaining features.")
+            
+        except ImportError:
+            self.logger.warning("PyOpenMS not available, only updating features_df")
+        except Exception as e:
+            self.logger.warning(f"Could not update OpenMS FeatureMap: {e}. FeatureMap may be out of sync.")
+    
+    # Update scans_df to remove feature_uid associations for deleted features
+    if hasattr(self, 'scans_df') and self.scans_df is not None:
+        self.scans_df = self.scans_df.with_columns(
+            pl.when(pl.col("feature_uid").is_in(feature_uids_to_delete))
+            .then(None)
+            .otherwise(pl.col("feature_uid"))
+            .alias("feature_uid")
+        )
+    
+    deleted_count = original_count - len(self.features_df)
+    self.logger.info(f"Deleted {deleted_count} features. Remaining features: {len(self.features_df)}")
+
+
+def _delete_ms2(self):
+    """
+    Unlinks MS2 spectra from features in the dataset.
+    This method removes the association between MS2 spectra and features in the features dataframe by setting
+    the 'ms2_scans' and 'ms2_specs' columns to None. It also updates the scans dataframe to remove the feature
+    id (feature_uid) association for the linked MS2 spectra.
+    Parameters:
+    Returns:
+        None
+    Side Effects:
+        Updates self.features_df by setting 'ms2_scans' and 'ms2_specs' columns to None. Also, updates self.scans_df
+        by resetting the 'feature_uid' column for linked MS2 spectra.
+    """
+    if self.features_df is None:
+        # self.logger.warning("No features found.")
+        return
+
+    self.logger.debug("Unlinking MS2 spectra from features...")
+
+    # Set ms2_scans and ms2_specs to None using Polars syntax
+    self.features_df = self.features_df.with_columns([
+        pl.lit(None).alias("ms2_scans"),
+        pl.lit(None).alias("ms2_specs"),
+    ])
+
+    # Update scans_df to remove feature_uid association for linked MS2 spectra
+    self.scans_df = self.scans_df.with_columns(
+        pl.when(pl.col("ms_level") == 2).then(None).otherwise(pl.col("feature_uid")).alias("feature_uid"),
+    )
+    self.logger.info("MS2 spectra unlinked from features.")
+
+
+def features_filter(self, features):
+    """
+    Keep only the specified features and delete all others. This is the opposite of features_delete().
+    
+    Parameters:
+        features: Can be one of the following:
+            - list: List of feature UIDs to keep
+            - polars.DataFrame: DataFrame with 'feature_uid' or 'feature_id' column - extracts unique values to keep
+            - pandas.DataFrame: DataFrame with 'feature_uid' or 'feature_id' column - extracts unique values to keep
+    
+    Returns:
+        None
+        
+    Side Effects:
+        Updates self.features_df by keeping only the specified features.
+        Updates self.features (OpenMS FeatureMap) by creating a new FeatureMap with only the specified features.
+        Updates self.scans_df by removing feature_uid associations for deleted features.
+        
+    Note:
+        The function preserves all OpenMS FeatureMap information by creating a new FeatureMap
+        containing only the features that should be kept.
+    """
+    if self.features_df is None:
+        self.logger.warning("No features found.")
+        return
+    
+    if features is None:
+        self.logger.warning("No features specified to keep. Use features_delete() to delete all features.")
+        return
+    
+    # Get the feature UIDs to keep
+    feature_uids_to_keep = self._get_feature_uids(features=features, verbose=True)
+    
+    if not feature_uids_to_keep:
+        self.logger.warning("No valid feature UIDs provided to keep.")
+        return
+    
+    original_count = len(self.features_df)
+    
+    # Update features_df by keeping only the specified features
+    self.features_df = self.features_df.filter(
+        pl.col("feature_uid").is_in(feature_uids_to_keep)
+    )
+    
+    # Calculate which features were deleted (all except the ones to keep)
+    all_feature_uids = set(range(original_count))  # Assuming sequential UIDs
+    feature_uids_to_delete = list(all_feature_uids - set(feature_uids_to_keep))
+    
+    # Update the OpenMS FeatureMap by creating a new one with only features to keep
+    if self.features is not None:
+        try:
+            # Import pyopenms
+            import pyopenms as oms
+            
+            # Create new FeatureMap with only features to keep
+            filtered_map = oms.FeatureMap()
+            
+            # Iterate through existing features and keep only those in the keep list
+            for i in range(self.features.size()):
+                feature = self.features[i]
+                # Since feature UIDs in DataFrame are sequential (0, 1, 2, ...) and correspond to indices
+                # we can check if the current index is in the keep UIDs
+                if i in feature_uids_to_keep:
+                    filtered_map.push_back(feature)
+            
+            # Replace the original FeatureMap with the filtered one
+            self.features = filtered_map
+            self.logger.debug(f"OpenMS FeatureMap updated with {filtered_map.size()} remaining features.")
+            
+        except ImportError:
+            self.logger.warning("PyOpenMS not available, only updating features_df")
+        except Exception as e:
+            self.logger.warning(f"Could not update OpenMS FeatureMap: {e}. FeatureMap may be out of sync.")
+    
+    # Update scans_df to remove feature_uid associations for deleted features
+    if hasattr(self, 'scans_df') and self.scans_df is not None and feature_uids_to_delete:
+        self.scans_df = self.scans_df.with_columns(
+            pl.when(pl.col("feature_uid").is_in(feature_uids_to_delete))
+            .then(None)
+            .otherwise(pl.col("feature_uid"))
+            .alias("feature_uid")
+        )
+    
+    kept_count = len(self.features_df)
+    deleted_count = original_count - kept_count
+    self.logger.info(f"Kept {kept_count} features, deleted {deleted_count} features. Remaining features: {kept_count}")
+
+
+def set_source(self, filename):
+    """
+    Reassign file_source. If filename contains only a path, keep the current basename 
+    and build an absolute path. Check that the new file exists before overwriting 
+    the old file_source.
+    
+    Parameters:
+        filename (str): New file path or directory path
+    
+    Returns:
+        None
+    """
+    import os
+    
+    # Store the old file_source for logging
+    old_file_source = getattr(self, 'file_source', None)
+    
+    # Check if filename is just a directory path
+    if os.path.isdir(filename):
+        if old_file_source is None:
+            self.logger.error("Cannot build path: no current file_source available")
+            return
+        
+        # Get the basename from current file_source
+        current_basename = os.path.basename(old_file_source)
+        # Build new absolute path
+        new_file_path = os.path.join(filename, current_basename)
+    else:
+        # filename is a full path, make it absolute
+        new_file_path = os.path.abspath(filename)
+    
+    # Check if the new file exists
+    if not os.path.exists(new_file_path):
+        self.logger.error(f"File does not exist: {new_file_path}")
+        return
+    
+    # Update file_source
+    self.file_source = new_file_path
+    
+    # Log the change
+    if old_file_source is not None:
+        self.logger.info(f"Updated file_source from {old_file_source} to {self.file_source}")
+    else:
+        self.logger.info(f"Set file_source to {self.file_source}")