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
 11@dataclasses.dataclass
 12class TransientSetting:
 13    """Transient processing settings class
 14
 15    Attributes
 16    ----------
 17    implemented_apodization_function : tuple
 18        Available apodization functions
 19    apodization_method : str
 20        Apodization function to use. Hanning is a good default for Fourier transform magnitude mode. For absorption mode processing, Half-Sine or Half-Kaiser may be more appropriate.
 21    number_of_truncations : int
 22        How many times to truncate the transient prior to Fourier transform
 23    number_of_zero_fills : int
 24        How many times to zero fille the transient prior to Fourier transform.
 25    next_power_of_two : bool
 26        If True, zero fill to the next power of two after the new length of len(transient)+(number_of_zero_fills*len(transient)).
 27    kaiser_beta : float
 28        Beta parameter for Kaiser or Half-Kaiser apodisation function. 0 is rectangular,  5 is similar to Hamming,
 29        6 is similar to hanning, and 8.6 is similar to Blackman (from numpy docs)
 30
 31    """
 32
 33    implemented_apodization_function: tuple = (
 34        "Hamming",
 35        "Hanning",
 36        "Blackman",
 37        "Full-Sine",
 38        "Half-Sine",
 39        "Kaiser",
 40        "Half-Kaiser",
 41    )
 42    apodization_method: str = "Hanning"
 43    number_of_truncations: int = 0
 44    number_of_zero_fills: int = 1
 45    next_power_of_two: bool = False
 46    kaiser_beta: float = 8.6
 47
 48    def __post_init__(self):
 49        # enforce datatype
 50        for field in dataclasses.fields(self):
 51            value = getattr(self, field.name)
 52            if not isinstance(value, field.type):
 53                value = field.type(value)
 54                setattr(self, field.name, value)
 55
 56
 57@dataclasses.dataclass
 58class DataInputSetting:
 59    """Data input settings class
 60
 61    Attributes
 62    ----------
 63    header_translate : dict
 64        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'}
 65    """
 66
 67    # add to this dict the VALUES to match your labels, THE ORDER WON"T MATTER
 68    # "column_translate" : {"m/z":"m/z", "Resolving Power":"Resolving Power", "Abundance":"Abundance" , "S/N":"S/N"}
 69    header_translate: dict = dataclasses.field(default_factory=dict)
 70
 71    def __post_init__(self):
 72        self.header_translate = {
 73            "m/z": Labels.mz,
 74            "mOz": Labels.mz,
 75            "Mass": Labels.mz,
 76            "Resolving Power": Labels.rp,
 77            "Res.": Labels.rp,
 78            "resolution": Labels.rp,
 79            "Intensity": Labels.abundance,
 80            "Peak Height": Labels.abundance,
 81            "I": Labels.abundance,
 82            "Abundance": Labels.abundance,
 83            "abs_abu": Labels.abundance,
 84            "Signal/Noise": Labels.s2n,
 85            "S/N": Labels.s2n,
 86            "sn": Labels.s2n,
 87        }
 88
 89    def add_mz_label(self, label):
 90        """Add a label to the header_translate dictionary to be translated to the corems label for mz."""
 91        self.header_translate[label] = Labels.mz
 92
 93    def add_peak_height_label(self, label):
 94        """Add a label to the header_translate dictionary to be translated to the corems label for peak height."""
 95
 96        self.header_translate[label] = Labels.abundance
 97
 98    def add_sn_label(self, label):
 99        """Add a label to the header_translate dictionary to be translated to the corems label for signal to noise."""
100        self.header_translate[label] = Labels.s2n
101
102    def add_resolving_power_label(self, label):
103        """Add a label to the header_translate dictionary to be translated to the corems label for resolving power."""
104        self.header_translate[label] = Labels.rp
105
106
107@dataclasses.dataclass
108class LiquidChromatographSetting:
109    """Liquid chromatograph processing settings class
110
111    Attributes
112    ----------
113    scans : list or tuple, optional
114        List of select scan to average or a tuple containing the range to average. Default is (0, 1).
115    eic_tolerance_ppm : float, optional
116        Mass tolerance in ppm for extracted ion chromatogram peak detection. Default is 5.
117    correct_eic_baseline : bool, optional
118        If True, correct the baseline of the extracted ion chromatogram. Default is True.
119    smooth_window : int, optional
120        Window size for smoothing the ion chromatogram (extracted or total). Default is 5.
121    smooth_method : str, optional
122        Smoothing method to use. Default is 'savgol'. Other options are 'hanning', 'blackman', 'bartlett', 'flat', 'boxcar'.
123    implemented_smooth_method : tuple, optional
124        Smoothing methods that can be implemented. Values are ('savgol', 'hanning', 'blackman', 'bartlett', 'flat', 'boxcar').
125    savgol_pol_order : int, optional
126        Polynomial order for Savitzky-Golay smoothing. Default is 2.
127    peak_height_max_percent : float, optional
128        1-100 % used for baseline detection use 0.1 for second_derivative and 10 for other methods. Default is 10.
129    peak_max_prominence_percent : float, optional
130        1-100 % used for baseline detection. Default is 1.
131    peak_derivative_threshold : float, optional
132        Threshold for defining derivative crossing. Default is 0.0005.
133    min_peak_datapoints : float, optional
134        minimum data point to define a chromatografic peak. Default is 5.
135    noise_threshold_method : str, optional
136        Method for detecting noise threshold. Default is 'manual_relative_abundance'.
137    noise_threshold_methods_implemented : tuple, optional
138        Methods for detected noise threshold that can be implemented. Default is ('auto_relative_abundance', 'manual_relative_abundance', 'second_derivative').
139    peak_height_min_percent : float, optional
140        0-100 % used for peak detection. Default is 0.1.
141    eic_signal_threshold : float, optional
142        0-100 % used for extracted ion chromatogram peak detection. Default is 0.01.
143    eic_buffer_time : float, optional
144        Buffer time to add to the start and end of the plot of the extracted ion chromatogram, in minutes. Default is 1.5.
145    ph_smooth_it : int, optional
146        Number of iterations to use for smoothing prior to finding mass features.
147        Called within the PHCalculations.find_mass_features_ph() method. Default is 7.
148    ph_smooth_radius_mz : int, optional
149        Radius in m/z steps (not daltons) for smoothing prior to finding mass features.
150        Called within the PHCalculations.find_mass_features_ph() method. Default is 0.
151    ph_smooth_radius_scan : int, optional
152        Radius in scan steps for smoothing prior to finding mass features.
153        Called within the PHCalculations.find_mass_features_ph() method. Default is 3.
154    ph_inten_min_rel : int, optional
155        Relative minimum intensity to use for finding mass features.
156        Calculated as a fraction of the maximum intensity of the unprocessed profile data (mz, scan).
157        Called within the PH_Calculations.find_mass_features() method. Default is 0.001.
158    ph_persis_min_rel : int, optional
159        Relative minimum persistence for retaining mass features.
160        Calculated as a fraction of the maximum intensity of the unprocessed profile data (mz, scan).
161        Should be greater to or equal to ph_inten_min_rel.
162        Called within the PH_Calculations.find_mass_features() method. Default is 0.001.
163    mass_feature_cluster_mz_tolerance_rel : float, optional
164        Relative m/z tolerance to use for clustering mass features.
165        Called with the PHCalculations.cluster_mass_features() and the LCCalculations.deconvolute_ms1_mass_features() methods.
166        Default is 5E-6 (5 ppm).
167    mass_feature_cluster_rt_tolerance : float, optional
168        Retention time tolerance to use for clustering mass features, in minutes.
169        Called with the PHCalculations.cluster_mass_features() and the LCCalculations.deconvolute_ms1_mass_features() methods.
170        Default is 0.2.
171    ms1_scans_to_average : int, optional
172        Number of MS1 scans to average for mass-feature associated m/zs.
173        Called within the LCMSBase.add_associated_ms1() method. Default is 1.
174    ms1_deconvolution_corr_min : float, optional
175        Minimum correlation to use for deconvoluting MS1 mass features.
176        Called within the LCCalculations.deconvolute_ms1_mass_features() method.
177        Default is 0.8.
178    ms2_dda_rt_tolerance : float, optional
179        Retention time tolerance to use for associating MS2 spectra to mass features, in minutes. Called within the LCMSBase.add_associated_ms2_dda() method. Default is 0.15.
180    ms2_dda_mz_tolerance : float, optional
181        Mass tolerance to use for associating MS2 spectra to mass features. Called within the LCMSBase.add_associated_ms2_dda() method. Default is 0.05.
182    ms2_min_fe_score : float, optional
183        Minimum flash entropy for retaining MS2 annotations. Called within the LCMSSpectralSearch.fe_search() method. Default is 0.2.
184    search_as_lipids : bool, optional
185        If True, prepare the database for lipid searching. Called within the LCMSSpectralSearch.fe_prep_search_db() method. Default is False.
186    include_fragment_types : bool, optional
187        If True, include fragment types in the database. Called within the LCMSSpectralSearch.fe_search() and related methods. Default is False.
188    verbose_processing : bool, optional
189        If True, print verbose processing information. Default is True.
190    """
191
192    scans: list | tuple = (-1, -1)
193
194    # Parameters used for generating EICs and performing 1D peak picking and EIC/TIC smoothing
195    eic_tolerance_ppm: float = 5
196    correct_eic_baseline = True
197    smooth_window: int = 5
198    smooth_method: str = "savgol"
199    implemented_smooth_method: tuple = (
200        "savgol",
201        "hanning",
202        "blackman",
203        "bartlett",
204        "flat",
205        "boxcar",
206    )
207    savgol_pol_order: int = 2
208    peak_height_max_percent: float = 10
209    peak_max_prominence_percent: float = 1
210    peak_derivative_threshold: float = 0.0005
211    min_peak_datapoints: float = 5
212    noise_threshold_method: str = "manual_relative_abundance"
213    noise_threshold_methods_implemented: tuple = (
214        "auto_relative_abundance",
215        "manual_relative_abundance",
216        "second_derivative",
217    )
218    peak_height_min_percent: float = 0.1
219    eic_signal_threshold: float = 0.01
220    eic_buffer_time = 1.5
221
222    # Parameters used for 2D peak picking
223    peak_picking_method: str = "persistent homology"
224    implemented_peak_picking_methods: tuple = ("persistent homology",)
225
226    # Parameters used in persistent homology calculations
227    ph_smooth_it = 1
228    ph_smooth_radius_mz = 0
229    ph_smooth_radius_scan = 1
230    ph_inten_min_rel = 0.001
231    ph_persis_min_rel = 0.001
232
233    # Parameters used to cluster mass features
234    mass_feature_cluster_mz_tolerance_rel: float = 5e-6
235    mass_feature_cluster_rt_tolerance: float = 0.3
236
237    # Parameters used in associating MS1 and MS2 spectra to LCMS mass features and deconvoluting MS1 mass features
238    ms1_scans_to_average: int = 1
239    ms1_deconvolution_corr_min: float = 0.8
240    ms2_dda_rt_tolerance: float = 0.15
241    ms2_dda_mz_tolerance: float = 0.05
242
243    # Parameters used for flash entropy searching and database preparation
244    ms2_min_fe_score: float = 0.2
245    search_as_lipids: bool = False
246    include_fragment_types: bool = False
247
248    # Parameters used for saving the data
249    export_profile_spectra: bool = False
250    export_eics: bool = True
251    export_unprocessed_ms1: bool = False
252
253    # Parameters used for verbose processing
254    verbose_processing: bool = True
255
256    def __post_init__(self):
257        # enforce datatype
258        for field in dataclasses.fields(self):
259            value = getattr(self, field.name)
260            if not isinstance(value, field.type):
261                value = field.type(value)
262                setattr(self, field.name, value)
263
264
265@dataclasses.dataclass
266class MassSpectrumSetting:
267    """Mass spectrum processing settings class
268
269    Attributes
270    ----------
271    noise_threshold_method : str, optional
272        Method for detecting noise threshold. Default is 'log'.
273    noise_threshold_methods_implemented : tuple, optional
274        Methods for detected noise threshold that can be implemented. Default is ('minima', 'signal_noise', 'relative_abundance', 'absolute_abundance', 'log').
275    noise_threshold_min_std : int, optional
276        Minumum value for noise thresholding when using 'minima' noise threshold method. Default is 6.
277    noise_threshold_min_s2n : float, optional
278        Minimum value for noise thresholding when using 'signal_noise' noise threshold method. Default is 4.
279    noise_threshold_min_relative_abundance : float, optional
280        Minimum value for noise thresholding when using 'relative_abundance' noise threshold method. Note that this is a percentage value. Default is 6 (6%).
281    noise_threshold_absolute_abundance : float, optional
282        Minimum value for noise thresholding when using 'absolute_abundance' noise threshold method. Default is 1_000_000.
283    noise_threshold_log_nsigma : int, optional
284        Number of standard deviations to use when using 'log' noise threshold method. Default is 6.
285    noise_threshold_log_nsigma_corr_factor : float, optional
286        Correction factor for log noise threshold method. Default is 0.463.
287    noise_threshold_log_nsigma_bins : int, optional
288        Number of bins to use for histogram when using 'log' noise threshold method. Default is 500.
289    noise_min_mz : float, optional
290        Minimum m/z to use for noise thresholding. Default is 50.0.
291    noise_max_mz : float, optional
292        Maximum m/z to use for noise thresholding. Default is 1200.0.
293    min_picking_mz : float, optional
294        Minimum m/z to use for peak picking. Default is 50.0.
295    max_picking_mz : float, optional
296        Maximum m/z to use for peak picking. Default is 1200.0.
297    picking_point_extrapolate : int, optional
298        How many data points (in each direction) to extrapolate the mz axis and 0 pad the abundance axis. Default is 3.
299        Recommend 3 for reduced profile data or if peak picking faults
300    calib_minimize_method : str, optional
301        Minimization method to use for calibration. Default is 'Powell'.
302    calib_pol_order : int, optional
303        Polynomial order to use for calibration. Default is 2.
304    max_calib_ppm_error : float, optional
305        Maximum ppm error to use for calibration. Default is 1.0.
306    min_calib_ppm_error : float, optional
307        Minimum ppm error to use for calibration. Default is -1.0.
308    calib_sn_threshold : float, optional
309        Signal to noise threshold to use for calibration. Default is 2.0.
310    calibration_ref_match_method: string, optional
311        Method for matching reference masses with measured masses for recalibration. Default is 'legacy'.
312    calibration_ref_match_tolerance: float, optional
313        If using the new method for calibration reference mass matching, this tolerance is the initial matching tolerance. Default is 0.003
314    do_calibration : bool, optional
315        If True, perform calibration. Default is True.
316    verbose_processing : bool, optional
317        If True, print verbose processing information. Default is True.
318    """
319
320    noise_threshold_method: str = "log"
321
322    noise_threshold_methods_implemented: tuple = (
323        "minima",
324        "signal_noise",
325        "relative_abundance",
326        "absolute_abundance",
327        "log",
328    )
329
330    noise_threshold_min_std: int = 6  # when using 'minima' method
331
332    noise_threshold_min_s2n: float = 4  # when using 'signal_noise' method
333
334    noise_threshold_min_relative_abundance: float = (
335        6  # from 0-100, when using 'relative_abundance' method
336    )
337
338    noise_threshold_absolute_abundance: float = (
339        1_000_000  # when using 'absolute_abundance' method
340    )
341
342    noise_threshold_log_nsigma: int = 6  # when using 'log' method
343    noise_threshold_log_nsigma_corr_factor: float = 0.463  # mFT is 0.463, aFT is 1.0
344    noise_threshold_log_nsigma_bins: int = 500  # bins for the histogram for the noise
345
346    noise_min_mz: float = 50.0
347    noise_max_mz: float = 1200.0
348
349    min_picking_mz: float = 50.0
350    max_picking_mz: float = 1200.0
351
352    # How many data points (in each direction) to extrapolate the mz axis and 0 pad the abundance axis
353    # This will fix peak picking at spectrum limit issues
354    #  0 to keep normal behaviour, typical value 3 to fix
355    picking_point_extrapolate: int = 3
356
357    calib_minimize_method: str = "Powell"
358    calib_pol_order: int = 2
359    max_calib_ppm_error: float = 1.0
360    min_calib_ppm_error: float = -1.0
361    calib_sn_threshold: float = 2.0
362    calibration_ref_match_method: str = "legacy"
363    calibration_ref_match_method_implemented: tuple = ("legacy", "merged")
364    calibration_ref_match_tolerance: float = 0.003
365    calibration_ref_match_std_raw_error_limit: float = 1.5
366    # calib_ref_mzs: list = [0]
367
368    do_calibration: bool = True
369    verbose_processing: bool = True
370
371    def __post_init__(self):
372        # enforce datatype
373        for field in dataclasses.fields(self):
374            value = getattr(self, field.name)
375            if not isinstance(value, field.type):
376                value = field.type(value)
377                setattr(self, field.name, value)
378
379
380@dataclasses.dataclass
381class MassSpecPeakSetting:
382    """Mass spectrum peak processing settings class
383
384    Attributes
385    ----------
386    kendrick_base : Dict, optional
387        Dictionary specifying the elements and their counts in the Kendrick base.
388        Defaults to {'C': 1, 'H': 2}.
389    kendrick_rounding_method : str, optional
390        Method for calculating the nominal Kendrick mass. Valid values are 'floor', 'ceil', or 'round'.
391        Defaults to 'floor'.
392    implemented_kendrick_rounding_methods : tuple
393        Tuple of valid rounding methods for calculating the nominal Kendrick mass.
394        Defaults to ('floor', 'ceil', 'round').
395    peak_derivative_threshold : float, optional
396        Threshold for defining derivative crossing. Should be a value between 0 and 1.
397        Defaults to 0.0.
398    peak_min_prominence_percent : float, optional
399        Minimum prominence percentage used for peak detection. Should be a value between 1 and 100.
400        Defaults to 0.1.
401    min_peak_datapoints : float, optional
402        Minimum number of data points used for peak detection. Should be a value between 0 and infinity.
403        Defaults to 5.
404    peak_max_prominence_percent : float, optional
405        Maximum prominence percentage used for baseline detection. Should be a value between 1 and 100.
406        Defaults to 0.1.
407    peak_height_max_percent : float, optional
408        Maximum height percentage used for baseline detection. Should be a value between 1 and 100.
409        Defaults to 10.
410    legacy_resolving_power : bool, optional
411        Flag indicating whether to use the legacy (CoreMS v1) resolving power calculation.
412        Defaults to True.
413    legacy_centroid_polyfit : bool, optional
414        Use legacy (numpy polyfit) to fit centroid
415        Default false.
416    """
417
418    kendrick_base: Dict = dataclasses.field(default_factory=dict)
419
420    kendrick_rounding_method: str = "floor"  # 'floor', 'ceil' or 'round' are valid methods for calculating nominal kendrick mass
421
422    implemented_kendrick_rounding_methods: tuple = ("floor", "ceil", "round")
423
424    peak_derivative_threshold: float = 0.0  # define derivative crossing threshould 0-1
425
426    peak_min_prominence_percent: float = 0.1  # 1-100 % used for peak detection
427
428    min_peak_datapoints: float = 5  # 0-inf used for peak detection
429
430    peak_max_prominence_percent: float = 0.1  # 1-100 % used for baseline detection
431
432    peak_height_max_percent: float = 10  # 1-100 % used for baseline detection
433
434    legacy_resolving_power: bool = (
435        True  # Use the legacy (CoreMS v1) resolving power calculation (True)
436    )
437
438    legacy_centroid_polyfit: bool = False
439
440    def __post_init__(self):
441        # default to CH2
442        if not self.kendrick_base:
443            self.kendrick_base = {"C": 1, "H": 2}
444        # enforce datatype
445        for field in dataclasses.fields(self):
446            value = getattr(self, field.name)
447            if not isinstance(value, field.type):
448                value = field.type(value)
449                setattr(self, field.name, value)
450
451
452@dataclasses.dataclass
453class GasChromatographSetting:
454    """Gas chromatograph processing settings class
455
456    Attributes
457    ----------
458    use_deconvolution : bool, optional
459        If True, use deconvolution. Default is False.
460    implemented_smooth_method : tuple, optional
461        Smoothing methods that can be implemented. Default is ('savgol', 'hanning', 'blackman', 'bartlett', 'flat', 'boxcar').
462    smooth_window : int, optional
463        Window size for smoothing the ion chromatogram. Default is 5.
464    smooth_method : str, optional
465        Smoothing method to use. Default is 'savgol'. Other options are 'hanning', 'blackman', 'bartlett', 'flat', 'boxcar'.
466    savgol_pol_order : int, optional
467        Polynomial order for Savitzky-Golay smoothing. Default is 2.
468    peak_derivative_threshold : float, optional
469        Threshold for defining derivative crossing. Should be a value between 0 and 1.
470        Defaults to 0.0005.
471    peak_height_max_percent : float, optional
472        Maximum height percentage used for baseline detection. Should be a value between 1 and 100.
473        Defaults to 10.
474    peak_max_prominence_percent : float, optional
475        Maximum prominence percentage used for baseline detection. Should be a value between 1 and 100.
476        Defaults to 1.
477    min_peak_datapoints : float, optional
478        Minimum number of data points used for peak detection. Should be a value between 0 and infinity.
479        Defaults to 5.
480    max_peak_width : float, optional
481        Maximum peak width used for peak detection. Should be a value between 0 and infinity.
482        Defaults to 0.1.
483    noise_threshold_method : str, optional
484        Method for detecting noise threshold. Default is 'manual_relative_abundance'.
485    noise_threshold_methods_implemented : tuple, optional
486        Methods for detected noise threshold that can be implemented. Default is ('auto_relative_abundance', 'manual_relative_abundance', 'second_derivative').
487    std_noise_threshold : int, optional
488        Default is 3.
489    peak_height_min_percent : float, optional
490        0-100 % used for peak detection. Default is 0.1.
491    peak_min_prominence_percent : float, optional
492        0-100 % used for peak detection. Default is 0.1.
493    eic_signal_threshold : float, optional
494        0-100 % used for extracted ion chromatogram peak detection. Default is 0.01.
495    max_rt_distance : float, optional
496        Maximum distance allowance for hierarchical cluster, in minutes. Default is 0.025.
497    verbose_processing : bool, optional
498        If True, print verbose processing information. Default is True.
499    """
500
501    use_deconvolution: bool = False
502
503    implemented_smooth_method: tuple = (
504        "savgol",
505        "hanning",
506        "blackman",
507        "bartlett",
508        "flat",
509        "boxcar",
510    )
511
512    smooth_window: int = 5
513
514    smooth_method: str = "savgol"
515
516    savgol_pol_order: int = 2
517
518    peak_derivative_threshold: float = 0.0005
519
520    peak_height_max_percent: float = 10  # 1-100 % used for baseline detection use 0.1 for second_derivative and 10 for other methods
521
522    peak_max_prominence_percent: float = 1  # 1-100 % used for baseline detection
523
524    min_peak_datapoints: float = 5
525
526    max_peak_width: float = 0.1
527
528    noise_threshold_method: str = "manual_relative_abundance"
529
530    noise_threshold_methods_implemented: tuple = (
531        "auto_relative_abundance",
532        "manual_relative_abundance",
533        "second_derivative",
534    )
535
536    std_noise_threshold: int = 3
537
538    peak_height_min_percent: float = 0.1  # 0-100 % used for peak detection
539
540    peak_min_prominence_percent: float = 0.1  # 0-100 % used for peak detection
541
542    eic_signal_threshold: float = (
543        0.01  # 0-100 % used for extracted ion chromatogram peak detection
544    )
545
546    max_rt_distance: float = (
547        0.025  # minutes, max distance allowance hierarchical clutter
548    )
549
550    verbose_processing: bool = True
551
552    def __post_init__(self):
553        # enforce datatype
554        for field in dataclasses.fields(self):
555            value = getattr(self, field.name)
556            if not isinstance(value, field.type):
557                value = field.type(value)
558                setattr(self, field.name, value)
559
560
561@dataclasses.dataclass
562class CompoundSearchSettings:
563    """Settings for compound search
564
565    Attributes
566    ----------
567    url_database : str, optional
568        URL for the database. Default is 'sqlite:///db/pnnl_lowres_gcms_compounds.sqlite'.
569    ri_search_range : float, optional
570        Retention index search range. Default is 35.
571    rt_search_range : float, optional
572        Retention time search range, in minutes. Default is 1.0.
573    correlation_threshold : float, optional
574        Threshold for correlation for spectral similarity. Default is 0.5.
575    score_threshold : float, optional
576        Threshold for compsite score. Default is 0.0.
577    ri_spacing : float, optional
578        Retention index spacing. Default is 200.
579    ri_std : float, optional
580        Retention index standard deviation. Default is 3.
581    ri_calibration_compound_names : list, optional
582        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'].
583
584    """
585
586    url_database: str = "postgresql+psycopg2://coremsappdb:coremsapppnnl@localhost:5432/lowres"  # 'postgresql://postgres:labthomson0102@172.22.113.27:5432/GCMS' # 'sqlite:///db/pnnl_lowres_gcms_compounds.sqlite'
587
588    ri_search_range: float = 35
589
590    rt_search_range: float = 1.0  # used for retention index calibration
591
592    correlation_threshold: float = 0.5  # used for calibration, spectral similarity
593
594    score_threshold: float = 0.0
595
596    ri_spacing: float = 200
597
598    ri_std: float = 3  # in standard deviation
599
600    ri_calibration_compound_names: List = dataclasses.field(default_factory=list)
601
602    # calculates and export all spectral similarity methods
603    exploratory_mode: bool = False
604
605    score_methods: tuple = ("highest_sim_score", "highest_ss")
606
607    output_score_method: str = "All"
608
609    def __post_init__(self):
610        # enforce datatype
611        self.url_database = os.getenv(
612            "SPECTRAL_GCMS_DATABASE_URL",
613            "sqlite:///db/pnnl_lowres_gcms_compounds.sqlite",
614        )
615
616        for field in dataclasses.fields(self):
617            value = getattr(self, field.name)
618            if not isinstance(value, field.type):
619                value = field.type(value)
620                setattr(self, field.name, value)
621
622        self.ri_calibration_compound_names = [
623            "Methyl Caprylate",
624            "Methyl Caprate",
625            "Methyl Pelargonate",
626            "Methyl Laurate",
627            "Methyl Myristate",
628            "Methyl Palmitate",
629            "Methyl Stearate",
630            "Methyl Eicosanoate",
631            "Methyl Docosanoate",
632            "Methyl Linocerate",
633            "Methyl Hexacosanoate",
634            "Methyl Octacosanoate",
635            "Methyl Triacontanoate",
636        ]
637
638
639class MolecularLookupDictSettings:
640    """Settings for molecular searching
641
642    These are used to generate the database entries, do not change.
643
644    Attributes
645    ----------
646    usedAtoms : dict, optional
647        Dictionary of atoms and ranges. Default is {'C': (1, 90), 'H': (4, 200), 'O': (0, 12), 'N': (0, 0), 'S': (0, 0), 'P': (0, 0), 'Cl': (0, 0)}.
648    min_mz : float, optional
649        Minimum m/z to use for searching. Default is 50.0.
650    max_mz : float, optional
651        Maximum m/z to use for searching. Default is 1200.0.
652    min_dbe : float, optional
653        Minimum double bond equivalent to use for searching. Default is 0.
654    max_dbe : float, optional
655        Maximum double bond equivalent to use for searching. Default is 50.
656    use_pah_line_rule : bool, optional
657        If True, use the PAH line rule. Default is False.
658    isRadical : bool, optional
659        If True, search for radical ions. Default is True.
660    isProtonated : bool, optional
661        If True, search for protonated ions. Default is True.
662    url_database : str, optional
663        URL for the database. Default is None.
664    db_jobs : int, optional
665        Number of jobs to use for database queries. Default is 1.
666    used_atom_valences : dict, optional
667        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}.
668
669    """
670
671    ### DO NOT CHANGE IT! These are used to generate the database entries
672
673    ### DO change when creating a new application database
674
675    ### FOR search settings runtime and database query check use the MolecularFormulaSearchSettings class below
676
677    ### C, H, N, O, S and P atoms are ALWAYS needed at usedAtoms
678    ### if you don't want to include one of those atoms set the max and min at 0
679    ### you can include any atom listed at Atoms class inside encapsulation.settings.constants module
680    ### make sure to include the selected covalence at the used_atoms_valences when adding new atoms
681    ### NOTE : Adducts atoms have zero covalence
682    ### NOTE : Not using static variable because this class is distributed using multiprocessing
683    def __init__(self):
684        self.usedAtoms = {
685            "C": (1, 90),
686            "H": (4, 200),
687            "O": (0, 12),
688            "N": (0, 0),
689            "S": (0, 0),
690            "P": (0, 0),
691            "Cl": (0, 0),
692        }
693
694        self.min_mz = 50
695
696        self.max_mz = 1200
697
698        self.min_dbe = 0
699
700        self.max_dbe = 50
701
702        # overwrites the dbe limits above to DBE = (C + heteroatoms) * 0.9
703        self.use_pah_line_rule = False
704
705        self.isRadical = True
706
707        self.isProtonated = True
708
709        self.url_database = None
710
711        self.db_jobs = 1
712
713        self.used_atom_valences = {
714            "C": 4,
715            "13C": 4,
716            "H": 1,
717            "O": 2,
718            "18O": 2,
719            "N": 3,
720            "S": 2,
721            "34S": 2,
722            "P": 3,
723            "Cl": 1,
724            "37Cl": 1,
725            "Br": 1,
726            "Na": 1,
727            "F": 1,
728            "K": 0,
729        }
730
731
732@dataclasses.dataclass
733class MolecularFormulaSearchSettings:
734    """Settings for molecular searching
735
736    Attributes
737    ----------
738    use_isotopologue_filter : bool, optional
739        If True, use isotopologue filter. Default is False.
740    isotopologue_filter_threshold : float, optional
741        Threshold for isotopologue filter. Default is 33.
742    isotopologue_filter_atoms : tuple, optional
743        Tuple of atoms to use for isotopologue filter. Default is ('Cl', 'Br').
744    use_runtime_kendrick_filter : bool, optional
745        If True, use runtime Kendrick filter. Default is False.
746    use_min_peaks_filter : bool, optional
747        If True, use minimum peaks filter. Default is True.
748    min_peaks_per_class : int, optional
749        Minimum number of peaks per class. Default is 15.
750    url_database : str, optional
751        URL for the database. Default is 'postgresql+psycopg2://coremsappdb:coremsapppnnl@localhost:5432/coremsapp'.
752    db_jobs : int, optional
753        Number of jobs to use for database queries. Default is 3.
754    db_chunk_size : int, optional
755        Chunk size to use for database queries. Default is 300.
756    ion_charge : int, optional
757        Ion charge. Default is -1.
758    min_hc_filter : float, optional
759        Minimum hydrogen to carbon ratio. Default is 0.3.
760    max_hc_filter : float, optional
761        Maximum hydrogen to carbon ratio. Default is 3.
762    min_oc_filter : float, optional
763        Minimum oxygen to carbon ratio. Default is 0.0.
764    max_oc_filter : float, optional
765        Maximum oxygen to carbon ratio. Default is 1.2.
766    min_op_filter : float, optional
767        Minimum oxygen to phosphorous ratio. Default is 2.
768    use_pah_line_rule : bool, optional
769        If True, use the PAH line rule. Default is False.
770    min_dbe : float, optional
771        Minimum double bond equivalent to use for searching. Default is 0.
772    max_dbe : float, optional
773        Maximum double bond equivalent to use for searching. Default is 40.
774    mz_error_score_weight : float, optional
775        Weight for m/z error score to contribute to composite score. Default is 0.6.
776    isotopologue_score_weight : float, optional
777        Weight for isotopologue score to contribute to composite score. Default is 0.4.
778    adduct_atoms_neg : tuple, optional
779        Tuple of atoms to use in negative polarity. Default is ('Cl', 'Br').
780    adduct_atoms_pos : tuple, optional
781        Tuple of atoms to use in positive polarity. Default is ('Na', 'K').
782    score_methods : tuple, optional
783        Tuple of score method that can be implemented.
784        Default is ('S_P_lowest_error', 'N_S_P_lowest_error', 'lowest_error', 'prob_score', 'air_filter_error', 'water_filter_error', 'earth_filter_error').
785    score_method : str, optional
786        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'.
787    output_min_score : float, optional
788        Minimum score for output. Default is 0.1.
789    output_score_method : str, optional
790        Score method to use for output. Default is 'All Candidates'.
791    isRadical : bool, optional
792        If True, search for radical ions. Default is False.
793    isProtonated : bool, optional
794        If True, search for protonated ions. Default is True.
795    isAdduct : bool, optional
796        If True, search for adduct ions. Default is False.
797    usedAtoms : dict, optional
798        Dictionary of atoms and ranges. Default is {'C': (1, 90), 'H': (4, 200), 'O': (0, 12), 'N': (0, 0), 'S': (0, 0), 'P': (0, 0), 'Cl': (0, 0)}.
799    ion_types_excluded : list, optional
800        List of ion types to exclude from molecular id search, commonly ['[M+CH3COO]-]'] or ['[M+COOH]-'] depending on mobile phase content. Default is [].
801    ionization_type : str, optional
802        Ionization type. Default is 'ESI'.
803    min_ppm_error : float, optional
804        Minimum ppm error. Default is -10.0.
805    max_ppm_error : float, optional
806        Maximum ppm error. Default is 10.0.
807    min_abun_error : float, optional
808        Minimum abundance error for isotolopologue search. Default is -100.0.
809    max_abun_error : float, optional
810        Maximum abundance error for isotolopologue search. Default is 100.0.
811    mz_error_range : float, optional
812        m/z error range. Default is 1.5.
813    error_method : str, optional
814        Error method. Default is 'None'. Options are 'distance', 'lowest', 'symmetrical','average' 'None'.
815    mz_error_average : float, optional
816        m/z error average. Default is 0.0.
817    used_atom_valences : dict, optional
818        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}.
819    verbose_processing: bool, optional
820        If True, print verbose processing information. Default is True.
821    """
822    verbose_processing: bool = True    
823
824    use_isotopologue_filter: bool = False
825
826    isotopologue_filter_threshold: float = 33
827
828    isotopologue_filter_atoms: tuple = ("Cl", "Br")
829
830    use_runtime_kendrick_filter: bool = False
831
832    use_min_peaks_filter: bool = True
833
834    min_peaks_per_class: int = 15
835
836    url_database: str = (
837        "postgresql+psycopg2://coremsappdb:coremsapppnnl@localhost:5432/coremsapp"
838    )
839
840    db_jobs: int = 3
841
842    db_chunk_size: int = 300
843
844    # query setting========
845    ion_charge: int = -1
846
847    min_hc_filter: float = 0.3
848
849    max_hc_filter: float = 3
850
851    min_oc_filter: float = 0.0
852
853    max_oc_filter: float = 1.2
854
855    min_op_filter: float = 2
856
857    use_pah_line_rule: bool = False
858
859    min_dbe: float = 0
860
861    max_dbe: float = 40
862
863    mz_error_score_weight: float = 0.6
864
865    isotopologue_score_weight: float = 0.4
866
867    # look for close shell ions [M + Adduct]+ only considers metal set in the list adduct_atoms
868    adduct_atoms_neg: tuple = ("Cl", "Br")
869
870    adduct_atoms_pos: tuple = ("Na", "K")
871
872    score_methods: tuple = (
873        "S_P_lowest_error",
874        "N_S_P_lowest_error",
875        "lowest_error",
876        "prob_score",
877        "air_filter_error",
878        "water_filter_error",
879        "earth_filter_error",
880    )
881
882    score_method: str = "prob_score"
883
884    output_min_score: float = 0.1
885
886    output_score_method: str = "All Candidates"
887
888    # depending on the polarity mode it looks for [M].+ , [M].-
889    # query and automatically compile add entry if it doesn't exist
890
891    isRadical: bool = False
892
893    # depending on the polarity mode it looks for [M + H]+ , [M - H]+
894    # query and automatically compile and push options if it doesn't exist
895    isProtonated: bool = True
896
897    isAdduct: bool = False
898
899    usedAtoms: dict = dataclasses.field(default_factory=dict)
900    ion_types_excluded: list = dataclasses.field(default_factory=list)
901
902    # search setting ========
903
904    ionization_type: str = "ESI"
905
906    # empirically set / needs optimization
907    min_ppm_error: float = -10.0  # ppm
908
909    # empirically set / needs optimization
910    max_ppm_error: float = 10.0  # ppm
911
912    # empirically set / needs optimization set for isotopologue search
913    min_abun_error: float = -100.0  # percentage
914
915    # empirically set / needs optimization set for isotopologue search
916    max_abun_error: float = 100.0  # percentage
917
918    # empirically set / needs optimization
919    mz_error_range: float = 1.5
920
921    # 'distance', 'lowest', 'symmetrical','average' 'None'
922    error_method: str = "None"
923
924    mz_error_average: float = 0.0
925
926    # used_atom_valences: {'C': 4, 'H':1, etc} = dataclasses.field(default_factory=dict)
927    used_atom_valences: dict = dataclasses.field(default_factory=dict)
928
929    def __post_init__(self):
930        if not self.url_database or self.url_database == "":
931            self.url_database = os.getenv(
932            "COREMS_DATABASE_URL", "sqlite:///db/molformula.db"
933            )
934        # enforce datatype
935        for field in dataclasses.fields(self):
936            value = getattr(self, field.name)
937            if not isinstance(value, field.type):
938                value = field.type(value)
939                setattr(self, field.name, value)
940
941        # enforce C and H if either do not exists
942        if "C" not in self.usedAtoms.keys():
943            self.usedAtoms["C"] = (1, 100)
944        if "H" not in self.usedAtoms.keys():
945            self.usedAtoms["H"] = (1, 200)
946
947        # add cummon values
948        current_used_atoms = self.used_atom_valences.keys()
949
950        for atom in Atoms.atoms_covalence.keys():
951            if atom not in current_used_atoms:
952                covalence = Atoms.atoms_covalence.get(atom)
953
954                if isinstance(covalence, int):
955                    self.used_atom_valences[atom] = covalence
956
957                else:
958                    # will get the first number of all possible covalances, which should be the most commum
959                    self.used_atom_valences[atom] = covalence[0]