Add validation utilities and extract filter validation

Author: sanketsabharwal

pyeyesweb/utils/signal_processing.py

@@ -8,6 +8,50 @@
 from scipy.signal import hilbert, butter, filtfilt
 
 
+def validate_filter_params(lowcut, highcut, fs):
+    """Validate filter frequency parameters.
+
+    Centralized validation for filter parameters used in bandpass_filter
+    and Synchronization class.
+
+    Parameters
+    ----------
+    lowcut : float
+        Low cutoff frequency in Hz
+    highcut : float
+        High cutoff frequency in Hz
+    fs : float
+        Sampling frequency in Hz
+
+    Returns
+    -------
+    tuple
+        Validated (lowcut, highcut, fs)
+
+    Raises
+    ------
+    ValueError
+        If parameters are invalid
+    """
+    # Validate individual parameters
+    if fs <= 0:
+        raise ValueError(f"Sampling frequency must be positive, got {fs}")
+    if lowcut <= 0:
+        raise ValueError(f"Low cutoff frequency must be positive, got {lowcut}")
+    if highcut <= 0:
+        raise ValueError(f"High cutoff frequency must be positive, got {highcut}")
+
+    # Validate relationships
+    if lowcut >= highcut:
+        raise ValueError(f"Low cutoff ({lowcut}) must be less than high cutoff ({highcut})")
+
+    nyquist = fs / 2
+    if highcut >= nyquist:
+        raise ValueError(f"High cutoff ({highcut}) must be less than Nyquist frequency ({nyquist})")
+
+    return lowcut, highcut, fs
+
+
 def bandpass_filter(data, filter_params):
     """Apply a band-pass filter if filter_params is set.
 
@@ -36,22 +80,10 @@ def bandpass_filter(data, filter_params):
     if filter_params is None:
         return data
 
-    lowcut, highcut, fs = filter_params
-
-    # Validate filter parameters
-    if fs <= 0:
-        raise ValueError(f"Sampling frequency must be positive, got {fs}")
-    if lowcut <= 0:
-        raise ValueError(f"Low cutoff frequency must be positive, got {lowcut}")
-    if highcut <= 0:
-        raise ValueError(f"High cutoff frequency must be positive, got {highcut}")
-    if lowcut >= highcut:
-        raise ValueError(f"Low cutoff ({lowcut}) must be less than high cutoff ({highcut})")
+    # Use centralized validation
+    lowcut, highcut, fs = validate_filter_params(*filter_params)
 
     nyquist = 0.5 * fs
-    if highcut >= nyquist:
-        raise ValueError(f"High cutoff ({highcut}) must be less than Nyquist frequency ({nyquist})")
-
     low = lowcut / nyquist
     high = highcut / nyquist
 

pyeyesweb/utils/validators.py

@@ -0,0 +1,168 @@
+"""Validation utilities for PyEyesWeb.
+
+This module provides common validation functions used across multiple
+PyEyesWeb modules to ensure consistent error handling.
+"""
+
+
+def validate_numeric(value, name, min_val=None, max_val=None):
+    """Validate numeric parameter with optional bounds checking.
+
+    Parameters
+    ----------
+    value : any
+        Value to validate
+    name : str
+        Parameter name for error messages
+    min_val : float, optional
+        Minimum allowed value (inclusive)
+    max_val : float, optional
+        Maximum allowed value (inclusive)
+
+    Returns
+    -------
+    float
+        Validated numeric value as float
+
+    Raises
+    ------
+    TypeError
+        If value is not numeric (int or float)
+    ValueError
+        If value is outside specified bounds
+
+    Examples
+    --------
+    >>> validate_numeric(50.0, 'rate_hz', min_val=0.1, max_val=100000)
+    50.0
+    >>> validate_numeric(-1, 'phase', min_val=0, max_val=1)
+    ValueError: phase must be >= 0, got -1
+    """
+    if not isinstance(value, (int, float)):
+        raise TypeError(f"{name} must be a number, got {type(value).__name__}")
+
+    value = float(value)
+
+    if min_val is not None and value < min_val:
+        raise ValueError(f"{name} must be >= {min_val}, got {value}")
+
+    if max_val is not None and value > max_val:
+        raise ValueError(f"{name} must be <= {max_val}, got {value}")
+
+    return value
+
+
+def validate_integer(value, name, min_val=None, max_val=None):
+    """Validate integer parameter with optional bounds checking.
+
+    Parameters
+    ----------
+    value : any
+        Value to validate
+    name : str
+        Parameter name for error messages
+    min_val : int, optional
+        Minimum allowed value (inclusive)
+    max_val : int, optional
+        Maximum allowed value (inclusive)
+
+    Returns
+    -------
+    int
+        Validated integer value
+
+    Raises
+    ------
+    TypeError
+        If value is not an integer
+    ValueError
+        If value is outside specified bounds
+
+    Examples
+    --------
+    >>> validate_integer(100, 'sensitivity', min_val=1, max_val=10000)
+    100
+    >>> validate_integer(0, 'max_length', min_val=1)
+    ValueError: max_length must be >= 1, got 0
+    """
+    if not isinstance(value, int):
+        raise TypeError(f"{name} must be an integer, got {type(value).__name__}")
+
+    if min_val is not None and value < min_val:
+        raise ValueError(f"{name} must be >= {min_val}, got {value}")
+
+    if max_val is not None and value > max_val:
+        raise ValueError(f"{name} must be <= {max_val}, got {value}")
+
+    return value
+
+
+def validate_boolean(value, name):
+    """Validate boolean parameter.
+
+    Parameters
+    ----------
+    value : any
+        Value to validate
+    name : str
+        Parameter name for error messages
+
+    Returns
+    -------
+    bool
+        Validated boolean value
+
+    Raises
+    ------
+    TypeError
+        If value is not a boolean
+
+    Examples
+    --------
+    >>> validate_boolean(True, 'use_filter')
+    True
+    >>> validate_boolean(1, 'output_phase')
+    TypeError: output_phase must be boolean, got int
+    """
+    if not isinstance(value, bool):
+        raise TypeError(f"{name} must be boolean, got {type(value).__name__}")
+    return value
+
+
+def validate_range(value, name, min_val, max_val):
+    """Validate that a value is within a specific range.
+
+    Useful for parameters that must be within a specific range like
+    phase_threshold (0-1), percentages (0-100), etc.
+
+    Parameters
+    ----------
+    value : float or int
+        Value to validate
+    name : str
+        Parameter name for error messages
+    min_val : float
+        Minimum allowed value (inclusive)
+    max_val : float
+        Maximum allowed value (inclusive)
+
+    Returns
+    -------
+    float
+        Validated value
+
+    Raises
+    ------
+    ValueError
+        If value is outside the specified range
+
+    Examples
+    --------
+    >>> validate_range(0.7, 'phase_threshold', 0, 1)
+    0.7
+    >>> validate_range(1.5, 'probability', 0, 1)
+    ValueError: probability must be between 0 and 1, got 1.5
+    """
+    if not min_val <= value <= max_val:
+        raise ValueError(f"{name} must be between {min_val} and {max_val}, got {value}")
+    return value