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

masster/logger.py

@@ -86,40 +86,44 @@ class MassterLogger:
 
                 # Loguru-style colors for different log levels
                 level_colors = {
-                    'TRACE': '\x1b[34m',      # blue
-                    'DEBUG': '\x1b[36m',      # cyan
-                    'INFO': '\x1b[37m',       # white
-                    'SUCCESS': '\x1b[32m',    # green
-                    'WARNING': '\x1b[33m',    # yellow
-                    'ERROR': '\x1b[31m',      # red
-                    'CRITICAL': '\x1b[35m',   # magenta
+                    "TRACE": "\x1b[34m",  # blue
+                    "DEBUG": "\x1b[36m",  # cyan
+                    "INFO": "\x1b[37m",  # white
+                    "SUCCESS": "\x1b[32m",  # green
+                    "WARNING": "\x1b[33m",  # yellow
+                    "ERROR": "\x1b[31m",  # red
+                    "CRITICAL": "\x1b[35m",  # magenta
                 }
 
                 level_str = record.levelname.ljust(8)
-                level_color = level_colors.get(record.levelname, '\x1b[37m')  # default white
+                level_color = level_colors.get(record.levelname, "\x1b[37m")  # default white
                 label_part = self.label + " | " if self.label else ""
-                
+
                 # For DEBUG and TRACE levels, add module/location information
                 location_info = ""
-                if record.levelname in ['TRACE']:
+                if record.levelname in ["TRACE"]:
                     # Use caller information if available (from extra), otherwise fall back to record info
-                    if hasattr(record, 'caller_module'):
-                        module_name = record.caller_module.split('.')[-1] if record.caller_module else 'unknown'
+                    if hasattr(record, "caller_module"):
+                        module_name = record.caller_module.split(".")[-1] if record.caller_module else "unknown"
                         line_no = record.caller_lineno
                         func_name = record.caller_funcname
                     else:
-                        module_name = record.module if hasattr(record, 'module') else 'unknown'
+                        module_name = record.module if hasattr(record, "module") else "unknown"
                         line_no = record.lineno
                         func_name = record.funcName
-                    location_info = f"\x1b[90m{module_name}:{func_name}:{line_no}\x1b[0m | "  # dim gray for location info
-                
+                    location_info = (
+                        f"\x1b[90m{module_name}:{func_name}:{line_no}\x1b[0m | "  # dim gray for location info
+                    )
+
                 # Loguru-style format: <white>timestamp</white> | <level>LEVEL</level> | <location> | <cyan>label</cyan> - <level>message</level>
-                return (f"\x1b[37m{timestamp}\x1b[0m | "  # white timestamp
-                       f"{level_color}{level_str}\x1b[0m | "  # colored level
-                       f"{location_info}"  # location info for DEBUG/TRACE
-                       f"{level_color}{label_part}\x1b[0m"  # colored label
-                       f"{level_color}{record.getMessage()}\x1b[0m")  # colored message
-        
+                return (
+                    f"\x1b[37m{timestamp}\x1b[0m | "  # white timestamp
+                    f"{level_color}{level_str}\x1b[0m | "  # colored level
+                    f"{location_info}"  # location info for DEBUG/TRACE
+                    f"{level_color}{label_part}\x1b[0m"  # colored label
+                    f"{level_color}{record.getMessage()}\x1b[0m"
+                )  # colored message
+
         self.handler.setFormatter(massterFormatter(self.label))
         self.logger_instance.addHandler(self.handler)
 
@@ -150,40 +154,44 @@ class MassterLogger:
 
                 # Loguru-style colors for different log levels
                 level_colors = {
-                    'TRACE': '\x1b[34m',      # blue
-                    'DEBUG': '\x1b[36m',      # cyan
-                    'INFO': '\x1b[37m',       # white
-                    'SUCCESS': '\x1b[32m',    # green
-                    'WARNING': '\x1b[33m',    # yellow
-                    'ERROR': '\x1b[31m',      # red
-                    'CRITICAL': '\x1b[35m',   # magenta
+                    "TRACE": "\x1b[34m",  # blue
+                    "DEBUG": "\x1b[36m",  # cyan
+                    "INFO": "\x1b[37m",  # white
+                    "SUCCESS": "\x1b[32m",  # green
+                    "WARNING": "\x1b[33m",  # yellow
+                    "ERROR": "\x1b[31m",  # red
+                    "CRITICAL": "\x1b[35m",  # magenta
                 }
 
                 level_str = record.levelname.ljust(8)
-                level_color = level_colors.get(record.levelname, '\x1b[37m')  # default white
+                level_color = level_colors.get(record.levelname, "\x1b[37m")  # default white
                 label_part = self.label + " | " if self.label else ""
-                
+
                 # For DEBUG and TRACE levels, add module/location information
                 location_info = ""
-                if record.levelname in ['TRACE']:
+                if record.levelname in ["TRACE"]:
                     # Use caller information if available (from extra), otherwise fall back to record info
-                    if hasattr(record, 'caller_module'):
-                        module_name = record.caller_module.split('.')[-1] if record.caller_module else 'unknown'
+                    if hasattr(record, "caller_module"):
+                        module_name = record.caller_module.split(".")[-1] if record.caller_module else "unknown"
                         line_no = record.caller_lineno
                         func_name = record.caller_funcname
                     else:
-                        module_name = record.module if hasattr(record, 'module') else 'unknown'
+                        module_name = record.module if hasattr(record, "module") else "unknown"
                         line_no = record.lineno
                         func_name = record.funcName
-                    location_info = f"\x1b[90m{module_name}:{func_name}:{line_no}\x1b[0m | "  # dim gray for location info
-                
+                    location_info = (
+                        f"\x1b[90m{module_name}:{func_name}:{line_no}\x1b[0m | "  # dim gray for location info
+                    )
+
                 # Loguru-style format: <white>timestamp</white> | <level>LEVEL</level> | <location> | <cyan>label</cyan> - <level>message</level>
-                return (f"\x1b[37m{timestamp}\x1b[0m | "  # white timestamp
-                       f"{level_color}{level_str}\x1b[0m | "  # colored level
-                       f"{location_info}"  # location info for DEBUG/TRACE
-                       f"{level_color}{label_part}\x1b[0m"  # colored label
-                       f"{level_color}{record.getMessage()}\x1b[0m")  # colored message
-        
+                return (
+                    f"\x1b[37m{timestamp}\x1b[0m | "  # white timestamp
+                    f"{level_color}{level_str}\x1b[0m | "  # colored level
+                    f"{location_info}"  # location info for DEBUG/TRACE
+                    f"{level_color}{label_part}\x1b[0m"  # colored label
+                    f"{level_color}{record.getMessage()}\x1b[0m"
+                )  # colored message
+
         self.handler.setFormatter(massterFormatter(self.label))
 
     def update_sink(self, sink: Any):
@@ -210,40 +218,44 @@ class MassterLogger:
 
                 # Loguru-style colors for different log levels
                 level_colors = {
-                    'TRACE': '\x1b[34m',      # blue
-                    'DEBUG': '\x1b[36m',      # cyan
-                    'INFO': '\x1b[37m',       # white
-                    'SUCCESS': '\x1b[32m',    # green
-                    'WARNING': '\x1b[33m',    # yellow
-                    'ERROR': '\x1b[31m',      # red
-                    'CRITICAL': '\x1b[35m',   # magenta
+                    "TRACE": "\x1b[34m",  # blue
+                    "DEBUG": "\x1b[36m",  # cyan
+                    "INFO": "\x1b[37m",  # white
+                    "SUCCESS": "\x1b[32m",  # green
+                    "WARNING": "\x1b[33m",  # yellow
+                    "ERROR": "\x1b[31m",  # red
+                    "CRITICAL": "\x1b[35m",  # magenta
                 }
 
                 level_str = record.levelname.ljust(8)
-                level_color = level_colors.get(record.levelname, '\x1b[37m')  # default white
+                level_color = level_colors.get(record.levelname, "\x1b[37m")  # default white
                 label_part = self.label + " | " if self.label else ""
-                
+
                 # For DEBUG and TRACE levels, add module/location information
                 location_info = ""
-                if record.levelname in ['TRACE']:
+                if record.levelname in ["TRACE"]:
                     # Use caller information if available (from extra), otherwise fall back to record info
-                    if hasattr(record, 'caller_module'):
-                        module_name = record.caller_module.split('.')[-1] if record.caller_module else 'unknown'
+                    if hasattr(record, "caller_module"):
+                        module_name = record.caller_module.split(".")[-1] if record.caller_module else "unknown"
                         line_no = record.caller_lineno
                         func_name = record.caller_funcname
                     else:
                         module_name = record.module
                         line_no = record.lineno
                         func_name = record.funcName
-                    location_info = f"\x1b[90m{module_name}:{func_name}:{line_no}\x1b[0m | "  # dim gray for location info
-                
+                    location_info = (
+                        f"\x1b[90m{module_name}:{func_name}:{line_no}\x1b[0m | "  # dim gray for location info
+                    )
+
                 # Loguru-style format: <white>timestamp</white> | <level>LEVEL</level> | <location> | <cyan>label</cyan> - <level>message</level>
-                return (f"\x1b[37m{timestamp}\x1b[0m | "  # white timestamp
-                       f"{level_color}{level_str}\x1b[0m | "  # colored level
-                       f"{location_info}"  # location info for DEBUG/TRACE
-                       f"{level_color}{label_part}\x1b[0m"  # colored label
-                       f"{level_color}{record.getMessage()}\x1b[0m")  # colored message
-        
+                return (
+                    f"\x1b[37m{timestamp}\x1b[0m | "  # white timestamp
+                    f"{level_color}{level_str}\x1b[0m | "  # colored level
+                    f"{location_info}"  # location info for DEBUG/TRACE
+                    f"{level_color}{label_part}\x1b[0m"  # colored label
+                    f"{level_color}{record.getMessage()}\x1b[0m"
+                )  # colored message
+
         self.handler.setFormatter(massterFormatter(self.label))
         self.logger_instance.addHandler(self.handler)
 
@@ -252,36 +264,38 @@ class MassterLogger:
         """Log a TRACE level message (mapped to DEBUG)."""
         # Get caller frame information (skip this method and go to actual caller)
         import inspect
+
         frame = inspect.currentframe().f_back
-        
+
         # Add caller information as extra parameters
-        extra = kwargs.get('extra', {})
+        extra = kwargs.get("extra", {})
         extra.update({
-            'caller_module': frame.f_globals.get('__name__', 'unknown'),
-            'caller_filename': frame.f_code.co_filename,
-            'caller_lineno': frame.f_lineno,
-            'caller_funcname': frame.f_code.co_name
+            "caller_module": frame.f_globals.get("__name__", "unknown"),
+            "caller_filename": frame.f_code.co_filename,
+            "caller_lineno": frame.f_lineno,
+            "caller_funcname": frame.f_code.co_name,
         })
-        kwargs['extra'] = extra
-        
+        kwargs["extra"] = extra
+
         self.logger_instance.debug(message, *args, **kwargs)
 
     def debug(self, message: str, *args, **kwargs):
         """Log a DEBUG level message."""
         # Get caller frame information (skip this method and go to actual caller)
         import inspect
+
         frame = inspect.currentframe().f_back
-        
+
         # Add caller information as extra parameters
-        extra = kwargs.get('extra', {})
+        extra = kwargs.get("extra", {})
         extra.update({
-            'caller_module': frame.f_globals.get('__name__', 'unknown'),
-            'caller_filename': frame.f_code.co_filename,
-            'caller_lineno': frame.f_lineno,
-            'caller_funcname': frame.f_code.co_name
+            "caller_module": frame.f_globals.get("__name__", "unknown"),
+            "caller_filename": frame.f_code.co_filename,
+            "caller_lineno": frame.f_lineno,
+            "caller_funcname": frame.f_code.co_name,
         })
-        kwargs['extra'] = extra
-        
+        kwargs["extra"] = extra
+
         self.logger_instance.debug(message, *args, **kwargs)
 
     def info(self, message: str, *args, **kwargs):

masster/sample/defaults/find_features_def.py

@@ -17,102 +17,104 @@ from typing import Any
 
 @dataclass
 class find_features_defaults:
+    """Configuration defaults for the feature-finding pipeline.
+
+    This dataclass centralizes parameters used by the `find_features()` routine
+    (mass-trace detection, elution-peak detection and feature assembly).  The
+    purpose of this docstring is to explain the role and impact of the main
+    parameters users commonly tune.
+
+    Main parameters (what they mean, units and guidance):
+
+    - chrom_fwhm (float, seconds):
+        Expected chromatographic peak full-width at half-maximum (FWHM) in
+        seconds. This value informs the peak detection algorithms about the
+        typical temporal width of chromatographic peaks. It is used for
+        smoothing, window sizes when searching for local maxima and when
+        calculating RT-based tolerances. Use a value that matches your LC
+        method: smaller values for sharp, fast chromatography and larger values
+        for broader peaks. Default: 1.0 s.
+
+    - noise (float, intensity units):
+        Intensity threshold used to filter out low-intensity signals before
+        mass-trace and peak detection. Points with intensity below this
+        threshold are treated as background and typically ignored. Raising
+        `noise` reduces false positives from background fluctuations but may
+        remove low-abundance true peaks; lowering it increases sensitivity at
+        the cost of more noise. Default: 200.0 (instrument-dependent).
+
+    - chrom_peak_snr (float, unitless):
+        Minimum signal-to-noise ratio required to accept a detected
+        chromatographic peak. SNR is typically computed as peak height
+        (or crest intensity) divided by an estimate of local noise. A higher
+        `chrom_peak_snr` makes detection stricter (fewer false positives),
+        while a lower value makes detection more permissive (more low-SNR
+        peaks accepted). Typical values range from ~3 (relaxed) to >10
+        (stringent). Default: 10.0.
+
+    - isotope_filtering_model (str):
+        Isotope filtering model to use ('metabolites (2% RMS)', 'metabolites (5% RMS)',
+        'peptides', 'none'). Default: 'metabolites (5% RMS)'.
+
+    Use these three parameters together to balance sensitivity and
+    specificity for your dataset: tune `chrom_fwhm` to match chromatographic
+    peak shapes, set `noise` to a conservative background level for your
+    instrument, then adjust `chrom_peak_snr` to control how aggressively
+    peaks are accepted or rejected.
+
+    The class also contains many other configuration options (mass tolerances,
+    isotope handling, post-processing and reporting flags). See individual
+    parameter metadata (`_param_metadata`) for allowed ranges and types.
     """
-    Parameters for mass spectrometry feature detection using OpenMS algorithms.
-
-    This class consolidates all parameters used in the find_features() method including
-    mass trace detection (MTD), elution peak detection (EPD), and feature finding (FFM).
-    It provides type checking, validation, and comprehensive parameter descriptions.
-
-    Mass Trace Detection (MTD) Parameters:
-        tol_ppm: Mass error tolerance in parts-per-million for mass trace detection.
-        noise: Noise threshold intensity to filter out low-intensity signals.
-        min_trace_length_multiplier: Multiplier for minimum trace length (multiplied by chrom_fwhm_min).
-        trace_termination_outliers: Number of outliers allowed before terminating a trace.
-
-    Elution Peak Detection (EPD) Parameters:
-        chrom_fwhm: Full width at half maximum for chromatographic peak shape.
-        chrom_fwhm_min: Minimum FWHM for chromatographic peak detection.
-        chrom_peak_snr: Signal-to-noise ratio required for chromatographic peaks.
-        masstrace_snr_filtering: Whether to apply SNR filtering to mass traces.
-        mz_scoring_13C: Whether to enable scoring of 13C isotopic patterns.
-        width_filtering: Width filtering method for mass traces.
-
-    Feature Finding (FFM) Parameters:
-        remove_single_traces: Whether to remove mass traces without satellite isotopic traces.
-        report_convex_hulls: Whether to report convex hulls for features.
-        report_summed_ints: Whether to report summed intensities.
-        report_chromatograms: Whether to report chromatograms.
-
-    Post-processing Parameters:
-        deisotope: Whether to perform deisotoping of detected features.
-        deisotope_mz_tol: m/z tolerance for deisotoping.
-        deisotope_rt_tol_factor: RT tolerance factor for deisotoping (multiplied by chrom_fwhm_min/4).
-        eic_mz_tol: m/z tolerance for EIC extraction.
-        eic_rt_tol: RT tolerance for EIC extraction.
-
-    Available Methods:
-        - validate(param_name, value): Validate a single parameter value
-        - validate_all(): Validate all parameters at once
-        - to_dict(): Convert parameters to dictionary
-        - set_from_dict(param_dict, validate=True): Update multiple parameters from dict
-        - set(param_name, value, validate=True): Set parameter value with validation
-        - get(param_name): Get parameter value
-        - get_description(param_name): Get parameter description
-        - get_info(param_name): Get full parameter metadata
-        - list_parameters(): Get list of all parameter names
-    """
+
+    # Main params
+    noise: float = 200.0
+    chrom_fwhm: float = 1.0
+    chrom_peak_snr: float = 10.0
 
     # Mass Trace Detection parameters
     tol_ppm: float = 30.0
-    noise: float = 200.0
-    min_trace_length_multiplier: float = 1.0
-    trace_termination_outliers: int = 2
+    reestimate_mt_sd: bool = True
+    quant_method: str = "area"
+    trace_termination_criterion: str = "outlier"
+    trace_termination_outliers: int = 5
+    min_sample_rate: float = 0.5
+
+    min_trace_length: float = 0.5
+    min_trace_length_multiplier: float = 0.2
+    max_trace_length: float = -1.0
 
     # Elution Peak Detection parameters
-    chrom_fwhm: float = 1.0
-    chrom_fwhm_min: float = 0.5
-    chrom_peak_snr: float = 10.0
-    masstrace_snr_filtering: bool = False
-    mz_scoring_13C: bool = False
+    enabled: bool = True
+    chrom_fwhm_min: float = 0.2
+    chrom_fwhm_max: float = 60.0
     width_filtering: str = "fixed"
+    masstrace_snr_filtering: bool = False
 
     # Feature Finding parameters
+    local_rt_range: float = 1.0
+    local_mz_range: float = 5.0
+    charge_lower_bound: int = 0
+    charge_upper_bound: int = 5
+
+    report_smoothed_intensities: bool = False
     remove_single_traces: bool = False
     report_convex_hulls: bool = True
     report_summed_ints: bool = False
     report_chromatograms: bool = True
+    mz_scoring_13C: bool = False
+
+    threads: int = 1
+    no_progress: bool = False
+    debug: bool = False
 
     # Post-processing parameters
     deisotope: bool = True
     deisotope_mz_tol: float = 0.02
-    deisotope_rt_tol_factor: float = 0.25  # Will be multiplied by chrom_fwhm_min/4
-    eic_mz_tol: float = 0.01
-    eic_rt_tol: float = 10.0
+    deisotope_rt_tol_factor: float = 0.5  # Will be multiplied by chrom_fwhm
+    isotope_filtering_model: str = "metabolites (5% RMS)"
 
-    # Additional OpenMS FeatureFinderMetabo parameters
-    threads: int = 1
-    no_progress: bool = False
-    debug: bool = False
-    min_sample_rate: float = 0.5
-    min_trace_length: int = 5
-    min_fwhm: float = 1.0
-    max_fwhm: float = 60.0
-    
-    # Additional Mass Trace Detection parameters
-    trace_termination_criterion: str = "outlier"
-    reestimate_mt_sd: bool = True
-    quant_method: str = "area"
-    
-    # Additional Elution Peak Detection parameters
-    enabled: bool = True
-    
-    # Additional Feature Finding parameters
-    local_rt_range: float = 10.0
-    local_mz_range: float = 6.5
-    charge_lower_bound: int = 1
-    charge_upper_bound: int = 3
-    report_smoothed_intensities: bool = False
+    # chrom extraction parameters
 
     # Parameter metadata for validation and description
     _param_metadata: dict[str, dict[str, Any]] = field(
@@ -132,8 +134,8 @@ class find_features_defaults:
             "min_trace_length_multiplier": {
                 "dtype": float,
                 "description": "Multiplier for minimum trace length calculation (multiplied by chrom_fwhm_min)",
-                "min_value": 1.0,
-                "max_value": 10.0,
+                "min_value": 0.1,
+                "max_value": 2.0,
             },
             "trace_termination_outliers": {
                 "dtype": int,
@@ -204,17 +206,11 @@ class find_features_defaults:
                 "min_value": 0.1,
                 "max_value": 2.0,
             },
-            "eic_mz_tol": {
-                "dtype": float,
-                "description": "m/z tolerance for EIC extraction (Da)",
-                "min_value": 0.001,
-                "max_value": 0.1,
-            },
-            "eic_rt_tol": {
-                "dtype": float,
-                "description": "RT tolerance for EIC extraction (seconds)",
-                "min_value": 1.0,
-                "max_value": 60.0,
+            "isotope_filtering_model": {
+                "dtype": str,
+                "description": "Isotope filtering model",
+                "default": "metabolites (5% RMS)",
+                "allowed_values": ["metabolites (2% RMS)", "metabolites (5% RMS)", "peptides", "none"],
             },
             "threads": {
                 "dtype": int,
@@ -242,13 +238,13 @@ class find_features_defaults:
                 "min_value": 2,
                 "max_value": 100,
             },
-            "min_fwhm": {
+            """            "min_fwhm": {
                 "dtype": float,
                 "description": "Minimum full width at half maximum for peaks (seconds)",
                 "min_value": 0.1,
                 "max_value": 10.0,
-            },
-            "max_fwhm": {
+            },"""
+            "chrom_fwhm_max": {
                 "dtype": float,
                 "description": "Maximum full width at half maximum for peaks (seconds)",
                 "min_value": 1.0,

masster/sample/defaults/sample_def.py

@@ -54,6 +54,9 @@ class sample_defaults:
     max_points_per_spectrum: int = 50000
     dia_window: float | None = None
 
+    eic_mz_tol: float = 0.01
+    eic_rt_tol: float = 10.0
+
     _param_metadata: dict[str, dict[str, Any]] = field(
         default_factory=lambda: {
             "filename": {
@@ -163,6 +166,18 @@ class sample_defaults:
                 "default": None,
                 "min_value": 0.0,
             },
+            "eic_mz_tol": {
+                "dtype": float,
+                "description": "m/z tolerance for EIC extraction (Da)",
+                "min_value": 0.001,
+                "max_value": 1.0,
+            },
+            "eic_rt_tol": {
+                "dtype": float,
+                "description": "RT tolerance for EIC extraction (seconds)",
+                "min_value": 0.2,
+                "max_value": 60.0,
+            },
         },
         repr=False,
     )

masster/sample/h5.py

@@ -294,13 +294,13 @@ def _load_sample5(self, filename: str, map: bool = True):
         if "metadata" in f:
             metadata_group = f["metadata"]
             self.file_path = decode_metadata_attr(metadata_group.attrs.get("file_path", ""))
-            
+
             # Load file_source if it exists, otherwise set it equal to file_path
             if "file_source" in metadata_group.attrs:
                 self.file_source = decode_metadata_attr(metadata_group.attrs.get("file_source", ""))
             else:
                 self.file_source = self.file_path
-            
+
             self.file_type = decode_metadata_attr(metadata_group.attrs.get("file_type", ""))
             self.label = decode_metadata_attr(metadata_group.attrs.get("label", ""))