oscura 0.6.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

oscura/analyzers/power/__init__.py

@@ -1,12 +1,13 @@
-"""Power analysis module for Oscura.
+"""Power analysis module for Oscura - IEEE 1459-2010 compliant.
 
 Provides comprehensive power analysis capabilities including:
-- Basic power measurements (instantaneous, average, RMS, peak)
-- AC power analysis (reactive, apparent, power factor)
+- Basic power measurements (instantaneous, average, RMS, peak) per IEEE 1459
+- AC power analysis (reactive, apparent, power factor, harmonics) per IEEE 1459
 - Switching loss analysis for power electronics
+- Conduction loss analysis (MOSFET, IGBT, diode)
 - Safe Operating Area (SOA) analysis
-- Ripple measurement
-- Efficiency calculations
+- Ripple measurement and analysis
+- Efficiency calculations (single and multi-output)
 
 
 Example:
@@ -14,6 +15,9 @@ Example:
     >>> power_trace = instantaneous_power(voltage_trace, current_trace)
     >>> stats = power_statistics(power_trace)
     >>> print(f"Average power: {stats['average']:.2f} W")
+
+References:
+    IEEE 1459-2010: Standard for Power Quality Definitions
 """
 
 from oscura.analyzers.power.ac_power import (
@@ -23,6 +27,7 @@ from oscura.analyzers.power.ac_power import (
     phase_angle,
     power_factor,
     reactive_power,
+    three_phase_power,
     total_harmonic_distortion_power,
 )
 from oscura.analyzers.power.basic import (
@@ -30,39 +35,51 @@ from oscura.analyzers.power.basic import (
     energy,
     instantaneous_power,
     peak_power,
+    power_profile,
     power_statistics,
     rms_power,
 )
 from oscura.analyzers.power.conduction import (
     conduction_loss,
+    diode_conduction_loss,
     duty_cycle_weighted_loss,
     forward_voltage,
+    igbt_conduction_loss,
     mosfet_conduction_loss,
     on_resistance,
+    temperature_derating,
 )
 from oscura.analyzers.power.efficiency import (
     efficiency,
+    efficiency_vs_load,
+    loss_breakdown,
     multi_output_efficiency,
     power_conversion_efficiency,
+    thermal_efficiency,
 )
 from oscura.analyzers.power.ripple import (
     extract_ripple,
     ripple,
+    ripple_envelope,
     ripple_frequency,
+    ripple_harmonics,
     ripple_percentage,
     ripple_statistics,
 )
 from oscura.analyzers.power.soa import (
     SOALimit,
+    SOAViolation,
     check_soa_violations,
     create_mosfet_soa,
     plot_soa,
     soa_analysis,
 )
 from oscura.analyzers.power.switching import (
+    SwitchingEvent,
     switching_energy,
     switching_frequency,
     switching_loss,
+    switching_times,
     total_switching_loss,
     turn_off_loss,
     turn_on_loss,
@@ -70,22 +87,25 @@ from oscura.analyzers.power.switching import (
 
 __all__ = [
     "SOALimit",
+    "SOAViolation",
+    "SwitchingEvent",
     "apparent_power",
     "average_power",
     "check_soa_violations",
-    # Conduction
     "conduction_loss",
     "create_mosfet_soa",
+    "diode_conduction_loss",
     "displacement_power_factor",
     "distortion_power_factor",
     "duty_cycle_weighted_loss",
-    # Efficiency
     "efficiency",
+    "efficiency_vs_load",
     "energy",
     "extract_ripple",
     "forward_voltage",
-    # Basic power
+    "igbt_conduction_loss",
     "instantaneous_power",
+    "loss_breakdown",
     "mosfet_conduction_loss",
     "multi_output_efficiency",
     "on_resistance",
@@ -94,21 +114,24 @@ __all__ = [
     "plot_soa",
     "power_conversion_efficiency",
     "power_factor",
+    "power_profile",
     "power_statistics",
-    # AC power
     "reactive_power",
-    # Ripple
     "ripple",
+    "ripple_envelope",
     "ripple_frequency",
+    "ripple_harmonics",
     "ripple_percentage",
     "ripple_statistics",
     "rms_power",
-    # SOA
     "soa_analysis",
     "switching_energy",
     "switching_frequency",
-    # Switching
     "switching_loss",
+    "switching_times",
+    "temperature_derating",
+    "thermal_efficiency",
+    "three_phase_power",
     "total_harmonic_distortion_power",
     "total_switching_loss",
     "turn_off_loss",

oscura/analyzers/statistics/__init__.py

@@ -20,11 +20,13 @@ from oscura.analyzers.statistics.advanced import (
 )
 from oscura.analyzers.statistics.basic import (
     basic_stats,
+    measure,
     percentiles,
     quartiles,
     running_stats,
     summary_stats,
     weighted_mean,
+    weighted_std,
 )
 from oscura.analyzers.statistics.correlation import (
     CrossCorrelationResult,
@@ -99,6 +101,7 @@ __all__ = [
     "kernel_density",
     # Advanced (STAT-012)
     "local_outlier_factor",
+    "measure",
     "modified_zscore_outliers",
     "moment",
     "moving_average",
@@ -114,6 +117,7 @@ __all__ = [
     "seasonal_decompose",
     "summary_stats",
     "weighted_mean",
+    "weighted_std",
     # Outlier detection
     "zscore_outliers",
 ]

oscura/analyzers/statistics/basic.py

@@ -171,6 +171,75 @@ def weighted_mean(
     return float(np.average(data, weights=weights))
 
 
+def weighted_std(
+    trace: WaveformTrace | NDArray[np.floating[Any]],
+    weights: NDArray[np.floating[Any]] | None = None,
+    *,
+    ddof: int = 0,
+) -> float:
+    """Compute weighted standard deviation.
+
+    Uses the reliability weights formula for weighted variance.
+
+    Args:
+        trace: Input trace or numpy array.
+        weights: Weight array (same length as data). If None, equal weights (unweighted std).
+        ddof: Delta degrees of freedom for bias correction (default 0).
+            - ddof=0: Maximum likelihood estimate (biased)
+            - ddof=1: Sample standard deviation (unbiased for normal distribution)
+
+    Returns:
+        Weighted standard deviation.
+
+    Raises:
+        ValueError: If weights and data have different lengths.
+        ValueError: If weights contain negative values.
+
+    Example:
+        >>> weights = np.linspace(0.5, 1.0, len(trace.data))
+        >>> wstd = weighted_std(trace, weights)
+        >>> print(f"Weighted std: {wstd:.6f}")
+
+        >>> # Sample standard deviation (Bessel's correction)
+        >>> wstd_unbiased = weighted_std(trace, weights, ddof=1)
+
+    References:
+        Wikipedia: Weighted arithmetic mean
+        https://en.wikipedia.org/wiki/Weighted_arithmetic_mean#Weighted_sample_variance
+    """
+    data = trace.data if isinstance(trace, WaveformTrace) else trace
+
+    if weights is None:
+        return float(np.std(data, ddof=ddof))
+
+    if len(weights) != len(data):
+        raise ValueError(f"Weights and data must have same length: {len(weights)} != {len(data)}")
+
+    if np.any(weights < 0):
+        raise ValueError("Weights must be non-negative")
+
+    # Handle edge cases
+    if len(data) == 0:
+        return float("nan")
+
+    if len(data) == 1:
+        return 0.0
+
+    # Compute weighted mean
+    w_sum = np.sum(weights)
+    if w_sum <= 0:
+        return float("nan")
+
+    w_mean = np.sum(weights * data) / w_sum
+
+    # Compute weighted variance with bias correction
+    # Reliability weights formula: var = sum(w * (x - mean)^2) / (sum(w) - ddof)
+    weighted_sq_deviations = weights * (data - w_mean) ** 2
+    variance = np.sum(weighted_sq_deviations) / (w_sum - ddof) if w_sum > ddof else 0.0
+
+    return float(np.sqrt(max(0.0, variance)))
+
+
 def running_stats(
     trace: WaveformTrace | NDArray[np.floating[Any]],
     window_size: int,
@@ -253,11 +322,91 @@ def summary_stats(
     return basic
 
 
+def measure(
+    trace: WaveformTrace | NDArray[np.floating[Any]],
+    *,
+    parameters: list[str] | None = None,
+    include_units: bool = True,
+) -> dict[str, Any]:
+    """Compute statistical measurements with consistent format.
+
+    Unified function matching the API pattern of waveform.measure() and spectral.measure().
+    Returns measurements with units for easy formatting and display.
+
+    Args:
+        trace: Input trace or numpy array.
+        parameters: List of measurement names to compute. If None, compute all.
+            Valid names: mean, variance, std, min, max, range, count, p1, p5, p25, p50, p75, p95, p99
+        include_units: If True, return {value, unit} dicts. If False, return flat values.
+
+    Returns:
+        Dictionary mapping measurement names to values (with units if requested).
+
+    Example:
+        >>> from oscura.analyzers.statistics import measure
+        >>> results = measure(trace)
+        >>> print(f"Mean: {results['mean']['value']} {results['mean']['unit']}")
+        >>> print(f"Std: {results['std']['value']} {results['std']['unit']}")
+
+        >>> # Get specific measurements only
+        >>> results = measure(trace, parameters=["mean", "std"])
+
+        >>> # Get flat values without units
+        >>> results = measure(trace, include_units=False)
+        >>> mean_value = results["mean"]  # Just the float
+    """
+    data = trace.data if isinstance(trace, WaveformTrace) else trace
+
+    # Define unit mappings for statistical measurements
+    # For generic signals we use voltage units, but this could be parameterized
+    unit_map = {
+        "mean": "V",
+        "variance": "V²",
+        "std": "V",
+        "min": "V",
+        "max": "V",
+        "range": "dimensionless",
+        "count": "samples",
+        "p1": "dimensionless",
+        "p5": "dimensionless",
+        "p25": "dimensionless",
+        "p50": "dimensionless",
+        "p75": "dimensionless",
+        "p95": "dimensionless",
+        "p99": "dimensionless",
+    }
+
+    # Get basic stats
+    basic = basic_stats(trace)
+
+    # Get percentiles
+    percentile_values = percentiles(data, [1, 5, 25, 50, 75, 95, 99])
+
+    # Combine into single dict
+    all_measurements = {**basic, **percentile_values}
+
+    # Select requested measurements or all
+    if parameters is not None:
+        all_measurements = {k: v for k, v in all_measurements.items() if k in parameters}
+
+    # Format results
+    if include_units:
+        results = {}
+        for name, value in all_measurements.items():
+            unit = unit_map.get(name, "")
+            results[name] = {"value": value, "unit": unit}
+        return results
+    else:
+        return all_measurements
+
+
 __all__ = [
     "basic_stats",
+    "measure",
     "percentiles",
     "quartiles",
     "running_stats",
     "summary_stats",
     "weighted_mean",
+    "weighted_std",
 ]

oscura/analyzers/statistics/correlation.py

@@ -338,24 +338,48 @@ def cross_correlation(
 def correlation_coefficient(
     trace1: WaveformTrace | NDArray[np.floating[Any]],
     trace2: WaveformTrace | NDArray[np.floating[Any]],
+    *,
+    method: Literal["pearson", "spearman", "kendall"] = "pearson",
 ) -> float:
-    """Compute Pearson correlation coefficient between two signals.
+    """Compute correlation coefficient between two signals.
 
-    Simple measure of linear relationship between signals at zero lag.
+    Supports Pearson (linear), Spearman (monotonic), and Kendall (rank) correlations.
 
     Args:
         trace1: First input trace or numpy array.
         trace2: Second input trace or numpy array.
+        method: Correlation method to use:
+            - "pearson": Linear correlation (default, parametric)
+            - "spearman": Monotonic correlation (non-parametric, robust to outliers)
+            - "kendall": Rank correlation (non-parametric, tau-b coefficient)
 
     Returns:
         Correlation coefficient in range [-1, 1].
 
+    Raises:
+        ValueError: If method is not one of the supported types.
+
     Example:
+        >>> # Linear correlation (default)
         >>> r = correlation_coefficient(trace1, trace2)
-        >>> print(f"Correlation: {r:.3f}")
+        >>> print(f"Pearson correlation: {r:.3f}")
+
+        >>> # Monotonic correlation (robust to outliers)
+        >>> rho = correlation_coefficient(trace1, trace2, method="spearman")
+        >>> print(f"Spearman correlation: {rho:.3f}")
+
+        >>> # Rank correlation (best for ordinal data)
+        >>> tau = correlation_coefficient(trace1, trace2, method="kendall")
+        >>> print(f"Kendall correlation: {tau:.3f}")
+
+    References:
+        Pearson, K. (1895). Correlation coefficient
+        Spearman, C. (1904). Rank correlation
+        Kendall, M. G. (1938). Tau rank correlation
     """
-    data1 = trace1.data if isinstance(trace1, WaveformTrace) else trace1
+    from scipy import stats as sp_stats
 
+    data1 = trace1.data if isinstance(trace1, WaveformTrace) else trace1
     data2 = trace2.data if isinstance(trace2, WaveformTrace) else trace2
 
     # Ensure same length
@@ -363,8 +387,25 @@ def correlation_coefficient(
     data1 = data1[:n]
     data2 = data2[:n]
 
-    # Compute correlation
-    return float(np.corrcoef(data1, data2)[0, 1])
+    # Compute correlation based on method
+    if method == "pearson":
+        # Pearson linear correlation (parametric)
+        return float(np.corrcoef(data1, data2)[0, 1])
+
+    elif method == "spearman":
+        # Spearman rank correlation (non-parametric, monotonic)
+        corr, _p_value = sp_stats.spearmanr(data1, data2)
+        return float(corr)
+
+    elif method == "kendall":
+        # Kendall tau-b rank correlation (non-parametric)
+        corr, _p_value = sp_stats.kendalltau(data1, data2)
+        return float(corr)
+
+    else:
+        raise ValueError(
+            f"Unknown correlation method: {method}. Available: 'pearson', 'spearman', 'kendall'"
+        )
 
 
 def _extract_periodicity_data(

oscura/analyzers/waveform/__init__.py

@@ -4,6 +4,7 @@ Provides timing and amplitude measurements for analog waveforms.
 """
 
 from oscura.analyzers.waveform.measurements import (
+    MEASUREMENT_METADATA,
     amplitude,
     duty_cycle,
     fall_time,
@@ -20,6 +21,7 @@ from oscura.analyzers.waveform.measurements import (
 )
 
 __all__ = [
+    "MEASUREMENT_METADATA",
     "amplitude",
     "duty_cycle",
     "fall_time",

oscura/analyzers/waveform/measurements.py

@@ -28,6 +28,47 @@ if TYPE_CHECKING:
     from oscura.core.types import WaveformTrace
 
 
+# Measurement metadata: unit information for all waveform measurements
+MEASUREMENT_METADATA: dict[str, dict[str, str]] = {
+    # Time-domain measurements
+    "rise_time": {"unit": "s", "description": "Rise time (10%-90%)"},
+    "fall_time": {"unit": "s", "description": "Fall time (90%-10%)"},
+    "period": {"unit": "s", "description": "Signal period"},
+    "pulse_width": {"unit": "s", "description": "Pulse width"},
+    "jitter": {"unit": "s", "description": "Period jitter"},
+    # Frequency measurements
+    "frequency": {"unit": "Hz", "description": "Signal frequency"},
+    "clock_frequency": {"unit": "Hz", "description": "Clock frequency"},
+    "dominant_freq": {"unit": "Hz", "description": "Dominant frequency"},
+    # Voltage measurements
+    "amplitude": {"unit": "V", "description": "Peak-to-peak amplitude"},
+    "mean": {"unit": "V", "description": "Mean voltage"},
+    "rms": {"unit": "V", "description": "RMS voltage"},
+    "threshold": {"unit": "V", "description": "Logic threshold"},
+    "min": {"unit": "V", "description": "Minimum voltage"},
+    "max": {"unit": "V", "description": "Maximum voltage"},
+    "std": {"unit": "V", "description": "Standard deviation"},
+    "median": {"unit": "V", "description": "Median voltage"},
+    # Ratio measurements (0-1, displayed as percentage)
+    "duty_cycle": {"unit": "ratio", "description": "Duty cycle"},
+    # Percentage measurements (already 0-100)
+    "overshoot": {"unit": "%", "description": "Overshoot percentage"},
+    "undershoot": {"unit": "%", "description": "Undershoot percentage"},
+    "thd": {"unit": "%", "description": "Total harmonic distortion"},
+    # Decibel measurements
+    "snr": {"unit": "dB", "description": "Signal-to-noise ratio"},
+    "sinad": {"unit": "dB", "description": "SINAD"},
+    "sfdr": {"unit": "dB", "description": "Spurious-free dynamic range"},
+    # Dimensionless measurements
+    "enob": {"unit": "", "description": "Effective number of bits"},
+    "rising_edges": {"unit": "", "description": "Rising edge count"},
+    "falling_edges": {"unit": "", "description": "Falling edge count"},
+    "outliers": {"unit": "", "description": "Outlier count"},
+    # Statistical measurements (squared units)
+    "variance": {"unit": "V²", "description": "Variance"},
+}
+
+
 def rise_time(
     trace: WaveformTrace,
     *,
@@ -255,12 +296,14 @@ def frequency(
     """Measure signal frequency.
 
     Computes frequency either from edge-to-edge period or using FFT.
+    The "edge" method automatically falls back to FFT if edge detection fails
+    (e.g., for sine or triangle waves without clear rising edges).
 
     Args:
         trace: Input waveform trace.
         method: Measurement method:
-            - "edge": 1/period from edge timing (default, more accurate)
-            - "fft": Peak of FFT magnitude spectrum
+            - "edge": 1/period from edge timing with automatic FFT fallback (default)
+            - "fft": Peak of FFT magnitude spectrum (always use FFT)
 
     Returns:
         Frequency in Hz, or np.nan if measurement not possible.
@@ -272,32 +315,65 @@ def frequency(
         >>> f = frequency(trace)
         >>> print(f"Frequency: {f / 1e6:.3f} MHz")
 
+        >>> # Force FFT method for smooth waveforms
+        >>> f = frequency(trace, method="fft")
+
     References:
         IEEE 181-2011 Section 5.3
     """
     if method == "edge":
+        # Try edge detection first (faster and more accurate for square waves)
         T = period(trace, edge_type="rising", return_all=False)
+
+        # Fall back to FFT if edge detection fails
         if np.isnan(T) or T <= 0:
-            return np.nan
+            # Try FFT fallback for smooth waveforms (sine, triangle)
+            return _frequency_fft(trace)
+
         return 1.0 / T
 
     elif method == "fft":
-        if len(trace.data) < 16:
-            return np.nan
+        return _frequency_fft(trace)
+
+    else:
+        raise ValueError(f"Unknown method: {method}")
 
-        data = trace.data - np.mean(trace.data)  # Remove DC
-        n = len(data)
-        fft_mag = np.abs(np.fft.rfft(data))
 
-        # Find peak (skip DC component)
-        peak_idx = np.argmax(fft_mag[1:]) + 1
+def _frequency_fft(trace: WaveformTrace) -> float | np_floating[Any]:
+    """Compute frequency using FFT peak detection.
 
-        # Calculate frequency
-        freq_resolution = trace.metadata.sample_rate / n
-        return float(peak_idx * freq_resolution)
+    Internal helper function for FFT-based frequency measurement.
 
-    else:
-        raise ValueError(f"Unknown method: {method}")
+    Args:
+        trace: Input waveform trace.
+
+    Returns:
+        Frequency in Hz, or np.nan if measurement not possible.
+    """
+    if len(trace.data) < 16:
+        return np.nan
+
+    # Remove DC offset before FFT
+    data = trace.data - np.mean(trace.data)
+
+    # Check if signal is essentially constant (DC only)
+    if np.std(data) < 1e-10:
+        return np.nan
+
+    n = len(data)
+    fft_mag = np.abs(np.fft.rfft(data))
+
+    # Find peak (skip DC component at index 0)
+    peak_idx = np.argmax(fft_mag[1:]) + 1
+
+    # Verify peak is significant (SNR check)
+    # If the peak is not at least 3x the mean, it's likely noise
+    if fft_mag[peak_idx] < 3.0 * np.mean(fft_mag[1:]):
+        return np.nan
+
+    # Calculate frequency from peak index
+    freq_resolution = trace.metadata.sample_rate / n
+    return float(peak_idx * freq_resolution)
 
 
 def duty_cycle(
@@ -308,13 +384,17 @@ def duty_cycle(
     """Measure duty cycle.
 
     Computes duty cycle as the ratio of positive pulse width to period.
+    Uses robust algorithm that handles extreme duty cycles (1%-99%) and
+    incomplete waveforms (fewer than 2 complete cycles visible).
+
+    Falls back to time-domain calculation when edge-based measurement fails.
 
     Args:
         trace: Input waveform trace.
         percentage: If True, return as percentage (0-100). If False, return ratio (0-1).
 
     Returns:
-        Duty cycle as ratio or percentage.
+        Duty cycle as ratio or percentage, or np.nan if measurement not possible.
 
     Example:
         >>> dc = duty_cycle(trace, percentage=True)
@@ -323,13 +403,49 @@ def duty_cycle(
     References:
         IEEE 181-2011 Section 5.4
     """
+    # Strategy: Use multiple methods depending on what edges are available
+    # Method 1 (best): period + pulse width (needs 2+ rising edges, 1+ falling edge)
+    # Method 2 (fallback): time-based calculation from data samples
+
     pw_pos = pulse_width(trace, polarity="positive", return_all=False)
     T = period(trace, edge_type="rising", return_all=False)
 
-    if np.isnan(pw_pos) or np.isnan(T) or T <= 0:
+    # Method 1: Standard period-based calculation
+    if not np.isnan(pw_pos) and not np.isnan(T) and T > 0:
+        dc = pw_pos / T
+        if percentage:
+            return dc * 100
+        return dc
+
+    # Method 2: Fallback for incomplete waveforms - time-domain calculation
+    # Calculate fraction of time signal spends above midpoint threshold
+    data = trace.data
+    if len(data) < 3:
+        return np.nan
+
+    # Convert boolean data to float if needed
+    if data.dtype == bool:
+        data = data.astype(np.float64)
+
+    low, high = _find_levels(data)
+    amplitude = high - low
+
+    # Check for invalid levels
+    if amplitude <= 0 or np.isnan(amplitude):
         return np.nan
 
-    dc = pw_pos / T
+    # Calculate threshold at 50% of amplitude
+    mid = low + 0.5 * amplitude
+
+    # Count samples above threshold
+    above_threshold = data >= mid
+    samples_high = np.sum(above_threshold)
+    total_samples = len(data)
+
+    if total_samples == 0:
+        return np.nan
+
+    dc = float(samples_high) / total_samples
 
     if percentage:
         return dc * 100
@@ -779,6 +895,9 @@ def measure(
 def _find_levels(data: NDArray[np_floating[Any]]) -> tuple[float, float]:
     """Find low and high levels using histogram method.
 
+    Robust algorithm that handles extreme duty cycles (1%-99%) by using
+    adaptive percentile-based level detection when histogram method fails.
+
     Args:
         data: Waveform data array.
 
@@ -794,12 +913,13 @@ def _find_levels(data: NDArray[np_floating[Any]]) -> tuple[float, float]:
         return float(np.nan), float(np.nan)
 
     # Use percentiles for robust level detection
-    p10, p90 = np.percentile(data, [10, 90])
+    # For extreme duty cycles, use wider percentile range
+    p01, p05, p10, p50, p90, p95, p99 = np.percentile(data, [1, 5, 10, 50, 90, 95, 99])
 
     # Check for constant or near-constant signal
-    data_range = p90 - p10
+    data_range = p99 - p01
     if data_range < 1e-10 or np.isnan(data_range):  # Essentially constant or NaN
-        return float(p10), float(p10)
+        return float(p50), float(p50)
 
     # Refine using histogram peaks
     hist, bin_edges = np.histogram(data, bins=50)
@@ -813,9 +933,11 @@ def _find_levels(data: NDArray[np_floating[Any]]) -> tuple[float, float]:
     low = bin_centers[low_idx]
     high = bin_centers[high_idx]
 
-    # Sanity check
+    # Sanity check - if histogram method failed, use adaptive percentiles
     if high <= low:
-        return float(p10), float(p90)
+        # For extreme duty cycles, use min/max with small outlier rejection
+        # p01 and p99 remove top/bottom 1% outliers (noise, ringing)
+        return float(p01), float(p99)
 
     return float(low), float(high)