masster 0.3.9__py3-none-any.whl → 0.3.11__py3-none-any.whl

masster/sample/processing.py

@@ -19,55 +19,34 @@ 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.
+    """Retrieve a single spectrum and optionally post-process it.
+
+    The function locates the requested scan in ``self.scans_df`` and returns a
+    :class:`Spectrum` object. Processing steps (centroiding, deisotoping,
+    trimming and optional DIA statistics) are controlled by parameters defined
+    in :class:`get_spectrum_defaults`. Pass an instance of that class via
+    ``**kwargs`` or override individual parameters (they will be validated
+    against the defaults class).
+
+    Main parameters (from ``get_spectrum_defaults``):
+
+    - scan (list[int]): Scan id(s) to retrieve. A single integer or a list is accepted.
+    - precursor_trim (int): m/z window used to trim precursor region for MS2 (default: -10).
+    - max_peaks (int | None): Maximum number of peaks to keep; ``None`` keeps all.
+    - centroid (bool): Whether to centroid the spectrum (default: True).
+    - deisotope (bool): Whether to apply deisotoping (default: True).
+    - dia_stats (bool | None): Collect DIA/ztscan statistics when applicable (default: False).
+    - feature (int | None): Optional feature id used for computing DIA statistics.
+    - label (str | None): Optional label to assign to the returned Spectrum.
+    - centroid_algo (str | None): Centroiding algorithm to use (allowed: 'lmp', 'cwt', 'gaussian').
 
     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.
+        Spectrum or None: Processed spectrum object (may be an empty Spectrum if
+        the scan is missing or on error).
 
     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.
+        This wrapper validates provided parameters against ``get_spectrum_defaults``.
+        Use the defaults class to discover parameter constraints and allowed values.
     """
 
     # parameters initialization
@@ -510,40 +489,51 @@ def _spec_to_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.
+    """Detect features from MS1 data (mass-trace detection, peak deconvolution, feature assembly).
 
-    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.
+    The method converts internal MS1 data into an MSExperiment (one MSSpectrum per cycle), runs mass-trace
+    detection, deconvolutes mass traces to find chromatographic peaks, and assembles features. Results are
+    cleaned, optionally deisotoped, assigned unique IDs and stored in ``self.features`` / ``self.features_df``.
 
     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).
+        **kwargs: Keyword overrides for any parameter available in :class:`find_features_defaults`.
+            You may pass a full ``find_features_defaults`` instance or individual parameter values.
+
+    Main parameters (what they mean, units and tuning guidance):
+
+    - chrom_fwhm (float, seconds):
+        Expected chromatographic peak full-width at half-maximum (FWHM) in seconds. This guides smoothing,
+        peak-finding window sizes and RT-based tolerances. Choose a value that matches your LC peak widths:
+        small values (e.g. 0.2–0.8 s) for sharp/fast separations, larger values (several seconds) for broad peaks.
+        Default: 1.0 s.
+
+    - noise (float, intensity units):
+        Intensity threshold used to ignore background points before mass-trace and peak detection. Raising
+        ``noise`` reduces false positives from baseline fluctuations but may discard low-abundance true signals;
+        lowering it increases sensitivity but raises the false-positive rate. Set this to a conservative estimate of
+        your instrument baseline (default: 200.0, instrument-dependent).
+
+    - chrom_peak_snr (float, unitless):
+        Minimum signal-to-noise ratio required to accept an elution peak during peak deconvolution. SNR is usually
+        computed as peak height divided by a local noise estimate. Higher values make detection stricter (fewer
+        low-quality peaks), lower values make it more permissive. Typical tuning range: ~3 (relaxed) to >10
+        (stringent). Default: 10.0.
+
+    - isotope_filtering_model (str):
+        Isotope filtering model ('metabolites (2% RMS)', 'metabolites (5% RMS)', 'peptides', 'none').
+        Default: 'metabolites (5% RMS)'.
+
+    Tuning recommendation: first set ``chrom_fwhm`` to match your LC peak shape, then set ``noise`` to a baseline
+    intensity filter for your data, and finally adjust ``chrom_peak_snr`` to reach the desired balance between
+    sensitivity and specificity.
 
     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.
+        self.features: OpenMS FeatureMap produced by the routine (after ensureUniqueId).
+        self.features_df: cleaned polars DataFrame of detected features (zero-quality peaks removed).
 
     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.
+        The implementation relies on OpenMS components (MassTraceDetection, ElutionPeakDetection,
+        FeatureFindingMetabo). See ``find_features_defaults`` for the full list of adjustable parameters.
     """
     if self.ms1_df is None:
         self.logger.error("No MS1 data found. Please load a file first.")
@@ -570,24 +560,25 @@ def find_features(self, **kwargs):
                 self.logger.warning(f"Unknown parameter {key} ignored")
 
     # Set global parameters
-    if hasattr(params, 'threads') and params.threads is not None:
+    if hasattr(params, "threads") and params.threads is not None:
         try:
             # Try setting via OpenMP environment variable first (newer approach)
             import os
-            os.environ['OMP_NUM_THREADS'] = str(params.threads)
+
+            os.environ["OMP_NUM_THREADS"] = str(params.threads)
             self.logger.debug(f"Set thread count to {params.threads} via OMP_NUM_THREADS")
         except Exception:
             self.logger.warning(f"Could not set thread count to {params.threads} - using default")
-    
+
     # Set debug mode if enabled
-    if hasattr(params, 'debug') and params.debug:
+    if hasattr(params, "debug") and params.debug:
         self.logger.debug("Debug mode enabled")
-    elif hasattr(params, 'no_progress') and params.no_progress:
+    elif hasattr(params, "no_progress") and params.no_progress:
         self.logger.debug("No progress mode enabled")
-    
+
     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')}",
+        f"Parameters: chrom_fwhm={params.get('chrom_fwhm')}, noise={params.get('noise')}, tol_ppm={params.get('tol_ppm')}, isotope_filtering_model={params.get('isotope_filtering_model')}",
     )
 
     exp = oms.MSExperiment()
@@ -625,7 +616,7 @@ def find_features(self, **kwargs):
         int(params.get("trace_termination_outliers")),
     )
     mtd_par.setValue("chrom_peak_snr", float(params.get("chrom_peak_snr")))
-    
+
     # Additional MTD parameters
     mtd_par.setValue("min_sample_rate", float(params.get("min_sample_rate")))
     mtd_par.setValue("min_trace_length", float(params.get("min_trace_length")))
@@ -644,19 +635,16 @@ def find_features(self, **kwargs):
     # 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("max_fwhm", float(params.get("chrom_fwhm_max")))
     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")
-    
+
     # Additional EPD parameters
     epd_par.setValue("enabled", "true" if params.get("enabled") else "false")
-    
-    # Set min/max FWHM parameters
-    epd_par.setValue("min_fwhm", float(params.get("min_fwhm")))
-    epd_par.setValue("max_fwhm", float(params.get("max_fwhm")))
 
     epd.setParameters(epd_par)
     epd.detectPeaks(mass_traces, mass_traces_deconvol)
@@ -684,18 +672,19 @@ def find_features(self, **kwargs):
         "report_chromatograms",
         "true" if params.get("report_chromatograms") else "false",
     )
-    
+    ffm_par.setValue(
+        "report_smoothed_intensities",
+        "true" if params.get("report_smoothed_intensities") else "false",
+    )
     # Additional FFM parameters
     ffm_par.setValue("local_rt_range", float(params.get("local_rt_range")))
     ffm_par.setValue("local_mz_range", float(params.get("local_mz_range")))
     ffm_par.setValue("charge_lower_bound", int(params.get("charge_lower_bound")))
     ffm_par.setValue("charge_upper_bound", int(params.get("charge_upper_bound")))
-    ffm_par.setValue(
-        "report_smoothed_intensities",
-        "true" if params.get("report_smoothed_intensities") else "false",
-    )
+    ffm_par.setValue("isotope_filtering_model", params.get("isotope_filtering_model"))
 
     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)
@@ -712,7 +701,7 @@ def find_features(self, **kwargs):
     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"),
+        rt_tol=params.get("chrom_fwhm") * params.get("deisotope_rt_tol_factor"),
     )
     if params.get("deisotope"):
         # record size before deisotoping
@@ -729,8 +718,8 @@ def find_features(self, **kwargs):
     prominence_scaleds: list[float] = []
     height_scaleds: list[float] = []
 
-    mz_tol = params.get("eic_mz_tol")
-    rt_tol = params.get("eic_rt_tol")
+    mz_tol = self.parameters.get("eic_mz_tol")
+    rt_tol = self.parameters.get("eic_rt_tol")
 
     # iterate over all rows in df using polars iteration
     self.logger.debug("Extracting EICs...")
@@ -807,27 +796,44 @@ def find_features(self, **kwargs):
 
 
 def find_adducts(self, **kwargs):
-    """
-    Detect adducts in mass spectrometry features using OpenMS MetaboliteFeatureDeconvolution.
+    """Detect adduct relationships among detected features.
 
-    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.
+    This method groups features that are likely adducts of the same molecular entity
+    using OpenMS MetaboliteFeatureDeconvolution. Parameters are taken from the
+    :class:`find_adducts_defaults` dataclass; you can pass an instance of that class
+    via ``**kwargs`` or override individual parameter names (they will be validated
+    against the defaults class).
 
-    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)
+    Main parameters (from ``find_adducts_defaults``):
 
-    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).
+    - adducts (list[str] | str | None):
+        List of potential adduct strings formatted for OpenMS, or a short ionization
+        mode string (``'pos'``/``'neg'``). When ``None`` a sensible positive-mode
+        default set is used.
 
-    Attributes set:
-        self.features_df: Updated with adduct information including 'adduct', 'adduct_mass',
-                         and 'adduct_group' columns.
+    - charge_min (int):
+        Minimum allowed charge state for grouping (default: 1).
+
+    - charge_max (int):
+        Maximum allowed charge state for grouping (default: 2).
+
+    - charge_span_max (int):
+        Maximum span between different charge states within the same adduct group
+        (default: 2).
+
+    - retention_max_diff (float, minutes):
+        Global maximum retention-time difference allowed for grouping (default: 1.0).
+
+    - retention_max_diff_local (float, minutes):
+        A tighter, local RT tolerance used for fine-grained grouping (default: 1.0).
+
+    Side effects:
+        Updates ``self.features_df`` with columns ``adduct``, ``adduct_mass`` and
+        ``adduct_group`` populated from the OpenMS results.
+
+    Notes:
+        Use ``find_adducts_defaults`` to inspect available parameters and their
+        canonical descriptions/constraints.
     """
     params = find_adducts_defaults()
     for key, value in kwargs.items():
@@ -1177,54 +1183,44 @@ def analyze_dda(self):
 
 
 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.
+    """Link MS2 spectra to detected features.
 
-    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.
+    Matches MS2 scans from ``self.scans_df`` to features in ``self.features_df`` using
+    retention time and precursor m/z criteria. Parameters are defined in
+    :class:`find_ms2_defaults`; pass an instance via ``**kwargs`` or override
+    individual parameters (they will be validated against the defaults class).
 
-    Returns:
-        None
+    Main parameters (from ``find_ms2_defaults``):
+
+    - mz_tol (float):
+        Precursor m/z tolerance used for matching. The effective tolerance may be
+        adjusted by file type (the defaults class provides ``get_mz_tolerance(file_type)``).
+        Default: 0.5 (ztscan/DIA defaults may be larger).
+
+    - centroid (bool):
+        If True, retrieved spectra will be centroided (default: True).
 
-    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.
+    - deisotope (bool):
+        If True, spectra will be deisotoped before returning (default: False).
+
+    - dia_stats (bool):
+        Collect additional DIA/ztscan statistics when retrieving spectra (default: False).
+
+    - features (int | list[int] | None):
+        Specific feature uid or list of uids to process. Use ``None`` to process all
+        features. An empty list is treated as ``None``.
+
+    - mz_tol_ztscan (float):
+        m/z tolerance used for ztscan/DIA file types (default: 4.0).
+
+    Side effects:
+        Updates ``self.features_df`` with columns ``ms2_scans`` and ``ms2_specs`` and
+        updates ``self.scans_df`` to set the ``feature_uid`` for matched scans.
 
     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])
+        The function is implemented to be efficient by vectorizing the matching
+        and performing batch updates. Use ``find_ms2_defaults`` to inspect all
+        available parameters and their canonical descriptions.
     """
 
     # parameters initialization
@@ -1374,6 +1370,7 @@ def find_ms2(self, **kwargs):
 
     self.logger.debug("Update features.")
     # Convert to polars if needed and batch update features_df
+    # Convert to polars if needed and batch update features_df
     if not isinstance(features_df, pl.DataFrame):
         features_df = pl.from_pandas(features_df)
 

masster/sample/sample.py

@@ -333,15 +333,15 @@ class Sample:
             if module_name.startswith(study_module_prefix) and module_name != current_module:
                 study_modules.append(module_name)
 
-        ''' # Add parameters submodules
+        """ # Add parameters submodules
         parameters_modules = []
         parameters_module_prefix = f"{base_modname}.parameters."
         for module_name in sys.modules:
             if module_name.startswith(parameters_module_prefix) and module_name != current_module:
                 parameters_modules.append(module_name)
-        '''
-    
-        all_modules_to_reload = core_modules + sample_modules + study_modules #+ parameters_modules
+        """
+
+        all_modules_to_reload = core_modules + sample_modules + study_modules  # + parameters_modules
 
         # Reload all discovered modules
         for full_module_name in all_modules_to_reload: