csiphon 0.1.0__tar.gz

csiphon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabian Portner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

csiphon-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: csiphon
+Version: 0.1.0
+Summary: An online-first, schema-validated CSI preprocessing pipeline library.
+Author: Fabian Portner
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nzqo/csiphon
+Project-URL: Repository, https://github.com/nzqo/csiphon
+Project-URL: Issues, https://github.com/nzqo/csiphon/issues
+Keywords: csi,wifi,channel-state-information,dsp,signal-processing,doppler,streaming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.1
+Provides-Extra: sst
+Requires-Dist: ssqueezepy>=0.6; extra == "sst"
+Provides-Extra: filters
+Requires-Dist: scipy>=1.11; extra == "filters"
+Provides-Extra: all
+Requires-Dist: csiphon[filters,sst]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: polars; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build; extra == "release"
+Requires-Dist: twine; extra == "release"
+Dynamic: license-file
+
+<p align="center">
+  <img
+    src="https://raw.githubusercontent.com/nzqo/csiphon/main/assets/ai_slop_mascot.png"
+    alt="slop Kanna doing Wi-Fi plumbing"
+    width="300"
+  >
+</p>
+
+# csiphon
+
+`csiphon` is an online-first processing library for WiFi Channel State
+Information. Compose reusable DSP steps, compile them against your capture
+setup, then pour a complete recording or stream live chunks through the same
+validated pipeline.
+
+```python
+from csiphon import AcquisitionProfile, Pipeline
+from csiphon.steps import GainNormalize, Magnitude, WindowedVariance
+
+profile = AcquisitionProfile(
+    n_rx_antennas=3,
+    subcarrier_indices=tuple(range(52)),
+    sampling_rate_hz=1000.0,
+)
+
+siphon = (
+    Pipeline()
+    .then(Magnitude())
+    .then(GainNormalize())
+    .then(WindowedVariance(win_size_s=0.1))
+    .compile(profile)
+)
+
+features = siphon.pour(profile.raw_signal(csi, timestamps)).single()
+```
+
+## What it does
+
+- **Catches structural mistakes before execution.** Compilation checks axes,
+  shapes, value semantics, and physical representations before data starts
+  flowing.
+- **Runs the same recipe in batch or live.** Every step states whether its
+  streaming computation matches batch, differs intentionally, or requires the
+  complete recording.
+- **Supports branching pipelines.** Split into parallel feature paths, merge
+  them again, and expose named intermediate outlets.
+- **Keeps real timestamps.** Non-uniform CSI sampling is expected; resampling is
+  explicit rather than silently assumed.
+- **Describes itself.** Steps and compiled siphons expose their contracts,
+  layouts, parameters, and streaming behavior, and can save that information
+  alongside results for reproducibility.
+
+The built-in steps cover calibration, cleaning, filtering, delay and
+time-frequency transforms, temporal features, pooling, statistics, reduction,
+and restructuring. Custom steps use the same contracts and inspection tools.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+The core only depends on NumPy. Install every optional transform with:
+
+```bash
+pip install -e ".[all]"
+```
+
+Runnable recipes live in [`examples/`](examples/).

csiphon-0.1.0/README.md

@@ -0,0 +1,69 @@
+<p align="center">
+  <img
+    src="https://raw.githubusercontent.com/nzqo/csiphon/main/assets/ai_slop_mascot.png"
+    alt="slop Kanna doing Wi-Fi plumbing"
+    width="300"
+  >
+</p>
+
+# csiphon
+
+`csiphon` is an online-first processing library for WiFi Channel State
+Information. Compose reusable DSP steps, compile them against your capture
+setup, then pour a complete recording or stream live chunks through the same
+validated pipeline.
+
+```python
+from csiphon import AcquisitionProfile, Pipeline
+from csiphon.steps import GainNormalize, Magnitude, WindowedVariance
+
+profile = AcquisitionProfile(
+    n_rx_antennas=3,
+    subcarrier_indices=tuple(range(52)),
+    sampling_rate_hz=1000.0,
+)
+
+siphon = (
+    Pipeline()
+    .then(Magnitude())
+    .then(GainNormalize())
+    .then(WindowedVariance(win_size_s=0.1))
+    .compile(profile)
+)
+
+features = siphon.pour(profile.raw_signal(csi, timestamps)).single()
+```
+
+## What it does
+
+- **Catches structural mistakes before execution.** Compilation checks axes,
+  shapes, value semantics, and physical representations before data starts
+  flowing.
+- **Runs the same recipe in batch or live.** Every step states whether its
+  streaming computation matches batch, differs intentionally, or requires the
+  complete recording.
+- **Supports branching pipelines.** Split into parallel feature paths, merge
+  them again, and expose named intermediate outlets.
+- **Keeps real timestamps.** Non-uniform CSI sampling is expected; resampling is
+  explicit rather than silently assumed.
+- **Describes itself.** Steps and compiled siphons expose their contracts,
+  layouts, parameters, and streaming behavior, and can save that information
+  alongside results for reproducibility.
+
+The built-in steps cover calibration, cleaning, filtering, delay and
+time-frequency transforms, temporal features, pooling, statistics, reduction,
+and restructuring. Custom steps use the same contracts and inspection tools.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+The core only depends on NumPy. Install every optional transform with:
+
+```bash
+pip install -e ".[all]"
+```
+
+Runnable recipes live in [`examples/`](examples/).

csiphon-0.1.0/pyproject.toml

@@ -0,0 +1,101 @@
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "csiphon"
+version = "0.1.0"
+description = "An online-first, schema-validated CSI preprocessing pipeline library."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Fabian Portner" }]
+keywords = [
+    "csi",
+    "wifi",
+    "channel-state-information",
+    "dsp",
+    "signal-processing",
+    "doppler",
+    "streaming",
+]
+
+# Trove classifiers for the PyPI page. No `License ::` classifier: the SPDX
+# `license` field above supersedes it (setuptools >= 77 rejects using both).
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Typing :: Typed",
+]
+
+# Core dependencies (pretty lean)
+dependencies = ["numpy>=2.1"]
+
+# Optional dependencies (required for specific steps only)
+[project.optional-dependencies]
+sst = ["ssqueezepy>=0.6"]
+filters = ["scipy>=1.11"]
+
+# Every optional feature at once (a self-reference to the extras above).
+all = ["csiphon[sst,filters]"]
+dev = ["pytest", "mypy", "ruff", "pyright", "pylint", "polars"]
+# Tooling for building and uploading the package to PyPI.
+release = ["build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/nzqo/csiphon"
+Repository = "https://github.com/nzqo/csiphon"
+Issues = "https://github.com/nzqo/csiphon/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+csiphon = ["py.typed"]
+
+[tool.mypy]
+strict = true
+python_version = "3.12"
+
+# Optional third-party dependencies ship no type information.
+[[tool.mypy.overrides]]
+module = ["ssqueezepy.*", "scipy.*"]
+ignore_missing_imports = true
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+
+# mypy --strict is the library's strict type gate (see [tool.mypy]).
+# pyright runs at basic so numpy's shape-Any typing and unannotated
+# pytest fixtures don't drown the editor in noise while still catching
+# real mistakes.
+typeCheckingMode = "basic"
+
+# scipy / ssqueezepy ship no type stubs.
+reportMissingModuleSource = false
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "ANN"]
+
+# RUF001-003: arrows / ∈ / ² in human-facing docstrings and spec strings are
+# intentional, not ambiguous-unicode mistakes.
+ignore = ["RUF001", "RUF002", "RUF003"]
+
+[tool.ruff.lint.per-file-ignores]
+# Test fixtures and parametrized args are conventionally left unannotated.
+"tests/**" = ["ANN001", "ANN002", "ANN003"]
+
+[tool.pylint.messages_control]
+# Ruff (its formatter for code + E501/noqa for prose) is the single line-length
+# authority; pylint's line-too-long would double-report and ignores ruff's noqa.
+disable = ["line-too-long"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

csiphon-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

csiphon-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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}]'"
+        )