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