oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/core/provenance.py

@@ -0,0 +1,358 @@
+"""Measurement provenance tracking for reproducibility.
+
+This module provides provenance tracking to record the complete history
+of how measurements were computed, including algorithms, parameters,
+timestamps, and library versions.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+# TraceKit version (in production would import from __version__)
+TRACEKIT_VERSION = "0.1.0"
+
+
+@dataclass
+class Provenance:
+    """Provenance information for a computation.
+
+    Tracks the complete chain of operations, parameters, and context
+    for reproducibility and debugging.
+
+    Attributes:
+        algorithm: Name of algorithm or method used.
+        parameters: Dictionary of parameters passed to the algorithm.
+        timestamp: ISO 8601 timestamp of computation.
+        library_version: Version of TraceKit used.
+        input_hash: Optional hash of input data for change detection.
+        metadata: Additional context information.
+
+    Example:
+        >>> prov = Provenance(
+        ...     algorithm='rise_time',
+        ...     parameters={'ref_levels': (10, 90)},
+        ...     timestamp='2025-12-21T10:30:00Z',
+        ...     library_version='0.1.0'
+        ... )
+
+    References:
+        API-011: Measurement Provenance Tracking
+    """
+
+    algorithm: str
+    parameters: dict[str, Any] = field(default_factory=dict)
+    timestamp: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+    library_version: str = TRACEKIT_VERSION
+    input_hash: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert provenance to dictionary for serialization.
+
+        Returns:
+            Dictionary representation of provenance.
+
+        Example:
+            >>> prov_dict = prov.to_dict()
+            >>> import json
+            >>> json.dumps(prov_dict)
+        """
+        return {
+            "algorithm": self.algorithm,
+            "parameters": self.parameters,
+            "timestamp": self.timestamp,
+            "library_version": self.library_version,
+            "input_hash": self.input_hash,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Provenance:
+        """Create Provenance from dictionary.
+
+        Args:
+            data: Dictionary containing provenance fields.
+
+        Returns:
+            Provenance object.
+
+        Example:
+            >>> prov = Provenance.from_dict(prov_dict)
+        """
+        return cls(
+            algorithm=data["algorithm"],
+            parameters=data.get("parameters", {}),
+            timestamp=data.get("timestamp", ""),
+            library_version=data.get("library_version", TRACEKIT_VERSION),
+            input_hash=data.get("input_hash"),
+            metadata=data.get("metadata", {}),
+        )
+
+    def __str__(self) -> str:
+        """Human-readable provenance summary."""
+        lines = [
+            f"Algorithm: {self.algorithm}",
+            f"Timestamp: {self.timestamp}",
+            f"Version: {self.library_version}",
+        ]
+        if self.parameters:
+            params_str = ", ".join(f"{k}={v}" for k, v in self.parameters.items())
+            lines.append(f"Parameters: {params_str}")
+        if self.input_hash:
+            lines.append(f"Input Hash: {self.input_hash[:16]}...")
+        return "\n".join(lines)
+
+
+@dataclass
+class MeasurementResultWithProvenance:
+    """Measurement result with full provenance tracking.
+
+    Extends the basic measurement result with comprehensive provenance
+    information for reproducibility and debugging.
+
+    Attributes:
+        value: Measured value.
+        units: Units of measurement (e.g., 'V', 'Hz', 's').
+        provenance: Provenance information.
+        confidence: Optional confidence interval (low, high).
+
+    Example:
+        >>> result = MeasurementResultWithProvenance(
+        ...     value=3.3,
+        ...     units='V',
+        ...     provenance=Provenance(
+        ...         algorithm='peak_to_peak',
+        ...         parameters={'window': (0, 1e-3)}
+        ...     )
+        ... )
+        >>> print(result)
+        3.3 V (peak_to_peak)
+
+    References:
+        API-011: Measurement Provenance Tracking
+    """
+
+    value: float
+    units: str | None = None
+    provenance: Provenance | None = None
+    confidence: tuple[float, float] | None = None
+
+    def is_equivalent(
+        self,
+        other: MeasurementResultWithProvenance,
+        *,
+        rtol: float = 1e-9,
+        atol: float = 0.0,
+        check_parameters: bool = True,
+    ) -> bool:
+        """Check if two results are equivalent.
+
+        Compares values within tolerance and optionally checks if the
+        same algorithm and parameters were used.
+
+        Args:
+            other: Other measurement result to compare.
+            rtol: Relative tolerance for value comparison.
+            atol: Absolute tolerance for value comparison.
+            check_parameters: If True, also verify matching algorithm and parameters.
+
+        Returns:
+            True if results are equivalent.
+
+        Example:
+            >>> result1.is_equivalent(result2, rtol=1e-6)
+            True
+        """
+        # Check value equivalence
+        if not np.isclose(self.value, other.value, rtol=rtol, atol=atol):
+            return False
+
+        # Check units match
+        if self.units != other.units:
+            return False
+
+        # Optionally check provenance
+        if check_parameters and self.provenance and other.provenance:
+            if self.provenance.algorithm != other.provenance.algorithm:
+                return False
+            # Check if critical parameters match
+            if self.provenance.parameters != other.provenance.parameters:
+                return False
+
+        return True
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization.
+
+        Returns:
+            Dictionary representation including provenance.
+
+        Example:
+            >>> result_dict = result.to_dict()
+            >>> import json
+            >>> json_str = json.dumps(result_dict)
+        """
+        result: dict[str, Any] = {
+            "value": self.value,
+            "units": self.units,
+        }
+        if self.provenance:
+            result["provenance"] = self.provenance.to_dict()
+        if self.confidence:
+            result["confidence"] = self.confidence
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> MeasurementResultWithProvenance:
+        """Create result from dictionary.
+
+        Args:
+            data: Dictionary containing result fields.
+
+        Returns:
+            MeasurementResultWithProvenance object.
+        """
+        provenance = None
+        if "provenance" in data:
+            provenance = Provenance.from_dict(data["provenance"])
+
+        confidence = None
+        if "confidence" in data:
+            confidence = tuple(data["confidence"])
+
+        return cls(
+            value=data["value"],
+            units=data.get("units"),
+            provenance=provenance,
+            confidence=confidence,
+        )
+
+    def __str__(self) -> str:
+        """Human-readable string representation."""
+        parts = [str(self.value)]
+        if self.units:
+            parts.append(self.units)
+        if self.provenance:
+            parts.append(f"({self.provenance.algorithm})")
+        return " ".join(parts)
+
+    def __repr__(self) -> str:
+        """Detailed representation."""
+        parts = [f"value={self.value}"]
+        if self.units:
+            parts.append(f"units='{self.units}'")
+        if self.provenance:
+            parts.append(f"algorithm='{self.provenance.algorithm}'")
+        return f"MeasurementResultWithProvenance({', '.join(parts)})"
+
+    def pretty_print(self) -> str:
+        """Pretty-print result with full provenance.
+
+        Returns:
+            Multi-line formatted string with all details.
+
+        Example:
+            >>> print(result.pretty_print())
+            Value: 3.3 V
+            Algorithm: peak_to_peak
+            Timestamp: 2025-12-21T10:30:00Z
+            Version: 0.1.0
+            Parameters: window=(0, 0.001)
+        """
+        lines = [f"Value: {self.value}"]
+        if self.units:
+            lines[-1] += f" {self.units}"
+
+        if self.confidence:
+            lines.append(f"Confidence: ({self.confidence[0]}, {self.confidence[1]})")
+
+        if self.provenance:
+            lines.append(str(self.provenance))
+
+        return "\n".join(lines)
+
+
+def compute_input_hash(data: NDArray[np.float64]) -> str:
+    """Compute hash of input data for change detection.
+
+    Uses SHA-256 hash of data array for reproducibility checks.
+
+    Args:
+        data: Input numpy array.
+
+    Returns:
+        Hexadecimal hash string.
+
+    Example:
+        >>> data = np.array([1.0, 2.0, 3.0])
+        >>> hash_str = compute_input_hash(data)
+
+    References:
+        API-011: Measurement Provenance Tracking
+    """
+    # Convert to bytes and hash
+    data_bytes = data.tobytes()
+    hash_obj = hashlib.sha256(data_bytes)
+    return hash_obj.hexdigest()
+
+
+def create_provenance(
+    algorithm: str,
+    parameters: dict[str, Any] | None = None,
+    *,
+    input_data: NDArray[np.float64] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> Provenance:
+    """Create provenance record for a computation.
+
+    Convenience function to create provenance with automatic timestamp
+    and optional input hash.
+
+    Args:
+        algorithm: Name of algorithm or method.
+        parameters: Parameters used in computation.
+        input_data: Optional input data to hash for change detection.
+        metadata: Additional context information.
+
+    Returns:
+        Provenance object.
+
+    Example:
+        >>> import numpy as np
+        >>> data = np.array([1.0, 2.0, 3.0])
+        >>> prov = create_provenance(
+        ...     algorithm='mean',
+        ...     parameters={'axis': 0},
+        ...     input_data=data
+        ... )
+
+    References:
+        API-011: Measurement Provenance Tracking
+    """
+    input_hash = None
+    if input_data is not None:
+        input_hash = compute_input_hash(input_data)
+
+    return Provenance(
+        algorithm=algorithm,
+        parameters=parameters or {},
+        input_hash=input_hash,
+        metadata=metadata or {},
+    )
+
+
+__all__ = [
+    "MeasurementResultWithProvenance",
+    "Provenance",
+    "compute_input_hash",
+    "create_provenance",
+]

oscura/core/results.py

@@ -0,0 +1,331 @@
+"""Analysis result classes with intermediate data access.
+
+This module provides rich result objects that store intermediate computation
+results (FFT coefficients, filter states, etc.) for multi-step analysis
+without recomputation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    from .types import WaveformTrace
+
+
+@dataclass
+class AnalysisResult:
+    """Container for analysis results with intermediate data.
+
+    Stores the final result along with intermediate computation artifacts
+    like FFT coefficients, filter states, wavelet coefficients, etc.
+    Enables multi-step analysis without recomputation.
+
+    Attributes:
+        value: The final computed value (measurement, trace, etc.).
+        intermediates: Dictionary of intermediate computation results.
+        metadata: Additional metadata about the computation.
+
+    Example:
+        >>> result = AnalysisResult(
+        ...     value=42.5,
+        ...     intermediates={'fft_coeffs': coeffs, 'frequencies': freqs}
+        ... )
+        >>> fft_data = result.get_intermediate('fft_coeffs')
+
+    References:
+        API-005: Intermediate Result Access
+    """
+
+    value: Any
+    intermediates: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def get_intermediate(self, key: str) -> Any:
+        """Get intermediate result by key.
+
+        Args:
+            key: Name of the intermediate result.
+
+        Returns:
+            The intermediate data.
+
+        Raises:
+            KeyError: If key not found in intermediates.
+
+        Example:
+            >>> spectrum = result.get_intermediate('fft_spectrum')
+        """
+        if key not in self.intermediates:
+            available = list(self.intermediates.keys())
+            raise KeyError(f"Intermediate '{key}' not found. Available: {available}")
+        return self.intermediates[key]
+
+    def has_intermediate(self, key: str) -> bool:
+        """Check if intermediate result exists.
+
+        Args:
+            key: Name of the intermediate result.
+
+        Returns:
+            True if key exists in intermediates.
+
+        Example:
+            >>> if result.has_intermediate('fft_coeffs'):
+            ...     coeffs = result.get_intermediate('fft_coeffs')
+        """
+        return key in self.intermediates
+
+    def list_intermediates(self) -> list[str]:
+        """List all available intermediate result keys.
+
+        Returns:
+            List of intermediate result names.
+
+        Example:
+            >>> print(result.list_intermediates())
+            ['fft_spectrum', 'fft_frequencies', 'fft_power', 'fft_phase']
+        """
+        return list(self.intermediates.keys())
+
+
+@dataclass
+class FFTResult(AnalysisResult):
+    """Result object for FFT analysis with intermediate data.
+
+    Provides convenient access to FFT spectrum, frequencies, power,
+    and phase information.
+
+    Attributes:
+        spectrum: Complex FFT coefficients.
+        frequencies: Frequency bins in Hz.
+        power: Power spectrum (magnitude squared).
+        phase: Phase spectrum in radians.
+        trace: Original or transformed trace (optional).
+
+    Example:
+        >>> fft_result = tk.fft(trace, nfft=8192)
+        >>> spectrum = fft_result.spectrum
+        >>> frequencies = fft_result.frequencies
+        >>> power = fft_result.power
+        >>> phase = fft_result.phase
+        >>> peak_freq = frequencies[power.argmax()]
+
+    References:
+        API-005: Intermediate Result Access
+    """
+
+    spectrum: NDArray[np.complex128] = field(default_factory=lambda: np.array([]))
+    frequencies: NDArray[np.float64] = field(default_factory=lambda: np.array([]))
+    power: NDArray[np.float64] = field(default_factory=lambda: np.array([]))
+    phase: NDArray[np.float64] = field(default_factory=lambda: np.array([]))
+    trace: WaveformTrace | None = None
+
+    def __post_init__(self) -> None:
+        """Initialize intermediate results dictionary."""
+        # Store as intermediates for generic access
+        self.intermediates.update(
+            {
+                "spectrum": self.spectrum,
+                "frequencies": self.frequencies,
+                "power": self.power,
+                "phase": self.phase,
+            }
+        )
+        if self.trace is not None:
+            self.intermediates["trace"] = self.trace
+
+        # Set value to spectrum by default
+        if self.value is None:
+            self.value = self.spectrum
+
+    @property
+    def peak_frequency(self) -> float:
+        """Frequency of maximum power.
+
+        Returns:
+            Frequency in Hz where power spectrum peaks.
+
+        Example:
+            >>> print(f"Peak at {fft_result.peak_frequency:.2e} Hz")
+        """
+        if len(self.power) == 0:
+            return 0.0
+        return float(self.frequencies[self.power.argmax()])
+
+    @property
+    def magnitude(self) -> NDArray[np.float64]:
+        """Magnitude spectrum (absolute value of FFT).
+
+        Returns:
+            Magnitude of complex spectrum.
+
+        Example:
+            >>> mag = fft_result.magnitude
+        """
+        return np.abs(self.spectrum)
+
+
+@dataclass
+class FilterResult(AnalysisResult):
+    """Result object for filter operations with intermediate data.
+
+    Provides access to filtered trace along with filter characteristics
+    like transfer function and impulse response.
+
+    Attributes:
+        trace: Filtered WaveformTrace.
+        transfer_function: Filter transfer function H(f) (optional).
+        impulse_response: Filter impulse response h[n] (optional).
+        frequency_response: Tuple of (frequencies, response) (optional).
+        filter_coefficients: Filter coefficients (sos or ba format) (optional).
+
+    Example:
+        >>> filter_result = tk.low_pass(trace, cutoff=1e6, return_details=True)
+        >>> filtered_trace = filter_result.trace
+        >>> transfer_func = filter_result.transfer_function
+        >>> impulse_resp = filter_result.impulse_response
+
+    References:
+        API-005: Intermediate Result Access
+        API-009: Filter Introspection API
+    """
+
+    trace: WaveformTrace | None = None
+    transfer_function: NDArray[np.complex128] | None = None
+    impulse_response: NDArray[np.float64] | None = None
+    frequency_response: tuple[NDArray[np.float64], NDArray[np.complex128]] | None = None
+    filter_coefficients: Any | None = None
+
+    def __post_init__(self) -> None:
+        """Initialize intermediate results dictionary."""
+        if self.trace is not None:
+            self.intermediates["trace"] = self.trace
+        if self.transfer_function is not None:
+            self.intermediates["transfer_function"] = self.transfer_function
+        if self.impulse_response is not None:
+            self.intermediates["impulse_response"] = self.impulse_response
+        if self.frequency_response is not None:
+            self.intermediates["frequency_response"] = self.frequency_response
+        if self.filter_coefficients is not None:
+            self.intermediates["filter_coefficients"] = self.filter_coefficients
+
+        # Set value to trace by default
+        if self.value is None:
+            self.value = self.trace
+
+
+@dataclass
+class WaveletResult(AnalysisResult):
+    """Result object for wavelet transform with intermediate data.
+
+    Provides access to wavelet coefficients, scales, and frequencies.
+
+    Attributes:
+        coeffs: Wavelet coefficients.
+        scales: Wavelet scales.
+        frequencies: Corresponding frequencies in Hz.
+        trace: Original trace (optional).
+
+    Example:
+        >>> wavelet_result = tk.wavelet_transform(trace)
+        >>> coeffs = wavelet_result.coeffs
+        >>> scales = wavelet_result.scales
+        >>> frequencies = wavelet_result.frequencies
+
+    References:
+        API-005: Intermediate Result Access
+    """
+
+    coeffs: NDArray[np.complex128] | None = None
+    scales: NDArray[np.float64] | None = None
+    frequencies: NDArray[np.float64] | None = None
+    trace: WaveformTrace | None = None
+
+    def __post_init__(self) -> None:
+        """Initialize intermediate results dictionary."""
+        if self.coeffs is not None:
+            self.intermediates["coeffs"] = self.coeffs
+        if self.scales is not None:
+            self.intermediates["scales"] = self.scales
+        if self.frequencies is not None:
+            self.intermediates["frequencies"] = self.frequencies
+        if self.trace is not None:
+            self.intermediates["trace"] = self.trace
+
+        # Set value to coeffs by default
+        if self.value is None:
+            self.value = self.coeffs
+
+
+@dataclass
+class MeasurementResult(AnalysisResult):
+    """Result object for measurements with metadata.
+
+    Stores a measurement value along with units, method, and parameters
+    used for computation.
+
+    Attributes:
+        value: Measured value.
+        units: Units of measurement (e.g., 'V', 'Hz', 's').
+        method: Method or algorithm used.
+        parameters: Dictionary of parameters used.
+        confidence: Confidence interval or uncertainty (optional).
+
+    Example:
+        >>> result = MeasurementResult(
+        ...     value=3.3,
+        ...     units='V',
+        ...     method='peak_to_peak',
+        ...     parameters={'window': (0, 1e-3)}
+        ... )
+
+    References:
+        API-005: Intermediate Result Access
+        API-011: Measurement Provenance Tracking
+    """
+
+    units: str | None = None
+    method: str | None = None
+    parameters: dict[str, Any] = field(default_factory=dict)
+    confidence: tuple[float, float] | None = None
+
+    def __post_init__(self) -> None:
+        """Initialize metadata dictionary."""
+        self.metadata.update(
+            {
+                "units": self.units,
+                "method": self.method,
+                "parameters": self.parameters,
+                "confidence": self.confidence,
+            }
+        )
+
+    def __str__(self) -> str:
+        """String representation of measurement."""
+        if self.units:
+            return f"{self.value} {self.units}"
+        return str(self.value)
+
+    def __repr__(self) -> str:
+        """Detailed representation of measurement."""
+        parts = [f"value={self.value}"]
+        if self.units:
+            parts.append(f"units='{self.units}'")
+        if self.method:
+            parts.append(f"method='{self.method}'")
+        return f"MeasurementResult({', '.join(parts)})"
+
+
+__all__ = [
+    "AnalysisResult",
+    "FFTResult",
+    "FilterResult",
+    "MeasurementResult",
+    "WaveletResult",
+]