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

oscura/jupyter/__init__.py

@@ -0,0 +1,32 @@
+"""Jupyter and IPython integration for Oscura.
+
+This package provides IPython magic commands, rich display integration,
+and Jupyter notebook-specific features.
+
+  - IPython magic commands (%oscura, %%analyze)
+  - Rich HTML display for results
+  - Inline plot rendering
+  - Progress bars (tqdm integration)
+"""
+
+from oscura.jupyter.display import (
+    MeasurementDisplay,
+    TraceDisplay,
+    display_measurements,
+    display_spectrum,
+    display_trace,
+)
+from oscura.jupyter.magic import (
+    OscuraMagics,
+    load_ipython_extension,
+)
+
+__all__ = [
+    "MeasurementDisplay",
+    "OscuraMagics",
+    "TraceDisplay",
+    "display_measurements",
+    "display_spectrum",
+    "display_trace",
+    "load_ipython_extension",
+]

oscura/jupyter/display.py

@@ -0,0 +1,268 @@
+"""Rich display integration for Jupyter notebooks.
+
+This module provides rich HTML display for Oscura objects including
+traces, measurements, and spectral data.
+
+  - HTML tables for measurements
+  - Inline plot rendering
+  - Interactive result display
+
+Example:
+    In [1]: from oscura.jupyter.display import display_trace
+    In [2]: display_trace(trace)  # Shows rich HTML summary
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from IPython.display import HTML, SVG, display
+
+    IPYTHON_AVAILABLE = True
+except ImportError:
+    IPYTHON_AVAILABLE = False
+
+    class HTML:  # type: ignore[no-redef]
+        """Fallback HTML class when IPython not available."""
+
+        def __init__(self, data: str) -> None:
+            self.data = data
+
+    class SVG:  # type: ignore[no-redef]
+        """Fallback SVG class when IPython not available."""
+
+        def __init__(self, data: str) -> None:
+            self.data = data
+
+    def display(*args: Any, **kwargs: Any) -> None:  # type: ignore[no-redef,misc]
+        """Fallback display when IPython not available."""
+        for arg in args:
+            print(arg)
+
+
+class TraceDisplay:
+    """Rich display wrapper for trace objects.
+
+    Provides _repr_html_ for Jupyter notebook rendering.
+    """
+
+    def __init__(self, trace: Any, title: str = "Trace") -> None:
+        """Initialize trace display.
+
+        Args:
+            trace: WaveformTrace or DigitalTrace object
+            title: Display title
+        """
+        self.trace = trace
+        self.title = title
+
+    def _repr_html_(self) -> str:
+        """Generate HTML representation for Jupyter."""
+        trace = self.trace
+
+        # Build info rows
+        rows = []
+
+        if hasattr(trace, "data"):
+            rows.append(("Samples", f"{len(trace.data):,}"))
+
+        if hasattr(trace, "metadata"):
+            meta = trace.metadata
+            if hasattr(meta, "sample_rate") and meta.sample_rate:
+                rate = meta.sample_rate
+                if rate >= 1e9:
+                    rate_str = f"{rate / 1e9:.3f} GSa/s"
+                elif rate >= 1e6:
+                    rate_str = f"{rate / 1e6:.3f} MSa/s"
+                else:
+                    rate_str = f"{rate / 1e3:.3f} kSa/s"
+                rows.append(("Sample Rate", rate_str))
+
+            if hasattr(meta, "channel_name") and meta.channel_name:
+                rows.append(("Channel", meta.channel_name))
+
+            if hasattr(meta, "source_file") and meta.source_file:
+                rows.append(("Source", meta.source_file))
+
+        # Calculate duration if possible
+        if hasattr(trace, "data") and hasattr(trace, "metadata"):
+            if hasattr(trace.metadata, "sample_rate") and trace.metadata.sample_rate:
+                duration = len(trace.data) / trace.metadata.sample_rate
+                if duration >= 1:
+                    dur_str = f"{duration:.3f} s"
+                elif duration >= 1e-3:
+                    dur_str = f"{duration * 1e3:.3f} ms"
+                elif duration >= 1e-6:
+                    dur_str = f"{duration * 1e6:.3f} us"
+                else:
+                    dur_str = f"{duration * 1e9:.3f} ns"
+                rows.append(("Duration", dur_str))
+
+        # Data statistics
+        if hasattr(trace, "data"):
+            import numpy as np
+
+            data = trace.data
+            rows.append(("Min", f"{np.min(data):.4g}"))
+            rows.append(("Max", f"{np.max(data):.4g}"))
+            rows.append(("Mean", f"{np.mean(data):.4g}"))
+            rows.append(("Std Dev", f"{np.std(data):.4g}"))
+
+        # Build HTML table
+        html = f"""
+<div style="border: 1px solid #ccc; border-radius: 4px; padding: 10px; max-width: 400px;">
+    <h4 style="margin: 0 0 10px 0; color: #333;">{self.title}</h4>
+    <table style="width: 100%; border-collapse: collapse;">
+"""
+        for label, value in rows:
+            html += f"""
+        <tr>
+            <td style="padding: 4px 8px; border-bottom: 1px solid #eee; font-weight: bold; color: #666;">{label}</td>
+            <td style="padding: 4px 8px; border-bottom: 1px solid #eee;">{value}</td>
+        </tr>
+"""
+        html += """
+    </table>
+</div>
+"""
+        return html
+
+
+class MeasurementDisplay:
+    """Rich display wrapper for measurement results.
+
+    Provides _repr_html_ for Jupyter notebook rendering.
+    """
+
+    def __init__(self, measurements: dict[str, Any], title: str = "Measurements") -> None:
+        """Initialize measurement display.
+
+        Args:
+            measurements: Dictionary of measurement name -> value
+            title: Display title
+        """
+        self.measurements = measurements
+        self.title = title
+
+    def _format_value(self, value: Any) -> str:
+        """Format a measurement value with appropriate units."""
+        if isinstance(value, float):
+            # Determine scale and units for common measurements
+            abs_val = abs(value)
+            if abs_val == 0:
+                return "0"
+            elif abs_val >= 1e9:
+                return f"{value / 1e9:.3f} G"
+            elif abs_val >= 1e6:
+                return f"{value / 1e6:.3f} M"
+            elif abs_val >= 1e3:
+                return f"{value / 1e3:.3f} k"
+            elif abs_val >= 1:
+                return f"{value:.4f}"
+            elif abs_val >= 1e-3:
+                return f"{value * 1e3:.3f} m"
+            elif abs_val >= 1e-6:
+                return f"{value * 1e6:.3f} u"
+            elif abs_val >= 1e-9:
+                return f"{value * 1e9:.3f} n"
+            elif abs_val >= 1e-12:
+                return f"{value * 1e12:.3f} p"
+            else:
+                return f"{value:.3e}"
+        else:
+            return str(value)
+
+    def _repr_html_(self) -> str:
+        """Generate HTML representation for Jupyter."""
+        html = f"""
+<div style="border: 1px solid #ccc; border-radius: 4px; padding: 10px; max-width: 500px;">
+    <h4 style="margin: 0 0 10px 0; color: #333;">{self.title}</h4>
+    <table style="width: 100%; border-collapse: collapse;">
+        <tr style="background-color: #f5f5f5;">
+            <th style="padding: 8px; text-align: left; border-bottom: 2px solid #ddd;">Measurement</th>
+            <th style="padding: 8px; text-align: right; border-bottom: 2px solid #ddd;">Value</th>
+        </tr>
+"""
+        for name, value in self.measurements.items():
+            formatted = self._format_value(value)
+            html += f"""
+        <tr>
+            <td style="padding: 6px 8px; border-bottom: 1px solid #eee;">{name}</td>
+            <td style="padding: 6px 8px; border-bottom: 1px solid #eee; text-align: right; font-family: monospace;">{formatted}</td>
+        </tr>
+"""
+        html += """
+    </table>
+</div>
+"""
+        return html
+
+
+def display_trace(trace: Any, title: str = "Trace") -> None:
+    """Display a trace with rich HTML formatting.
+
+    Args:
+        trace: WaveformTrace or DigitalTrace object
+        title: Display title
+    """
+    wrapper = TraceDisplay(trace, title)
+    if IPYTHON_AVAILABLE:
+        display(HTML(wrapper._repr_html_()))  # type: ignore[no-untyped-call]
+    else:
+        print(wrapper._repr_html_())
+
+
+def display_measurements(measurements: dict[str, Any], title: str = "Measurements") -> None:
+    """Display measurements with rich HTML formatting.
+
+    Args:
+        measurements: Dictionary of measurement name -> value
+        title: Display title
+    """
+    wrapper = MeasurementDisplay(measurements, title)
+    if IPYTHON_AVAILABLE:
+        display(HTML(wrapper._repr_html_()))  # type: ignore[no-untyped-call]
+    else:
+        for name, value in measurements.items():
+            print(f"{name}: {value}")
+
+
+def display_spectrum(
+    frequencies: Any,
+    magnitudes: Any,
+    title: str = "Spectrum",
+    log_scale: bool = True,
+    figsize: tuple[int, int] = (10, 4),
+) -> None:
+    """Display a spectrum plot inline in Jupyter.
+
+    Args:
+        frequencies: Frequency array (Hz)
+        magnitudes: Magnitude array (dB or linear)
+        title: Plot title
+        log_scale: Use log scale for x-axis
+        figsize: Figure size tuple
+    """
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    _fig, ax = plt.subplots(figsize=figsize)
+
+    if log_scale and np.min(frequencies[frequencies > 0]) > 0:
+        ax.semilogx(frequencies, magnitudes)
+    else:
+        ax.plot(frequencies, magnitudes)
+
+    ax.set_xlabel("Frequency (Hz)")
+    ax.set_ylabel("Magnitude (dB)")
+    ax.set_title(title)
+    ax.grid(True, alpha=0.3)
+
+    plt.tight_layout()
+
+    if IPYTHON_AVAILABLE:
+        # Display inline
+        plt.show()
+    else:
+        plt.show()

oscura/jupyter/magic.py

@@ -0,0 +1,334 @@
+"""IPython magic commands for Oscura.
+
+This module provides IPython/Jupyter magic commands for convenient
+trace analysis in notebooks.
+
+  - %oscura load <file> - Load a trace file
+  - %oscura measure - Run measurements on current trace
+  - %%analyze - Multi-line analysis cell
+  - Auto-display of results with rich HTML
+
+Example:
+    In [1]: %load_ext oscura
+
+    In [2]: %oscura load capture.wfm
+    Loaded: WaveformTrace with 10000 samples @ 1 GSa/s
+
+    In [3]: %oscura measure rise_time fall_time
+    rise_time: 2.5 ns
+    fall_time: 2.8 ns
+
+    In [4]: %%analyze
+       ...: trace = load("capture.wfm")
+       ...: print(f"THD: {thd(trace):.2f} dB")
+
+References:
+    - IPython Magic Commands documentation
+    - Jupyter display architecture
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from IPython.core.interactiveshell import InteractiveShell
+
+
+# Store current trace for magic commands
+_current_trace: Any = None
+_current_file: str | None = None
+
+
+def get_current_trace() -> Any:
+    """Get the currently loaded trace from magic commands."""
+    return _current_trace
+
+
+def set_current_trace(trace: Any, filename: str | None = None) -> None:
+    """Set the current trace for magic commands."""
+    global _current_trace, _current_file
+    _current_trace = trace
+    _current_file = filename
+
+
+try:
+    from IPython.core.magic import (
+        Magics,
+        cell_magic,
+        line_magic,
+        magics_class,
+    )
+    from IPython.display import HTML, display  # noqa: F401
+
+    IPYTHON_AVAILABLE = True
+except ImportError:
+    IPYTHON_AVAILABLE = False
+
+    class Magics:  # type: ignore[no-redef]
+        """Fallback Magics class when IPython not available."""
+
+    def magics_class(cls: type[Any]) -> type[Any]:  # type: ignore[no-redef,misc]
+        """Dummy decorator when IPython not available."""
+        return cls
+
+    def line_magic(func):  # type: ignore[no-untyped-def]
+        """Dummy decorator."""
+        return func
+
+    def cell_magic(func):  # type: ignore[no-untyped-def]
+        """Dummy decorator."""
+        return func
+
+
+@magics_class
+class OscuraMagics(Magics):  # type: ignore[misc]
+    """IPython magics for Oscura analysis.
+
+    Provides convenient shortcuts for loading traces, running measurements,
+    and displaying results in Jupyter notebooks.
+    """
+
+    @line_magic  # type: ignore[misc, untyped-decorator]
+    def oscura(self, line: str) -> Any:
+        """Oscura line magic for quick operations.
+
+        Usage:
+            %oscura load <filename>    - Load a trace file
+            %oscura measure [names...] - Run measurements
+            %oscura info               - Show current trace info
+            %oscura formats            - List supported formats
+            %oscura help               - Show help
+
+        Args:
+            line: Magic command arguments
+
+        Returns:
+            Command result or None
+        """
+        import oscura as osc
+
+        parts = line.strip().split()
+        if not parts:
+            return self._show_help()
+
+        cmd = parts[0].lower()
+
+        if cmd == "load":
+            if len(parts) < 2:
+                print("Usage: %oscura load <filename>")
+                return None
+            filename = " ".join(parts[1:])
+            return self._load_trace(filename)
+
+        elif cmd == "measure":
+            measurements = parts[1:] if len(parts) > 1 else None
+            return self._run_measurements(measurements)
+
+        elif cmd == "info":
+            return self._show_trace_info()
+
+        elif cmd == "formats":
+            formats = osc.get_supported_formats()
+            print("Supported formats:")
+            for fmt in formats:
+                print(f"  - {fmt}")
+            return formats
+
+        elif cmd == "help":
+            return self._show_help()
+
+        else:
+            print(f"Unknown command: {cmd}")
+            return self._show_help()
+
+    def _load_trace(self, filename: str) -> Any:
+        """Load a trace file and store as current."""
+        import oscura as osc
+
+        try:
+            trace = osc.load(filename)
+            set_current_trace(trace, filename)
+
+            # Display summary
+            info = {
+                "file": filename,
+                "type": type(trace).__name__,
+                "samples": len(trace.data) if hasattr(trace, "data") else "N/A",
+                "sample_rate": f"{trace.metadata.sample_rate / 1e9:.3f} GSa/s"
+                if hasattr(trace, "metadata")
+                else "N/A",
+            }
+
+            print(f"Loaded: {info['type']} with {info['samples']} samples @ {info['sample_rate']}")
+            return trace
+
+        except Exception as e:
+            print(f"Error loading {filename}: {e}")
+            return None
+
+    def _run_measurements(self, measurement_names: list[str] | None) -> dict[str, Any]:
+        """Run measurements on current trace."""
+        import oscura as osc
+
+        trace = get_current_trace()
+        if trace is None:
+            print("No trace loaded. Use: %oscura load <filename>")
+            return {}
+
+        if measurement_names:
+            # Run specific measurements
+            results = {}
+            for name in measurement_names:
+                if hasattr(osc, name):
+                    try:
+                        func = getattr(osc, name)
+                        results[name] = func(trace)
+                    except Exception as e:
+                        results[name] = f"Error: {e}"
+                else:
+                    results[name] = "Unknown measurement"
+        else:
+            # Run all measurements
+            try:
+                results = osc.measure(trace)
+            except Exception as e:
+                print(f"Error running measurements: {e}")
+                return {}
+
+        # Display results
+        self._display_measurements(results)
+        return results
+
+    def _display_measurements(self, results: dict[str, Any]) -> None:
+        """Display measurement results with formatting."""
+        if IPYTHON_AVAILABLE:
+            from oscura.jupyter.display import display_measurements
+
+            display_measurements(results)
+        else:
+            for name, value in results.items():
+                if isinstance(value, float):
+                    print(f"{name}: {value:.6g}")
+                else:
+                    print(f"{name}: {value}")
+
+    def _show_trace_info(self) -> dict[str, Any] | None:
+        """Show information about current trace."""
+        trace = get_current_trace()
+        if trace is None:
+            print("No trace loaded. Use: %oscura load <filename>")
+            return None
+
+        info = {
+            "file": _current_file,
+            "type": type(trace).__name__,
+        }
+
+        if hasattr(trace, "data"):
+            info["samples"] = len(trace.data)  # type: ignore[assignment]
+
+        if hasattr(trace, "metadata"):
+            meta = trace.metadata
+            if hasattr(meta, "sample_rate"):
+                info["sample_rate"] = meta.sample_rate
+            if hasattr(meta, "channel_name"):
+                info["channel"] = meta.channel_name
+
+        for key, value in info.items():
+            print(f"{key}: {value}")
+
+        return info
+
+    def _show_help(self) -> None:
+        """Show magic command help."""
+        help_text = """
+Oscura Magic Commands
+=======================
+
+%oscura load <filename>    Load a trace file
+%oscura measure [names...] Run measurements on current trace
+%oscura info               Show current trace info
+%oscura formats            List supported file formats
+%oscura help               Show this help
+
+%%analyze                    Multi-line analysis cell magic
+
+Available measurements: rise_time, fall_time, frequency, period,
+    amplitude, rms, overshoot, undershoot, thd, snr, sinad
+
+Example:
+    %oscura load capture.wfm
+    %oscura measure rise_time fall_time
+"""
+        print(help_text)
+
+    @cell_magic  # type: ignore[misc, untyped-decorator]
+    def analyze(self, line: str, cell: str) -> Any:
+        """Cell magic for multi-line analysis.
+
+        Args:
+            line: Magic command line arguments (unused).
+            cell: Multi-line cell content to execute.
+
+        Returns:
+            Result from cell execution (if 'result' variable defined).
+
+        Usage:
+            %%analyze
+            trace = load("capture.wfm")
+            result = measure(trace)
+            print(f"Rise time: {result['rise_time']}")
+
+        All oscura functions are auto-imported in the cell namespace.
+        """
+        import oscura as osc
+
+        # Build execution namespace with oscura imports
+        namespace = {
+            "osc": osc,
+            "load": osc.load,
+            "measure": osc.measure,
+            "fft": osc.fft,
+            "psd": osc.psd,
+            "thd": osc.thd,
+            "snr": osc.snr,
+            "rise_time": osc.rise_time,
+            "fall_time": osc.fall_time,
+            "frequency": osc.frequency,
+            "amplitude": osc.amplitude,
+            "low_pass": osc.low_pass,
+            "high_pass": osc.high_pass,
+        }
+
+        # Add current trace if available
+        trace = get_current_trace()
+        if trace is not None:
+            namespace["trace"] = trace
+
+        # Execute cell
+        exec(cell, namespace)
+
+        # Return any result variable if defined
+        return namespace.get("result")
+
+
+def load_ipython_extension(ipython: InteractiveShell) -> None:
+    """Load Oscura IPython extension.
+
+    Called when user runs: %load_ext oscura
+
+    Args:
+        ipython: The IPython shell instance
+    """
+    ipython.register_magics(OscuraMagics)
+    print("Oscura magics loaded. Type '%oscura help' for usage.")
+
+
+def unload_ipython_extension(ipython: InteractiveShell) -> None:
+    """Unload Oscura IPython extension.
+
+    Args:
+        ipython: The IPython shell instance
+    """
+    # IPython handles magic cleanup automatically