oscura 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

oscura/inference/spectral.py

@@ -75,84 +75,126 @@ def auto_spectral_config(
     # Analyze signal stationarity
     stationarity_score = _assess_stationarity(trace.data)
 
-    # Determine method based on stationarity
+    # Select method and window based on signal characteristics
+    method, method_rationale = _select_spectral_method(stationarity_score)
+    window, window_rationale = _select_window_function(dynamic_range_db)
+
+    # Build rationale if requested
+    rationale = f"{method_rationale} {window_rationale}" if log_rationale else ""
+
+    # Calculate segment sizes and FFT parameters
+    n_samples = len(trace.data)
+    sample_rate = trace.metadata.sample_rate
+    nperseg = _calculate_segment_size(target_resolution, stationarity_score, n_samples, sample_rate)
+    noverlap = _calculate_overlap(method, nperseg)
+    nfft = 2 ** int(np.ceil(np.log2(nperseg)))
+
+    # Build configuration dictionary
+    config = {
+        "method": method,
+        "window": window,
+        "nperseg": nperseg,
+        "noverlap": noverlap,
+        "nfft": nfft,
+        "stationarity_score": stationarity_score,
+    }
+
+    if log_rationale:
+        config["rationale"] = rationale
+
+    return config
+
+
+def _select_spectral_method(stationarity_score: float) -> tuple[str, str]:
+    """Select spectral method based on stationarity score.
+
+    Args:
+        stationarity_score: Signal stationarity score (0-1).
+
+    Returns:
+        Tuple of (method_name, rationale).
+    """
     if stationarity_score > 0.8:
-        # Stationary - can use simpler methods
-        method = "bartlett"
-        rationale = f"Signal is stationary (score={stationarity_score:.2f}). Bartlett method provides good variance reduction."
+        return (
+            "bartlett",
+            f"Signal is stationary (score={stationarity_score:.2f}). "
+            "Bartlett method provides good variance reduction.",
+        )
     elif stationarity_score > 0.5:
-        # Moderately stationary - Welch is safest
-        method = "welch"
-        rationale = f"Signal is moderately stationary (score={stationarity_score:.2f}). Welch method with overlap for variance reduction."
+        return (
+            "welch",
+            f"Signal is moderately stationary (score={stationarity_score:.2f}). "
+            "Welch method with overlap for variance reduction.",
+        )
     else:
-        # Non-stationary - need time-frequency analysis or careful windowing
-        method = "welch"
-        rationale = f"Signal is non-stationary (score={stationarity_score:.2f}). Welch method with short segments to track changes."
+        return (
+            "welch",
+            f"Signal is non-stationary (score={stationarity_score:.2f}). "
+            "Welch method with short segments to track changes.",
+        )
+
+
+def _select_window_function(dynamic_range_db: float) -> tuple[str, str]:
+    """Select window function based on dynamic range requirements.
+
+    Args:
+        dynamic_range_db: Required dynamic range in dB.
 
-    # Select window function based on dynamic range requirements
+    Returns:
+        Tuple of (window_name, rationale).
+    """
     if dynamic_range_db > 80:
-        window = "blackman-harris"
-        window_rationale = "Blackman-Harris window for high dynamic range (>80 dB)"
+        return "blackman-harris", "Blackman-Harris window for high dynamic range (>80 dB)"
     elif dynamic_range_db > 60:
-        window = "blackman"
-        window_rationale = "Blackman window for good dynamic range (60-80 dB)"
+        return "blackman", "Blackman window for good dynamic range (60-80 dB)"
     elif dynamic_range_db > 40:
-        window = "hamming"
-        window_rationale = "Hamming window for moderate dynamic range (40-60 dB)"
+        return "hamming", "Hamming window for moderate dynamic range (40-60 dB)"
     else:
-        window = "hann"
-        window_rationale = "Hann window for general purpose (<40 dB)"
+        return "hann", "Hann window for general purpose (<40 dB)"
 
-    if log_rationale:
-        rationale += " " + window_rationale
 
-    # Determine segment size
-    n_samples = len(trace.data)
-    sample_rate = trace.metadata.sample_rate
+def _calculate_segment_size(
+    target_resolution: float | None,
+    stationarity_score: float,
+    n_samples: int,
+    sample_rate: float,
+) -> int:
+    """Calculate segment size for spectral analysis.
+
+    Args:
+        target_resolution: Target frequency resolution in Hz or None.
+        stationarity_score: Signal stationarity score (0-1).
+        n_samples: Number of samples in signal.
+        sample_rate: Sample rate in Hz.
 
+    Returns:
+        Segment size (nperseg).
+    """
     if target_resolution is not None:
-        # User specified resolution
         nperseg = int(sample_rate / target_resolution)
-        # Round to next power of 2 for efficiency
         nperseg = 2 ** int(np.ceil(np.log2(nperseg)))
-    # Auto-select based on signal length and stationarity
     elif stationarity_score > 0.8:
-        # Stationary - can use longer segments
-        nperseg = min(n_samples, 2**14)  # Up to 16k samples
+        nperseg = min(n_samples, 2**14)
     else:
-        # Non-stationary - shorter segments
-        nperseg = min(n_samples // 8, 2**12)  # Up to 4k samples
+        nperseg = min(n_samples // 8, 2**12)
 
-    # Ensure nperseg is reasonable
-    nperseg = max(256, min(nperseg, n_samples // 2))
+    return max(256, min(nperseg, n_samples // 2))
 
-    # Determine overlap
-    if method == "welch":
-        # Welch typically uses 50% overlap
-        noverlap = nperseg // 2
-    elif method == "bartlett":
-        # Bartlett uses no overlap
-        noverlap = 0
-    else:
-        # Periodogram doesn't use segments
-        noverlap = 0
 
-    # FFT size (usually same as segment size or next power of 2)
-    nfft = 2 ** int(np.ceil(np.log2(nperseg)))
+def _calculate_overlap(method: str, nperseg: int) -> int:
+    """Calculate overlap for spectral method.
 
-    config = {
-        "method": method,
-        "window": window,
-        "nperseg": nperseg,
-        "noverlap": noverlap,
-        "nfft": nfft,
-        "stationarity_score": stationarity_score,
-    }
-
-    if log_rationale:
-        config["rationale"] = rationale
+    Args:
+        method: Spectral method name.
+        nperseg: Segment size.
 
-    return config
+    Returns:
+        Overlap size in samples.
+    """
+    if method == "welch":
+        return nperseg // 2
+    else:
+        return 0
 
 
 def _assess_stationarity(data: NDArray[np.floating[Any]]) -> float: