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

oscura/exporters/csv.py

@@ -0,0 +1,303 @@
+"""CSV export functionality.
+
+This module provides trace and measurement export to CSV format.
+
+
+Example:
+    >>> from oscura.exporters.csv import export_csv
+    >>> export_csv(trace, "output.csv")
+    >>> export_csv(measurements, "results.csv")
+
+References:
+    RFC 4180 (CSV format)
+"""
+
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from oscura.core.types import DigitalTrace, WaveformTrace
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+def export_csv(
+    data: WaveformTrace | DigitalTrace | dict[str, Any] | NDArray[Any],
+    path: str | Path,
+    *,
+    include_time: bool = True,
+    time_unit: str = "s",
+    precision: int = 9,
+    delimiter: str = ",",
+    header: bool = True,
+) -> None:
+    """Export data to CSV format.
+
+    Args:
+        data: Data to export. Can be:
+            - WaveformTrace or DigitalTrace (with metadata as comments)
+            - Dictionary of measurements
+            - NumPy array
+        path: Output file path.
+        include_time: Include time column for traces.
+        time_unit: Time unit ("s", "ms", "us", "ns").
+        precision: Decimal precision for floating point values.
+        delimiter: Column delimiter.
+        header: Include header row and metadata comments.
+
+    Raises:
+        TypeError: If data type is not supported.
+
+    Example:
+        >>> export_csv(trace, "waveform.csv")
+        >>> export_csv(trace, "data.csv", precision=6, delimiter="\t")
+        >>> export_csv(measurements, "results.csv")
+
+    Note:
+        When exporting traces, metadata is included as comment lines
+        starting with '#' when header=True.
+
+    References:
+        EXP-001
+    """
+    path = Path(path)
+
+    if isinstance(data, WaveformTrace | DigitalTrace):
+        _export_trace(data, path, include_time, time_unit, precision, delimiter, header)
+    elif isinstance(data, dict):
+        _export_dict(data, path, precision, delimiter, header)
+    elif isinstance(data, np.ndarray):
+        _export_array(data, path, precision, delimiter, header)
+    else:
+        raise TypeError(f"Unsupported data type: {type(data)}")
+
+
+def _export_trace(
+    trace: WaveformTrace | DigitalTrace,
+    path: Path,
+    include_time: bool,
+    time_unit: str,
+    precision: int,
+    delimiter: str,
+    header: bool,
+) -> None:
+    """Export trace to CSV.
+
+    Args:
+        trace: Trace to export.
+        path: Output file path.
+        include_time: Include time column.
+        time_unit: Time unit for column.
+        precision: Decimal precision.
+        delimiter: Column delimiter.
+        header: Include header row.
+    """
+    time_multipliers = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
+    multiplier = time_multipliers.get(time_unit, 1.0)
+
+    with open(path, "w", newline="") as f:
+        writer = csv.writer(f, delimiter=delimiter)
+
+        # Write metadata as comments if header is enabled
+        if header:
+            # Metadata comments
+            meta = trace.metadata
+            f.write("# TraceKit CSV Export\n")
+            f.write(f"# Sample Rate: {meta.sample_rate} Hz\n")
+            f.write(f"# Time Base: {meta.time_base} s\n")
+            f.write(f"# Samples: {len(trace.data)}\n")
+            f.write(f"# Duration: {trace.duration} s\n")
+
+            if meta.vertical_scale is not None:
+                f.write(f"# Vertical Scale: {meta.vertical_scale} V/div\n")
+            if meta.vertical_offset is not None:
+                f.write(f"# Vertical Offset: {meta.vertical_offset} V\n")
+            if meta.acquisition_time is not None:
+                f.write(f"# Acquisition Time: {meta.acquisition_time.isoformat()}\n")
+            if meta.source_file is not None:
+                f.write(f"# Source File: {meta.source_file}\n")
+            if meta.channel_name is not None:
+                f.write(f"# Channel: {meta.channel_name}\n")
+
+            f.write("#\n")
+
+            # Column headers
+            if include_time:
+                if isinstance(trace, WaveformTrace):
+                    writer.writerow([f"Time ({time_unit})", "Voltage"])
+                else:
+                    writer.writerow([f"Time ({time_unit})", "Digital"])
+            elif isinstance(trace, WaveformTrace):
+                writer.writerow(["Voltage"])
+            else:
+                writer.writerow(["Digital"])
+
+        # Data
+        n_samples = len(trace.data)
+        time_base = trace.metadata.time_base
+
+        for i in range(n_samples):
+            if include_time:
+                time_val = i * time_base * multiplier
+                if isinstance(trace, WaveformTrace):
+                    writer.writerow([f"{time_val:.{precision}g}", f"{trace.data[i]:.{precision}g}"])
+                else:
+                    writer.writerow([f"{time_val:.{precision}g}", int(trace.data[i])])
+            elif isinstance(trace, WaveformTrace):
+                writer.writerow([f"{trace.data[i]:.{precision}g}"])
+            else:
+                writer.writerow([int(trace.data[i])])
+
+
+def _export_dict(
+    data: dict[str, Any],
+    path: Path,
+    precision: int,
+    delimiter: str,
+    header: bool,
+) -> None:
+    """Export dictionary to CSV.
+
+    Args:
+        data: Dictionary to export.
+        path: Output file path.
+        precision: Decimal precision.
+        delimiter: Column delimiter.
+        header: Include header row.
+    """
+    with open(path, "w", newline="") as f:
+        writer = csv.writer(f, delimiter=delimiter)
+
+        if header:
+            writer.writerow(["Parameter", "Value", "Unit"])
+
+        for key, value in data.items():
+            if isinstance(value, dict):
+                # Nested dict with value/unit
+                val = value.get("value", value)
+                unit = value.get("unit", "")
+                if isinstance(val, float):
+                    writer.writerow([key, f"{val:.{precision}g}", unit])
+                else:
+                    writer.writerow([key, val, unit])
+            elif isinstance(value, float):
+                writer.writerow([key, f"{value:.{precision}g}", ""])
+            else:
+                writer.writerow([key, value, ""])
+
+
+def _export_array(
+    data: NDArray[Any],
+    path: Path,
+    precision: int,
+    delimiter: str,
+    header: bool,
+) -> None:
+    """Export numpy array to CSV.
+
+    Args:
+        data: NumPy array to export.
+        path: Output file path.
+        precision: Decimal precision.
+        delimiter: Column delimiter.
+        header: Include header row.
+    """
+    # Handle different array dimensions
+    if data.ndim == 1:
+        data = data.reshape(-1, 1)
+
+    with open(path, "w", newline="") as f:
+        writer = csv.writer(f, delimiter=delimiter)
+
+        if header:
+            cols = [f"Column_{i}" for i in range(data.shape[1])]
+            writer.writerow(cols)
+
+        for row in data:
+            formatted = []
+            for val in row:
+                if isinstance(val, float | np.floating):
+                    formatted.append(f"{val:.{precision}g}")
+                else:
+                    formatted.append(str(val))  # type: ignore[unreachable]
+            writer.writerow(formatted)
+
+
+def export_multi_trace_csv(
+    traces: list[WaveformTrace | DigitalTrace],
+    path: str | Path,
+    *,
+    names: list[str] | None = None,
+    include_time: bool = True,
+    time_unit: str = "s",
+    precision: int = 9,
+) -> None:
+    """Export multiple traces to single CSV file.
+
+    Args:
+        traces: List of traces to export.
+        path: Output file path.
+        names: Column names for each trace.
+        include_time: Include time column.
+        time_unit: Time unit.
+        precision: Decimal precision.
+
+    Example:
+        >>> export_multi_trace_csv([ch1, ch2, ch3], "channels.csv",
+        ...                         names=["CH1", "CH2", "CH3"])
+    """
+    if len(traces) == 0:
+        return
+
+    path = Path(path)
+
+    if names is None:
+        names = [f"Trace_{i}" for i in range(len(traces))]
+
+    # Use first trace for timing
+    ref_trace = traces[0]
+    n_samples = len(ref_trace.data)
+    time_base = ref_trace.metadata.time_base
+
+    time_multipliers = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
+    multiplier = time_multipliers.get(time_unit, 1.0)
+
+    with open(path, "w", newline="") as f:
+        writer = csv.writer(f)
+
+        # Header
+        header_row = []
+        if include_time:
+            header_row.append(f"Time ({time_unit})")
+        header_row.extend(names)
+        writer.writerow(header_row)
+
+        # Data
+        for i in range(n_samples):
+            row = []
+
+            if include_time:
+                time_val = i * time_base * multiplier
+                row.append(f"{time_val:.{precision}g}")
+
+            for trace in traces:
+                if i < len(trace.data):
+                    if isinstance(trace, WaveformTrace):
+                        row.append(f"{trace.data[i]:.{precision}g}")
+                    else:
+                        row.append(str(int(trace.data[i])))
+                else:
+                    row.append("")
+
+            writer.writerow(row)
+
+
+__all__ = [
+    "export_csv",
+    "export_multi_trace_csv",
+]

oscura/exporters/exporters.py

@@ -0,0 +1,44 @@
+"""Exporters namespace module.
+
+This module provides a namespace for export functions to support:
+    from oscura.exporters import exporters
+    exporters.csv(trace, "output.csv")
+
+Re-exports main export functions with short names.
+"""
+
+from oscura.exporters.csv import (
+    export_csv as csv,
+)
+from oscura.exporters.hdf5 import (
+    export_hdf5 as hdf5,
+)
+from oscura.exporters.html_export import (
+    export_html as html,
+)
+from oscura.exporters.json_export import (
+    export_json as json,
+)
+from oscura.exporters.markdown_export import (
+    export_markdown as markdown,
+)
+from oscura.exporters.matlab_export import (
+    export_mat as mat,
+)
+from oscura.exporters.npz_export import (
+    export_npz as npz,
+)
+from oscura.exporters.spice_export import (
+    export_pwl as pwl,
+)
+
+__all__ = [
+    "csv",
+    "hdf5",
+    "html",
+    "json",
+    "markdown",
+    "mat",
+    "npz",
+    "pwl",
+]

oscura/exporters/hdf5.py

@@ -0,0 +1,219 @@
+"""HDF5 export functionality.
+
+This module provides trace export to HDF5 format with metadata attributes.
+
+
+Example:
+    >>> from oscura.exporters.hdf5 import export_hdf5
+    >>> export_hdf5(trace, "output.h5")
+
+References:
+    HDF5 specification (https://www.hdfgroup.org/)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+try:
+    import h5py
+
+    HAS_H5PY = True
+except ImportError:
+    HAS_H5PY = False
+
+from oscura.core.types import DigitalTrace, WaveformTrace
+
+
+def export_hdf5(
+    data: WaveformTrace | DigitalTrace | dict[str, WaveformTrace | DigitalTrace],
+    path: str | Path,
+    *,
+    compression: str | None = "gzip",
+    compression_opts: int = 4,
+    include_metadata: bool = True,
+) -> None:
+    """Export data to HDF5 format.
+
+    Args:
+        data: Data to export. Can be:
+            - Single WaveformTrace or DigitalTrace
+            - Dictionary mapping names to traces
+        path: Output file path.
+        compression: Compression algorithm ("gzip", "lzf", None).
+        compression_opts: Compression level (1-9 for gzip).
+        include_metadata: Include trace metadata as attributes.
+
+    Raises:
+        ImportError: If h5py is not installed.
+
+    Example:
+        >>> export_hdf5(trace, "waveform.h5")
+        >>> export_hdf5({"ch1": ch1, "ch2": ch2}, "channels.h5")
+    """
+    if not HAS_H5PY:
+        raise ImportError("h5py is required for HDF5 export. Install with: pip install h5py")
+
+    path = Path(path)
+
+    if isinstance(data, WaveformTrace | DigitalTrace):
+        data = {"trace": data}
+
+    with h5py.File(path, "w") as f:
+        # Add file-level metadata
+        f.attrs["created"] = datetime.now().isoformat()
+        f.attrs["oscura_version"] = "1.0"
+        f.attrs["format"] = "oscura_hdf5"
+
+        for name, trace in data.items():
+            _write_trace_dataset(
+                f,
+                name,
+                trace,
+                compression,
+                compression_opts,
+                include_metadata,
+            )
+
+
+def _write_trace_dataset(
+    f: h5py.File,
+    name: str,
+    trace: WaveformTrace | DigitalTrace,
+    compression: str | None,
+    compression_opts: int,
+    include_metadata: bool,
+) -> None:
+    """Write trace to HDF5 dataset.
+
+    Args:
+        f: HDF5 file object.
+        name: Dataset name.
+        trace: Trace to write.
+        compression: Compression algorithm.
+        compression_opts: Compression level.
+        include_metadata: Include metadata as attributes.
+    """
+    # Create dataset
+    dtype = np.float64 if isinstance(trace, WaveformTrace) else np.bool_
+
+    kwargs = {}
+    if compression:
+        kwargs["compression"] = compression
+        if compression == "gzip":
+            kwargs["compression_opts"] = compression_opts  # type: ignore[assignment]
+
+    ds = f.create_dataset(name, data=trace.data.astype(dtype), **kwargs)
+
+    # Add metadata attributes
+    if include_metadata:
+        meta = trace.metadata
+
+        ds.attrs["sample_rate"] = meta.sample_rate
+        ds.attrs["time_base"] = meta.time_base
+
+        if meta.vertical_scale is not None:
+            ds.attrs["vertical_scale"] = meta.vertical_scale
+
+        if meta.vertical_offset is not None:
+            ds.attrs["vertical_offset"] = meta.vertical_offset
+
+        if meta.acquisition_time is not None:
+            ds.attrs["acquisition_time"] = meta.acquisition_time.isoformat()
+
+        if meta.source_file is not None:
+            ds.attrs["source_file"] = str(meta.source_file)
+
+        if meta.channel_name is not None:
+            ds.attrs["channel_name"] = meta.channel_name
+
+        if meta.trigger_info:
+            for key, value in meta.trigger_info.items():
+                ds.attrs[f"trigger_{key}"] = value
+
+        # Type indicator
+        ds.attrs["trace_type"] = "waveform" if isinstance(trace, WaveformTrace) else "digital"
+
+
+def export_measurement_results(
+    results: dict[str, Any],
+    path: str | Path,
+    *,
+    group_name: str = "measurements",
+) -> None:
+    """Export measurement results to HDF5.
+
+    Args:
+        results: Dictionary of measurement results.
+        path: Output file path.
+        group_name: HDF5 group name for results.
+
+    Raises:
+        ImportError: If h5py is not installed.
+
+    Example:
+        >>> results = measure(trace)
+        >>> export_measurement_results(results, "measurements.h5")
+    """
+    if not HAS_H5PY:
+        raise ImportError("h5py is required for HDF5 export")
+
+    path = Path(path)
+
+    with h5py.File(path, "a") as f:
+        grp = f.require_group(group_name)
+
+        for name, value in results.items():
+            if isinstance(value, dict):
+                # Nested dict (value/unit pairs)
+                sub_grp = grp.require_group(name)
+                for k, v in value.items():
+                    if isinstance(v, np.ndarray):
+                        sub_grp.create_dataset(k, data=v)
+                    else:
+                        sub_grp.attrs[k] = v
+            elif isinstance(value, np.ndarray):
+                grp.create_dataset(name, data=value)
+            else:
+                grp.attrs[name] = value
+
+
+def append_trace(
+    path: str | Path,
+    name: str,
+    trace: WaveformTrace | DigitalTrace,
+    *,
+    compression: str | None = "gzip",
+) -> None:
+    """Append trace to existing HDF5 file.
+
+    Args:
+        path: HDF5 file path.
+        name: Dataset name for new trace.
+        trace: Trace to append.
+        compression: Compression algorithm.
+
+    Raises:
+        ImportError: If h5py is not installed.
+
+    Example:
+        >>> append_trace("data.h5", "ch3", channel3_trace)
+    """
+    if not HAS_H5PY:
+        raise ImportError("h5py is required for HDF5 export")
+
+    path = Path(path)
+
+    with h5py.File(path, "a") as f:
+        _write_trace_dataset(f, name, trace, compression, 4, True)
+
+
+__all__ = [
+    "append_trace",
+    "export_hdf5",
+    "export_measurement_results",
+]