csiphon 0.1.0__py3-none-any.whl

csiphon/__init__.py

@@ -0,0 +1,80 @@
+"""csiphon: an online-first, schema-validated CSI preprocessing pipeline.
+
+Build an immutable Pipeline from steps (branch and merge as needed), compile it
+against an AcquisitionProfile into a Siphon, then run it over a whole recording
+(`siphon.pour()`) or chunk by chunk (`siphon.stream()`). A run returns Outlets,
+the named results.
+"""
+
+from __future__ import annotations
+
+from csiphon.core import (
+    AcquisitionProfile,
+    Axis,
+    AxisName,
+    Layout,
+    Representation,
+    Signal,
+    ValueKind,
+    create_signal,
+)
+from csiphon.inspection import describe
+from csiphon.pipeline import (
+    Alignment,
+    Concatenate,
+    Exact,
+    Fuse,
+    Hold,
+    Junction,
+    Mean,
+    MergeStrategy,
+    Node,
+    Outlets,
+    Pipeline,
+    PointwiseStep,
+    Sequence,
+    Siphon,
+    Stack,
+    Step,
+    Stream,
+    StreamOperator,
+    Sum,
+    Time,
+)
+from csiphon.spec import Category, Description, StepSpec, Streaming
+
+__all__ = [
+    "AcquisitionProfile",
+    "Alignment",
+    "Axis",
+    "AxisName",
+    "Category",
+    "Concatenate",
+    "Description",
+    "Exact",
+    "Fuse",
+    "Hold",
+    "Junction",
+    "Layout",
+    "Mean",
+    "MergeStrategy",
+    "Node",
+    "Outlets",
+    "Pipeline",
+    "PointwiseStep",
+    "Representation",
+    "Sequence",
+    "Signal",
+    "Siphon",
+    "Stack",
+    "Step",
+    "StepSpec",
+    "Stream",
+    "StreamOperator",
+    "Streaming",
+    "Sum",
+    "Time",
+    "ValueKind",
+    "create_signal",
+    "describe",
+]

csiphon/core/__init__.py

@@ -0,0 +1,62 @@
+"""Core data model: axes, layout, signal, acquisition profile, sampling."""
+
+from __future__ import annotations
+
+from csiphon.core.arrays import (
+    ComplexArray,
+    RealArray,
+    SignalArray,
+    as_complex_array,
+    as_real_array,
+    as_signal_array,
+)
+from csiphon.core.axes import Axis, AxisName, Coordinate
+from csiphon.core.errors import (
+    ClogError,
+    CompileError,
+    DataError,
+    LayoutError,
+    MissingDependencyError,
+    StreamingError,
+)
+from csiphon.core.layout import Layout
+from csiphon.core.profile import AcquisitionProfile
+from csiphon.core.sampling import (
+    JitterWarning,
+    check_jitter,
+    effective_rate_hz,
+    estimate_rate_hz,
+    jitter_ratio,
+)
+from csiphon.core.semantics import Representation, ValueKind
+from csiphon.core.signal import Signal, create_signal, empty_signal
+
+__all__ = [
+    "AcquisitionProfile",
+    "Axis",
+    "AxisName",
+    "ClogError",
+    "CompileError",
+    "ComplexArray",
+    "Coordinate",
+    "DataError",
+    "JitterWarning",
+    "Layout",
+    "LayoutError",
+    "MissingDependencyError",
+    "RealArray",
+    "Representation",
+    "Signal",
+    "SignalArray",
+    "StreamingError",
+    "ValueKind",
+    "as_complex_array",
+    "as_real_array",
+    "as_signal_array",
+    "check_jitter",
+    "create_signal",
+    "effective_rate_hz",
+    "empty_signal",
+    "estimate_rate_hz",
+    "jitter_ratio",
+]

csiphon/core/arrays.py

@@ -0,0 +1,31 @@
+"""Concrete NumPy array types used at numerical boundaries."""
+
+from __future__ import annotations
+
+import numpy as np
+import numpy.typing as npt
+
+type RealArray = npt.NDArray[np.float64]
+type ComplexArray = npt.NDArray[np.complex128]
+type SignalArray = RealArray | ComplexArray
+
+
+def as_complex_array(values: npt.ArrayLike) -> ComplexArray:
+    """Return values as the canonical complex array type."""
+
+    return np.asarray(values, dtype=np.complex128)
+
+
+def as_real_array(values: npt.ArrayLike) -> RealArray:
+    """Return values as the canonical real array type."""
+
+    return np.asarray(values, dtype=np.float64)
+
+
+def as_signal_array(values: npt.ArrayLike) -> SignalArray:
+    """Preserve real or complex values while normalizing the dtype."""
+
+    if np.iscomplexobj(values):
+        return as_complex_array(values)
+
+    return as_real_array(values)

csiphon/core/axes.py

@@ -0,0 +1,162 @@
+"""Named tensor axes; mostly for semantics-based processing (vs. raw axis numbers)
+
+An Axis is a named tensor dimension. Steps address dimensions by name
+(`AxisName.SUBCARRIER`), never by integer position, so unrelated dimensions can
+sit in any order.
+
+Size and coordinates come in three cases:
+
+- Statically sized.
+    `size` and (optionally) `coordinates` are known at compile time from the
+    profile and each step's config: subcarriers, delay taps, dyadic bands,
+    the frequency bins of a windowed FFT, and so on.
+- Runtime sized.
+    `size is None` because the length only shows up once data arrives.
+    Not just time: the number of SST frequency bins depends on the recording
+    length, so that axis is runtime sized and carries its coordinates on the
+    Signal (`coords`) instead of in the layout. Any number of axes can be
+    runtime sized.
+- The time axis, named AxisName.TIME.
+    Its coordinates ride with the data as `Signal.times`. It is runtime sized
+    too, since you don't know a recording's or a stream's length up front. A
+    layout has at most one time axis.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+
+from csiphon.core.errors import LayoutError
+
+# The axis name gives a dimension its semantics.
+# Its coordinates give each position along it a physical meaning.
+# For example:
+#   - the exact frequency values along a `FREQUENCY` axis
+#   - the subcarrier index each `SUBCARRIER` position corresponds to.
+# Any hashable value works; axes with no meaningful label (eg. PCA components)
+# just use their integer index.
+type Coordinate = Hashable
+
+
+class AxisName(StrEnum):
+    """Semantic dimensions used by CSI preprocessing steps.
+
+    A curated, closed set (which we might extend)
+    The fixed vocabulary keeps describe() and cross-step validation type-safe.
+    The spatial names describe a general MIMO / multi-device capture,
+    such as (receivers, transmit/receive antennas, spatial streams).
+
+    When a step produces a genuinely new kind of dimension (say, reducing subcarriers
+    to abstract components), pick the closest name here (`COMPONENT`, `FEATURE`, or
+    `LATENT` for learned reductions) rather than mislabelling the output. Add a
+    member when you need a new physical dimension.
+    """
+
+    # fmt: off
+    # time
+    TIME           = "time"
+
+    # spatial (MIMO / multi-device)
+    RECEIVER       = "receiver"        # receiver device, for a multi-device capture
+    RX_ANTENNA     = "rx_antenna"      # receive antenna
+    TX_ANTENNA     = "tx_antenna"      # transmit antenna
+    SPATIAL_STREAM = "spatial_stream"  # spatial stream (Nss)
+
+    # spectral / delay / doppler
+    SUBCARRIER     = "subcarrier"
+    FREQUENCY      = "frequency"
+    DELAY          = "delay"
+    DOPPLER        = "doppler"
+    BAND           = "band"
+    WAVELET_BAND   = "wavelet_band"
+    LAG            = "lag"
+
+    # derived / learned
+    COMPONENT      = "component"        # e.g. a PCA component
+    LATENT         = "latent"
+    FEATURE        = "feature"          # several axes folded into one
+    # fmt: on
+
+
+@dataclass(frozen=True, slots=True)
+class Axis:
+    """One named tensor dimension.
+
+    `size` is `None` when the length is only known at run time (the time axis, or
+    an axis like the SST frequency bins whose count depends on the data).
+
+    Statically sized axes provide a positive `size` and, optionally, matching
+    `coordinates`.
+    """
+
+    # fmt: off
+    name        : AxisName
+    size        : int | None
+    coordinates : tuple[Coordinate, ...] | None = None
+    unit        : str | None                    = None
+    # fmt: on
+
+    def __post_init__(self) -> None:
+        """Validate the size / coordinates relationship."""
+
+        if self.size is None:
+            if self.coordinates is not None:
+                raise LayoutError(
+                    f"Dynamic axis '{self.name}' must not carry coordinates."
+                )
+            return
+
+        if self.size < 1:
+            raise LayoutError(f"Axis '{self.name}' must have a positive size.")
+
+        if self.coordinates is not None and len(self.coordinates) != self.size:
+            raise LayoutError(
+                f"Axis '{self.name}' has {len(self.coordinates)} coordinates "
+                f"but size {self.size}."
+            )
+
+    # -------------------------------------------------------------------------
+    # Properties
+    # -------------------------------------------------------------------------
+    @property
+    def is_dynamic(self) -> bool:
+        """Return whether the size is only known at runtime (`size is None`)."""
+
+        return self.size is None
+
+    # -------------------------------------------------------------------------
+    # Constructors
+    # -------------------------------------------------------------------------
+    @classmethod
+    def dynamic(cls, name: AxisName = AxisName.TIME, unit: str | None = "s") -> Axis:
+        """Create the dynamic time / window axis."""
+
+        return cls(name=name, size=None, coordinates=None, unit=unit)
+
+    @classmethod
+    def static(
+        cls,
+        name: AxisName,
+        coordinates: Sequence[Coordinate],
+        unit: str | None = None,
+    ) -> Axis:
+        """Create a static axis from explicit coordinates."""
+
+        values = tuple(coordinates)
+        return cls(name=name, size=len(values), coordinates=values, unit=unit)
+
+    @classmethod
+    def sized(cls, name: AxisName, size: int, unit: str | None = None) -> Axis:
+        """Create a static axis of a known size without explicit coordinates."""
+
+        return cls(name=name, size=size, coordinates=None, unit=unit)
+
+    # -------------------------------------------------------------------------
+    # Transformations
+    # -------------------------------------------------------------------------
+    def relabel(self, coordinates: Sequence[Coordinate]) -> Axis:
+        """Return this axis with new coordinates (and matching size)."""
+
+        return Axis.static(self.name, coordinates, unit=self.unit)

csiphon/core/errors.py

@@ -0,0 +1,35 @@
+"""Exceptions raised by layouts, steps, and pipeline compilation."""
+
+from __future__ import annotations
+
+
+class LayoutError(ValueError):
+    """A signal layout does not satisfy a step's structural requirements."""
+
+
+class DataError(ValueError):
+    """Numerical values violate an assumption checked during execution."""
+
+
+class CompileError(ValueError):
+    """A pipeline step is incompatible with the layout before it."""
+
+
+class StreamingError(ValueError):
+    """A pipeline (or one of its steps) cannot run in streaming mode."""
+
+
+class ClogError(StreamingError):
+    """A merge branch held too many samples without aligning (a stalled branch)."""
+
+
+class MissingDependencyError(ImportError):
+    """A step needs an optional dependency that is not installed."""
+
+    def __init__(self, package: str, extra: str) -> None:
+        """Explain which extra to install for the missing dependency."""
+
+        super().__init__(
+            f"This step requires the optional dependency '{package}'. "
+            f"Install it with:  pip install 'csiphon[{extra}]'"
+        )

csiphon/core/layout.py

@@ -0,0 +1,211 @@
+"""The structural contract carried through a pipeline.
+
+A Layout is the structure of a signal: its ordered named axes and their semantics.
+It does not hold the recording's timestamps or data.
+
+A pipeline is "compiled" against an `AcquisitionProfile` (antennas, subcarriers,
+bandwidth, ...), which builds this layout. Because the layout carries no
+per-recording data, one compiled pipeline then works for every recording from
+that profile, and for an unbounded live stream where we don't know the
+timestamps up front.
+
+The concrete data and timestamps live on the runtime Signal.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, replace
+
+from csiphon.core.axes import Axis, AxisName
+from csiphon.core.errors import LayoutError
+from csiphon.core.semantics import Representation, ValueKind
+
+
+@dataclass(frozen=True, slots=True)
+class Layout:
+    """Axes and semantic information known before numerical execution."""
+
+    # fmt: off
+    axes           : tuple[Axis, ...]
+    representation : Representation
+    values         : ValueKind
+    # fmt: on
+
+    def __post_init__(self) -> None:
+        """Reject duplicate axis names.
+
+        An axis may have an unknown size (`size is None`) when it only resolves
+        at run time, like the SST frequency axis whose bin count depends on the
+        recording length.
+
+        The time axis (AxisName.TIME) is special: its coordinates are the
+        per-sample timestamps, and they live on the Signal (Signal.times), not
+        in the layout.
+        """
+
+        names = tuple(axis.name for axis in self.axes)
+        if len(names) != len(set(names)):
+            raise LayoutError("Every axis name must be unique within a signal.")
+
+    # -------------------------------------------------------------------------
+    # Introspection
+    # -------------------------------------------------------------------------
+
+    @property
+    def axis_names(self) -> tuple[AxisName, ...]:
+        """Return current semantic axes in tensor order."""
+
+        return tuple(axis.name for axis in self.axes)
+
+    @property
+    def shape(self) -> tuple[int | None, ...]:
+        """Return the tensor shape, with `None` for the dynamic axis."""
+
+        return tuple(axis.size for axis in self.axes)
+
+    @property
+    def dynamic_index(self) -> int | None:
+        """Return the position of the time axis, or `None` if there is none.
+
+        The time axis carries the timestamps on the Signal; every other
+        axis is fixed by the layout (even if its size is only known at run time).
+        """
+
+        for position, axis in enumerate(self.axes):
+            if axis.name == AxisName.TIME:
+                return position
+        return None
+
+    def axis(self, name: AxisName) -> Axis:
+        """Return one axis or fail with the available names."""
+
+        for axis in self.axes:
+            if axis.name == name:
+                return axis
+
+        available = ", ".join(self.axis_names) or "<none>"
+        raise LayoutError(
+            f"Required axis '{name}' is missing. Available axes: {available}."
+        )
+
+    def axis_position(self, name: AxisName) -> int:
+        """Return the current tensor position of a named axis."""
+
+        for position, axis in enumerate(self.axes):
+            if axis.name == name:
+                return position
+
+        # The axis is missing: this call raises with a helpful message. The
+        # AssertionError after it never runs; it is only here so the type checker
+        # sees that this branch cannot fall through without a return.
+        self.axis(name)
+        raise AssertionError("")
+
+    def has_axis(self, name: AxisName) -> bool:
+        """Return whether an axis with this name exists."""
+
+        return name in self.axis_names
+
+    # -------------------------------------------------------------------------
+    # Requirements (used by Step.output_layout)
+    # -------------------------------------------------------------------------
+
+    def require_values(self, allowed: Iterable[ValueKind]) -> None:
+        """Fail when current value semantics are unsupported."""
+
+        allowed_values = tuple(allowed)
+        if self.values in allowed_values:
+            return
+
+        expected = ", ".join(value.value for value in allowed_values)
+        raise LayoutError(f"Expected {expected}; received {self.values.value}.")
+
+    def require_representation(self, allowed: Iterable[Representation]) -> None:
+        """Fail when the current scientific representation is unsupported."""
+
+        allowed_reprs = tuple(allowed)
+        if self.representation in allowed_reprs:
+            return
+
+        expected = ", ".join(value.value for value in allowed_reprs)
+        raise LayoutError(
+            f"Expected representation {expected}; received {self.representation.value}."
+        )
+
+    def require_axis(self, name: AxisName) -> Axis:
+        """Return a required axis (raising a helpful error if absent)."""
+
+        return self.axis(name)
+
+    def require_axis_absent(self, name: AxisName) -> None:
+        """Fail when a step would create a duplicate axis."""
+
+        if name in self.axis_names:
+            raise LayoutError(f"Axis '{name}' already exists.")
+
+    def require_static_axis(self, name: AxisName) -> Axis:
+        """Return a required axis, failing if it is the dynamic axis."""
+
+        axis = self.axis(name)
+        if axis.is_dynamic:
+            raise LayoutError(f"Axis '{name}' must be static for this step.")
+        return axis
+
+    # -------------------------------------------------------------------------
+    # Transformations (return new layouts)
+    # -------------------------------------------------------------------------
+
+    def with_values(self, values: ValueKind) -> Layout:
+        """Return this layout with different value semantics."""
+
+        return replace(self, values=values)
+
+    def with_representation(self, representation: Representation) -> Layout:
+        """Return this layout with a different representation."""
+
+        return replace(self, representation=representation)
+
+    def replace_axis(self, old_name: AxisName, new_axis: Axis) -> Layout:
+        """Replace an axis without changing its tensor position."""
+
+        if new_axis.name != old_name:
+            self.require_axis_absent(new_axis.name)
+
+        position = self.axis_position(old_name)
+        axes = list(self.axes)
+        axes[position] = new_axis
+        return replace(self, axes=tuple(axes))
+
+    def insert_axis_after(self, existing: AxisName, new_axis: Axis) -> Layout:
+        """Insert a new axis directly after an existing one."""
+
+        self.require_axis_absent(new_axis.name)
+        position = self.axis_position(existing) + 1
+        axes = list(self.axes)
+        axes.insert(position, new_axis)
+        return replace(self, axes=tuple(axes))
+
+    def remove_axes(self, names: Sequence[AxisName]) -> Layout:
+        """Remove named axes while preserving remaining order."""
+
+        target = set(names)
+        for name in target:
+            # Raise now if any named axis is missing, before we drop anything.
+            self.axis(name)
+        remaining = tuple(axis for axis in self.axes if axis.name not in target)
+        return replace(self, axes=remaining)
+
+    def set_axes(self, axes: Sequence[Axis]) -> Layout:
+        """Return this layout with an explicit new axis tuple."""
+
+        return replace(self, axes=tuple(axes))
+
+    def describe_axes(self) -> str:
+        """Return a compact human-readable axis summary."""
+
+        parts: list[str] = []
+        for axis in self.axes:
+            size = "?" if axis.size is None else str(axis.size)
+            parts.append(f"{axis.name}[{size}]")
+        return ", ".join(parts) or "<scalar>"