corems.encapsulation.factory.processingSetting

   1__author__ = "Yuri E. Corilo"
   2__date__ = "Jul 02, 2019"
   3
   4import dataclasses
   5import os
   6from typing import List, Dict
   7
   8from corems.encapsulation.constant import Atoms, Labels
   9
  10# Field metadata: omit from JSON/TOML parameter export (in-memory back-compat only).
  11LEGACY_PARAMETER = "legacy"
  12
  13
  14def legacy_field(default, **kwargs):
  15    """``dataclasses.field`` that marks a setting as legacy (not exported).
  16
  17    Use for in-memory / back-compat aliases that must not appear in
  18    parameter JSON/TOML when settings are dumped. Export paths should use
  19    :func:`settings_to_export_dict` (or equivalent) so this metadata is honored.
  20    """
  21    metadata = dict(kwargs.pop("metadata", {}) or {})
  22    metadata[LEGACY_PARAMETER] = True
  23    return dataclasses.field(default=default, metadata=metadata, **kwargs)
  24
  25
  26def settings_to_export_dict(settings_obj) -> dict:
  27    """Serialize settings for parameter export; skip fields marked legacy.
  28
  29    Fields defined with :func:`legacy_field` (metadata
  30    ``LEGACY_PARAMETER=True``) are omitted. Used by LCMS parameter dump so
  31    old annotation knobs on ``LiquidChromatographSetting`` are not rewritten
  32    into TOML/JSON after migration to ``spectral_similarity_search``.
  33    """
  34    if not dataclasses.is_dataclass(settings_obj) or isinstance(settings_obj, type):
  35        return dict(getattr(settings_obj, "__dict__", {}))
  36    out = {}
  37    for f in dataclasses.fields(settings_obj):
  38        if f.metadata.get(LEGACY_PARAMETER, False):
  39            continue
  40        out[f.name] = getattr(settings_obj, f.name)
  41    return out
  42
  43
  44def validate_used_atoms_keys(used_atoms):
  45    """Validate that usedAtoms keys are element symbols, not rare isotopes.
  46
  47    Molecular formula search treats each usedAtoms key as a monoisotopic
  48    (most-abundant) element. Heavy isotopologues (e.g. 13C, 54Fe, 37Cl) are
  49    produced later by isotopologue expansion of mono formulas, not by listing
  50    rare-isotope labels in usedAtoms. Membership in ``Atoms.isotopes`` does
  51    not mean the element is ready to search: each key still needs a valence
  52    in ``used_atom_valences`` (typically copied from ``Atoms.atoms_covalence``),
  53    or DBE calculation can fail.
  54
  55    Parameters
  56    ----------
  57    used_atoms : dict
  58        Mapping of atom symbol to (min, max) count range.
  59
  60    Raises
  61    ------
  62    ValueError
  63        If any key is not a mono element symbol (key of Atoms.isotopes).
  64    TypeError
  65        If used_atoms is not a mapping.
  66    """
  67    if used_atoms is None:
  68        return
  69    if not hasattr(used_atoms, "keys"):
  70        raise TypeError(
  71            "usedAtoms must be a dict of element symbols to (min, max) ranges"
  72        )
  73    invalid = [k for k in used_atoms.keys() if k not in Atoms.isotopes]
  74    if invalid:
  75        raise ValueError(
  76            "usedAtoms keys must be element symbols (e.g. Fe, C, Cl), "
  77            "not specific isotope labels (e.g. 54Fe, 13C, 37Cl). "
  78            f"Invalid key(s): {invalid}. "
  79            "Heavy isotopologues are generated from mono formulas during search."
  80        )
  81
  82
  83@dataclasses.dataclass
  84class TransientSetting:
  85    """Transient processing settings class
  86
  87    Attributes
  88    ----------
  89    implemented_apodization_function : tuple
  90        Available apodization functions
  91    apodization_method : str
  92        Apodization function to use. Hanning is a good default for Fourier transform magnitude mode.
  93        For absorption mode processing, Half-Sine or Half-Kaiser may be more appropriate.
  94    number_of_truncations : int
  95        How many times to truncate the transient prior to Fourier transform
  96    number_of_zero_fills : int
  97        How many times to zero fille the transient prior to Fourier transform.
  98    next_power_of_two : bool
  99        If True, zero fill to the next power of two after the new length of len(transient)+(number_of_zero_fills*len(transient)).
 100    kaiser_beta : float
 101        Beta parameter for Kaiser or Half-Kaiser apodisation function. 0 is rectangular,  5 is similar to Hamming,
 102        6 is similar to hanning, and 8.6 is similar to Blackman (from numpy docs)
 103
 104    """
 105
 106    implemented_apodization_function: tuple = (
 107        "Hamming",
 108        "Hanning",
 109        "Blackman",
 110        "Full-Sine",
 111        "Half-Sine",
 112        "Kaiser",
 113        "Half-Kaiser",
 114        "Rectangle",
 115    )
 116    apodization_method: str = "Hanning"
 117    number_of_truncations: int = 0
 118    number_of_zero_fills: int = 1
 119    next_power_of_two: bool = False
 120    kaiser_beta: float = 8.6
 121
 122    def __post_init__(self):
 123        # enforce datatype
 124        for field in dataclasses.fields(self):
 125            value = getattr(self, field.name)
 126            if not isinstance(value, field.type):
 127                value = field.type(value)
 128                setattr(self, field.name, value)
 129
 130
 131@dataclasses.dataclass
 132class DataInputSetting:
 133    """Data input settings class
 134
 135    Attributes
 136    ----------
 137    header_translate : dict
 138        Dictionary with the header labels to be translated to the corems labels. For example, {'m/z':'m/z', 'Resolving Power':'Resolving Power', 'Abundance':'Abundance' , 'S/N':'S/N'}
 139    """
 140
 141    # add to this dict the VALUES to match your labels, THE ORDER WON"T MATTER
 142    # "column_translate" : {"m/z":"m/z", "Resolving Power":"Resolving Power", "Abundance":"Abundance" , "S/N":"S/N"}
 143    header_translate: dict = dataclasses.field(default_factory=dict)
 144
 145    def __post_init__(self):
 146        self.header_translate = {
 147            "m/z": Labels.mz,
 148            "mOz": Labels.mz,
 149            "Mass": Labels.mz,
 150            "Resolving Power": Labels.rp,
 151            "Res.": Labels.rp,
 152            "resolution": Labels.rp,
 153            "Intensity": Labels.abundance,
 154            "Peak Height": Labels.abundance,
 155            "I": Labels.abundance,
 156            "Abundance": Labels.abundance,
 157            "abs_abu": Labels.abundance,
 158            "Signal/Noise": Labels.s2n,
 159            "S/N": Labels.s2n,
 160            "sn": Labels.s2n,
 161        }
 162
 163    def add_mz_label(self, label):
 164        """Add a label to the header_translate dictionary to be translated to the corems label for mz."""
 165        self.header_translate[label] = Labels.mz
 166
 167    def add_peak_height_label(self, label):
 168        """Add a label to the header_translate dictionary to be translated to the corems label for peak height."""
 169
 170        self.header_translate[label] = Labels.abundance
 171
 172    def add_sn_label(self, label):
 173        """Add a label to the header_translate dictionary to be translated to the corems label for signal to noise."""
 174        self.header_translate[label] = Labels.s2n
 175
 176    def add_resolving_power_label(self, label):
 177        """Add a label to the header_translate dictionary to be translated to the corems label for resolving power."""
 178        self.header_translate[label] = Labels.rp
 179
 180
 181@dataclasses.dataclass
 182class LiquidChromatographSetting:
 183    """Liquid chromatograph processing settings class
 184
 185    Attributes
 186    ----------
 187    scans : list or tuple, optional
 188        List of select scan to average or a tuple containing the range to average.
 189        Default is (-1, -1).
 190    eic_tolerance_ppm : float, optional
 191        Mass tolerance in ppm for extracted ion chromatogram peak detection.
 192        Default is 5.
 193    correct_eic_baseline : bool, optional
 194        If True, correct the baseline of the extracted ion chromatogram.
 195        Default is True.
 196    smooth_window : int, optional
 197        Window size for smoothing the ion chromatogram (extracted or total).
 198        Default is 5.
 199    smooth_method : str, optional
 200        Smoothing method to use. See implemented_smooth_method for options.
 201        Default is 'savgol'.
 202    implemented_smooth_method : tuple, optional
 203        Smoothing methods that can be implemented.
 204        Default is ('savgol', 'hanning', 'blackman', 'bartlett', 'flat', 'boxcar').
 205    savgol_pol_order : int, optional
 206        Polynomial order for Savitzky-Golay smoothing.
 207        Default is 2.
 208    consecutive_scan_min : int, optional
 209        Minimum number of consecutive scans to consider for peak detection.
 210        Default is 0 for backwards compatibility, but a value of 3 is recommended.
 211    peak_height_max_percent : float, optional
 212        1-100 % used for baseline detection use 0.1 for second_derivative and 10 for other methods.
 213        Default is 10.
 214    peak_max_prominence_percent : float, optional
 215        1-100 % used for baseline detection.
 216        Default is 1.
 217    peak_derivative_threshold : float, optional
 218        Threshold for defining derivative crossing.
 219        Default is 0.0005.
 220    min_peak_datapoints : float, optional
 221        minimum data point to define a chromatografic peak.
 222        Default is 5.
 223    noise_threshold_method : str, optional
 224        Method for detecting noise threshold.
 225        Default is 'manual_relative_abundance'.
 226    noise_threshold_methods_implemented : tuple, optional
 227        Methods for detected noise threshold that can be implemented.
 228        Default is ('auto_relative_abundance', 'manual_relative_abundance', 'second_derivative').
 229    peak_height_min_percent : float, optional
 230        0-100 % used for peak detection.
 231        Default is 0.1.
 232    eic_signal_threshold : float, optional
 233        0-100 % used for extracted ion chromatogram peak detection.
 234        Default is 0.01.
 235    eic_buffer_time : float, optional
 236        Buffer time to add to the start and end of the plot of the extracted ion chromatogram, in minutes.
 237        Default is 1.5.
 238    dispersity_index_window : float, optional
 239        Dispersity index window size, in minutes.
 240        Default is 3.0.
 241    noise_window_factor : float, optional
 242        Factor to determine noise estimation window size relative to peak width.
 243        Larger values use wider windows for noise estimation.
 244        For example, a value of 2.0 uses a window size equal to twice the peak width
 245        (depending on it's start and end scans) on each side.
 246        Called within the LCMSMassFeature.calc_noise_score() method.
 247        Default is 2.0.
 248    remove_redundant_mass_features : bool, optional
 249        If True, remove redundant mass features that are likely contaminants based on
 250        their m/z values and scan frequency.
 251        Especially useful for HILIC data where signals do not return to baseline between peaks
 252        or for data with significant background noise.
 253        Called within the LC_Calculations.find_mass_features() method.
 254        Default is False.
 255    redundant_scan_frequency_min : float, optional
 256        Minimum fraction of scans that must contain the m/z to be considered a likely
 257        noise/contaminant when using remove_redundant_mass_features.
 258        Default is 0.1 (10% of scans).
 259    redundant_feature_retain_n : int, optional
 260        Number of features to retain in each group when using remove_redundant_mass_features.
 261        Default is 3.
 262    remove_mass_features_by_peak_metrics : bool, optional
 263        If True, remove mass features based on their peak metrics such as S/N, Gaussian similarity,
 264        dispersity index, and noise score.
 265        Called within the LC_Calculations.add_peak_metrics() method.
 266        Default is False.
 267    mass_feature_attribute_filter_dict : dict, optional
 268        Dictionary specifying filtering criteria for mass feature attributes.
 269        Each key is an attribute name, and each value is a dict with 'value' and 'operator' keys.
 270
 271        Structure: {attribute_name: {'value': threshold, 'operator': comparison}}
 272
 273        Available operators:
 274        - '>' or 'greater': Keep features where attribute > threshold
 275        - '<' or 'less': Keep features where attribute < threshold
 276        - '>=' or 'greater_equal': Keep features where attribute >= threshold
 277        - '<=' or 'less_equal': Keep features where attribute <= threshold
 278
 279        Examples:
 280        {
 281            'noise_score_max': {'value': 0.5, 'operator': '>'},  # Keep if noise_score_max > 0.5
 282            'dispersity_index': {'value': 0.1, 'operator': '<'},  # Keep if dispersity_index < 0.1
 283            'gaussian_similarity': {'value': 0.7, 'operator': '>='}  # Keep if gaussian_similarity >= 0.7
 284        }
 285
 286        Available attributes include: 'noise_score', 'noise_score_min', 'noise_score_max',
 287        'gaussian_similarity', 'tailing_factor', 'dispersity_index', 'half_height_width', 'intensity'.
 288        Default is {"noise_score_max": {"value": 0.8, "operator": ">="},"noise_score_min": {"value": 0.5, "operator": ">="}},
 289    peak_picking_method : str, optional
 290        Peak picking method to use. See implemented_peak_picking_methods for options.
 291        Default is 'by_format', which selects persistent homology when all scans
 292        at the requested MS level are profile and centroided persistent
 293        homology when all are centroid, then stores the concrete method on
 294        this setting so saved parameters record what was used.
 295    implemented_peak_picking_methods : tuple, optional
 296        Peak picking methods that can be implemented.
 297        Default is ('by_format', 'persistent homology', 'centroided_persistent_homology').
 298    ph_smooth_it : int, optional
 299        Number of iterations to use for smoothing prior to finding mass features.
 300        Used only for "persistent homology" peak picking method.
 301        Called within the PHCalculations.find_mass_features_ph() method.
 302        Default is 1.
 303    ph_smooth_radius_mz : int, optional
 304        Radius in m/z steps (not daltons) for smoothing prior to finding mass features.
 305        Used only for "persistent homology" peak picking method.
 306        Called within the PHCalculations.find_mass_features_ph() method.
 307        Default is 0.
 308    ph_smooth_radius_scan : int, optional
 309        Radius in scan steps for smoothing prior to finding mass features.
 310        Used only for "persistent homology" peak picking method.
 311        Called within the PHCalculations.find_mass_features_ph() method.
 312        Default is 1.
 313    ph_inten_min_rel : float, optional
 314        Relative minimum intensity to use for finding mass features for persistent homology.
 315        Used only for "persistent homology" peak picking method.
 316        Calculated as a fraction of the maximum intensity of the unprocessed profile data (mz, scan).
 317        Called within the PH_Calculations.find_mass_features() method.
 318        Default is 0.001.
 319    ph_persis_min_rel : float, optional
 320        Relative minimum persistence for retaining mass features.
 321        Used for both "persistent homology" and "centroided_persistent_homology" peak picking methods.
 322        Calculated as a fraction of the maximum intensity of the unprocessed profile data (mz, scan).
 323        Should be greater to or equal to ph_inten_min_rel.
 324        Called within the PH_Calculations.find_mass_features() method.
 325        Default is 0.001.
 326    ph_inten_min_abs : float, optional
 327        Absolute minimum intensity for points that enter persistent homology.
 328        Applied with ph_inten_min_rel on profile and centroided data.
 329        The relative floor is still a fraction of the unfiltered maximum.
 330        0 disables the absolute floor. Default is 0.0.
 331    mass_feature_cluster_mz_tolerance_rel : float, optional
 332        Relative m/z tolerance to use for clustering mass features.
 333        Used for both "persistent homology" and "centroided_persistent_homology"
 334        peak picking methods.
 335        Called with the PHCalculations.cluster_mass_features() and the
 336        LCCalculations.deconvolute_ms1_mass_features() methods.
 337        Default is 5e-6 (5 ppm).
 338    mass_feature_cluster_rt_tolerance : float, optional
 339        Retention time tolerance to use for clustering mass features, in minutes.
 340        Used for both "persistent homology" and "centroided_persistent_homology"
 341        peak picking methods.
 342        Called with the PHCalculations.cluster_mass_features() and the
 343        LCCalculations.deconvolute_ms1_mass_features() methods.
 344        Default is 0.3.
 345    ms1_scans_to_average : int, optional
 346        Number of MS1 scans to average for mass-feature associated m/zs.
 347        Called within the LCMSBase.add_associated_ms1() method.
 348        Default is 1.
 349    ms1_deconvolution_corr_min : float, optional
 350        Minimum correlation to use for deconvoluting MS1 mass features.
 351        Called within the LCCalculations.deconvolute_ms1_mass_features() method.
 352        Default is 0.8.
 353    ms2_dda_rt_tolerance : float, optional
 354        Retention time tolerance to use for associating MS2 spectra to mass features, in minutes.
 355        Called within the LCMSBase.add_associated_ms2_dda() method.
 356        Default is 0.15.
 357    ms2_dda_mz_tolerance : float, optional
 358        Mass tolerance to use for associating MS2 spectra to mass features.
 359        Called within the LCMSBase.add_associated_ms2_dda() method.
 360        Default is 0.05.
 361    ms2_min_fe_score : float, optional
 362        Minimum flash entropy for retaining MS2 annotations.
 363        Legacy; prefer ``mass_spectrum["ms2"].spectral_similarity_search.ms2_min_fe_score``.
 364        Default is 0.2.
 365    search_as_lipids : bool, optional
 366        Legacy lipid-search flag; prefer ``mass_spectrum["ms2"].spectral_similarity_search``.
 367        Default is False.
 368    include_fragment_types : bool, optional
 369        Legacy fragment-type flag; prefer ``mass_spectrum["ms2"].spectral_similarity_search``.
 370        Default is False.
 371    export_profile_spectra : bool, optional
 372        If True, export profile spectra data.
 373        Default is False.
 374    export_eics : bool, optional
 375        If True, export extracted ion chromatograms.
 376        Default is True.
 377    export_unprocessed_ms1 : bool, optional
 378        If True, export unprocessed MS1 data.
 379        Default is False.
 380    export_only_relevant_mass_spectra : bool, optional
 381        If True, export only mass spectra associated with detected mass features:
 382        specifically the apex MS1 scan for each mass feature and the best MS2 scan
 383        for each mass feature (if available). If False, export all mass spectra.
 384        This parameter reduces HDF5 file size by excluding non-feature spectra.
 385        Default is False (backwards compatible - exports all spectra).
 386    verbose_processing : bool, optional
 387        If True, print verbose processing information.
 388        Default is True.
 389    """
 390
 391    scans: list | tuple = (-1, -1)
 392
 393    # Parameters used for generating EICs and performing 1D peak picking and EIC/TIC smoothing
 394    eic_tolerance_ppm: float = 5
 395    correct_eic_baseline = True
 396    smooth_window: int = 5
 397    smooth_method: str = "savgol"
 398    implemented_smooth_method: tuple = (
 399        "savgol",
 400        "hanning",
 401        "blackman",
 402        "bartlett",
 403        "flat",
 404        "boxcar",
 405    )
 406    savgol_pol_order: int = 2
 407    consecutive_scan_min: int = 0
 408    peak_height_max_percent: float = 10
 409    peak_max_prominence_percent: float = 1
 410    peak_derivative_threshold: float = 0.0005
 411    min_peak_datapoints: float = 5
 412    noise_threshold_method: str = "manual_relative_abundance"
 413    noise_threshold_methods_implemented: tuple = (
 414        "auto_relative_abundance",
 415        "manual_relative_abundance",
 416        "second_derivative",
 417    )
 418    peak_height_min_percent: float = 0.1
 419    eic_signal_threshold: float = 0.01
 420    eic_buffer_time = 1.5
 421    dispersity_index_window: float = 3.0  # minutes
 422    noise_window_factor: float = 2.0  # times the peak width for detemining SN for EIC
 423
 424    # Parameters used for filtering mass features after peak picking
 425    remove_redundant_mass_features: bool = False
 426    redundant_scan_frequency_min: float = 0.1
 427    redundant_feature_retain_n: int = 3
 428    remove_mass_features_by_peak_metrics: bool = False
 429    # note that this is a dictionary of dictionaries and set in __post_init__ instead of here
 430    mass_feature_attribute_filter_dict: Dict = dataclasses.field(default_factory=dict)
 431
 432    # Parameters used for 2D peak picking
 433    peak_picking_method: str = "by_format"
 434    implemented_peak_picking_methods: tuple = (
 435        "by_format",
 436        "persistent homology",
 437        "centroided_persistent_homology",
 438    )
 439
 440    # Parameters used in persistent homology calculations
 441    ph_smooth_it = 1
 442    ph_smooth_radius_mz = 0
 443    ph_smooth_radius_scan = 1
 444    ph_inten_min_rel = 0.001
 445    ph_persis_min_rel = 0.001
 446    ph_inten_min_abs: float = 0.0
 447
 448    # Parameters used to cluster mass features
 449    mass_feature_cluster_mz_tolerance_rel: float = 5e-6
 450    mass_feature_cluster_rt_tolerance: float = 0.3
 451
 452    # Parameters used in associating MS1 and MS2 spectra to LCMS mass features and deconvoluting MS1 mass features
 453    ms1_scans_to_average: int = 1
 454    ms1_deconvolution_corr_min: float = 0.8
 455    ms2_dda_rt_tolerance: float = 0.15
 456    ms2_dda_mz_tolerance: float = 0.05
 457
 458    # Legacy MS2 spectral annotation aliases (not exported; prefer MSParameters.spectral_similarity_search)
 459    ms2_min_fe_score: float = legacy_field(0.2)
 460    search_as_lipids: bool = legacy_field(False)
 461    include_fragment_types: bool = legacy_field(False)
 462
 463    # Parameters used for saving the data
 464    export_profile_spectra: bool = False
 465    export_eics: bool = True
 466    export_unprocessed_ms1: bool = False
 467    export_only_relevant_mass_spectra: bool = False
 468
 469    # Parameters used for verbose processing
 470    verbose_processing: bool = True
 471
 472    def __post_init__(self):
 473        # Set default values for mass_feature_attribute_filter_dict if empty
 474        if not self.mass_feature_attribute_filter_dict:
 475            self.mass_feature_attribute_filter_dict = {
 476                "noise_score_max": {"value": 0.8, "operator": ">="},
 477                "noise_score_min": {"value": 0.5, "operator": ">="},
 478            }
 479
 480        # enforce datatype
 481        for field in dataclasses.fields(self):
 482            value = getattr(self, field.name)
 483            if not isinstance(value, field.type):
 484                value = field.type(value)
 485                setattr(self, field.name, value)
 486
 487
 488@dataclasses.dataclass
 489class SpectralSimilaritySearchSettings:
 490    """Parameters for using spectral similarity to search spectra against a library of reference spectra (including within molecular networking).
 491
 492    Lives on :class:`~corems.encapsulation.factory.parameters.MSParameters`
 493    as ``spectral_similarity_search`` (e.g. ``lcms.parameters.mass_spectrum["ms2"].spectral_similarity_search``).
 494
 495    Not used for MS2 *molecular formula* search
 496    (``mass_spectrum[key].molecular_search``).
 497    """
 498
 499    # --- FlashEntropy library build (intensity normalize always on) ---
 500    max_ms2_tolerance_in_da: float = 0.01
 501    max_indexed_mz: float = 3000.0
 502    precursor_ions_removal_da: float | None = None
 503    noise_threshold: float = 0.0
 504
 505    # --- Annotation ---
 506    ms2_min_fe_score: float = 0.2
 507    include_fragment_types: bool = False
 508    search_as_lipids: bool = False
 509    peak_sep_da: float | None = None
 510
 511    # --- Molecular networking ---
 512    search_type: str = "open"
 513    additional_similarities: list = dataclasses.field(
 514        default_factory=lambda: ["cosine"]
 515    )
 516    similarity_thresholds: dict = dataclasses.field(default_factory=dict)
 517    ms1_tolerance_da: float | None = None
 518    ms2_tolerance_da: float | None = None
 519    entropy_threshold_low: float | None = None
 520    library_similarity_threshold: float = 0.3
 521    hydrate_library_similarities: bool = False
 522
 523    def __post_init__(self):
 524        if self.additional_similarities is not None:
 525            self.additional_similarities = list(self.additional_similarities)
 526        if self.similarity_thresholds is not None:
 527            self.similarity_thresholds = dict(self.similarity_thresholds)
 528
 529    @property
 530    def min_ms2_difference_in_da(self) -> float:
 531        """Minimum peak separation (Da); always ``2 * max_ms2_tolerance_in_da``."""
 532        return 2.0 * float(self.max_ms2_tolerance_in_da)
 533
 534    def copy(self) -> "SpectralSimilaritySearchSettings":
 535        """Return a copy with mutable list/dict fields isolated."""
 536        return dataclasses.replace(
 537            self,
 538            additional_similarities=list(self.additional_similarities),
 539            similarity_thresholds=dict(self.similarity_thresholds),
 540        )
 541
 542    def as_fe_kwargs(self) -> dict:
 543        """FlashEntropy library-build kwargs (historical ``fe_kwargs`` shape)."""
 544        return {
 545            "min_ms2_difference_in_da": self.min_ms2_difference_in_da,
 546            "max_ms2_tolerance_in_da": self.max_ms2_tolerance_in_da,
 547            "max_indexed_mz": self.max_indexed_mz,
 548            "precursor_ions_removal_da": self.precursor_ions_removal_da,
 549            "noise_threshold": self.noise_threshold,
 550        }
 551
 552    @property
 553    def resolved_peak_sep_da(self) -> float:
 554        """Peak separation (Da) for annotation search."""
 555        if self.peak_sep_da is not None:
 556            return float(self.peak_sep_da)
 557        return float(self.min_ms2_difference_in_da)
 558
 559
 560@dataclasses.dataclass
 561class MassSpectrumSetting:
 562    """Mass spectrum processing settings class
 563
 564    Attributes
 565    ----------
 566    noise_threshold_method : str, optional
 567        Method for detecting noise threshold. Default is 'by_format', which
 568        selects 'log' for a profile spectrum and 'relative_abundance' for
 569        a centroid spectrum, then stores that concrete method on this
 570        setting so saved parameters record what was used.
 571    noise_threshold_methods_implemented : tuple, optional
 572        Methods for detected noise threshold that can be implemented. Default is ('by_format', 'minima', 'signal_noise', 'relative_abundance', 'absolute_abundance', 'log').
 573    noise_threshold_min_std : int, optional
 574        Minumum value for noise thresholding when using 'minima' noise threshold method. Default is 6.
 575    noise_threshold_min_s2n : float, optional
 576        Minimum value for noise thresholding when using 'signal_noise' noise threshold method. Default is 4.
 577    noise_threshold_min_relative_abundance : float, optional
 578        Minimum value for noise thresholding when using 'relative_abundance' noise threshold method. Note that this is a percentage value. Default is 6 (6%).
 579    noise_threshold_absolute_abundance : float, optional
 580        Minimum value for noise thresholding when using 'absolute_abundance' noise threshold method. Default is 1_000_000.
 581    noise_threshold_log_nsigma : int, optional
 582        Number of standard deviations to use when using 'log' noise threshold method. Default is 6.
 583    noise_threshold_log_nsigma_corr_factor : float, optional
 584        Correction factor for log noise threshold method. Default is 0.463.
 585    noise_threshold_log_nsigma_bins : int, optional
 586        Number of bins to use for histogram when using 'log' noise threshold method. Default is 500.
 587    noise_min_mz : float, optional
 588        Minimum m/z to use for noise thresholding. Default is 50.0.
 589    noise_max_mz : float, optional
 590        Maximum m/z to use for noise thresholding. Default is 1200.0.
 591    min_picking_mz : float, optional
 592        Minimum m/z to use for peak picking. Default is 50.0.
 593    max_picking_mz : float, optional
 594        Maximum m/z to use for peak picking. Default is 1200.0.
 595    picking_point_extrapolate : int, optional
 596        How many data points (in each direction) to extrapolate the mz axis and 0 pad the abundance axis. Default is 3.
 597        Recommend not changing this value unless necessary.
 598    calib_minimize_method : str, optional
 599        Minimization method to use for calibration. Default is 'Powell'.
 600    calib_pol_order : int, optional
 601        Polynomial order to use for calibration. Default is 2.
 602    max_calib_ppm_error : float, optional
 603        Maximum ppm error to use for calibration. Default is 1.0.
 604    min_calib_ppm_error : float, optional
 605        Minimum ppm error to use for calibration. Default is -1.0.
 606    calib_sn_threshold : float, optional
 607        Signal to noise threshold to use for calibration. Default is 2.0.
 608    calibration_ref_match_method: string, optional
 609        Method for matching reference masses with measured masses for recalibration. Default is 'legacy'.
 610    calibration_ref_match_tolerance: float, optional
 611        If using the new method for calibration reference mass matching, this tolerance is the initial matching tolerance. Default is 0.003
 612    do_calibration : bool, optional
 613        If True, perform calibration. Default is True.
 614    verbose_processing : bool, optional
 615        If True, print verbose processing information. Default is True.
 616    """
 617
 618    noise_threshold_method: str = "by_format"
 619
 620    noise_threshold_methods_implemented: tuple = (
 621        "by_format",
 622        "minima",
 623        "signal_noise",
 624        "relative_abundance",
 625        "absolute_abundance",
 626        "log",
 627    )
 628
 629    noise_threshold_min_std: int = 6  # when using 'minima' method
 630
 631    noise_threshold_min_s2n: float = 4  # when using 'signal_noise' method
 632
 633    noise_threshold_min_relative_abundance: float = (
 634        6  # from 0-100, when using 'relative_abundance' method
 635    )
 636
 637    noise_threshold_absolute_abundance: float = (
 638        1_000_000  # when using 'absolute_abundance' method
 639    )
 640
 641    noise_threshold_log_nsigma: int = 6  # when using 'log' method
 642    noise_threshold_log_nsigma_corr_factor: float = 0.463  # mFT is 0.463, aFT is 1.0
 643    noise_threshold_log_nsigma_bins: int = 500  # bins for the histogram for the noise
 644
 645    noise_min_mz: float = 50.0
 646    noise_max_mz: float = 1200.0
 647
 648    min_picking_mz: float = 50.0
 649    max_picking_mz: float = 1200.0
 650
 651    # How many data points (in each direction) to extrapolate the mz axis and 0 pad the abundance axis
 652    # This will fix peak picking at spectrum limit issues
 653    #  0 to keep normal behaviour, typical value 3 to fix
 654    picking_point_extrapolate: int = 3
 655
 656    calib_minimize_method: str = "Powell"
 657    calib_pol_order: int = 2
 658    max_calib_ppm_error: float = 1.0
 659    min_calib_ppm_error: float = -1.0
 660    calib_sn_threshold: float = 2.0
 661    calibration_ref_match_method: str = "merged"
 662    calibration_ref_match_method_implemented: tuple = ("legacy", "merged")
 663    calibration_ref_match_tolerance: float = 0.003
 664    calibration_ref_match_std_raw_error_limit: float = 1.5
 665    # calib_ref_mzs: list = [0]
 666
 667    do_calibration: bool = True
 668    verbose_processing: bool = True
 669
 670    def __post_init__(self):
 671        # enforce datatype
 672        for field in dataclasses.fields(self):
 673            value = getattr(self, field.name)
 674            if not isinstance(value, field.type):
 675                value = field.type(value)
 676                setattr(self, field.name, value)
 677
 678
 679@dataclasses.dataclass
 680class MassSpecPeakSetting:
 681    """Mass spectrum peak processing settings class
 682
 683    Attributes
 684    ----------
 685    kendrick_base : Dict, optional
 686        Dictionary specifying the elements and their counts in the Kendrick base.
 687        Defaults to {'C': 1, 'H': 2}.
 688    kendrick_rounding_method : str, optional
 689        Method for calculating the nominal Kendrick mass. Valid values are 'floor', 'ceil', or 'round'.
 690        Defaults to 'floor'.
 691    implemented_kendrick_rounding_methods : tuple
 692        Tuple of valid rounding methods for calculating the nominal Kendrick mass.
 693        Defaults to ('floor', 'ceil', 'round').
 694    peak_derivative_threshold : float, optional
 695        Threshold for defining derivative crossing. Should be a value between 0 and 1.
 696        Defaults to 0.0.
 697    peak_min_prominence_percent : float, optional
 698        Minimum prominence percentage used for peak detection. Should be a value between 1 and 100.
 699        Defaults to 0.1.
 700    min_peak_datapoints : float, optional
 701        Minimum number of data points used for peak detection. Should be a value between 0 and infinity.
 702        Defaults to 5.
 703    peak_max_prominence_percent : float, optional
 704        Maximum prominence percentage used for baseline detection. Should be a value between 1 and 100.
 705        Defaults to 0.1.
 706    peak_height_max_percent : float, optional
 707        Maximum height percentage used for baseline detection. Should be a value between 1 and 100.
 708        Defaults to 10.
 709    legacy_resolving_power : bool, optional
 710        Flag indicating whether to use the legacy (CoreMS v1) resolving power calculation.
 711        Defaults to True.
 712    legacy_centroid_polyfit : bool, optional
 713        Use legacy (numpy polyfit) to fit centroid
 714        Default false.
 715    """
 716
 717    kendrick_base: Dict = dataclasses.field(default_factory=dict)
 718
 719    kendrick_rounding_method: str = "floor"  # 'floor', 'ceil' or 'round' are valid methods for calculating nominal kendrick mass
 720
 721    implemented_kendrick_rounding_methods: tuple = ("floor", "ceil", "round")
 722
 723    peak_derivative_threshold: float = 0.0  # define derivative crossing threshould 0-1
 724
 725    peak_min_prominence_percent: float = 0.1  # 1-100 % used for peak detection
 726
 727    min_peak_datapoints: float = 5  # 0-inf used for peak detection
 728
 729    peak_max_prominence_percent: float = 0.1  # 1-100 % used for baseline detection
 730
 731    peak_height_max_percent: float = 10  # 1-100 % used for baseline detection
 732
 733    legacy_resolving_power: bool = (
 734        True  # Use the legacy (CoreMS v1) resolving power calculation (True)
 735    )
 736
 737    legacy_centroid_polyfit: bool = False
 738
 739    def __post_init__(self):
 740        # default to CH2
 741        if not self.kendrick_base:
 742            self.kendrick_base = {"C": 1, "H": 2}
 743        # enforce datatype
 744        for field in dataclasses.fields(self):
 745            value = getattr(self, field.name)
 746            if not isinstance(value, field.type):
 747                value = field.type(value)
 748                setattr(self, field.name, value)
 749
 750
 751@dataclasses.dataclass
 752class GasChromatographSetting:
 753    """Gas chromatograph processing settings class
 754
 755    Attributes
 756    ----------
 757    use_deconvolution : bool, optional
 758        If True, use deconvolution. Default is False.
 759    implemented_smooth_method : tuple, optional
 760        Smoothing methods that can be implemented. Default is ('savgol', 'hanning', 'blackman', 'bartlett', 'flat', 'boxcar').
 761    smooth_window : int, optional
 762        Window size for smoothing the ion chromatogram. Default is 5.
 763    smooth_method : str, optional
 764        Smoothing method to use. Default is 'savgol'. Other options are 'hanning', 'blackman', 'bartlett', 'flat', 'boxcar'.
 765    savgol_pol_order : int, optional
 766        Polynomial order for Savitzky-Golay smoothing. Default is 2.
 767    peak_derivative_threshold : float, optional
 768        Threshold for defining derivative crossing. Should be a value between 0 and 1.
 769        Defaults to 0.0005.
 770    peak_height_max_percent : float, optional
 771        Maximum height percentage used for baseline detection. Should be a value between 1 and 100.
 772        Defaults to 10.
 773    peak_max_prominence_percent : float, optional
 774        Maximum prominence percentage used for baseline detection. Should be a value between 1 and 100.
 775        Defaults to 1.
 776    min_peak_datapoints : float, optional
 777        Minimum number of data points used for peak detection. Should be a value between 0 and infinity.
 778        Defaults to 5.
 779    max_peak_width : float, optional
 780        Maximum peak width used for peak detection. Should be a value between 0 and infinity.
 781        Defaults to 0.1.
 782    noise_threshold_method : str, optional
 783        Method for detecting noise threshold. Default is 'manual_relative_abundance'.
 784    noise_threshold_methods_implemented : tuple, optional
 785        Methods for detected noise threshold that can be implemented. Default is ('auto_relative_abundance', 'manual_relative_abundance', 'second_derivative').
 786    std_noise_threshold : int, optional
 787        Default is 3.
 788    peak_height_min_percent : float, optional
 789        0-100 % used for peak detection. Default is 0.1.
 790    peak_min_prominence_percent : float, optional
 791        0-100 % used for peak detection. Default is 0.1.
 792    eic_signal_threshold : float, optional
 793        0-100 % used for extracted ion chromatogram peak detection. Default is 0.01.
 794    max_rt_distance : float, optional
 795        Maximum distance allowance for hierarchical cluster, in minutes. Default is 0.025.
 796    verbose_processing : bool, optional
 797        If True, print verbose processing information. Default is True.
 798    """
 799
 800    use_deconvolution: bool = False
 801
 802    implemented_smooth_method: tuple = (
 803        "savgol",
 804        "hanning",
 805        "blackman",
 806        "bartlett",
 807        "flat",
 808        "boxcar",
 809    )
 810
 811    smooth_window: int = 5
 812
 813    smooth_method: str = "savgol"
 814
 815    savgol_pol_order: int = 2
 816
 817    peak_derivative_threshold: float = 0.0005
 818
 819    peak_height_max_percent: float = 10  # 1-100 % used for baseline detection use 0.1 for second_derivative and 10 for other methods
 820
 821    peak_max_prominence_percent: float = 1  # 1-100 % used for baseline detection
 822
 823    min_peak_datapoints: float = 5
 824
 825    max_peak_width: float = 0.1
 826
 827    noise_threshold_method: str = "manual_relative_abundance"
 828
 829    noise_threshold_methods_implemented: tuple = (
 830        "auto_relative_abundance",
 831        "manual_relative_abundance",
 832        "second_derivative",
 833    )
 834
 835    std_noise_threshold: int = 3
 836
 837    peak_height_min_percent: float = 0.1  # 0-100 % used for peak detection
 838
 839    peak_min_prominence_percent: float = 0.1  # 0-100 % used for peak detection
 840
 841    eic_signal_threshold: float = (
 842        0.01  # 0-100 % used for extracted ion chromatogram peak detection
 843    )
 844
 845    max_rt_distance: float = (
 846        0.025  # minutes, max distance allowance hierarchical clutter
 847    )
 848
 849    verbose_processing: bool = True
 850
 851    def __post_init__(self):
 852        # enforce datatype
 853        for field in dataclasses.fields(self):
 854            value = getattr(self, field.name)
 855            if not isinstance(value, field.type):
 856                value = field.type(value)
 857                setattr(self, field.name, value)
 858
 859
 860@dataclasses.dataclass
 861class CompoundSearchSettings:
 862    """Settings for compound search
 863
 864    Attributes
 865    ----------
 866    url_database : str, optional
 867        URL for the database. Default is 'sqlite:///db/pnnl_lowres_gcms_compounds.sqlite'.
 868    ri_search_range : float, optional
 869        Retention index search range. Default is 35.
 870    rt_search_range : float, optional
 871        Retention time search range, in minutes. Default is 1.0.
 872    correlation_threshold : float, optional
 873        Threshold for correlation for spectral similarity. Default is 0.5.
 874    score_threshold : float, optional
 875        Threshold for compsite score. Default is 0.0.
 876    ri_spacing : float, optional
 877        Retention index spacing. Default is 200.
 878    ri_std : float, optional
 879        Retention index standard deviation. Default is 3.
 880    ri_calibration_compound_names : list, optional
 881        List of compound names to use for retention index calibration. Default is ['Methyl Caprylate', 'Methyl Caprate', 'Methyl Pelargonate', 'Methyl Laurate', 'Methyl Myristate', 'Methyl Palmitate', 'Methyl Stearate', 'Methyl Eicosanoate', 'Methyl Docosanoate', 'Methyl Linocerate', 'Methyl Hexacosanoate', 'Methyl Octacosanoate', 'Methyl Triacontanoate'].
 882
 883    """
 884
 885    url_database: str = "postgresql+psycopg://coremsappdb:coremsapppnnl@localhost:5432/lowres"  # 'postgresql+psycopg://postgres:labthomson0102@172.22.113.27:5432/GCMS' # 'sqlite:///db/pnnl_lowres_gcms_compounds.sqlite'
 886
 887    ri_search_range: float = 35
 888
 889    rt_search_range: float = 1.0  # used for retention index calibration
 890
 891    correlation_threshold: float = 0.5  # used for calibration, spectral similarity
 892
 893    score_threshold: float = 0.0
 894
 895    ri_spacing: float = 200
 896
 897    ri_std: float = 3  # in standard deviation
 898
 899    ri_calibration_compound_names: List = dataclasses.field(default_factory=list)
 900
 901    # calculates and export all spectral similarity methods
 902    exploratory_mode: bool = False
 903
 904    score_methods: tuple = ("highest_sim_score", "highest_ss")
 905
 906    output_score_method: str = "All"
 907
 908    def __post_init__(self):
 909        # enforce datatype
 910        self.url_database = os.getenv(
 911            "SPECTRAL_GCMS_DATABASE_URL",
 912            "sqlite:///db/pnnl_lowres_gcms_compounds.sqlite",
 913        )
 914
 915        for field in dataclasses.fields(self):
 916            value = getattr(self, field.name)
 917            if not isinstance(value, field.type):
 918                value = field.type(value)
 919                setattr(self, field.name, value)
 920
 921        self.ri_calibration_compound_names = [
 922            "Methyl Caprylate",
 923            "Methyl Caprate",
 924            "Methyl Pelargonate",
 925            "Methyl Laurate",
 926            "Methyl Myristate",
 927            "Methyl Palmitate",
 928            "Methyl Stearate",
 929            "Methyl Eicosanoate",
 930            "Methyl Docosanoate",
 931            "Methyl Linocerate",
 932            "Methyl Hexacosanoate",
 933            "Methyl Octacosanoate",
 934            "Methyl Triacontanoate",
 935        ]
 936
 937
 938class MolecularLookupDictSettings:
 939    """Settings for molecular searching
 940
 941    These are used to generate the database entries, do not change.
 942
 943    Attributes
 944    ----------
 945    usedAtoms : dict, optional
 946        Dictionary of **element symbols** (most-abundant mono codes) to
 947        (min, max) count ranges. Keys must be element symbols present in
 948        ``Atoms.isotopes`` (e.g. ``C``, ``Fe``, ``Cl``), **not** specific
 949        isotope labels (e.g. ``13C``, ``54Fe``, ``37Cl``). Rare isotopes are
 950        produced by isotopologue expansion of mono formulas after assignment.
 951        Each key also needs a valence in ``used_atom_valences``.
 952        Default is {'C': (1, 90), 'H': (4, 200), 'O': (0, 12), 'N': (0, 0),
 953        'S': (0, 0), 'P': (0, 0), 'Cl': (0, 0)}.
 954    min_mz : float, optional
 955        Minimum m/z to use for searching. Default is 50.0.
 956    max_mz : float, optional
 957        Maximum m/z to use for searching. Default is 1200.0.
 958    min_dbe : float, optional
 959        Minimum double bond equivalent to use for searching. Default is 0.
 960    max_dbe : float, optional
 961        Maximum double bond equivalent to use for searching. Default is 50.
 962    use_pah_line_rule : bool, optional
 963        If True, use the PAH line rule. Default is False.
 964    isRadical : bool, optional
 965        If True, search for radical ions. Default is True.
 966    isProtonated : bool, optional
 967        If True, search for protonated ions. Default is True.
 968    url_database : str, optional
 969        URL for the database. Default is None.
 970    db_jobs : int, optional
 971        Number of jobs to use for database queries. Default is 1.
 972    used_atom_valences : dict, optional
 973        Dictionary of atoms and valences. Default is {'C': 4, '13C': 4, 'H': 1, 'O': 2, '18O': 2, 'N': 3, 'S': 2, '34S': 2, 'P': 3, 'Cl': 1, '37Cl': 1, 'Br': 1, 'Na': 1, 'F': 1, 'K': 0}.
 974
 975    """
 976
 977    ### DO NOT CHANGE IT! These are used to generate the database entries
 978
 979    ### DO change when creating a new application database
 980
 981    ### FOR search settings runtime and database query check use the MolecularFormulaSearchSettings class below
 982
 983    ### C, H, N, O, S and P atoms are ALWAYS needed at usedAtoms
 984    ### if you don't want to include one of those atoms set the max and min at 0
 985    ### Keys must be element symbols (Atoms.isotopes), not rare-isotope labels
 986    ### you can include any mono element in Atoms.isotopes
 987    ### make sure to include the selected covalence at the used_atoms_valences when adding new atoms
 988    ### NOTE : Adducts atoms have zero covalence
 989    ### NOTE : Not using static variable because this class is distributed using multiprocessing
 990    def __init__(self):
 991        self.usedAtoms = {
 992            "C": (1, 90),
 993            "H": (4, 200),
 994            "O": (0, 12),
 995            "N": (0, 0),
 996            "S": (0, 0),
 997            "P": (0, 0),
 998            "Cl": (0, 0),
 999        }
1000        validate_used_atoms_keys(self.usedAtoms)
1001
1002        self.min_mz = 50
1003
1004        self.max_mz = 1200
1005
1006        self.min_dbe = 0
1007
1008        self.max_dbe = 50
1009
1010        # overwrites the dbe limits above to DBE = (C + heteroatoms) * 0.9
1011        self.use_pah_line_rule = False
1012
1013        self.isRadical = True
1014
1015        self.isProtonated = True
1016
1017        self.url_database = None
1018
1019        self.db_jobs = 1
1020
1021        self.used_atom_valences = {
1022            "C": 4,
1023            "13C": 4,
1024            "H": 1,
1025            "O": 2,
1026            "18O": 2,
1027            "N": 3,
1028            "S": 2,
1029            "34S": 2,
1030            "P": 3,
1031            "Cl": 1,
1032            "37Cl": 1,
1033            "Br": 1,
1034            "Na": 1,
1035            "F": 1,
1036            "K": 0,
1037        }
1038
1039
1040@dataclasses.dataclass
1041class MolecularFormulaSearchSettings:
1042    """Settings for molecular searching
1043
1044    Attributes
1045    ----------
1046    use_isotopologue_filter : bool, optional
1047        If True, use isotopologue filter. Default is False.
1048    isotopologue_filter_threshold : float, optional
1049        Threshold for isotopologue filter. Default is 33.
1050    isotopologue_filter_atoms : tuple, optional
1051        Tuple of atoms to use for isotopologue filter. Default is ('Cl', 'Br').
1052    use_runtime_kendrick_filter : bool, optional
1053        If True, use runtime Kendrick filter. Default is False.
1054    use_min_peaks_filter : bool, optional
1055        If True, use minimum peaks filter. Default is True.
1056    min_peaks_per_class : int, optional
1057        Minimum number of peaks per class. Default is 15.
1058    url_database : str, optional
1059        URL for the database. Default is 'postgresql+psycopg://coremsappdb:coremsapppnnl@localhost:5432/coremsapp'.
1060    db_jobs : int, optional
1061        Number of jobs to use for database queries. Default is 1. Can increase to 3 when python environment supports it.
1062    db_chunk_size : int, optional
1063        Chunk size to use for database queries. Default is 300.
1064    ion_charge : int, optional
1065        **Legacy / unused for formula search.** Kept so older YAML/JSON/TOML
1066        and ``MolecularFormulaSearchSettings(ion_charge=...)`` keep loading
1067        without error. Default is -1. Search polarity comes from the mass
1068        spectrum or LCMS object (DI often -1 from data; LC has no default).
1069        Absolute multi-charge range uses ``min_ion_charge`` / ``max_ion_charge``
1070        only. Do not use this field for new workflows.
1071    min_ion_charge : int, optional
1072        Minimum **absolute** ion charge for molecular formula search. Default is 1.
1073        With ``max_ion_charge``, defines the inclusive absolute charge range searched
1074        at polarity-signed values (e.g. positive polarity and max 2 → z = +1, +2).
1075        No 13C-based charge determination is performed; every selected peak is
1076        searched at each charge and candidates are ranked by existing formula
1077        scores (isotopologue similarity, confidence). Peak ``polarity`` remains
1078        ±1 (legacy alias ``peak.ion_charge``); assignment charge lives on
1079        ``MolecularFormula.ion_charge``.
1080    max_ion_charge : int, optional
1081        Maximum **absolute** ion charge for molecular formula search. Default is 1
1082        (legacy single-charge behavior). Must be >= ``min_ion_charge``.
1083        Incompatible with ``isAdduct=True`` when greater than 1 (adduct search is
1084        single-charge only; multi-charge adducts are not modeled).
1085    min_hc_filter : float, optional
1086        Minimum hydrogen to carbon ratio. Default is 0.3.
1087    max_hc_filter : float, optional
1088        Maximum hydrogen to carbon ratio. Default is 3.
1089    min_oc_filter : float, optional
1090        Minimum oxygen to carbon ratio. Default is 0.0.
1091    max_oc_filter : float, optional
1092        Maximum oxygen to carbon ratio. Default is 1.2.
1093    min_op_filter : float, optional
1094        Minimum oxygen to phosphorous ratio. Default is 2.
1095    use_pah_line_rule : bool, optional
1096        If True, use the PAH line rule. Default is False.
1097    min_dbe : float, optional
1098        Minimum double bond equivalent to use for searching. Default is 0.
1099    max_dbe : float, optional
1100        Maximum double bond equivalent to use for searching. Default is 40.
1101    mz_error_score_weight : float, optional
1102        Weight ``w_err`` for the formula-level mass-error term
1103        (``MolecularFormula.average_mz_error_score``) in the composite
1104        ``confidence_score``. Default is 0.6. See the
1105        ``corems.molecular_formula`` package documentation.
1106    isotopologue_score_weight : float, optional
1107        Weight ``w_iso`` for the isotopologue similarity term
1108        (``MolecularFormula.isotopologue_similarity``) in the composite
1109        ``confidence_score``. Default is 0.4. Some literature examples use
1110        equal weights (0.5 / 0.5).
1111    adduct_atoms_neg : tuple, optional
1112        Tuple of atoms to use in negative polarity. Default is ('Cl', 'Br').
1113    adduct_atoms_pos : tuple, optional
1114        Tuple of atoms to use in positive polarity. Default is ('Na', 'K').
1115    score_methods : tuple, optional
1116        Tuple of score method that can be implemented.
1117        Default is ('S_P_lowest_error', 'N_S_P_lowest_error', 'lowest_error', 'prob_score', 'air_filter_error', 'water_filter_error', 'earth_filter_error').
1118    score_method : str, optional
1119        Score method to use. Default is 'prob_score'. Options are 'S_P_lowest_error', 'N_S_P_lowest_error', 'lowest_error', 'prob_score', 'air_filter_error', 'water_filter_error', 'earth_filter_error'.
1120    output_min_score : float, optional
1121        Minimum score for output. Default is 0.1.
1122    output_score_method : str, optional
1123        Score method to use for output. Default is 'All Candidates'.
1124    isRadical : bool, optional
1125        If True, search for radical ions. Default is False.
1126    isProtonated : bool, optional
1127        If True, search for protonated ions. Default is True.
1128    isAdduct : bool, optional
1129        If True, search for adduct ions. Default is False.
1130        Requires ``max_ion_charge == 1`` (and typically ``min_ion_charge == 1``);
1131        multi-charge formula search does not include adduct ion types.
1132    usedAtoms : dict, optional
1133        Dictionary of **element symbols** (most-abundant mono codes) to
1134        (min, max) count ranges for molecular formula search. Keys must be
1135        element symbols present in ``Atoms.isotopes`` (e.g. ``C``, ``Fe``,
1136        ``Cl``), **not** specific isotope labels (e.g. ``13C``, ``54Fe``,
1137        ``37Cl``). Rare / heavy isotopes are generated by isotopologue
1138        expansion of mono formulas after assignment (when
1139        ``find_isotopologues`` is enabled), not by listing them here.
1140        Invalid keys raise ``ValueError`` at settings construction, assignment,
1141        or search entry. Each key also needs a valence in
1142        ``used_atom_valences`` (usually from ``Atoms.atoms_covalence``).
1143        Default empty dict is filled with C and H ranges in
1144        ``__post_init__``.
1145    ion_types_excluded : list, optional
1146        List of ion types to exclude from molecular id search, commonly ['[M+CH3COO]-]'] or ['[M+COOH]-'] depending on mobile phase content. Default is [].
1147    ionization_type : str, optional
1148        Ionization type. Default is 'ESI'.
1149    min_ppm_error : float, optional
1150        Minimum ppm error. Default is -10.0.
1151    max_ppm_error : float, optional
1152        Maximum ppm error. Default is 10.0.
1153    min_abun_error : float, optional
1154        Minimum abundance error for isotolopologue search. Default is -100.0.
1155    max_abun_error : float, optional
1156        Maximum abundance error for isotolopologue search. Default is 100.0.
1157    mz_error_range : float, optional
1158        m/z error range. Default is 1.5.
1159    error_method : str, optional
1160        Error method. Default is 'None'. Options are 'distance', 'lowest', 'symmetrical','average' 'None'.
1161    mz_error_average : float, optional
1162        m/z error average. Default is 0.0.
1163    used_atom_valences : dict, optional
1164        Dictionary of atoms and valences. Default is {'C': 4, '13C': 4, 'H': 1, 'O': 2, '18O': 2, 'N': 3, 'S': 2, '34S': 2, 'P': 3, 'Cl': 1, '37Cl': 1, 'Br': 1, 'Na': 1, 'F': 1, 'K': 0}.
1165    verbose_processing: bool, optional
1166        If True, print verbose processing information. Default is True.
1167    """
1168
1169    verbose_processing: bool = True
1170
1171    use_isotopologue_filter: bool = False
1172
1173    isotopologue_filter_threshold: float = 33
1174
1175    isotopologue_filter_atoms: tuple = ("Cl", "Br")
1176
1177    use_runtime_kendrick_filter: bool = False
1178
1179    use_min_peaks_filter: bool = True
1180
1181    min_peaks_per_class: int = 15
1182
1183    url_database: str = (
1184        "postgresql+psycopg://coremsappdb:coremsapppnnl@localhost:5432/coremsapp"
1185    )
1186
1187    db_jobs: int = 1
1188
1189    db_chunk_size: int = 300
1190
1191    # query setting========
1192    # Legacy BC only (parameter files / constructor). Not used for search.
1193    # Polarity: spectrum/LCMS data. Multi-z absolute range: min/max_ion_charge.
1194    ion_charge: int = -1
1195
1196    # Absolute charge range for formula search (polarity supplies sign).
1197    # Defaults 1..1 preserve single-charge behavior.
1198    min_ion_charge: int = 1
1199    max_ion_charge: int = 1
1200
1201    min_hc_filter: float = 0.3
1202
1203    max_hc_filter: float = 3
1204
1205    min_oc_filter: float = 0.0
1206
1207    max_oc_filter: float = 1.2
1208
1209    min_op_filter: float = 2
1210
1211    use_pah_line_rule: bool = False
1212
1213    min_dbe: float = 0
1214
1215    max_dbe: float = 40
1216
1217    mz_error_score_weight: float = 0.6
1218
1219    isotopologue_score_weight: float = 0.4
1220
1221    # look for close shell ions [M + Adduct]+ only considers metal set in the list adduct_atoms
1222    adduct_atoms_neg: tuple = ("Cl", "Br")
1223
1224    adduct_atoms_pos: tuple = ("Na", "K")
1225
1226    score_methods: tuple = (
1227        "S_P_lowest_error",
1228        "N_S_P_lowest_error",
1229        "lowest_error",
1230        "prob_score",
1231        "air_filter_error",
1232        "water_filter_error",
1233        "earth_filter_error",
1234    )
1235
1236    score_method: str = "prob_score"
1237
1238    output_min_score: float = 0.1
1239
1240    output_score_method: str = "All Candidates"
1241
1242    # depending on the polarity mode it looks for [M].+ , [M].-
1243    # query and automatically compile add entry if it doesn't exist
1244
1245    isRadical: bool = False
1246
1247    # depending on the polarity mode it looks for [M + H]+ , [M - H]+
1248    # query and automatically compile and push options if it doesn't exist
1249    isProtonated: bool = True
1250
1251    isAdduct: bool = False
1252
1253    usedAtoms: dict = dataclasses.field(default_factory=dict)
1254    ion_types_excluded: list = dataclasses.field(default_factory=list)
1255
1256    # search setting ========
1257
1258    ionization_type: str = "ESI"
1259
1260    # empirically set / needs optimization
1261    min_ppm_error: float = -10.0  # ppm
1262
1263    # empirically set / needs optimization
1264    max_ppm_error: float = 10.0  # ppm
1265
1266    # empirically set / needs optimization set for isotopologue search
1267    min_abun_error: float = -100.0  # percentage
1268
1269    # empirically set / needs optimization set for isotopologue search
1270    max_abun_error: float = 100.0  # percentage
1271
1272    # empirically set / needs optimization
1273    mz_error_range: float = 1.5
1274
1275    # 'distance', 'lowest', 'symmetrical','average' 'None'
1276    error_method: str = "None"
1277
1278    mz_error_average: float = 0.0
1279
1280    # used_atom_valences: {'C': 4, 'H':1, etc} = dataclasses.field(default_factory=dict)
1281    used_atom_valences: dict = dataclasses.field(default_factory=dict)
1282
1283    def __setattr__(self, name, value):
1284        # Catch full reassignment of usedAtoms after construction (common API).
1285        # In-place mutation (usedAtoms[key] = ...) is validated at search entry.
1286        if name == "usedAtoms" and value is not None:
1287            validate_used_atoms_keys(value)
1288        super().__setattr__(name, value)
1289
1290    def __post_init__(self):
1291        if not self.url_database or self.url_database == "":
1292            self.url_database = os.getenv(
1293                "COREMS_DATABASE_URL", "sqlite:///db/molformula.db"
1294            )
1295        # enforce datatype
1296        for field in dataclasses.fields(self):
1297            value = getattr(self, field.name)
1298            if not isinstance(value, field.type):
1299                value = field.type(value)
1300                setattr(self, field.name, value)
1301
1302        # enforce C and H if either do not exists
1303        if "C" not in self.usedAtoms.keys():
1304            self.usedAtoms["C"] = (1, 100)
1305        if "H" not in self.usedAtoms.keys():
1306            self.usedAtoms["H"] = (1, 200)
1307
1308        validate_used_atoms_keys(self.usedAtoms)
1309
1310        # add cummon values
1311        current_used_atoms = self.used_atom_valences.keys()
1312
1313        for atom in Atoms.atoms_covalence.keys():
1314            if atom not in current_used_atoms:
1315                covalence = Atoms.atoms_covalence.get(atom)
1316
1317                if isinstance(covalence, int):
1318                    self.used_atom_valences[atom] = covalence
1319
1320                else:
1321                    # will get the first number of all possible covalances, which should be the most commum
1322                    self.used_atom_valences[atom] = covalence[0]
1323
1324        self.validate_ion_charge_settings()
1325
1326    def validate_ion_charge_settings(self):
1327        """Validate absolute charge range and adduct compatibility.
1328
1329        Raises
1330        ------
1331        ValueError
1332            If ``min_ion_charge`` / ``max_ion_charge`` are invalid, or if
1333            ``isAdduct`` is enabled with multi-charge search
1334            (``max_ion_charge > 1``).
1335        """
1336        min_z = int(self.min_ion_charge)
1337        max_z = int(self.max_ion_charge)
1338        if min_z < 1:
1339            raise ValueError("min_ion_charge must be >= 1")
1340        if max_z < min_z:
1341            raise ValueError("max_ion_charge must be >= min_ion_charge")
1342        # Multi-charge adducts ([M+Na+H]2+, [M+2Na]2+, etc.) are not modeled;
1343        # adduct search is single-charge only.
1344        if self.isAdduct and max_z > 1:
1345            raise ValueError(
1346                "isAdduct=True is incompatible with multi-charge formula search "
1347                f"(max_ion_charge={max_z}). Set max_ion_charge=1 for adduct "
1348                "search, or disable isAdduct for multi-charge protonated/radical "
1349                "search."
1350            )
1351
1352
1353@dataclasses.dataclass
1354class LCMSCollectionSettings:
1355    """Settings for LCMS collection class
1356
1357    Attributes
1358    ----------
1359    cores : int, optional
1360        Number of cores to use for processing. Default is 1.
1361    drop_isotopologues : bool, optional
1362        If True, drop isotopologues from all analyses.
1363        Note that this will keep mass features identified as monoisotopes and any largest ion in deconvoluted mass spectrum.
1364        It will also keep mass features not identified as isotopologues or monoisotopes.
1365        Default is True.
1366    mass_feature_anchor_technique: list, optional
1367        List of mass feature anchor techniques for retention time alignment.
1368        Default is ['absolute_intensity'].
1369    mass_feature_anchor_techniques_available: tuple, optional
1370        Tuple of available mass feature anchor techniques for retention time alignment.
1371        Default is ('deconvoluted_mass_spectra', 'absolute_intensity', 'relative_intensity').
1372    mass_feature_anchor_absolute_intensity_threshold: int, optional
1373        Absolute intensity threshold for mass feature anchor for retention time alignment.
1374        Used when mass_feature_anchor_technique includes 'relative_intensity'.
1375        Default is 10000.
1376    mass_feature_anchor_relative_intensity_threshold: float, optional
1377        Relative intensity threshold (0-1) for mass feature anchor for retention time alignment.
1378        Removes the lower fraction of mass features by intensity from consideration.
1379        For example, 0.6 removes the lower 60% of intensity features.
1380        Used when mass_feature_anchor_technique includes 'relative_intensity'.
1381        Default is 0.6.
1382    alignment_minimum_matches: int, optional
1383        Minimum number of matched features required to attempt retention time alignment.
1384        If fewer matches are found between samples, alignment will be skipped for that sample.
1385        This is particularly useful when aligning blank samples or samples with very few features.
1386        Default is 5.
1387    alignment_hold_out_fraction: float, optional
1388        Hold out fraction for testing retention time alignment.
1389        Default is 0.3.
1390    alignment_acceptance_technique: list, optional
1391        List of alignment acceptance techniques for retention time alignment.
1392        Default is ['fraction_improved', 'mean_squared_error_improved'].
1393    alignment_acceptance_techniques_available: tuple, optional
1394        Tuple of available alignment acceptance techniques for retention time alignment.
1395        Default is ('fraction_improved', 'mean_squared_error_improved').
1396    alignment_acceptance_fraction_improved_threshold: float, optional
1397        Threshold for the improved fraction of the hold out mass features for accepting retention time alignment.
1398        Default is 0.5.
1399    alignment_mz_tol_ppm: int, optional
1400        m/z tolerance in ppm for retention time alignment and for consensus feature
1401        grouping isotope (and later adduct) mass deltas. Default is 5.
1402    alignment_rt_tol: float, optional
1403        Retention time tolerance in minutes for retention time alignment and for
1404        consensus feature grouping coelution windows. Default is 0.3.
1405    consensus_mz_tol_ppm: int, optional
1406        m/z tolerance in ppm for consensus mass feature alignment. Default is 5.
1407        The recommendation is that this value should be the same as alignment_mz_tol_ppm.
1408    consensus_rt_tol: float, optional
1409        Retention time tolerance for consensus mass feature alignment, in minutes. Default is 0.2.
1410    consensus_partition_size: int, optional
1411        Partition size for consensus mass feature alignment. Default is 5000.
1412    consensus_min_sample_fraction : float, optional
1413        Minimum fraction of samples (0-1) that must contain a cluster.
1414        Used for filtering consensus features and for gap-filling threshold.
1415        Default is 0.5 (50%). Higher values focus on more prevalent features.
1416    gap_fill_expand_on_miss : bool, optional
1417        If True, expands the search window when no peak is found inside the
1418        cluster bounds. m/z widens by consensus_mz_tol_ppm. Retention time
1419        widens by consensus_rt_tol minutes. Default is True.
1420    consensus_representative_metric : str, optional
1421        Metric used to determine the most representative sample for a consensus mass feature.
1422        Options:
1423        - 'intensity': Selects the mass feature with the highest intensity value
1424        - 'intensity_prefer_ms2': Selects the mass feature with the highest intensity among
1425          those that have MS2 scan numbers assigned. If no features have MS2 scans, falls
1426          back to selecting the highest intensity feature overall.
1427        Default is 'intensity_prefer_ms2'.
1428    consensus_representative_metrics_available : tuple, optional
1429        Tuple of available metrics for determining the most representative sample.
1430        Default is ('intensity', 'intensity_prefer_ms2').
1431    feature_group_isotope_atoms : tuple of str, optional
1432        Mono elements for natural-abundance isotope Δm edges via ``Atoms``
1433        (e.g. ``("C",)``). Default ``("C",)``. Not for tracer labeling.
1434    feature_group_min_isotope_abundance : float, optional
1435        Min natural abundance (0–1) for rare forms in isotope spacing.
1436        Default 0.01.
1437    feature_group_max_isotope_offset : int, optional
1438        Max M+n roll-up depth for one rare form (e.g. ¹³Cₙ). Default 4.
1439    feature_group_corr_threshold : float, optional
1440        Min Pearson correlation of apex ``intensity`` vectors for an edge
1441        (pairwise-complete; zeros dropped). Default 0.80.
1442    feature_group_min_shared_sample_fraction : float, optional
1443        Min fraction of samples with both heights > 0 before correlation
1444        is trusted (``ceil(fraction * n_samples)``). Default 0.15.
1445    feature_group_ion_types : tuple of str, optional
1446        Allow-list of ``ION_TYPE_DICT`` keys for adduct linking (``|z| = 1``).
1447        Empty/one type → isotopes only. Default is a curated common set
1448        (``DEFAULT_ION_TYPES``); narrow further to reduce false adduct links.
1449        Filtered by collection polarity at ``group_consensus_features()``.
1450    feature_group_constrain_annotation : bool, optional
1451        If True and labels exist, skip consensus isotopes in collection
1452        MS1/MS2/annotation and keep IDs only if ion type is in
1453        ``possible_ion_types``. Default True.
1454    feature_group_partition_size : int, optional
1455        Reserved RT-partition size for future multicore grouping.
1456        Default 5000.
1457    """
1458
1459    # Settings for general processing
1460    cores: int = 1
1461    drop_isotopologues: bool = False
1462
1463    # Settings for doing mass feature alignment
1464    _mass_feature_anchor_technique: list = dataclasses.field(
1465        default_factory=lambda: ["relative_intensity"]
1466    )
1467    mass_feature_anchor_techniques_available: tuple = (
1468        "deconvoluted_mass_spectra",
1469        "absolute_intensity",
1470        "relative_intensity",
1471    )
1472    mass_feature_anchor_absolute_intensity_threshold: int = 10000
1473    mass_feature_anchor_relative_intensity_threshold: float = 0.6
1474    alignment_minimum_matches: int = 5
1475    alignment_hold_out_fraction: float = 0.3
1476    _alignment_acceptance_technique: list = dataclasses.field(
1477        default_factory=lambda: ["fraction_improved", "mean_squared_error_improved"]
1478    )
1479    alignment_acceptance_techniques_available: tuple = (
1480        "fraction_improved",
1481        "mean_squared_error_improved",
1482    )
1483    alignment_acceptance_fraction_improved_threshold: float = 0.5
1484    alignment_mz_tol_ppm: int = 5
1485    alignment_rt_tol: float = 0.4
1486
1487    # Consensus mass feature settings
1488    consensus_mz_tol_ppm: int = alignment_mz_tol_ppm
1489    consensus_rt_tol: float = 0.3
1490    consensus_partition_size: int = 10000
1491    filter_consensus_mass_features: bool = True
1492    consensus_min_sample_fraction: float = 0.5
1493
1494    # Gap-filling settings
1495    gap_fill_expand_on_miss: bool = True
1496
1497    # Consensus mass feature visualization parameters
1498    consensus_representative_metric: str = "intensity_prefer_ms2"
1499    consensus_representative_metrics_available: tuple = (
1500        "intensity",
1501        "intensity_prefer_ms2",
1502    )
1503
1504    # Feature grouping (isotopes + z=1 adducts); RT/m/z use alignment_* tols
1505    feature_group_isotope_atoms: tuple = ("C",)
1506    feature_group_min_isotope_abundance: float = 0.01
1507    feature_group_max_isotope_offset: int = 4
1508    feature_group_corr_threshold: float = 0.80
1509    feature_group_min_shared_sample_fraction: float = 0.15
1510    feature_group_ion_types: tuple = dataclasses.field(
1511        default_factory=lambda: (
1512            __import__(
1513                "corems.mass_spectra.calc.feature_grouping",
1514                fromlist=["DEFAULT_ION_TYPES"],
1515            ).DEFAULT_ION_TYPES
1516        )
1517    )
1518    feature_group_constrain_annotation: bool = True
1519    feature_group_partition_size: int = 5000
1520
1521    def __post_init__(self):
1522        self.consensus_mz_tol_ppm = self.alignment_mz_tol_ppm
1523        self._validate_alignment_acceptance_technique(
1524            self.alignment_acceptance_technique
1525        )
1526        self._validate_mass_feature_anchor_technique(self.mass_feature_anchor_technique)
1527
1528    def _validate_alignment_acceptance_technique(self, techniques):
1529        for technique in techniques:
1530            if technique not in self.alignment_acceptance_techniques_available:
1531                raise ValueError(
1532                    f"Alignment acceptance technique '{technique}' is not available. Alignment acceptance technique must be passed as a list. Available techniques: {self.alignment_acceptance_techniques_available}"
1533                )
1534
1535    def _validate_mass_feature_anchor_technique(self, techniques):
1536        for technique in techniques:
1537            if technique not in self.mass_feature_anchor_techniques_available:
1538                raise ValueError(
1539                    f"Mass feature anchor technique '{technique}' is not available. Alignment acceptance technique must be passed as a list. Available techniques: {self.mass_feature_anchor_techniques_available}"
1540                )
1541
1542    @property
1543    def alignment_acceptance_technique(self):
1544        return self._alignment_acceptance_technique
1545
1546    @alignment_acceptance_technique.setter
1547    def alignment_acceptance_technique(self, value):
1548        self._validate_alignment_acceptance_technique(value)
1549        self._alignment_acceptance_technique = value
1550
1551    @property
1552    def mass_feature_anchor_technique(self):
1553        return self._mass_feature_anchor_technique
1554
1555    @mass_feature_anchor_technique.setter
1556    def mass_feature_anchor_technique(self, value):
1557        self._validate_mass_feature_anchor_technique(value)
1558        self._mass_feature_anchor_technique = value