Metadata-Version: 2.4
Name: csiphon
Version: 0.3.1
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"
Requires-Dist: numpy<2.5; 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="400"
  >
</p>

# csiphon

`csiphon` is a Python library for preprocessing WiFi Channel State Information.
You plug DSP steps together into a pipeline, csiphon checks that the pieces fit
before you run anything, and the finished pipeline handles recordings and live
streams alike. Every signal carries its axes by name, so you never have to
wonder which one was the subcarrier again.

```python
from csiphon import AcquisitionProfile, Pipeline
from csiphon.steps import GainNormalize, Magnitude, WindowedVariance

# Describe the capture setup
profile = AcquisitionProfile(
    n_rx_antennas=3,
    subcarrier_indices=tuple(range(52)),
    sampling_rate_hz=1000.0,
)

# Define the pipeline steps
siphon = (
    Pipeline()
    .then(Magnitude())
    .then(GainNormalize())
    .then(WindowedVariance(win_size_s=0.1))
    .compile(profile)
)

# Generate a summary of the pipeline
print(siphon.describe())

# Push some data through it to run
features = siphon.pour(profile.raw_signal(csi, timestamps)).single()
```

A compiled pipeline is a `Siphon`. You `pour()` a recording through it or
`stream()` live data, and collect results from named `Outlets`, which you can tap
anywhere along the pipeline.

## 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.
- **Merges receivers.** Feed several receivers through their own inlets and line
  them up on timestamps or on packet sequence numbers, which survive clock drift.
- **Keeps real timestamps.** Non-uniform CSI sampling is expected; resampling is
  explicit rather than silently assumed. You can also drop packets on purpose,
  with independent or bursty loss, to test how a pipeline copes.
- **Describes itself.** `describe()` draws a compiled siphon as a data-flow graph
  in the terminal. Steps and siphons expose their contracts, layouts, parameters,
  and streaming behavior, and can save that information alongside results for
  reproducibility.
- **Measures itself.** `siphon.measure(signal)` pours once and reports each
  step's time and output shape (memory on request), per step or for a named
  group of consecutive steps.

Ready-made steps cover the usual CSI preprocessing stuff, from calibration and
filtering to Doppler, temporal features, dimensionality reduction and resampling.
See the [steps README](https://github.com/nzqo/csiphon/blob/main/src/csiphon/steps/README.md)
for the full list. Custom steps use the same pipeline contracts.


## Install

```bash
pip install csiphon
```

The core only depends on NumPy. A few steps (filters, STFT, multitaper,
cubic-spline resampling) need the `[filters]` extra (SciPy), and the
synchrosqueezed transform needs `[sst]`. Install everything with:

```bash
pip install "csiphon[all]"
```

Runnable recipes live in [`examples/`](https://github.com/nzqo/csiphon/tree/main/examples).
