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

masster/sample/processing.py

@@ -1,1416 +1,1402 @@
-from __future__ import annotations
-
-from datetime import datetime
-
-import numpy as np
-import polars as pl
-import pyopenms as oms
-
-from tqdm import tqdm
-
-from masster.chromatogram import Chromatogram
-# Parameters removed - using hardcoded defaults
-from masster.spectrum import Spectrum
-from .defaults.find_features_def import find_features_defaults
-from .defaults.find_adducts_def import find_adducts_defaults
-from .defaults.find_ms2_def import find_ms2_defaults
-from .defaults.get_spectrum_def import get_spectrum_defaults
-
-
-def get_spectrum(self, scan, **kwargs):
-    """
-    Retrieve and process a spectrum from the data file based on the given scan identifier.
-
-    This method locates the scan in the internal DataFrame, extracts the metadata (such as energy,
-    MS level, and retention time), and then retrieves the corresponding spectrum data from the file.
-    Depending on the file interface (either 'oms' or 'alpharaw'), the spectrum data is obtained
-    and processed (including optional denoising, centroiding, deisotoping, and precursor m/z trimming).
-
-    Parameters:
-        scan (int): Unique identifier of the scan to retrieve. This is a mandatory parameter.
-        **kwargs: Keyword arguments for spectrum retrieval parameters. Can include:
-            - A get_spectrum_defaults instance to set all parameters at once
-            - Individual parameter names and values (see get_spectrum_defaults for details)
-
-    Key Parameters:
-        precursor_trim (int, optional): Value used to trim the precursor m/z for MS2 spectra.
-                                        If provided and the spectrum's MS level is greater than 1,
-                                        m/z values above (precursor_mz - precursor_trim) will be trimmed.
-                                        Default is 20.
-        max_peaks (int, optional): Maximum number of peaks to retain in the spectrum. Default is 100.
-        centroid (bool, optional): Flag indicating whether the spectrum should be centroided.
-                                    If True and the spectrum is not already centroided, the method
-                                    applies denoising followed by centroiding using parameters from self.parameters.
-                                    Default is True.
-        deisotope (bool, optional): Flag indicating whether deisotoping should be performed. Default is False.
-        dia_stats (optional): Flag or parameter for processing DIA (data-independent acquisition)
-                                statistics. If provided (and if applicable to the file type), additional
-                                statistics will be computed for 'ztscan' files. Default is None.
-        feature (optional): An optional identifier used when computing DIA statistics. Default is None.
-        label (str, optional): Optional label to assign to the spectrum. If not provided,
-                                a default name is generated based on the MS level and retention time.
-                                Default is None.
-        centroid_algo (str, optional): Algorithm to use for centroiding. Default is None.
-
-    Returns:
-        spectrum: A processed spectrum object containing:
-                    - m/z and intensity arrays
-                    - metadata such as MS level, retention time, energy, and an assigned label
-                    Depending on the processing steps (centroiding, trimming, deisotoping, etc.), the
-                    returned spectrum is modified accordingly.
-                    Returns None or an empty spectrum if the scan is not found or if an error occurs.
-
-    Notes:
-        - For the 'oms' file interface, the spectrum is retrieved via self.file_obj.getSpectrum
-            and handled accordingly.
-        - For the 'alpharaw' file interface, the method uses internal DataFrame attributes to locate the
-            scan and its associated peaks.
-        - The method applies additional processing (denoising, centroiding, deisotoping, trimming) based on
-            the input flags and the MS level of the spectrum.
-    """
-
-    # parameters initialization
-    params = get_spectrum_defaults(scan=scan)
-    for key, value in kwargs.items():
-        if isinstance(value, get_spectrum_defaults):
-            params = value
-            self.logger.debug("Using provided get_spectrum_defaults parameters")
-        else:
-            if hasattr(params, key):
-                if params.set(key, value, validate=True):
-                    self.logger.debug(f"Updated parameter {key} = {value}")
-                else:
-                    self.logger.warning(
-                        f"Failed to set parameter {key} = {value} (validation failed)",
-                    )
-            else:
-                self.logger.debug(f"Unknown parameter {key} ignored")
-    # end of parameter initialization
-
-    # Extract parameter values
-    scan = params.get("scan")
-    precursor_trim = params.get("precursor_trim")
-    max_peaks = params.get("max_peaks")
-    centroid = params.get("centroid")
-    deisotope = params.get("deisotope")
-    dia_stats = params.get("dia_stats")
-    feature_uid = params.get("feature")
-    label = params.get("label")
-    centroid_algo = params.get("centroid_algo")
-
-    # get energy, ms_level, rt from scans_df
-    scan_uid = scan  # Preserve original scan ID
-    scan_info = self.scans_df.filter(pl.col("scan_uid") == scan_uid)
-    if len(scan_info) == 0:
-        self.logger.warning(f"Scan {scan_uid} not found.")
-        return None
-    scan_info = scan_info[0]
-    energy = scan_info["energy"][0]
-    ms_level = scan_info["ms_level"][0]
-    rt = scan_info["rt"][0]
-    if label is None:
-        if ms_level == 1:
-            name = f"MS1, rt {rt:.2f} s, scan {scan_uid}"
-        else:
-            name = f"MS2 of mz {scan_info['prec_mz'][0]:0.1f}, rt {rt:.2f} s, scan {scan_uid}"
-    else:
-        name = label
-
-    if centroid_algo is None:
-        if "centroid_algo" in self.parameters:
-            centroid_algo = self.parameters.get("centroid_algo")
-        else:
-            # this is for backward compatibility. This is the old default
-            self.parameters.centroid_algo = "lmp"
-        centroid_algo = self.parameters.get("centroid_algo")
-
-    spec0 = Spectrum(mz=np.array([]), inty=np.array([]))
-    if self.file_interface == "oms":
-        # if check that file_obj is not None
-        if self.file_obj is None:
-            self.logger.error("Please load a file first.")
-            return
-        try:
-            spect = self.file_obj.getSpectrum(scan_uid).get_peaks()
-        except Exception as e:
-            self.logger.error(f"Error: {e}")
-            return spec0
-        if len(spect[0]) == 0:
-            return spec0
-        elif len(spect[0]) == 1:
-            mz = np.array([spect[0][0]])
-            inty = np.array([spect[1][0]])
-        else:
-            mz = np.array(spect[0])
-            inty = np.array(spect[1])
-        if ms_level == 1:
-            spect = Spectrum(
-                mz=mz,
-                inty=inty,
-                ms_level=ms_level,
-                rt=rt,
-                energy=None,
-                precursor_mz=None,
-                label=name,
-            )
-        else:
-            spect = Spectrum(
-                mz=mz,
-                inty=inty,
-                ms_level=ms_level,
-                rt=rt,
-                energy=energy,
-                precursor_mz=scan_info["prec_mz"][0],
-                label=name,
-            )
-        if centroid and not spect.centroided:
-            spect = spect.denoise()
-            if Spectrum.ms_level == 1:
-                spect = spect.centroid(
-                    algo=centroid_algo,
-                    tolerance=self.parameters.get("mz_tol_ms1_da"),
-                    ppm=self.parameters.get("mz_tol_ms1_ppm"),
-                    min_points=self.parameters.get("centroid_min_points_ms1"),
-                    smooth=self.parameters.get("centroid_smooth"),
-                    prominence=self.parameters.get("centroid_prominence"),
-                    refine=self.parameters.get("centroid_refine"),
-                )
-            elif Spectrum.ms_level == 2:
-                spect = spect.centroid(
-                    algo=centroid_algo,
-                    tolerance=self.parameters.get("mz_tol_ms2_da"),
-                    ppm=self.parameters.get("mz_tol_ms2_ppm"),
-                    min_points=self.parameters.get("centroid_min_points_ms2"),
-                    smooth=self.parameters.get("centroid_smooth"),
-                    prominence=self.parameters.get("centroid_prominence"),
-                    refine=self.parameters.get("centroid_refine"),
-                )
-
-    elif self.file_interface == "alpharaw":
-        spec_df = self.file_obj.spectrum_df
-        spect = (
-            spec_df.filter(pl.col("scan_id") == scan_uid).row(0, named=True)
-            if isinstance(spec_df, pl.DataFrame)
-            else spec_df.loc[scan_uid]
-        )
-        peak_stop_idx = spect["peak_stop_idx"]
-        peak_start_idx = spect["peak_start_idx"]
-
-        if isinstance(self.file_obj.peak_df, pl.DataFrame):
-            peaks = self.file_obj.peak_df.slice(
-                peak_start_idx,
-                peak_stop_idx - peak_start_idx,
-            )
-            mz_values = peaks.select("mz").to_numpy().flatten()
-            intensity_values = peaks.select("intensity").to_numpy().flatten()
-        else:
-            peaks = self.file_obj.peak_df.loc[peak_start_idx : peak_stop_idx - 1]
-            mz_values = peaks.mz.values
-            intensity_values = peaks.intensity.values
-
-        if spect["ms_level"] > 1:
-            spect = Spectrum(
-                mz=np.asarray(mz_values, dtype=np.float64),
-                inty=np.asarray(intensity_values, dtype=np.float64),
-                ms_level=ms_level,
-                centroided=False,
-                precursor_mz=spect["precursor_mz"],
-                energy=energy,
-                rt=rt,
-                label=name,
-            )
-        else:
-            spect = Spectrum(
-                mz=np.asarray(mz_values, dtype=np.float64),
-                inty=np.asarray(intensity_values, dtype=np.float64),
-                ms_level=ms_level,
-                centroided=False,
-                precursor_mz=None,
-                energy=None,
-                rt=rt,
-                label=name,
-            )
-
-        if len(spect) and centroid and not spect.centroided:
-            spect = spect.denoise()
-            if spect.ms_level == 1:
-                spect = spect.centroid(
-                    algo=centroid_algo,
-                    tolerance=self.parameters.get("mz_tol_ms1_da"),
-                    ppm=self.parameters.get("mz_tol_ms1_ppm"),
-                    min_points=self.parameters.get("centroid_min_points_ms1"),
-                    smooth=self.parameters.get("centroid_smooth"),
-                    prominence=self.parameters.get("centroid_prominence"),
-                    refine=self.parameters.get("centroid_refine"),
-                )
-            elif spect.ms_level == 2:
-                spect = spect.centroid(
-                    algo=centroid_algo,
-                    tolerance=self.parameters.get("mz_tol_ms2_da"),
-                    ppm=self.parameters.get("mz_tol_ms2_ppm"),
-                    min_points=self.parameters.get("centroid_min_points_ms2"),
-                    smooth=self.parameters.get("centroid_smooth"),
-                    prominence=self.parameters.get("centroid_prominence"),
-                    refine=self.parameters.get("centroid_refine"),
-                )
-
-    else:
-        self.logger.error(
-            f"File interface {self.file_interface} not supported. Reload data.",
-        )
-        return spec0
-
-    if precursor_trim is not None and spect.ms_level > 1:
-        spect = spect.trim(mz_min=None, mz_max=spect.precursor_mz - precursor_trim)  # type: ignore[attr-defined]
-    if deisotope:
-        spect = spect.deisotope()
-
-    if max_peaks is not None:
-        spect = spect.keep_top(max_peaks)
-
-    if dia_stats:
-        if self.file_type in ["ztscan", "dia"]:
-            spect = self._get_ztscan_stats(
-                spec=spect,
-                scan_uid=scan_uid,
-                feature_uid=scan_info["feature_uid"][0]
-                if "feature_uid" in scan_info
-                and scan_info["feature_uid"][0] is not None
-                else feature_uid,
-                q1_step=2,
-                deisotope=deisotope,
-                centroid=centroid,
-            )
-    return spect
-
-
-def _get_ztscan_stats(
-    self,
-    spec,
-    scan_uid=None,
-    feature_uid=None,
-    q1_step=2,
-    mz_tol=0.005,
-    # TODO check this
-    # deisotope=SpectrumParameters().deisotope,
-    deisotope=False,
-    # TODO there is no `centroid_algo`?
-    centroid=True,
-):
-    spec.size = spec.mz.size
-    # spec.ms_entropy = spec.entropy()
-
-    if self.scans_df is None:
-        self.logger.warning("No scans found.")
-        return spec
-    scan = self.scans_df.filter(pl.col("scan_uid") == scan_uid)
-    if len(scan) == 0:
-        self.logger.warning(f"Scan {scan_uid} not found.")
-        return spec
-    scan = scan[0]
-    if scan["ms_level"][0] != 2:
-        self.logger.warning(f"Scan {scan_uid} is not a MS2 scan.")
-    # Q1
-    lscan = self.scans_df.filter(pl.col("scan_uid") == scan_uid - q1_step)
-    if len(lscan) == 0:
-        self.logger.warning(f"Scan {scan_uid - q1_step} not found.")
-        return spec
-    lscan = lscan[0]
-    # check that lscan['ms_level'] == 2 and lscan['cycle'] == scan['cycle']
-    if lscan["ms_level"][0] != 2:
-        self.logger.warning(f"Scan {scan_uid - q1_step} is not a MS2 scan.")
-        return spec
-    if lscan["cycle"][0] != scan["cycle"][0]:
-        self.logger.warning(
-            f"Scan {scan_uid - q1_step} is not in the same cycle as scan {scan_uid}.",
-        )
-        return spec
-    rscan = self.scans_df.filter(pl.col("scan_uid") == scan_uid + q1_step)
-    if len(rscan) == 0:
-        self.logger.warning(f"Scan {scan_uid + q1_step} not found.")
-        return spec
-    rscan = rscan[0]
-    # check that rscan['ms_level'] == 2 and rscan['cycle'] == scan['cycle']
-    if rscan["ms_level"][0] != 2:
-        self.logger.warning(f"Scan {scan_uid + q1_step} is not a MS2 scan.")
-        return spec
-    if rscan["cycle"][0] != scan["cycle"][0]:
-        self.logger.warning(
-            f"Scan {scan_uid + q1_step} is not in the same cycle as scan {scan_uid}.",
-        )
-        return spec
-    intymat = self._spec_to_mat(
-        scan_uids=[scan_uid - q1_step, scan_uid, scan_uid + q1_step],
-        mz_ref=spec.mz,
-        mz_tol=mz_tol,
-        deisotope=deisotope,
-        centroid=centroid,
-    )
-    # pick only mzs that are close to spec.mz
-    if intymat is None:
-        return spec
-    if intymat.shape[1] < 3:
-        self.logger.warning(f"Not enough data points for scan {scan_uid}.")
-        return spec
-    q1_ratio = (2 * intymat[:, 1] + 0.01) / (intymat[:, 0] + intymat[:, 2] + 0.01)
-    spec.q1_ratio = np.log2(q1_ratio)
-    # where intymat[:, 0] + intymat[:, 2]==0, set q1_ratio to -1
-    spec.q1_ratio[np.isclose(intymat[:, 0] + intymat[:, 2], 0)] = -10
-
-    # EIC correlation
-    # find rt_start and rt_end of the feature_uid
-    if self.features_df is None:
-        self.logger.warning("No features found.")
-        return spec
-    if feature_uid is None:
-        return spec
-    # spec.precursor_mz = feature['mz']
-    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 spec
-    feature = feature.row(0, named=True)
-    rt_start = feature["rt_start"]
-    rt_end = feature["rt_end"]
-    # get the cycle at rt_start and the cycle at rt_end from the closest scan with ms_level == 1
-    scans = self.scans_df.filter(pl.col("ms_level") == 1)
-    scans = scans.filter(pl.col("rt") > rt_start)
-    scans = scans.filter(pl.col("rt") < rt_end)
-    if len(scans) == 0:
-        self.logger.warning(f"No scans found between {rt_start} and {rt_end}.")
-        return spec
-    scan_uids = scans["scan_uid"].to_list()
-    eic_prec = self._spec_to_mat(
-        scan_uids=scan_uids,
-        mz_ref=feature["mz"],
-        mz_tol=mz_tol,
-        deisotope=deisotope,
-        centroid=centroid,
-    )
-    # find width at half maximum of the eic_prec
-    # hm = np.max(eic_prec[0, :]) / 3
-    # find index of maximum
-    # eic_prec_max_idx = np.argmax(eic_prec[0, :])
-    # find index of the closest point to half maximum
-    # idx = np.argmin(np.abs(eic_prec[0, :] - hm))
-    # eic_fwhm_prec = abs(eic_prec_max_idx - idx)
-
-    # get all unique cycles from scans
-    cycles = scans["cycle"].unique()
-    scandids = []
-    # iterate over all cycles and get the scan_uid of scan with ms_level == 2 and closest precursor_mz to spec.precursor_mz
-    for cycle in cycles:
-        scans = self.scans_df.filter(pl.col("cycle") == cycle)
-        scans = scans.filter(pl.col("ms_level") == 2)
-        scans = scans.filter(pl.col("prec_mz") > feature["mz"] - 4)
-        scans = scans.filter(pl.col("prec_mz") < feature["mz"] + 4)
-        if len(scans) == 0:
-            self.logger.warning(f"No scans found for cycle {cycle}.")
-            continue
-        scan = scans[(scans["prec_mz"] - feature["mz"]).abs().arg_sort()[:1]]
-        scandids.append(scan["scan_uid"][0])
-
-    eic_prod = self._spec_to_mat(
-        scandids,
-        mz_ref=spec.mz,
-        mz_tol=mz_tol,
-        deisotope=deisotope,
-        centroid=centroid,
-    )
-    # eic_prod = eic_prod.T
-    # eic_prec = eic_prec.T
-    # calculate correlation between eic_prec and all columns of eic_prod, column by column
-    eic_corr = np.zeros(eic_prod.shape[0])
-    # eic_width_ratio = np.zeros(eic_prod.shape[0])
-    for i in range(eic_prod.shape[0]):
-        try:
-            with np.errstate(divide="ignore", invalid="ignore"):
-                eic_corr[i] = np.corrcoef(eic_prod[i, :], eic_prec[0, :])[0, 1]
-        except:
-            pass
-
-    spec.eic_corr = eic_corr
-    return spec
-
-
-def _spec_to_mat(
-    self,
-    scan_uids,
-    mz_ref=None,
-    mz_tol=0.01,
-    # TODO check this
-    # deisotope=SpectrumParameters().deisotope,
-    deisotope=False,
-    # TODO there is no `centroid_algo`?
-    # TODO there is no `dia_stats`?
-    # TODO unused (see below)
-    centroid=True,
-    # TODO check this
-    # precursor_trim=SpectrumParameters().precursor_trim,
-    # TODO unused (see below)
-    precursor_trim=None,
-):
-    # get all spectra in scan_uids
-
-    if mz_ref is None:
-        return None
-
-    if not isinstance(mz_ref, np.ndarray):
-        if isinstance(mz_ref, list):
-            mz_ref = np.array(mz_ref)
-        else:
-            mz_ref = np.array([mz_ref])
-
-    def align_mzs(ar1, ar2, tol):
-        closest_indices = []
-        # find the closest pair between each element in ar1 and ar2, within a maximum tolerance of tol
-        for i, val1 in enumerate(ar1):
-            closest_index = np.argmin(np.abs(ar2 - val1))
-            closest_indices.append((i, closest_index))
-        # filter out pairs that are not within the specified tolerance
-        closest_indices = [
-            (i, j) for i, j in closest_indices if np.abs(ar1[i] - ar2[j]) <= tol
-        ]
-        # remove duplicates from the list of indices
-        closest_indices = list(set(closest_indices))
-        # sort the list of indices by the first element (i) in ascending order
-        closest_indices = sorted(closest_indices, key=lambda x: x[0])
-
-        # Convert the list of indices into an array for easier indexing in subsequent operations
-        return np.array(closest_indices)
-
-    specs = []
-    for scan_uid in scan_uids:
-        spec = self.get_spectrum(
-            scan_uid=scan_uid,
-            centroid=True,
-            dia_stats=False,
-            precursor_trim=5,
-        )
-        if deisotope:
-            spec = spec.deisotope()
-        # align to reference spectrum
-        if spec.mz.size == 0:
-            continue
-        if mz_ref.size == 0:
-            continue
-        closest_indices = align_mzs(spec.mz, mz_ref, mz_tol)
-        # store the aligned spectrum in the list
-        aligned_inty = np.zeros(len(mz_ref))
-        for i, j in closest_indices:
-            if abs(spec.mz[i] - mz_ref[j]) <= mz_tol:
-                if aligned_inty[j] < spec.inty[i]:
-                    aligned_inty[j] = spec.inty[i]
-        specs.append(aligned_inty)
-
-    if len(specs) == 0:
-        return None
-    # create a matrix with the aligned spectra. Each spec goes into a column
-    mat = np.column_stack(specs)
-
-    return mat
-
-
-def find_features(self, **kwargs):
-    """
-    Detect features in mass spectrometry data by processing MS1 spectra, performing mass trace detection,
-    elution peak detection, and feature detection. Optionally, deisotope features and remove low-quality peaks.
-
-    This method leverages an MSExperiment constructed from the object's ms1_df, where each cycle in the data
-    corresponds to an MSSpectrum. It then runs mass trace detection using set parameters, deconvolutes the mass
-    traces to detect chromatographic peaks, and finally identifies features with a feature finding algorithm. The
-    resulting feature map is cleaned, deisotoped (if enabled), and assigned unique IDs before being stored.
-
-    Parameters:
-        **kwargs: Keyword arguments for feature detection parameters. Can include:
-            - A find_features_defaults instance to set all parameters at once
-            - Individual parameter names and values (see find_features_defaults for details)
-
-    Key Parameters:
-        tol_ppm (float): Mass error tolerance in parts-per-million for mass trace detection (default: 30.0).
-        noise (float): Noise threshold intensity to filter out low-intensity signals (default: 200.0).
-        chrom_fwhm (float): Full width at half maximum for chromatographic peak shape (default: 1.0).
-        chrom_fwhm_min (float): Minimum FWHM for chromatographic peak detection (default: 0.5).
-        chrom_peak_snr (float): Signal-to-noise ratio required for chromatographic peaks (default: 10.0).
-        mz_scoring_13C (bool): Whether to enable scoring of 13C isotopic patterns (default: False).
-        masstrace_snr_filtering (bool): Whether to apply SNR filtering to mass traces (default: False).
-        deisotope (bool): Whether to perform deisotoping of detected features (default: True).
-
-    Attributes set:
-        self.features: An updated feature map with unique IDs after feature detection and deisotoping.
-        self.features_df: A cleaned DataFrame of features, with peaks of zero quality removed, representing the final
-                            detected features.
-
-    Notes:
-        - The method processes the ms1_df by iterating over cycles to build an MSExperiment.
-        - External OMS modules (e.g., MSExperiment, MSSpectrum, MassTraceDetection, ElutionPeakDetection,
-            FeatureFindingMetabo) are used throughout the processing.
-        - After feature detection, additional cleaning is performed via internal helper methods.
-    """
-    if self.ms1_df is None:
-        self.logger.error("No MS1 data found. Please load a file first.")
-        return
-    if len(self.ms1_df) == 0:
-        self.logger.error("MS1 data is empty. Please load a file first.")
-        return
-    # parameters initialization
-    params = find_features_defaults()
-    for key, value in kwargs.items():
-        if isinstance(value, find_features_defaults):
-            # set
-            params = value
-            self.logger.debug("Using provided find_features_defaults parameters")
-        else:
-            if hasattr(params, key):
-                if params.set(key, value, validate=True):
-                    self.logger.debug(f"Updated parameter {key} = {value}")
-                else:
-                    self.logger.warning(
-                        f"Failed to set parameter {key} = {value} (validation failed)",
-                    )
-            else:
-                self.logger.warning(f"Unknown parameter {key} ignored")
-
-    self.logger.debug("Starting feature detection...")
-    self.logger.debug(
-        f"Parameters: chrom_fwhm={params.get('chrom_fwhm')}, noise={params.get('noise')}, tol_ppm={params.get('tol_ppm')}",
-    )
-
-    exp = oms.MSExperiment()
-    # find max number of cycles in self.ms1_df
-    max_cycle = self.ms1_df["cycle"].max()
-    # iterate over all cycles, find rows with 1 cycle and append to exp2
-    for cycle in range(1, max_cycle + 1):
-        cycle_df = self.ms1_df.filter(pl.col("cycle") == cycle)
-        # check if len(cycle_df) > 0
-        if len(cycle_df) > 0:
-            spectrum = oms.MSSpectrum()
-            spectrum.setRT(cycle_df[0]["rt"].item())
-            spectrum.setMSLevel(1)  # MS1
-            mz = cycle_df["mz"]
-            inty = cycle_df["inty"]
-            spectrum.set_peaks([mz, inty])  # type: ignore[attr-defined]
-            spectrum.sortByPosition()
-            exp.addSpectrum(spectrum)
-
-    # exp.sortSpectra(True)
-    # mass trace detection
-    mass_traces: list = []
-    mtd = oms.MassTraceDetection()
-    mtd_par = mtd.getDefaults()
-
-    # Apply MTD parameters
-    mtd_par.setValue("mass_error_ppm", float(params.get("tol_ppm")))
-    mtd_par.setValue("noise_threshold_int", float(params.get("noise")))
-    mtd_par.setValue(
-        "min_trace_length",
-        float(params.get("min_trace_length_multiplier"))
-        * float(params.get("chrom_fwhm_min")),
-    )
-    mtd_par.setValue(
-        "trace_termination_outliers",
-        int(params.get("trace_termination_outliers")),
-    )
-    mtd_par.setValue("chrom_peak_snr", float(params.get("chrom_peak_snr")))
-
-    mtd.setParameters(mtd_par)  # set the new parameters
-    mtd.run(exp, mass_traces, 0)  # run mass trace detection
-
-    # elution peak detection
-    mass_traces_deconvol: list = []
-    epd = oms.ElutionPeakDetection()
-    epd_par = epd.getDefaults()
-
-    # Apply EPD parameters using our parameter class
-    epd_par.setValue("width_filtering", params.get("width_filtering"))
-    epd_par.setValue("min_fwhm", float(params.get("chrom_fwhm_min")))
-    epd_par.setValue("chrom_fwhm", float(params.get("chrom_fwhm")))
-    epd_par.setValue("chrom_peak_snr", float(params.get("chrom_peak_snr")))
-    if params.get("masstrace_snr_filtering"):
-        epd_par.setValue("masstrace_snr_filtering", "true")
-    if params.get("mz_scoring_13C"):
-        epd_par.setValue("mz_scoring_13C", "true")
-
-    epd.setParameters(epd_par)
-    epd.detectPeaks(mass_traces, mass_traces_deconvol)
-
-    # feature detection
-    feature_map = oms.FeatureMap()  # output features
-    chrom_out: list = []  # output chromatograms
-    ffm = oms.FeatureFindingMetabo()
-    ffm_par = ffm.getDefaults()
-
-    # Apply FFM parameters using our parameter class
-    ffm_par.setValue(
-        "remove_single_traces",
-        "true" if params.get("remove_single_traces") else "false",
-    )
-    ffm_par.setValue(
-        "report_convex_hulls",
-        "true" if params.get("report_convex_hulls") else "false",
-    )
-    ffm_par.setValue(
-        "report_summed_ints",
-        "true" if params.get("report_summed_ints") else "false",
-    )
-    ffm_par.setValue(
-        "report_chromatograms",
-        "true" if params.get("report_chromatograms") else "false",
-    )
-
-    ffm.setParameters(ffm_par)
-    self.logger.debug("Running feature finding with parameters:")
-    self.logger.debug(ffm_par)
-    ffm.run(mass_traces_deconvol, feature_map, chrom_out)
-    # Assigns a new, valid unique id per feature
-    feature_map.ensureUniqueId()
-    df = feature_map.get_df(export_peptide_identifications=False)  # type: ignore[attr-defined]
-    # Sets the file path to the primary MS run (usually the mzML file)
-    feature_map.setPrimaryMSRunPath([self.file_path.encode()])
-    self.features = feature_map
-    # remove peaks with quality == 0
-    df = self._clean_features_df(df)
-
-    # desotope features
-    df = self._features_deisotope(
-        df,
-        mz_tol=params.get("deisotope_mz_tol"),
-        rt_tol=params.get("chrom_fwhm_min") / 4 * params.get("deisotope_rt_tol_factor"),
-    )
-    if params.get("deisotope"):
-        # record size before deisotoping
-        size_before_deisotope = len(df)
-        df = df.filter(pl.col("iso") == 0)
-        self.logger.debug(
-            f"Deisotoping features: {size_before_deisotope - len(df)} features removed.",
-        )
-
-    # update eic - create lists to collect results
-    chroms: list[Chromatogram] = []
-    coherences: list[float] = []
-    prominences: list[float] = []
-    prominence_scaleds: list[float] = []
-    height_scaleds: list[float] = []
-
-    mz_tol = params.get("eic_mz_tol")
-    rt_tol = params.get("eic_rt_tol")
-
-    # iterate over all rows in df using polars iteration
-    self.logger.debug("Extracting EICs...")
-    for row in df.iter_rows(named=True):
-        # select data in ms1_df with mz in range [mz_start - mz_tol, mz_end + mz_tol] and rt in range [rt_start - rt_tol, rt_end + rt_tol]
-        d = self.ms1_df.filter(
-            (pl.col("rt") >= row["rt_start"] - rt_tol)
-            & (pl.col("rt") <= row["rt_end"] + rt_tol)
-            & (pl.col("mz") >= row["mz"] - mz_tol)
-            & (pl.col("mz") <= row["mz"] + mz_tol),
-        )
-        # for all unique rt values, find the maximum inty
-        eic_rt = d.group_by("rt").agg(pl.col("inty").max())
-        if len(eic_rt) < 4:
-            chroms.append(None)
-            coherences.append(None)
-            prominences.append(None)
-            prominence_scaleds.append(None)
-            height_scaleds.append(None)
-            continue
-
-        eic = Chromatogram(
-            eic_rt["rt"].to_numpy(),
-            eic_rt["inty"].to_numpy(),
-            label=f"EIC mz={row['mz']:.4f}",
-            file=self.file_path,
-            mz=row["mz"],
-            mz_tol=mz_tol,
-            feature_start=row["rt_start"],
-            feature_end=row["rt_end"],
-            feature_apex=row["rt"],
-        ).find_peaks()
-
-        # collect results
-        chroms.append(eic)
-        if len(eic.peak_widths) > 0:
-            coherences.append(round(eic.feature_coherence, 3))
-            prominences.append(round(eic.peak_prominences[0], 3))
-            prominence_scaleds.append(
-                round(eic.peak_prominences[0] / (np.mean(eic.inty) + 1e-10), 3),
-            )
-            height_scaleds.append(
-                round(eic.peak_heights[0] / (np.mean(eic.inty) + 1e-10), 3),
-            )
-        else:
-            coherences.append(None)
-            prominences.append(None)
-            prominence_scaleds.append(None)
-            height_scaleds.append(None)
-
-    # Add the computed columns to the dataframe
-    df = df.with_columns([
-        pl.Series("chrom", chroms, dtype=pl.Object),
-        pl.Series("chrom_coherence", coherences, dtype=pl.Float64),
-        pl.Series("chrom_prominence", prominences, dtype=pl.Float64),
-        pl.Series("chrom_prominence_scaled", prominence_scaleds, dtype=pl.Float64),
-        pl.Series("chrom_height_scaled", height_scaleds, dtype=pl.Float64),
-    ])
-
-    self.features_df = df
-    self.logger.info(f"Feature detection completed. Total features: {len(df)}")
-
-    # store params
-    self.store_history(["find_features"], params.to_dict())
-    self.logger.debug(
-        "Parameters stored to find_features",
-    )
-    keys_to_remove = ["find_adducts", "find_ms2"]
-    for key in keys_to_remove:
-        if key in self.history:
-            del self.history[key]
-            self.logger.debug(f"Removed {key} from history")
-
-
-def find_adducts(self, **kwargs):
-    """
-    Detect adducts in mass spectrometry features using OpenMS MetaboliteFeatureDeconvolution.
-
-    This method analyzes detected features to identify adduct relationships based on mass differences,
-    charge states, and retention time proximity. It groups features that likely represent the same
-    metabolite in different ionization states.
-
-    Parameters:
-        **kwargs: Keyword arguments for adduct detection parameters. Can include:
-            - A find_adducts_defaults instance to set all parameters at once
-            - Individual parameter names and values (see find_adducts_defaults for details)
-
-    Key Parameters:
-        adducts (Union[List[str], str, None]): List of potential adducts or ionization mode string.
-        charge_min (int): Minimal possible charge state (default: 1).
-        charge_max (int): Maximal possible charge state (default: 2).
-        retention_max_diff (float): Maximum retention time difference for grouping (default: 1.0).
-
-    Attributes set:
-        self.features_df: Updated with adduct information including 'adduct', 'adduct_mass',
-                         and 'adduct_group' columns.
-    """
-    params = find_adducts_defaults()
-    for key, value in kwargs.items():
-        if isinstance(value, find_adducts_defaults):
-            # set
-            params = value
-            self.logger.debug("Using provided find_adducts_defaults parameters")
-        else:
-            if hasattr(params, key):
-                if params.set(key, value, validate=True):
-                    self.logger.debug(f"Updated parameter {key} = {value}")
-                else:
-                    self.logger.warning(
-                        f"Failed to set parameter {key} = {value} (validation failed)",
-                    )
-            else:
-                self.logger.warning(f"Unknown parameter {key} ignored")
-
-    self.logger.debug("Starting adduct detection...")
-    self.logger.debug(
-        f"Parameters: adducts={params.get('adducts')}, charge_min={params.get('charge_min')}, charge_max={params.get('charge_max')}",
-    )
-
-    mfd = oms.MetaboliteFeatureDeconvolution()
-
-    openms_params = mfd.getDefaults()
-
-    # Set adducts using the helper method
-    adducts_list = params.get_openms_adducts()
-    openms_params.setValue("potential_adducts", [a.encode() for a in adducts_list])
-
-    # Apply other parameters
-    openms_params.setValue("charge_min", params.get("charge_min"))
-    openms_params.setValue("charge_max", params.get("charge_max"))
-    openms_params.setValue("charge_span_max", params.get("charge_span_max"))
-    openms_params.setValue("retention_max_diff", params.get("retention_max_diff"))
-    openms_params.setValue(
-        "retention_max_diff_local",
-        params.get("retention_max_diff_local"),
-    )
-
-    # set updated parameters object
-    mfd.setParameters(openms_params)
-    self.logger.debug("Running adduct detection with parameters:")
-    self.logger.debug(openms_params)
-    # result feature map: will store features with adduct information
-    feature_map_MFD = oms.FeatureMap()
-    # result consensus map: will store grouped features belonging to a charge group
-    groups = oms.ConsensusMap()
-    # result consensus map: will store paired features connected by an edge
-    edges = oms.ConsensusMap()
-
-    # compute adducts
-    mfd.compute(self.features, feature_map_MFD, groups, edges)
-    self.logger.debug("Extracting information.")
-
-    # export feature map as pandas DataFrame and append adduct information
-    adducts_map = feature_map_MFD.get_df(export_peptide_identifications=False)  # type: ignore[attr-defined]
-    adducts_map["adduct"] = [
-        f.getMetaValue("dc_charge_adducts") for f in feature_map_MFD
-    ]
-    adducts_map["adduct_group_id"] = [f.getMetaValue("Group") for f in feature_map_MFD]
-    adducts_map["adduct_mass"] = [
-        f.getMetaValue("dc_charge_adduct_mass") for f in feature_map_MFD
-    ]
-    # clean up the DataFrame
-
-    # Clean up 'None' strings that should be actual None values from OpenMS getMetaValue
-    for col in ["adduct", "adduct_group_id", "adduct_mass"]:
-        if col in adducts_map.columns:
-            adducts_map[col] = adducts_map[col].replace("None", None)
-
-    # Convert adducts_map to polars and merge
-    adducts_df = pl.DataFrame({
-        "index": range(len(adducts_map)),
-        "adduct": adducts_map["adduct"],
-        "adduct_mass": adducts_map["adduct_mass"],
-        "adduct_group_id": adducts_map["adduct_group_id"],
-    })
-    features_pl = (
-        self.features_df
-        if isinstance(self.features_df, pl.DataFrame)
-        else pl.from_pandas(self.features_df)
-    )
-
-    # Remove existing adduct columns if they exist (likely all null)
-    if "adduct" in features_pl.columns:
-        features_pl = features_pl.drop("adduct")
-    if "adduct_mass" in features_pl.columns:
-        features_pl = features_pl.drop("adduct_mass")
-    if "adduct_group" in features_pl.columns:
-        features_pl = features_pl.drop("adduct_group")
-
-    df = features_pl.join(
-        adducts_df,
-        left_on="feature_uid",
-        right_on="index",
-        how="left",
-    )
-
-    # Create adduct_group from adduct_group_id column
-    unique_groups = df["adduct_group_id"].unique().to_list()
-    group_mapping = {group: idx for idx, group in enumerate(unique_groups)}
-    df = df.with_columns(
-        pl.col("adduct_group_id")
-        .map_elements(lambda x: group_mapping.get(x, 0), return_dtype=pl.Int64)
-        .alias("adduct_group"),
-    )
-
-    # remove adduct_group_id
-    df = df.drop("adduct_group_id")
-    # move adduct, adduct_mass, and adduct_group after column iso_of
-    if "iso_of" in df.columns:
-        adduct_cols = ["adduct", "adduct_mass", "adduct_group"]
-        # Get all column names and reorder them
-        all_cols = df.columns
-        iso_of_idx = all_cols.index("iso_of")
-
-        # Create new column order: everything before iso_of, then iso_of, then adduct columns, then the rest
-        new_order = []
-        # columns up to and including iso_of
-        new_order.extend(all_cols[: iso_of_idx + 1])
-        # adduct columns that exist
-        new_order.extend([col for col in adduct_cols if col in all_cols])
-        new_order.extend([
-            col for col in all_cols[iso_of_idx + 1 :] if col not in adduct_cols
-        ])  # remaining columns
-
-        df = df.select(new_order)
-    # Update the features_df attribute with the new DataFrame
-
-    self.features_df = df
-    total_adducts = df.filter(pl.col("adduct").is_not_null()).shape[0]
-    self.logger.info(f"Adduct detection completed. Total adducts: {total_adducts}")
-
-    # store params
-    self.store_history(["find_adducts"], params.to_dict())
-    self.logger.debug(
-        "Parameters stored to find_adducts",
-    )
-
-
-def _clean_features_df(self, df):
-    # Convert pandas DataFrame to polars if needed
-    df["feature_id"] = df.index
-    if hasattr(df, "columns") and not isinstance(df, pl.DataFrame):
-        df_pl = pl.from_pandas(df)
-    else:
-        df_pl = df
-
-    # Filter out rows with quality == 0
-    df2 = df_pl.filter(pl.col("quality") != 0)
-
-    # Create new dataframe with required columns and transformations using select
-    df_result = df2.select([
-        pl.int_range(pl.len()).alias("feature_uid"),
-        pl.col("feature_id").cast(pl.String).alias("feature_id"),
-        pl.col("mz").round(5),
-        pl.col("RT").round(3).alias("rt"),
-        pl.col("RT").round(3).alias("rt_original"),  # keep original RT
-        pl.col("RTstart").round(3).alias("rt_start"),
-        pl.col("RTend").round(3).alias("rt_end"),
-        (pl.col("RTend") - pl.col("RTstart")).round(3).alias("rt_delta"),
-        pl.col("MZstart").round(5).alias("mz_start"),
-        pl.col("MZend").round(5).alias("mz_end"),
-        pl.col("intensity").alias("inty"),
-        pl.col("quality"),
-        pl.col("charge"),
-        pl.lit(0).alias("iso"),
-        pl.lit(None, dtype=pl.Int64).alias("iso_of"),
-        pl.lit(None, dtype=pl.Int64).alias("adduct_group"),
-        pl.lit(None, dtype=pl.Utf8).alias("adduct"),
-        pl.lit(None, dtype=pl.Float64).alias("adduct_mass"),
-        pl.lit(None, dtype=pl.Object).alias("chrom"),
-        pl.lit(None, dtype=pl.Float64).alias("chrom_coherence"),
-        pl.lit(None, dtype=pl.Float64).alias("chrom_prominence"),
-        pl.lit(None, dtype=pl.Float64).alias("chrom_prominence_scaled"),
-        pl.lit(None, dtype=pl.Float64).alias("chrom_height_scaled"),
-        pl.lit(None, dtype=pl.Object).alias("ms2_scans"),
-        pl.lit(None, dtype=pl.Object).alias("ms2_specs"),
-    ])
-
-    return df_result
-
-
-def _features_deisotope(
-    self,
-    df,
-    mz_tol=None,
-    rt_tol=None,
-):
-    if mz_tol is None:
-        mz_tol = 0.02
-    if rt_tol is None:
-        rt_tol = 0.2
-
-    # Convert to polars if needed
-    if not isinstance(df, pl.DataFrame):
-        df = pl.from_pandas(df)
-
-    # Initialize new columns
-    df = df.with_columns([
-        pl.lit(0).alias("iso"),
-        pl.col("feature_uid").alias("iso_of"),
-    ])
-
-    # Sort by 'mz'
-    df = df.sort("mz")
-
-    # Get arrays for efficient processing
-    rt_arr = df["rt"].to_numpy()
-    mz_arr = df["mz"].to_numpy()
-    intensity_arr = df["inty"].to_numpy()
-    feature_uid_arr = df["feature_uid"].to_numpy()
-    n = len(df)
-    mz_diff = 1.003355
-
-    # Create arrays to track isotope assignments
-    iso_arr = np.zeros(n, dtype=int)
-    iso_of_arr = feature_uid_arr.copy()
-
-    for i in range(n):
-        base_rt = rt_arr[i]
-        base_mz = mz_arr[i]
-        base_int = intensity_arr[i]
-        base_feature_uid = feature_uid_arr[i]
-
-        # Search for first isotope candidate (offset = mz_diff)
-        t1_lower = base_mz + mz_diff - mz_tol
-        t1_upper = base_mz + mz_diff + mz_tol
-        li = np.searchsorted(mz_arr, t1_lower, side="left")
-        ri = np.searchsorted(mz_arr, t1_upper, side="right")
-        if li < ri:
-            cand_idx = np.arange(li, ri)
-            mask = (
-                (rt_arr[cand_idx] > base_rt - rt_tol)
-                & (rt_arr[cand_idx] < base_rt + rt_tol)
-                & (intensity_arr[cand_idx] < 2 * base_int)
-            )
-            valid_cand = cand_idx[mask]
-            for cand in valid_cand:
-                if cand != i and iso_of_arr[cand] == feature_uid_arr[cand]:
-                    iso_arr[cand] = iso_arr[i] + 1  # first isotope
-                    iso_of_arr[cand] = base_feature_uid
-
-        # Search for second isotope candidate (offset = 2*mz_diff)
-        t2_lower = base_mz + 2 * mz_diff - 1.5 * mz_tol
-        t2_upper = base_mz + 2 * mz_diff + 1.5 * mz_tol
-        li = np.searchsorted(mz_arr, t2_lower, side="left")
-        ri = np.searchsorted(mz_arr, t2_upper, side="right")
-        if li < ri:
-            cand_idx = np.arange(li, ri)
-            mask = (
-                (rt_arr[cand_idx] > base_rt - rt_tol)
-                & (rt_arr[cand_idx] < base_rt + rt_tol)
-                & (intensity_arr[cand_idx] < 2 * base_int)
-            )
-            valid_cand = cand_idx[mask]
-            for cand in valid_cand:
-                if cand != i and iso_of_arr[cand] == feature_uid_arr[cand]:
-                    iso_arr[cand] = iso_arr[i] + 2  # second isotope
-                    iso_of_arr[cand] = base_feature_uid
-
-        # Search for third isotope candidate (offset = 3*mz_diff)
-        t3_lower = base_mz + 3 * mz_diff - 1.5 * mz_tol
-        t3_upper = base_mz + 3 * mz_diff + 1.5 * mz_tol
-        li = np.searchsorted(mz_arr, t3_lower, side="left")
-        ri = np.searchsorted(mz_arr, t3_upper, side="right")
-        if li < ri:
-            cand_idx = np.arange(li, ri)
-            mask = (
-                (rt_arr[cand_idx] > base_rt - rt_tol)
-                & (rt_arr[cand_idx] < base_rt + rt_tol)
-                & (intensity_arr[cand_idx] < 2 * base_int)
-            )
-            valid_cand = cand_idx[mask]
-            for cand in valid_cand:
-                if cand != i and iso_of_arr[cand] == feature_uid_arr[cand]:
-                    iso_arr[cand] = iso_arr[i] + 3  # third isotope
-                    iso_of_arr[cand] = base_feature_uid
-
-    # Update the dataframe with isotope assignments
-    df = df.with_columns([
-        pl.Series("iso", iso_arr),
-        pl.Series("iso_of", iso_of_arr),
-    ])
-
-    return df
-
-
-def analyze_dda(self):
-    # Preallocate variables
-    cycle_records = []
-    previous_rt = 0
-    previous_level = 0
-    ms1_index = None
-    cyclestart = None
-    ms2_n = 0
-    ms1_duration = 0
-    ms2_duration: list[float] = []
-
-    for row in self.scans_df.iter_rows(named=True):
-        if row["ms_level"] == 1:
-            if previous_level == 2:
-                ms2_to_ms2 = float(np.mean(ms2_duration)) if ms2_duration else -1.0
-                d = {
-                    "scan_uid": ms1_index,
-                    "ms2_n": ms2_n,
-                    "time_cycle": row["rt"] - cyclestart,
-                    "time_ms1_to_ms1": -1.0,
-                    "time_ms1_to_ms2": ms1_duration,
-                    "time_ms2_to_ms2": ms2_to_ms2,
-                    "time_ms2_to_ms1": row["rt"] - previous_rt,
-                }
-                cycle_records.append(d)
-            elif previous_level == 1:
-                d = {
-                    "scan_uid": ms1_index,
-                    "ms2_n": 0,
-                    "time_cycle": row["rt"] - cyclestart,
-                    "time_ms1_to_ms1": row["rt"] - cyclestart,
-                    "time_ms1_to_ms2": -1.0,
-                    "time_ms2_to_ms2": -1.0,
-                    "time_ms2_to_ms1": -1.0,
-                }
-                cycle_records.append(d)
-
-            ms1_index = row["scan_uid"]
-            cyclestart = row["rt"]
-            ms2_n = 0
-            ms1_duration = 0
-            ms2_duration = []
-        elif previous_level == 2:
-            ms2_n += 1
-            ms2_duration.append(row["rt"] - previous_rt)
-        elif previous_level == 1:
-            ms1_duration = row["rt"] - cyclestart
-            ms2_n += 1
-        previous_level = row["ms_level"]
-        previous_rt = row["rt"]
-
-    # Create DataFrame once at the end
-    if cycle_records:
-        cycle_data = pl.DataFrame(cycle_records)
-        self.scans_df = self.scans_df.join(cycle_data, on="scan_uid", how="left")
-    else:
-        self.scans_df = self.scans_df.with_columns(
-            [
-                pl.lit(None).alias("ms2_n"),
-                pl.lit(None).alias("time_cycle"),
-                pl.lit(None).alias("time_ms1_to_ms1"),
-                pl.lit(None).alias("time_ms1_to_ms2"),
-                pl.lit(None).alias("time_ms2_to_ms2"),
-                pl.lit(None).alias("time_ms2_to_ms1"),
-            ],
-        )
-
-
-def find_ms2(self, **kwargs):
-    """
-    Link MS2 spectra to features in the dataset.
-    This method matches MS2 spectra from the scans dataframe with features in the features dataframe
-    based on retention time (RT) and precursor m/z tolerance criteria. For each feature in the provided
-    or inferred list of feature ids (feature_uid), it computes the RT difference between the feature and available
-    MS2 spectra. It then selects MS2 spectra that fall within a computed RT radius (based on the feature's
-    start and end times) and a specified m/z tolerance. For each feature, it chooses one MS2 spectrum per
-    unique cycle based on the closest RT difference, and it updates the feature with the list of matched
-    scan ids and the spectrum corresponding to the first matching scan id. Additionally, the scan dataframe
-    is updated to associate matched scan ids with the corresponding feature id.
-
-    Parameters:
-        **kwargs: Keyword arguments for MS2 linking parameters. Can include:
-            - A find_ms2_defaults instance to set all parameters at once
-            - Individual parameter names and values (see find_ms2_defaults for details)
-
-    Key Parameters:
-        features (int or list of int, optional): A specific feature id or a list of feature ids to process.
-            If an individual feature_uid is provided and equals -1, all features with no associated MS2 data will be processed.
-            If None, all features in the features dataframe are processed.
-        mz_tol (float, optional): The precursor m/z tolerance to consider when matching MS2 spectra. If not provided,
-            it defaults to 0.5, except for certain file types ('ztscan' or 'dia') which set it to 4.
-        centroid (bool, optional): If True, the returned spectrum will be centroided. Default is True.
-        deisotope (bool, optional): Flag indicating whether deisotoping should be performed. Default is False.
-        dia_stats (bool, optional): A flag to collect additional DIA-related statistics when retrieving a spectrum.
-            Default is False.
-
-    Returns:
-        None
-
-    Side Effects:
-        Updates self.features_df with new columns 'ms2_scans' (a list of scan ids) and 'ms2_specs' (containing
-        the retrieved spectrum for the first matched scan id). Also, self.scans_df is updated by setting the 'feature_uid'
-        column for matched MS2 spectra.
-
-    Notes:
-        - The function uses vectorized operations to quickly filter MS2 spectra with ms_level equal to 2.
-        - If no MS2 spectra are available or if features_df is not loaded, appropriate messages are printed and the
-            method exits early.
-        - The function assumes that self.features_df and self.scans_df are already set up and contain the expected
-            columns ('feature_uid', 'rt', 'rt_start', 'rt_end', 'mz' for features and 'scan_uid', 'rt', 'prec_mz', 'cycle', 'ms_level'
-            for scans).
-
-    Examples:
-        Assume the current instance has features and scans data loaded, then to link MS2 spectra for all features:
-            instance.find_ms2()
-        To link MS2 spectra for a specific list of feature ids:
-            instance.find_ms2(feature_uid=[1, 3, 5])
-    """
-
-    # parameters initialization
-    params = find_ms2_defaults()
-    for key, value in kwargs.items():
-        if isinstance(value, find_ms2_defaults):
-            params = value
-            self.logger.debug("Using provided find_ms2_defaults parameters")
-        else:
-            if hasattr(params, key):
-                if params.set(key, value, validate=True):
-                    self.logger.debug(f"Updated parameter {key} = {value}")
-                else:
-                    self.logger.warning(
-                        f"Failed to set parameter {key} = {value} (validation failed)",
-                    )
-            else:
-                self.logger.debug(f"Unknown parameter {key} ignored")
-    # end of parameter initialization
-
-    # Extract parameter values
-    features = params.get("features")
-    mz_tol = params.get_mz_tolerance(self.file_type)
-    centroid = params.get("centroid")
-    deisotope = params.get("deisotope")
-    dia_stats = params.get("dia_stats")
-
-    self.logger.debug("Starting MS2 spectra linking...")
-    self.logger.debug(
-        f"Parameters: mz_tol={mz_tol}, centroid={centroid}, deisotope={deisotope}",
-    )
-
-    # Ensure features_df is loaded and has the MS2 columns
-    if self.features_df is None:
-        self.logger.error("Please find features first.")
-        return
-    if "ms2_scans" not in self.features_df.columns:
-        self.features_df["ms2_scans"] = None
-    if "ms2_specs" not in self.features_df.columns:
-        self.features_df["ms2_specs"] = None
-
-    feature_uid_list = []
-    self.logger.debug("Building lookup lists")
-    if features == []:
-        features = None  # If empty list, treat as None
-    feature_uid_list = self._get_feature_uids(features)
-
-    if len(feature_uid_list) == 0:
-        self.logger.warning("No features to process.")
-        return
-
-    ms2_df = self.scans_df.filter(pl.col("ms_level") == 2)
-    if len(ms2_df) == 0:
-        self.logger.warning("No MS2 spectra found in file.")
-        return
-
-    ms2_index_arr = ms2_df["scan_uid"].to_numpy()
-    ms2_rt = ms2_df["rt"].to_numpy()
-    ms2_precursor = ms2_df["prec_mz"].to_numpy()
-    ms2_cycle = ms2_df["cycle"].to_numpy()
-
-    features_df = self.features_df
-    c = 0
-
-    if self.file_interface is None:
-        self.index_file()
-
-    # Vectorize the entire operation for better performance
-    features_subset = features_df.filter(pl.col("feature_uid").is_in(feature_uid_list))
-
-    if len(features_subset) == 0:
-        return
-
-    # Convert to numpy arrays for vectorized operations
-    feature_rt = features_subset.select("rt").to_numpy().flatten()
-    feature_mz = features_subset.select("mz").to_numpy().flatten()
-    feature_rt_start = features_subset.select("rt_start").to_numpy().flatten()
-    feature_rt_end = features_subset.select("rt_end").to_numpy().flatten()
-    feature_uids = features_subset.select("feature_uid").to_numpy().flatten()
-    feature_indices = (
-        features_subset.with_row_index().select("index").to_numpy().flatten()
-    )
-
-    # Pre-compute RT radius for all features
-    rt_radius = np.minimum(feature_rt - feature_rt_start, feature_rt_end - feature_rt)
-
-    # Batch process all features
-    scan_uid_lists: list[list[int]] = []
-    spec_lists: list[list[Spectrum]] = []
-    updated_feature_uids = []
-    updated_scan_uids = []
-
-    tdqm_disable = self.log_level not in ["TRACE", "DEBUG", "INFO"]
-
-    for i, (rt_center, mz_center, radius, feature_uid, idx) in enumerate(
-        tqdm(
-            zip(
-                feature_rt,
-                feature_mz,
-                rt_radius,
-                feature_uids,
-                feature_indices,
-                strict=False,
-            ),
-            total=len(features_subset),
-            desc=f"{datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]} | INFO     | {self.log_label}Link MS2 spectra",
-            disable=tdqm_disable,
-        ),
-    ):
-        # Vectorized filtering
-        rt_mask = np.abs(ms2_rt - rt_center) <= radius
-        mz_mask = np.abs(ms2_precursor - mz_center) <= mz_tol
-        valid_mask = rt_mask & mz_mask
-
-        if not np.any(valid_mask):
-            scan_uid_lists.append(None)
-            spec_lists.append(None)
-            continue
-
-        valid_indices = np.nonzero(valid_mask)[0]
-        rt_diffs = np.abs(ms2_rt[valid_indices] - rt_center)
-        sorted_indices = valid_indices[np.argsort(rt_diffs)]
-
-        # Get unique cycles and their first occurrences
-        cycles = ms2_cycle[sorted_indices]
-        _, first_idx = np.unique(cycles, return_index=True)
-        final_indices = sorted_indices[first_idx]
-
-        # Sort by RT difference again
-        final_rt_diffs = np.abs(ms2_rt[final_indices] - rt_center)
-        final_indices = final_indices[np.argsort(final_rt_diffs)]
-
-        scan_uids = ms2_index_arr[final_indices].tolist()
-        scan_uid_lists.append(scan_uids)
-        spec_lists.append([
-            self.get_spectrum(
-                scan_uids[0],
-                centroid=centroid,
-                deisotope=deisotope,
-                dia_stats=dia_stats,
-                feature_uid=feature_uid,
-            ),
-        ])
-
-        # Collect updates for batch processing
-        updated_feature_uids.extend([feature_uid] * len(final_indices))
-        updated_scan_uids.extend(ms2_index_arr[final_indices])
-        c += 1
-
-    self.logger.debug("Update features.")
-    # Convert to polars if needed and batch update features_df
-    if not isinstance(features_df, pl.DataFrame):
-        features_df = pl.from_pandas(features_df)
-
-    # Update the features_df
-    update_df = pl.DataFrame({
-        "temp_idx": feature_indices,
-        "ms2_scans": pl.Series("ms2_scans", scan_uid_lists, dtype=pl.Object),
-        "ms2_specs": pl.Series("ms2_specs", spec_lists, dtype=pl.Object),
-    })
-
-    # Join and update
-    features_df = (
-        features_df.with_row_index("temp_idx")
-        .join(
-            update_df,
-            on="temp_idx",
-            how="left",
-            suffix="_new",
-        )
-        .with_columns([
-            pl.when(pl.col("ms2_scans_new").is_not_null())
-            .then(pl.col("ms2_scans_new"))
-            .otherwise(pl.col("ms2_scans"))
-            .alias("ms2_scans"),
-            pl.when(pl.col("ms2_specs_new").is_not_null())
-            .then(pl.col("ms2_specs_new"))
-            .otherwise(pl.col("ms2_specs"))
-            .alias("ms2_specs"),
-        ])
-        .drop(["temp_idx", "ms2_scans_new", "ms2_specs_new"])
-    )
-
-    # Batch update scans_df
-    if updated_scan_uids:
-        scan_feature_uid_updates = dict(
-            zip(updated_scan_uids, updated_feature_uids, strict=True),
-        )
-        self.scans_df = (
-            self.scans_df.with_columns(
-                pl.col("scan_uid")
-                .map_elements(
-                    lambda x: scan_feature_uid_updates.get(x),
-                    return_dtype=pl.Int64,
-                )
-                .alias("feature_uid_update"),
-            )
-            .with_columns(
-                pl.when(pl.col("feature_uid_update").is_not_null())
-                .then(pl.col("feature_uid_update"))
-                .otherwise(pl.col("feature_uid"))
-                .alias("feature_uid"),
-            )
-            .drop("feature_uid_update")
-        )
-
-    # Log completion
-    self.logger.info(
-        f"MS2 linking completed. Total features with MS2 data: {c}",
-    )
-    self.features_df = features_df
-
-    # store params
-    self.store_history(["find_ms2"], params.to_dict())
-    self.logger.debug(
-        "Parameters stored to find_ms2",
-    )
+from __future__ import annotations
+
+from datetime import datetime
+
+import numpy as np
+import polars as pl
+import pyopenms as oms
+
+from tqdm import tqdm
+
+from masster.chromatogram import Chromatogram
+
+# Parameters removed - using hardcoded defaults
+from masster.spectrum import Spectrum
+from .defaults.find_features_def import find_features_defaults
+from .defaults.find_adducts_def import find_adducts_defaults
+from .defaults.find_ms2_def import find_ms2_defaults
+from .defaults.get_spectrum_def import get_spectrum_defaults
+
+
+def get_spectrum(self, scan, **kwargs):
+    """
+    Retrieve and process a spectrum from the data file based on the given scan identifier.
+
+    This method locates the scan in the internal DataFrame, extracts the metadata (such as energy,
+    MS level, and retention time), and then retrieves the corresponding spectrum data from the file.
+    Depending on the file interface (either 'oms' or 'alpharaw'), the spectrum data is obtained
+    and processed (including optional denoising, centroiding, deisotoping, and precursor m/z trimming).
+
+    Parameters:
+        scan (int): Unique identifier of the scan to retrieve. This is a mandatory parameter.
+        **kwargs: Keyword arguments for spectrum retrieval parameters. Can include:
+            - A get_spectrum_defaults instance to set all parameters at once
+            - Individual parameter names and values (see get_spectrum_defaults for details)
+
+    Key Parameters:
+        precursor_trim (int, optional): Value used to trim the precursor m/z for MS2 spectra.
+                                        If provided and the spectrum's MS level is greater than 1,
+                                        m/z values above (precursor_mz - precursor_trim) will be trimmed.
+                                        Default is 20.
+        max_peaks (int, optional): Maximum number of peaks to retain in the spectrum. Default is 100.
+        centroid (bool, optional): Flag indicating whether the spectrum should be centroided.
+                                    If True and the spectrum is not already centroided, the method
+                                    applies denoising followed by centroiding using parameters from self.parameters.
+                                    Default is True.
+        deisotope (bool, optional): Flag indicating whether deisotoping should be performed. Default is False.
+        dia_stats (optional): Flag or parameter for processing DIA (data-independent acquisition)
+                                statistics. If provided (and if applicable to the file type), additional
+                                statistics will be computed for 'ztscan' files. Default is None.
+        feature (optional): An optional identifier used when computing DIA statistics. Default is None.
+        label (str, optional): Optional label to assign to the spectrum. If not provided,
+                                a default name is generated based on the MS level and retention time.
+                                Default is None.
+        centroid_algo (str, optional): Algorithm to use for centroiding. Default is None.
+
+    Returns:
+        spectrum: A processed spectrum object containing:
+                    - m/z and intensity arrays
+                    - metadata such as MS level, retention time, energy, and an assigned label
+                    Depending on the processing steps (centroiding, trimming, deisotoping, etc.), the
+                    returned spectrum is modified accordingly.
+                    Returns None or an empty spectrum if the scan is not found or if an error occurs.
+
+    Notes:
+        - For the 'oms' file interface, the spectrum is retrieved via self.file_obj.getSpectrum
+            and handled accordingly.
+        - For the 'alpharaw' file interface, the method uses internal DataFrame attributes to locate the
+            scan and its associated peaks.
+        - The method applies additional processing (denoising, centroiding, deisotoping, trimming) based on
+            the input flags and the MS level of the spectrum.
+    """
+
+    # parameters initialization
+    params = get_spectrum_defaults(scan=scan)
+    for key, value in kwargs.items():
+        if isinstance(value, get_spectrum_defaults):
+            params = value
+            self.logger.debug("Using provided get_spectrum_defaults parameters")
+        else:
+            if hasattr(params, key):
+                if params.set(key, value, validate=True):
+                    self.logger.debug(f"Updated parameter {key} = {value}")
+                else:
+                    self.logger.warning(
+                        f"Failed to set parameter {key} = {value} (validation failed)",
+                    )
+            else:
+                self.logger.debug(f"Unknown parameter {key} ignored")
+    # end of parameter initialization
+
+    # Extract parameter values
+    scan = params.get("scan")
+    precursor_trim = params.get("precursor_trim")
+    max_peaks = params.get("max_peaks")
+    centroid = params.get("centroid")
+    deisotope = params.get("deisotope")
+    dia_stats = params.get("dia_stats")
+    feature_uid = params.get("feature")
+    label = params.get("label")
+    centroid_algo = params.get("centroid_algo")
+
+    # get energy, ms_level, rt from scans_df
+    scan_uid = scan  # Preserve original scan ID
+    scan_info = self.scans_df.filter(pl.col("scan_uid") == scan_uid)
+    if len(scan_info) == 0:
+        self.logger.warning(f"Scan {scan_uid} not found.")
+        return None
+    scan_info = scan_info[0]
+    energy = scan_info["energy"][0]
+    ms_level = scan_info["ms_level"][0]
+    rt = scan_info["rt"][0]
+    if label is None:
+        if ms_level == 1:
+            name = f"MS1, rt {rt:.2f} s, scan {scan_uid}"
+        else:
+            name = f"MS2 of mz {scan_info['prec_mz'][0]:0.1f}, rt {rt:.2f} s, scan {scan_uid}"
+    else:
+        name = label
+
+    if centroid_algo is None:
+        if "centroid_algo" in self.parameters:
+            centroid_algo = self.parameters.get("centroid_algo")
+        else:
+            # this is for backward compatibility. This is the old default
+            self.parameters.centroid_algo = "lmp"
+        centroid_algo = self.parameters.get("centroid_algo")
+
+    spec0 = Spectrum(mz=np.array([]), inty=np.array([]))
+    if self.file_interface == "oms":
+        # if check that file_obj is not None
+        if self.file_obj is None:
+            self.logger.error("Please load a file first.")
+            return
+        try:
+            spect = self.file_obj.getSpectrum(scan_uid).get_peaks()
+        except Exception as e:
+            self.logger.error(f"Error: {e}")
+            return spec0
+        if len(spect[0]) == 0:
+            return spec0
+        elif len(spect[0]) == 1:
+            mz = np.array([spect[0][0]])
+            inty = np.array([spect[1][0]])
+        else:
+            mz = np.array(spect[0])
+            inty = np.array(spect[1])
+        if ms_level == 1:
+            spect = Spectrum(
+                mz=mz,
+                inty=inty,
+                ms_level=ms_level,
+                rt=rt,
+                energy=None,
+                precursor_mz=None,
+                label=name,
+            )
+        else:
+            spect = Spectrum(
+                mz=mz,
+                inty=inty,
+                ms_level=ms_level,
+                rt=rt,
+                energy=energy,
+                precursor_mz=scan_info["prec_mz"][0],
+                label=name,
+            )
+        if centroid and not spect.centroided:
+            spect = spect.denoise()
+            if spect.ms_level == 1:
+                spect = spect.centroid(
+                    algo=centroid_algo,
+                    tolerance=self.parameters.get("mz_tol_ms1_da"),
+                    ppm=self.parameters.get("mz_tol_ms1_ppm"),
+                    min_points=self.parameters.get("centroid_min_points_ms1"),
+                    smooth=self.parameters.get("centroid_smooth"),
+                    prominence=self.parameters.get("centroid_prominence"),
+                    refine=self.parameters.get("centroid_refine"),
+                )
+            elif spect.ms_level == 2:
+                spect = spect.centroid(
+                    algo=centroid_algo,
+                    tolerance=self.parameters.get("mz_tol_ms2_da"),
+                    ppm=self.parameters.get("mz_tol_ms2_ppm"),
+                    min_points=self.parameters.get("centroid_min_points_ms2"),
+                    smooth=self.parameters.get("centroid_smooth"),
+                    prominence=self.parameters.get("centroid_prominence"),
+                    refine=self.parameters.get("centroid_refine"),
+                )
+
+    elif self.file_interface == "alpharaw":
+        spec_df = self.file_obj.spectrum_df
+        spect = (
+            spec_df.filter(pl.col("scan_id") == scan_uid).row(0, named=True)
+            if isinstance(spec_df, pl.DataFrame)
+            else spec_df.loc[scan_uid]
+        )
+        peak_stop_idx = spect["peak_stop_idx"]
+        peak_start_idx = spect["peak_start_idx"]
+
+        if isinstance(self.file_obj.peak_df, pl.DataFrame):
+            peaks = self.file_obj.peak_df.slice(
+                peak_start_idx,
+                peak_stop_idx - peak_start_idx,
+            )
+            mz_values = peaks.select("mz").to_numpy().flatten()
+            intensity_values = peaks.select("intensity").to_numpy().flatten()
+        else:
+            peaks = self.file_obj.peak_df.loc[peak_start_idx : peak_stop_idx - 1]
+            mz_values = peaks.mz.values
+            intensity_values = peaks.intensity.values
+
+        if spect["ms_level"] > 1:
+            spect = Spectrum(
+                mz=np.asarray(mz_values, dtype=np.float64),
+                inty=np.asarray(intensity_values, dtype=np.float64),
+                ms_level=ms_level,
+                centroided=False,
+                precursor_mz=spect["precursor_mz"],
+                energy=energy,
+                rt=rt,
+                label=name,
+            )
+        else:
+            spect = Spectrum(
+                mz=np.asarray(mz_values, dtype=np.float64),
+                inty=np.asarray(intensity_values, dtype=np.float64),
+                ms_level=ms_level,
+                centroided=False,
+                precursor_mz=None,
+                energy=None,
+                rt=rt,
+                label=name,
+            )
+
+        if len(spect) and centroid and not spect.centroided:
+            spect = spect.denoise()
+            if spect.ms_level == 1:
+                spect = spect.centroid(
+                    algo=centroid_algo,
+                    tolerance=self.parameters.get("mz_tol_ms1_da"),
+                    ppm=self.parameters.get("mz_tol_ms1_ppm"),
+                    min_points=self.parameters.get("centroid_min_points_ms1"),
+                    smooth=self.parameters.get("centroid_smooth"),
+                    prominence=self.parameters.get("centroid_prominence"),
+                    refine=self.parameters.get("centroid_refine"),
+                )
+            elif spect.ms_level == 2:
+                spect = spect.centroid(
+                    algo=centroid_algo,
+                    tolerance=self.parameters.get("mz_tol_ms2_da"),
+                    ppm=self.parameters.get("mz_tol_ms2_ppm"),
+                    min_points=self.parameters.get("centroid_min_points_ms2"),
+                    smooth=self.parameters.get("centroid_smooth"),
+                    prominence=self.parameters.get("centroid_prominence"),
+                    refine=self.parameters.get("centroid_refine"),
+                )
+
+    else:
+        self.logger.error(
+            f"File interface {self.file_interface} not supported. Reload data.",
+        )
+        return spec0
+
+    if precursor_trim is not None and spect.ms_level > 1:
+        spect = spect.trim(mz_min=None, mz_max=spect.precursor_mz - precursor_trim)  # type: ignore[attr-defined]
+    if deisotope:
+        spect = spect.deisotope()
+
+    if max_peaks is not None:
+        spect = spect.keep_top(max_peaks)
+
+    if dia_stats:
+        if self.file_type in ["ztscan", "dia"]:
+            spect = self._get_ztscan_stats(
+                spec=spect,
+                scan_uid=scan_uid,
+                feature_uid=scan_info["feature_uid"][0]
+                if "feature_uid" in scan_info and scan_info["feature_uid"][0] is not None
+                else feature_uid,
+                q1_step=2,
+                deisotope=deisotope,
+                centroid=centroid,
+            )
+    return spect
+
+
+def _get_ztscan_stats(
+    self,
+    spec,
+    scan_uid=None,
+    feature_uid=None,
+    q1_step=2,
+    mz_tol=0.005,
+    # TODO check this
+    # deisotope=SpectrumParameters().deisotope,
+    deisotope=False,
+    # TODO there is no `centroid_algo`?
+    centroid=True,
+):
+    spec.size = spec.mz.size
+    # spec.ms_entropy = spec.entropy()
+
+    if self.scans_df is None:
+        self.logger.warning("No scans found.")
+        return spec
+    scan = self.scans_df.filter(pl.col("scan_uid") == scan_uid)
+    if len(scan) == 0:
+        self.logger.warning(f"Scan {scan_uid} not found.")
+        return spec
+    scan = scan[0]
+    if scan["ms_level"][0] != 2:
+        self.logger.warning(f"Scan {scan_uid} is not a MS2 scan.")
+    # Q1
+    lscan = self.scans_df.filter(pl.col("scan_uid") == scan_uid - q1_step)
+    if len(lscan) == 0:
+        self.logger.warning(f"Scan {scan_uid - q1_step} not found.")
+        return spec
+    lscan = lscan[0]
+    # check that lscan['ms_level'] == 2 and lscan['cycle'] == scan['cycle']
+    if lscan["ms_level"][0] != 2:
+        self.logger.warning(f"Scan {scan_uid - q1_step} is not a MS2 scan.")
+        return spec
+    if lscan["cycle"][0] != scan["cycle"][0]:
+        self.logger.warning(
+            f"Scan {scan_uid - q1_step} is not in the same cycle as scan {scan_uid}.",
+        )
+        return spec
+    rscan = self.scans_df.filter(pl.col("scan_uid") == scan_uid + q1_step)
+    if len(rscan) == 0:
+        self.logger.warning(f"Scan {scan_uid + q1_step} not found.")
+        return spec
+    rscan = rscan[0]
+    # check that rscan['ms_level'] == 2 and rscan['cycle'] == scan['cycle']
+    if rscan["ms_level"][0] != 2:
+        self.logger.warning(f"Scan {scan_uid + q1_step} is not a MS2 scan.")
+        return spec
+    if rscan["cycle"][0] != scan["cycle"][0]:
+        self.logger.warning(
+            f"Scan {scan_uid + q1_step} is not in the same cycle as scan {scan_uid}.",
+        )
+        return spec
+    intymat = self._spec_to_mat(
+        scan_uids=[scan_uid - q1_step, scan_uid, scan_uid + q1_step],
+        mz_ref=spec.mz,
+        mz_tol=mz_tol,
+        deisotope=deisotope,
+        centroid=centroid,
+    )
+    # pick only mzs that are close to spec.mz
+    if intymat is None:
+        return spec
+    if intymat.shape[1] < 3:
+        self.logger.warning(f"Not enough data points for scan {scan_uid}.")
+        return spec
+    q1_ratio = (2 * intymat[:, 1] + 0.01) / (intymat[:, 0] + intymat[:, 2] + 0.01)
+    spec.q1_ratio = np.log2(q1_ratio)
+    # where intymat[:, 0] + intymat[:, 2]==0, set q1_ratio to -1
+    spec.q1_ratio[np.isclose(intymat[:, 0] + intymat[:, 2], 0)] = -10
+
+    # EIC correlation
+    # find rt_start and rt_end of the feature_uid
+    if self.features_df is None:
+        self.logger.warning("No features found.")
+        return spec
+    if feature_uid is None:
+        return spec
+    # spec.precursor_mz = feature['mz']
+    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 spec
+    feature = feature.row(0, named=True)
+    rt_start = feature["rt_start"]
+    rt_end = feature["rt_end"]
+    # get the cycle at rt_start and the cycle at rt_end from the closest scan with ms_level == 1
+    scans = self.scans_df.filter(pl.col("ms_level") == 1)
+    scans = scans.filter(pl.col("rt") > rt_start)
+    scans = scans.filter(pl.col("rt") < rt_end)
+    if len(scans) == 0:
+        self.logger.warning(f"No scans found between {rt_start} and {rt_end}.")
+        return spec
+    scan_uids = scans["scan_uid"].to_list()
+    eic_prec = self._spec_to_mat(
+        scan_uids=scan_uids,
+        mz_ref=feature["mz"],
+        mz_tol=mz_tol,
+        deisotope=deisotope,
+        centroid=centroid,
+    )
+    # find width at half maximum of the eic_prec
+    # hm = np.max(eic_prec[0, :]) / 3
+    # find index of maximum
+    # eic_prec_max_idx = np.argmax(eic_prec[0, :])
+    # find index of the closest point to half maximum
+    # idx = np.argmin(np.abs(eic_prec[0, :] - hm))
+    # eic_fwhm_prec = abs(eic_prec_max_idx - idx)
+
+    # get all unique cycles from scans
+    cycles = scans["cycle"].unique()
+    scandids = []
+    # iterate over all cycles and get the scan_uid of scan with ms_level == 2 and closest precursor_mz to spec.precursor_mz
+    for cycle in cycles:
+        scans = self.scans_df.filter(pl.col("cycle") == cycle)
+        scans = scans.filter(pl.col("ms_level") == 2)
+        scans = scans.filter(pl.col("prec_mz") > feature["mz"] - 4)
+        scans = scans.filter(pl.col("prec_mz") < feature["mz"] + 4)
+        if len(scans) == 0:
+            self.logger.warning(f"No scans found for cycle {cycle}.")
+            continue
+        scan = scans[(scans["prec_mz"] - feature["mz"]).abs().arg_sort()[:1]]
+        scandids.append(scan["scan_uid"][0])
+
+    eic_prod = self._spec_to_mat(
+        scandids,
+        mz_ref=spec.mz,
+        mz_tol=mz_tol,
+        deisotope=deisotope,
+        centroid=centroid,
+    )
+    # eic_prod = eic_prod.T
+    # eic_prec = eic_prec.T
+    # calculate correlation between eic_prec and all columns of eic_prod, column by column
+    eic_corr = np.zeros(eic_prod.shape[0])
+    # eic_width_ratio = np.zeros(eic_prod.shape[0])
+    for i in range(eic_prod.shape[0]):
+        try:
+            with np.errstate(divide="ignore", invalid="ignore"):
+                eic_corr[i] = np.corrcoef(eic_prod[i, :], eic_prec[0, :])[0, 1]
+        except:
+            pass
+
+    spec.eic_corr = eic_corr
+    return spec
+
+
+def _spec_to_mat(
+    self,
+    scan_uids,
+    mz_ref=None,
+    mz_tol=0.01,
+    # TODO check this
+    # deisotope=SpectrumParameters().deisotope,
+    deisotope=False,
+    # TODO there is no `centroid_algo`?
+    # TODO there is no `dia_stats`?
+    # TODO unused (see below)
+    centroid=True,
+    # TODO check this
+    # precursor_trim=SpectrumParameters().precursor_trim,
+    # TODO unused (see below)
+    precursor_trim=None,
+):
+    # get all spectra in scan_uids
+
+    if mz_ref is None:
+        return None
+
+    if not isinstance(mz_ref, np.ndarray):
+        if isinstance(mz_ref, list):
+            mz_ref = np.array(mz_ref)
+        else:
+            mz_ref = np.array([mz_ref])
+
+    def align_mzs(ar1, ar2, tol):
+        closest_indices = []
+        # find the closest pair between each element in ar1 and ar2, within a maximum tolerance of tol
+        for i, val1 in enumerate(ar1):
+            closest_index = np.argmin(np.abs(ar2 - val1))
+            closest_indices.append((i, closest_index))
+        # filter out pairs that are not within the specified tolerance
+        closest_indices = [(i, j) for i, j in closest_indices if np.abs(ar1[i] - ar2[j]) <= tol]
+        # remove duplicates from the list of indices
+        closest_indices = list(set(closest_indices))
+        # sort the list of indices by the first element (i) in ascending order
+        closest_indices = sorted(closest_indices, key=lambda x: x[0])
+
+        # Convert the list of indices into an array for easier indexing in subsequent operations
+        return np.array(closest_indices)
+
+    specs = []
+    for scan_uid in scan_uids:
+        spec = self.get_spectrum(
+            scan_uid=scan_uid,
+            centroid=True,
+            dia_stats=False,
+            precursor_trim=5,
+        )
+        if deisotope:
+            spec = spec.deisotope()
+        # align to reference spectrum
+        if spec.mz.size == 0:
+            continue
+        if mz_ref.size == 0:
+            continue
+        closest_indices = align_mzs(spec.mz, mz_ref, mz_tol)
+        # store the aligned spectrum in the list
+        aligned_inty = np.zeros(len(mz_ref))
+        for i, j in closest_indices:
+            if abs(spec.mz[i] - mz_ref[j]) <= mz_tol:
+                if aligned_inty[j] < spec.inty[i]:
+                    aligned_inty[j] = spec.inty[i]
+        specs.append(aligned_inty)
+
+    if len(specs) == 0:
+        return None
+    # create a matrix with the aligned spectra. Each spec goes into a column
+    mat = np.column_stack(specs)
+
+    return mat
+
+
+def find_features(self, **kwargs):
+    """
+    Detect features in mass spectrometry data by processing MS1 spectra, performing mass trace detection,
+    elution peak detection, and feature detection. Optionally, deisotope features and remove low-quality peaks.
+
+    This method leverages an MSExperiment constructed from the object's ms1_df, where each cycle in the data
+    corresponds to an MSSpectrum. It then runs mass trace detection using set parameters, deconvolutes the mass
+    traces to detect chromatographic peaks, and finally identifies features with a feature finding algorithm. The
+    resulting feature map is cleaned, deisotoped (if enabled), and assigned unique IDs before being stored.
+
+    Parameters:
+        **kwargs: Keyword arguments for feature detection parameters. Can include:
+            - A find_features_defaults instance to set all parameters at once
+            - Individual parameter names and values (see find_features_defaults for details)
+
+    Key Parameters:
+        tol_ppm (float): Mass error tolerance in parts-per-million for mass trace detection (default: 30.0).
+        noise (float): Noise threshold intensity to filter out low-intensity signals (default: 200.0).
+        chrom_fwhm (float): Full width at half maximum for chromatographic peak shape (default: 1.0).
+        chrom_fwhm_min (float): Minimum FWHM for chromatographic peak detection (default: 0.5).
+        chrom_peak_snr (float): Signal-to-noise ratio required for chromatographic peaks (default: 10.0).
+        mz_scoring_13C (bool): Whether to enable scoring of 13C isotopic patterns (default: False).
+        masstrace_snr_filtering (bool): Whether to apply SNR filtering to mass traces (default: False).
+        deisotope (bool): Whether to perform deisotoping of detected features (default: True).
+
+    Attributes set:
+        self.features: An updated feature map with unique IDs after feature detection and deisotoping.
+        self.features_df: A cleaned DataFrame of features, with peaks of zero quality removed, representing the final
+                            detected features.
+
+    Notes:
+        - The method processes the ms1_df by iterating over cycles to build an MSExperiment.
+        - External OMS modules (e.g., MSExperiment, MSSpectrum, MassTraceDetection, ElutionPeakDetection,
+            FeatureFindingMetabo) are used throughout the processing.
+        - After feature detection, additional cleaning is performed via internal helper methods.
+    """
+    if self.ms1_df is None:
+        self.logger.error("No MS1 data found. Please load a file first.")
+        return
+    if len(self.ms1_df) == 0:
+        self.logger.error("MS1 data is empty. Please load a file first.")
+        return
+    # parameters initialization
+    params = find_features_defaults()
+    for key, value in kwargs.items():
+        if isinstance(value, find_features_defaults):
+            # set
+            params = value
+            self.logger.debug("Using provided find_features_defaults parameters")
+        else:
+            if hasattr(params, key):
+                if params.set(key, value, validate=True):
+                    self.logger.debug(f"Updated parameter {key} = {value}")
+                else:
+                    self.logger.warning(
+                        f"Failed to set parameter {key} = {value} (validation failed)",
+                    )
+            else:
+                self.logger.warning(f"Unknown parameter {key} ignored")
+
+    self.logger.info("Starting feature detection...")
+    self.logger.debug(
+        f"Parameters: chrom_fwhm={params.get('chrom_fwhm')}, noise={params.get('noise')}, tol_ppm={params.get('tol_ppm')}",
+    )
+
+    exp = oms.MSExperiment()
+    # find max number of cycles in self.ms1_df
+    max_cycle = self.ms1_df["cycle"].max()
+    # iterate over all cycles, find rows with 1 cycle and append to exp2
+    for cycle in range(1, max_cycle + 1):
+        cycle_df = self.ms1_df.filter(pl.col("cycle") == cycle)
+        # check if len(cycle_df) > 0
+        if len(cycle_df) > 0:
+            spectrum = oms.MSSpectrum()
+            spectrum.setRT(cycle_df[0]["rt"].item())
+            spectrum.setMSLevel(1)  # MS1
+            mz = cycle_df["mz"]
+            inty = cycle_df["inty"]
+            spectrum.set_peaks([mz, inty])  # type: ignore[attr-defined]
+            spectrum.sortByPosition()
+            exp.addSpectrum(spectrum)
+
+    # exp.sortSpectra(True)
+    # mass trace detection
+    mass_traces: list = []
+    mtd = oms.MassTraceDetection()
+    mtd_par = mtd.getDefaults()
+
+    # Apply MTD parameters
+    mtd_par.setValue("mass_error_ppm", float(params.get("tol_ppm")))
+    mtd_par.setValue("noise_threshold_int", float(params.get("noise")))
+    mtd_par.setValue(
+        "min_trace_length",
+        float(params.get("min_trace_length_multiplier")) * float(params.get("chrom_fwhm_min")),
+    )
+    mtd_par.setValue(
+        "trace_termination_outliers",
+        int(params.get("trace_termination_outliers")),
+    )
+    mtd_par.setValue("chrom_peak_snr", float(params.get("chrom_peak_snr")))
+
+    mtd.setParameters(mtd_par)  # set the new parameters
+    mtd.run(exp, mass_traces, 0)  # run mass trace detection
+
+    # elution peak detection
+    mass_traces_deconvol: list = []
+    epd = oms.ElutionPeakDetection()
+    epd_par = epd.getDefaults()
+
+    # Apply EPD parameters using our parameter class
+    epd_par.setValue("width_filtering", params.get("width_filtering"))
+    epd_par.setValue("min_fwhm", float(params.get("chrom_fwhm_min")))
+    epd_par.setValue("chrom_fwhm", float(params.get("chrom_fwhm")))
+    epd_par.setValue("chrom_peak_snr", float(params.get("chrom_peak_snr")))
+    if params.get("masstrace_snr_filtering"):
+        epd_par.setValue("masstrace_snr_filtering", "true")
+    if params.get("mz_scoring_13C"):
+        epd_par.setValue("mz_scoring_13C", "true")
+
+    epd.setParameters(epd_par)
+    epd.detectPeaks(mass_traces, mass_traces_deconvol)
+
+    # feature detection
+    feature_map = oms.FeatureMap()  # output features
+    chrom_out: list = []  # output chromatograms
+    ffm = oms.FeatureFindingMetabo()
+    ffm_par = ffm.getDefaults()
+
+    # Apply FFM parameters using our parameter class
+    ffm_par.setValue(
+        "remove_single_traces",
+        "true" if params.get("remove_single_traces") else "false",
+    )
+    ffm_par.setValue(
+        "report_convex_hulls",
+        "true" if params.get("report_convex_hulls") else "false",
+    )
+    ffm_par.setValue(
+        "report_summed_ints",
+        "true" if params.get("report_summed_ints") else "false",
+    )
+    ffm_par.setValue(
+        "report_chromatograms",
+        "true" if params.get("report_chromatograms") else "false",
+    )
+
+    ffm.setParameters(ffm_par)
+    self.logger.debug("Running feature finding with parameters:")
+    self.logger.debug(ffm_par)
+    ffm.run(mass_traces_deconvol, feature_map, chrom_out)
+    # Assigns a new, valid unique id per feature
+    feature_map.ensureUniqueId()
+    df = feature_map.get_df(export_peptide_identifications=False)  # type: ignore[attr-defined]
+    # Sets the file path to the primary MS run (usually the mzML file)
+    feature_map.setPrimaryMSRunPath([self.file_path.encode()])
+    self.features = feature_map
+    # remove peaks with quality == 0
+    df = self._clean_features_df(df)
+
+    # desotope features
+    df = self._features_deisotope(
+        df,
+        mz_tol=params.get("deisotope_mz_tol"),
+        rt_tol=params.get("chrom_fwhm_min") / 4 * params.get("deisotope_rt_tol_factor"),
+    )
+    if params.get("deisotope"):
+        # record size before deisotoping
+        size_before_deisotope = len(df)
+        df = df.filter(pl.col("iso") == 0)
+        self.logger.debug(
+            f"Deisotoping features: {size_before_deisotope - len(df)} features removed.",
+        )
+
+    # update eic - create lists to collect results
+    chroms: list[Chromatogram] = []
+    coherences: list[float] = []
+    prominences: list[float] = []
+    prominence_scaleds: list[float] = []
+    height_scaleds: list[float] = []
+
+    mz_tol = params.get("eic_mz_tol")
+    rt_tol = params.get("eic_rt_tol")
+
+    # iterate over all rows in df using polars iteration
+    self.logger.debug("Extracting EICs...")
+    for row in df.iter_rows(named=True):
+        # select data in ms1_df with mz in range [mz_start - mz_tol, mz_end + mz_tol] and rt in range [rt_start - rt_tol, rt_end + rt_tol]
+        d = self.ms1_df.filter(
+            (pl.col("rt") >= row["rt_start"] - rt_tol)
+            & (pl.col("rt") <= row["rt_end"] + rt_tol)
+            & (pl.col("mz") >= row["mz"] - mz_tol)
+            & (pl.col("mz") <= row["mz"] + mz_tol),
+        )
+        # for all unique rt values, find the maximum inty
+        eic_rt = d.group_by("rt").agg(pl.col("inty").max())
+        if len(eic_rt) < 4:
+            chroms.append(None)
+            coherences.append(None)
+            prominences.append(None)
+            prominence_scaleds.append(None)
+            height_scaleds.append(None)
+            continue
+
+        eic = Chromatogram(
+            eic_rt["rt"].to_numpy(),
+            eic_rt["inty"].to_numpy(),
+            label=f"EIC mz={row['mz']:.4f}",
+            file=self.file_path,
+            mz=row["mz"],
+            mz_tol=mz_tol,
+            feature_start=row["rt_start"],
+            feature_end=row["rt_end"],
+            feature_apex=row["rt"],
+        ).find_peaks()
+
+        # collect results
+        chroms.append(eic)
+        if len(eic.peak_widths) > 0:
+            coherences.append(round(eic.feature_coherence, 3))
+            prominences.append(round(eic.peak_prominences[0], 3))
+            prominence_scaleds.append(
+                round(eic.peak_prominences[0] / (np.mean(eic.inty) + 1e-10), 3),
+            )
+            height_scaleds.append(
+                round(eic.peak_heights[0] / (np.mean(eic.inty) + 1e-10), 3),
+            )
+        else:
+            coherences.append(None)
+            prominences.append(None)
+            prominence_scaleds.append(None)
+            height_scaleds.append(None)
+
+    # Add the computed columns to the dataframe
+    df = df.with_columns([
+        pl.Series("chrom", chroms, dtype=pl.Object),
+        pl.Series("chrom_coherence", coherences, dtype=pl.Float64),
+        pl.Series("chrom_prominence", prominences, dtype=pl.Float64),
+        pl.Series("chrom_prominence_scaled", prominence_scaleds, dtype=pl.Float64),
+        pl.Series("chrom_height_scaled", height_scaleds, dtype=pl.Float64),
+    ])
+
+    self.features_df = df
+    self._features_sync()
+    self.logger.info(f"Feature detection completed. Total features: {len(df)}")
+
+    # store params
+    self.store_history(["find_features"], params.to_dict())
+    self.logger.debug(
+        "Parameters stored to find_features",
+    )
+    keys_to_remove = ["find_adducts", "find_ms2"]
+    for key in keys_to_remove:
+        if key in self.history:
+            del self.history[key]
+            self.logger.debug(f"Removed {key} from history")
+
+
+def find_adducts(self, **kwargs):
+    """
+    Detect adducts in mass spectrometry features using OpenMS MetaboliteFeatureDeconvolution.
+
+    This method analyzes detected features to identify adduct relationships based on mass differences,
+    charge states, and retention time proximity. It groups features that likely represent the same
+    metabolite in different ionization states.
+
+    Parameters:
+        **kwargs: Keyword arguments for adduct detection parameters. Can include:
+            - A find_adducts_defaults instance to set all parameters at once
+            - Individual parameter names and values (see find_adducts_defaults for details)
+
+    Key Parameters:
+        adducts (Union[List[str], str, None]): List of potential adducts or ionization mode string.
+        charge_min (int): Minimal possible charge state (default: 1).
+        charge_max (int): Maximal possible charge state (default: 2).
+        retention_max_diff (float): Maximum retention time difference for grouping (default: 1.0).
+
+    Attributes set:
+        self.features_df: Updated with adduct information including 'adduct', 'adduct_mass',
+                         and 'adduct_group' columns.
+    """
+    params = find_adducts_defaults()
+    for key, value in kwargs.items():
+        if isinstance(value, find_adducts_defaults):
+            # set
+            params = value
+            self.logger.debug("Using provided find_adducts_defaults parameters")
+        else:
+            if hasattr(params, key):
+                if params.set(key, value, validate=True):
+                    self.logger.debug(f"Updated parameter {key} = {value}")
+                else:
+                    self.logger.warning(
+                        f"Failed to set parameter {key} = {value} (validation failed)",
+                    )
+            else:
+                self.logger.warning(f"Unknown parameter {key} ignored")
+
+    self.logger.debug("Starting adduct detection...")
+    self.logger.debug(
+        f"Parameters: adducts={params.get('adducts')}, charge_min={params.get('charge_min')}, charge_max={params.get('charge_max')}",
+    )
+
+    mfd = oms.MetaboliteFeatureDeconvolution()
+
+    openms_params = mfd.getDefaults()
+
+    # Set adducts using the helper method
+    adducts_list = params.get_openms_adducts()
+    openms_params.setValue("potential_adducts", [a.encode() for a in adducts_list])
+
+    # Apply other parameters
+    openms_params.setValue("charge_min", params.get("charge_min"))
+    openms_params.setValue("charge_max", params.get("charge_max"))
+    openms_params.setValue("charge_span_max", params.get("charge_span_max"))
+    openms_params.setValue("retention_max_diff", params.get("retention_max_diff"))
+    openms_params.setValue(
+        "retention_max_diff_local",
+        params.get("retention_max_diff_local"),
+    )
+
+    # set updated parameters object
+    mfd.setParameters(openms_params)
+    self.logger.debug("Running adduct detection with parameters:")
+    self.logger.debug(openms_params)
+    # result feature map: will store features with adduct information
+    feature_map_MFD = oms.FeatureMap()
+    # result consensus map: will store grouped features belonging to a charge group
+    groups = oms.ConsensusMap()
+    # result consensus map: will store paired features connected by an edge
+    edges = oms.ConsensusMap()
+
+    # compute adducts
+    mfd.compute(self.features, feature_map_MFD, groups, edges)
+    self.logger.debug("Extracting information.")
+
+    # export feature map as pandas DataFrame and append adduct information
+    adducts_map = feature_map_MFD.get_df(export_peptide_identifications=False)  # type: ignore[attr-defined]
+    adducts_map["adduct"] = [f.getMetaValue("dc_charge_adducts") for f in feature_map_MFD]
+    adducts_map["adduct_group_id"] = [f.getMetaValue("Group") for f in feature_map_MFD]
+    adducts_map["adduct_mass"] = [f.getMetaValue("dc_charge_adduct_mass") for f in feature_map_MFD]
+    # clean up the DataFrame
+
+    # Clean up 'None' strings that should be actual None values from OpenMS getMetaValue
+    for col in ["adduct", "adduct_group_id", "adduct_mass"]:
+        if col in adducts_map.columns:
+            adducts_map[col] = adducts_map[col].replace("None", None)
+
+    # Convert adducts_map to polars and merge
+    adducts_df = pl.DataFrame({
+        "index": range(len(adducts_map)),
+        "adduct": adducts_map["adduct"],
+        "adduct_mass": adducts_map["adduct_mass"],
+        "adduct_group_id": adducts_map["adduct_group_id"],
+    })
+    features_pl = self.features_df if isinstance(self.features_df, pl.DataFrame) else pl.from_pandas(self.features_df)
+
+    # Remove existing adduct columns if they exist (likely all null)
+    if "adduct" in features_pl.columns:
+        features_pl = features_pl.drop("adduct")
+    if "adduct_mass" in features_pl.columns:
+        features_pl = features_pl.drop("adduct_mass")
+    if "adduct_group" in features_pl.columns:
+        features_pl = features_pl.drop("adduct_group")
+
+    df = features_pl.join(
+        adducts_df,
+        left_on="feature_uid",
+        right_on="index",
+        how="left",
+    )
+
+    # Create adduct_group from adduct_group_id column
+    unique_groups = df["adduct_group_id"].unique().to_list()
+    group_mapping = {group: idx for idx, group in enumerate(unique_groups)}
+    df = df.with_columns(
+        pl.col("adduct_group_id")
+        .map_elements(lambda x: group_mapping.get(x, 0), return_dtype=pl.Int64)
+        .alias("adduct_group"),
+    )
+
+    # remove adduct_group_id
+    df = df.drop("adduct_group_id")
+    # move adduct, adduct_mass, and adduct_group after column iso_of
+    if "iso_of" in df.columns:
+        adduct_cols = ["adduct", "adduct_mass", "adduct_group"]
+        # Get all column names and reorder them
+        all_cols = df.columns
+        iso_of_idx = all_cols.index("iso_of")
+
+        # Create new column order: everything before iso_of, then iso_of, then adduct columns, then the rest
+        new_order = []
+        # columns up to and including iso_of
+        new_order.extend(all_cols[: iso_of_idx + 1])
+        # adduct columns that exist
+        new_order.extend([col for col in adduct_cols if col in all_cols])
+        new_order.extend([col for col in all_cols[iso_of_idx + 1 :] if col not in adduct_cols])  # remaining columns
+
+        df = df.select(new_order)
+    # Update the features_df attribute with the new DataFrame
+
+    self.features_df = df
+    total_adducts = df.filter(pl.col("adduct").is_not_null()).shape[0]
+    self.logger.info(f"Adduct detection completed. Total adducts: {total_adducts}")
+
+    # store params
+    self.store_history(["find_adducts"], params.to_dict())
+    self.logger.debug(
+        "Parameters stored to find_adducts",
+    )
+
+
+def _clean_features_df(self, df):
+    # Convert pandas DataFrame to polars if needed
+    df["feature_id"] = df.index
+    if hasattr(df, "columns") and not isinstance(df, pl.DataFrame):
+        df_pl = pl.from_pandas(df)
+    else:
+        df_pl = df
+
+    # Filter out rows with quality == 0
+    df2 = df_pl.filter(pl.col("quality") != 0)
+
+    # Create new dataframe with required columns and transformations using select
+    df_result = df2.select([
+        pl.int_range(pl.len()).alias("feature_uid"),
+        pl.col("feature_id").cast(pl.String).alias("feature_id"),
+        pl.col("mz").round(5),
+        pl.col("RT").round(3).alias("rt"),
+        pl.col("RT").round(3).alias("rt_original"),  # keep original RT
+        pl.col("RTstart").round(3).alias("rt_start"),
+        pl.col("RTend").round(3).alias("rt_end"),
+        (pl.col("RTend") - pl.col("RTstart")).round(3).alias("rt_delta"),
+        pl.col("MZstart").round(5).alias("mz_start"),
+        pl.col("MZend").round(5).alias("mz_end"),
+        pl.col("intensity").alias("inty"),
+        pl.col("quality"),
+        pl.col("charge"),
+        pl.lit(0).alias("iso"),
+        pl.lit(None, dtype=pl.Int64).alias("iso_of"),
+        pl.lit(None, dtype=pl.Int64).alias("adduct_group"),
+        pl.lit(None, dtype=pl.Utf8).alias("adduct"),
+        pl.lit(None, dtype=pl.Float64).alias("adduct_mass"),
+        pl.lit(None, dtype=pl.Object).alias("chrom"),
+        pl.lit(None, dtype=pl.Float64).alias("chrom_coherence"),
+        pl.lit(None, dtype=pl.Float64).alias("chrom_prominence"),
+        pl.lit(None, dtype=pl.Float64).alias("chrom_prominence_scaled"),
+        pl.lit(None, dtype=pl.Float64).alias("chrom_height_scaled"),
+        pl.lit(None, dtype=pl.Object).alias("ms2_scans"),
+        pl.lit(None, dtype=pl.Object).alias("ms2_specs"),
+    ])
+
+    return df_result
+
+
+def _features_deisotope(
+    self,
+    df,
+    mz_tol=None,
+    rt_tol=None,
+):
+    if mz_tol is None:
+        mz_tol = 0.02
+    if rt_tol is None:
+        rt_tol = 0.2
+
+    # Convert to polars if needed
+    if not isinstance(df, pl.DataFrame):
+        df = pl.from_pandas(df)
+
+    # Initialize new columns
+    df = df.with_columns([
+        pl.lit(0).alias("iso"),
+        pl.col("feature_uid").alias("iso_of"),
+    ])
+
+    # Sort by 'mz'
+    df = df.sort("mz")
+
+    # Get arrays for efficient processing
+    rt_arr = df["rt"].to_numpy()
+    mz_arr = df["mz"].to_numpy()
+    intensity_arr = df["inty"].to_numpy()
+    feature_uid_arr = df["feature_uid"].to_numpy()
+    n = len(df)
+    mz_diff = 1.003355
+
+    # Create arrays to track isotope assignments
+    iso_arr = np.zeros(n, dtype=int)
+    iso_of_arr = feature_uid_arr.copy()
+
+    for i in range(n):
+        base_rt = rt_arr[i]
+        base_mz = mz_arr[i]
+        base_int = intensity_arr[i]
+        base_feature_uid = feature_uid_arr[i]
+
+        # Search for first isotope candidate (offset = mz_diff)
+        t1_lower = base_mz + mz_diff - mz_tol
+        t1_upper = base_mz + mz_diff + mz_tol
+        li = np.searchsorted(mz_arr, t1_lower, side="left")
+        ri = np.searchsorted(mz_arr, t1_upper, side="right")
+        if li < ri:
+            cand_idx = np.arange(li, ri)
+            mask = (
+                (rt_arr[cand_idx] > base_rt - rt_tol)
+                & (rt_arr[cand_idx] < base_rt + rt_tol)
+                & (intensity_arr[cand_idx] < 2 * base_int)
+            )
+            valid_cand = cand_idx[mask]
+            for cand in valid_cand:
+                if cand != i and iso_of_arr[cand] == feature_uid_arr[cand]:
+                    iso_arr[cand] = iso_arr[i] + 1  # first isotope
+                    iso_of_arr[cand] = base_feature_uid
+
+        # Search for second isotope candidate (offset = 2*mz_diff)
+        t2_lower = base_mz + 2 * mz_diff - 1.5 * mz_tol
+        t2_upper = base_mz + 2 * mz_diff + 1.5 * mz_tol
+        li = np.searchsorted(mz_arr, t2_lower, side="left")
+        ri = np.searchsorted(mz_arr, t2_upper, side="right")
+        if li < ri:
+            cand_idx = np.arange(li, ri)
+            mask = (
+                (rt_arr[cand_idx] > base_rt - rt_tol)
+                & (rt_arr[cand_idx] < base_rt + rt_tol)
+                & (intensity_arr[cand_idx] < 2 * base_int)
+            )
+            valid_cand = cand_idx[mask]
+            for cand in valid_cand:
+                if cand != i and iso_of_arr[cand] == feature_uid_arr[cand]:
+                    iso_arr[cand] = iso_arr[i] + 2  # second isotope
+                    iso_of_arr[cand] = base_feature_uid
+
+        # Search for third isotope candidate (offset = 3*mz_diff)
+        t3_lower = base_mz + 3 * mz_diff - 1.5 * mz_tol
+        t3_upper = base_mz + 3 * mz_diff + 1.5 * mz_tol
+        li = np.searchsorted(mz_arr, t3_lower, side="left")
+        ri = np.searchsorted(mz_arr, t3_upper, side="right")
+        if li < ri:
+            cand_idx = np.arange(li, ri)
+            mask = (
+                (rt_arr[cand_idx] > base_rt - rt_tol)
+                & (rt_arr[cand_idx] < base_rt + rt_tol)
+                & (intensity_arr[cand_idx] < 2 * base_int)
+            )
+            valid_cand = cand_idx[mask]
+            for cand in valid_cand:
+                if cand != i and iso_of_arr[cand] == feature_uid_arr[cand]:
+                    iso_arr[cand] = iso_arr[i] + 3  # third isotope
+                    iso_of_arr[cand] = base_feature_uid
+
+    # Update the dataframe with isotope assignments
+    df = df.with_columns([
+        pl.Series("iso", iso_arr),
+        pl.Series("iso_of", iso_of_arr),
+    ])
+
+    return df
+
+
+def analyze_dda(self):
+    # Preallocate variables
+    cycle_records = []
+    previous_rt = 0
+    previous_level = 0
+    ms1_index = None
+    cyclestart = None
+    ms2_n = 0
+    ms1_duration = 0
+    ms2_duration: list[float] = []
+
+    for row in self.scans_df.iter_rows(named=True):
+        if row["ms_level"] == 1:
+            if previous_level == 2:
+                ms2_to_ms2 = float(np.mean(ms2_duration)) if ms2_duration else -1.0
+                d = {
+                    "scan_uid": ms1_index,
+                    "ms2_n": ms2_n,
+                    "time_cycle": row["rt"] - cyclestart,
+                    "time_ms1_to_ms1": -1.0,
+                    "time_ms1_to_ms2": ms1_duration,
+                    "time_ms2_to_ms2": ms2_to_ms2,
+                    "time_ms2_to_ms1": row["rt"] - previous_rt,
+                }
+                cycle_records.append(d)
+            elif previous_level == 1:
+                d = {
+                    "scan_uid": ms1_index,
+                    "ms2_n": 0,
+                    "time_cycle": row["rt"] - cyclestart,
+                    "time_ms1_to_ms1": row["rt"] - cyclestart,
+                    "time_ms1_to_ms2": -1.0,
+                    "time_ms2_to_ms2": -1.0,
+                    "time_ms2_to_ms1": -1.0,
+                }
+                cycle_records.append(d)
+
+            ms1_index = row["scan_uid"]
+            cyclestart = row["rt"]
+            ms2_n = 0
+            ms1_duration = 0
+            ms2_duration = []
+        elif previous_level == 2:
+            ms2_n += 1
+            ms2_duration.append(row["rt"] - previous_rt)
+        elif previous_level == 1:
+            ms1_duration = row["rt"] - cyclestart
+            ms2_n += 1
+        previous_level = row["ms_level"]
+        previous_rt = row["rt"]
+
+    # Create DataFrame once at the end
+    if cycle_records:
+        cycle_data = pl.DataFrame(cycle_records)
+        self.scans_df = self.scans_df.join(cycle_data, on="scan_uid", how="left")
+    else:
+        self.scans_df = self.scans_df.with_columns(
+            [
+                pl.lit(None).alias("ms2_n"),
+                pl.lit(None).alias("time_cycle"),
+                pl.lit(None).alias("time_ms1_to_ms1"),
+                pl.lit(None).alias("time_ms1_to_ms2"),
+                pl.lit(None).alias("time_ms2_to_ms2"),
+                pl.lit(None).alias("time_ms2_to_ms1"),
+            ],
+        )
+
+
+def find_ms2(self, **kwargs):
+    """
+    Link MS2 spectra to features in the dataset.
+    This method matches MS2 spectra from the scans dataframe with features in the features dataframe
+    based on retention time (RT) and precursor m/z tolerance criteria. For each feature in the provided
+    or inferred list of feature ids (feature_uid), it computes the RT difference between the feature and available
+    MS2 spectra. It then selects MS2 spectra that fall within a computed RT radius (based on the feature's
+    start and end times) and a specified m/z tolerance. For each feature, it chooses one MS2 spectrum per
+    unique cycle based on the closest RT difference, and it updates the feature with the list of matched
+    scan ids and the spectrum corresponding to the first matching scan id. Additionally, the scan dataframe
+    is updated to associate matched scan ids with the corresponding feature id.
+
+    Parameters:
+        **kwargs: Keyword arguments for MS2 linking parameters. Can include:
+            - A find_ms2_defaults instance to set all parameters at once
+            - Individual parameter names and values (see find_ms2_defaults for details)
+
+    Key Parameters:
+        features (int or list of int, optional): A specific feature id or a list of feature ids to process.
+            If an individual feature_uid is provided and equals -1, all features with no associated MS2 data will be processed.
+            If None, all features in the features dataframe are processed.
+        mz_tol (float, optional): The precursor m/z tolerance to consider when matching MS2 spectra. If not provided,
+            it defaults to 0.5, except for certain file types ('ztscan' or 'dia') which set it to 4.
+        centroid (bool, optional): If True, the returned spectrum will be centroided. Default is True.
+        deisotope (bool, optional): Flag indicating whether deisotoping should be performed. Default is False.
+        dia_stats (bool, optional): A flag to collect additional DIA-related statistics when retrieving a spectrum.
+            Default is False.
+
+    Returns:
+        None
+
+    Side Effects:
+        Updates self.features_df with new columns 'ms2_scans' (a list of scan ids) and 'ms2_specs' (containing
+        the retrieved spectrum for the first matched scan id). Also, self.scans_df is updated by setting the 'feature_uid'
+        column for matched MS2 spectra.
+
+    Notes:
+        - The function uses vectorized operations to quickly filter MS2 spectra with ms_level equal to 2.
+        - If no MS2 spectra are available or if features_df is not loaded, appropriate messages are printed and the
+            method exits early.
+        - The function assumes that self.features_df and self.scans_df are already set up and contain the expected
+            columns ('feature_uid', 'rt', 'rt_start', 'rt_end', 'mz' for features and 'scan_uid', 'rt', 'prec_mz', 'cycle', 'ms_level'
+            for scans).
+
+    Examples:
+        Assume the current instance has features and scans data loaded, then to link MS2 spectra for all features:
+            instance.find_ms2()
+        To link MS2 spectra for a specific list of feature ids:
+            instance.find_ms2(feature_uid=[1, 3, 5])
+    """
+
+    # parameters initialization
+    params = find_ms2_defaults()
+    for key, value in kwargs.items():
+        if isinstance(value, find_ms2_defaults):
+            params = value
+            self.logger.debug("Using provided find_ms2_defaults parameters")
+        else:
+            if hasattr(params, key):
+                if params.set(key, value, validate=True):
+                    self.logger.debug(f"Updated parameter {key} = {value}")
+                else:
+                    self.logger.warning(
+                        f"Failed to set parameter {key} = {value} (validation failed)",
+                    )
+            else:
+                self.logger.debug(f"Unknown parameter {key} ignored")
+    # end of parameter initialization
+
+    # Extract parameter values
+    features = params.get("features")
+    mz_tol = params.get_mz_tolerance(self.file_type)
+    centroid = params.get("centroid")
+    deisotope = params.get("deisotope")
+    dia_stats = params.get("dia_stats")
+
+    self.logger.debug("Starting MS2 spectra linking...")
+    self.logger.debug(
+        f"Parameters: mz_tol={mz_tol}, centroid={centroid}, deisotope={deisotope}",
+    )
+
+    # Ensure features_df is loaded and has the MS2 columns
+    if self.features_df is None:
+        self.logger.error("Please find features first.")
+        return
+    if "ms2_scans" not in self.features_df.columns:
+        self.features_df["ms2_scans"] = None
+    if "ms2_specs" not in self.features_df.columns:
+        self.features_df["ms2_specs"] = None
+
+    feature_uid_list = []
+    self.logger.debug("Building lookup lists")
+    if features == []:
+        features = None  # If empty list, treat as None
+    feature_uid_list = self._get_feature_uids(features)
+
+    if len(feature_uid_list) == 0:
+        self.logger.warning("No features to process.")
+        return
+
+    ms2_df = self.scans_df.filter(pl.col("ms_level") == 2)
+    if len(ms2_df) == 0:
+        self.logger.warning("No MS2 spectra found in file.")
+        return
+
+    ms2_index_arr = ms2_df["scan_uid"].to_numpy()
+    ms2_rt = ms2_df["rt"].to_numpy()
+    ms2_precursor = ms2_df["prec_mz"].to_numpy()
+    ms2_cycle = ms2_df["cycle"].to_numpy()
+
+    features_df = self.features_df
+    c = 0
+
+    if self.file_interface is None:
+        self.index_file()
+
+    # Vectorize the entire operation for better performance
+    features_subset = features_df.filter(pl.col("feature_uid").is_in(feature_uid_list))
+
+    if len(features_subset) == 0:
+        return
+
+    # Convert to numpy arrays for vectorized operations
+    feature_rt = features_subset.select("rt").to_numpy().flatten()
+    feature_mz = features_subset.select("mz").to_numpy().flatten()
+    feature_rt_start = features_subset.select("rt_start").to_numpy().flatten()
+    feature_rt_end = features_subset.select("rt_end").to_numpy().flatten()
+    feature_uids = features_subset.select("feature_uid").to_numpy().flatten()
+    feature_indices = features_subset.with_row_index().select("index").to_numpy().flatten()
+
+    # Pre-compute RT radius for all features
+    rt_radius = np.minimum(feature_rt - feature_rt_start, feature_rt_end - feature_rt)
+
+    # Batch process all features
+    scan_uid_lists: list[list[int]] = []
+    spec_lists: list[list[Spectrum]] = []
+    updated_feature_uids = []
+    updated_scan_uids = []
+
+    tdqm_disable = self.log_level not in ["TRACE", "DEBUG", "INFO"]
+
+    for i, (rt_center, mz_center, radius, feature_uid, idx) in enumerate(
+        tqdm(
+            zip(
+                feature_rt,
+                feature_mz,
+                rt_radius,
+                feature_uids,
+                feature_indices,
+                strict=False,
+            ),
+            total=len(features_subset),
+            desc=f"{datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]} | INFO     | {self.log_label}Link MS2 spectra",
+            disable=tdqm_disable,
+        ),
+    ):
+        # Vectorized filtering
+        rt_mask = np.abs(ms2_rt - rt_center) <= radius
+        mz_mask = np.abs(ms2_precursor - mz_center) <= mz_tol
+        valid_mask = rt_mask & mz_mask
+
+        if not np.any(valid_mask):
+            scan_uid_lists.append(None)
+            spec_lists.append(None)
+            continue
+
+        valid_indices = np.nonzero(valid_mask)[0]
+        rt_diffs = np.abs(ms2_rt[valid_indices] - rt_center)
+        sorted_indices = valid_indices[np.argsort(rt_diffs)]
+
+        # Get unique cycles and their first occurrences
+        cycles = ms2_cycle[sorted_indices]
+        _, first_idx = np.unique(cycles, return_index=True)
+        final_indices = sorted_indices[first_idx]
+
+        # Sort by RT difference again
+        final_rt_diffs = np.abs(ms2_rt[final_indices] - rt_center)
+        final_indices = final_indices[np.argsort(final_rt_diffs)]
+
+        scan_uids = ms2_index_arr[final_indices].tolist()
+        scan_uid_lists.append(scan_uids)
+        spec_lists.append([
+            self.get_spectrum(
+                scan_uids[0],
+                centroid=centroid,
+                deisotope=deisotope,
+                dia_stats=dia_stats,
+                feature_uid=feature_uid,
+            ),
+        ])
+
+        # Collect updates for batch processing
+        updated_feature_uids.extend([feature_uid] * len(final_indices))
+        updated_scan_uids.extend(ms2_index_arr[final_indices])
+        c += 1
+
+    self.logger.debug("Update features.")
+    # Convert to polars if needed and batch update features_df
+    if not isinstance(features_df, pl.DataFrame):
+        features_df = pl.from_pandas(features_df)
+
+    # Update the features_df
+    update_df = pl.DataFrame({
+        "temp_idx": feature_indices,
+        "ms2_scans": pl.Series("ms2_scans", scan_uid_lists, dtype=pl.Object),
+        "ms2_specs": pl.Series("ms2_specs", spec_lists, dtype=pl.Object),
+    })
+
+    # Join and update
+    features_df = (
+        features_df.with_row_index("temp_idx")
+        .join(
+            update_df,
+            on="temp_idx",
+            how="left",
+            suffix="_new",
+        )
+        .with_columns([
+            pl.when(pl.col("ms2_scans_new").is_not_null())
+            .then(pl.col("ms2_scans_new"))
+            .otherwise(pl.col("ms2_scans"))
+            .alias("ms2_scans"),
+            pl.when(pl.col("ms2_specs_new").is_not_null())
+            .then(pl.col("ms2_specs_new"))
+            .otherwise(pl.col("ms2_specs"))
+            .alias("ms2_specs"),
+        ])
+        .drop(["temp_idx", "ms2_scans_new", "ms2_specs_new"])
+    )
+
+    # Batch update scans_df
+    if updated_scan_uids:
+        scan_feature_uid_updates = dict(
+            zip(updated_scan_uids, updated_feature_uids, strict=True),
+        )
+        self.scans_df = (
+            self.scans_df.with_columns(
+                pl.col("scan_uid")
+                .map_elements(
+                    lambda x: scan_feature_uid_updates.get(x),
+                    return_dtype=pl.Int64,
+                )
+                .alias("feature_uid_update"),
+            )
+            .with_columns(
+                pl.when(pl.col("feature_uid_update").is_not_null())
+                .then(pl.col("feature_uid_update"))
+                .otherwise(pl.col("feature_uid"))
+                .alias("feature_uid"),
+            )
+            .drop("feature_uid_update")
+        )
+
+    # Log completion
+    self.logger.info(
+        f"MS2 linking completed. Total features with MS2 data: {c}",
+    )
+    self.features_df = features_df
+
+    # store params
+    self.store_history(["find_ms2"], params.to_dict())
+    self.logger.debug(
+        "Parameters stored to find_ms2",
+    )