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

oscura/analyzers/statistics/basic.py

@@ -20,6 +20,7 @@ from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
+from oscura.core.measurement_result import make_measurement
 from oscura.core.types import WaveformTrace
 
 if TYPE_CHECKING:
@@ -171,6 +172,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 +323,93 @@ 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 MeasurementResult format with applicability tracking and formatting.
+
+    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 MeasurementResult format. If False, return flat values.
+
+    Returns:
+        Dictionary mapping measurement names to MeasurementResults (if include_units=True)
+        or raw values (if include_units=False).
+
+    Example:
+        >>> from oscura.analyzers.statistics import measure
+        >>> results = measure(trace)
+        >>> if results['mean']['applicable']:
+        ...     print(f"Mean: {results['mean']['display']}")
+
+        >>> # Get specific measurements only
+        >>> results = measure(trace, parameters=["mean", "std"])
+
+        >>> # Get flat values (legacy compatibility)
+        >>> 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, "")
+            # All statistical measurements are always applicable (never NaN from valid data)
+            results[name] = make_measurement(value, 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/validation.py

@@ -64,7 +64,7 @@ def is_suitable_for_frequency_measurement(trace: WaveformTrace) -> tuple[bool, s
 
     # Check period consistency (is it periodic?)
     if len(rising_edges) >= 3:
-        edge_times = rising_edges * trace.metadata.time_base
+        edge_times = rising_edges / trace.metadata.sample_rate
         periods = np.diff(edge_times)
         period_cv = np.std(periods) / np.mean(periods) if np.mean(periods) > 0 else float("inf")
 

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",