# CSI timestamp-gap spectral sensitivity

This package measures how timestamp gaps in the public Router CSI Lab capture
change two spectral-analysis workflows.

## Input

- Dataset DOI: <https://doi.org/10.5281/zenodo.23434789>
- Public de-identified capture SHA-256:
  `527466ceb8b5f835e55ff348f02808736b947db39e7baac1f34e375de146a440`
- Duration: 599.924 s
- Usable measurement groups: 7,608
- Selected chain: `tx0/rx0` in all 7,608 groups

The source capture contains no human-event or respiration ground truth.

## Files

| File | Purpose |
| :--- | :--- |
| `analyze_csi_gap_spectrum.py` | NumPy-only analysis and dependency-free SVG figure generator |
| `summary.json` | Machine-readable results and explicit limitations |
| `frequency_sweep.csv` | Synthetic-control error from 0.10 to 0.50 Hz |
| `SHA256SUMS` | Checksums for this package |
| `../../../img/csi-gap-spectrum.svg` | Four-panel figure used by the article |

## Run

Python 3.9+ and NumPy are sufficient. Matplotlib and SciPy are not required.

```bash
python3 analyze_csi_gap_spectrum.py csi-10m.anon.bin \
  --summary summary.json \
  --csv frequency_sweep.csv \
  --img csi-gap-spectrum.svg
```

Expected key output:

```text
usable_groups: 7608
duration_s: 599.924
synthetic_interpolation_error_rms: 0.099658019
actual_naive_peak_hz: 0.068359
actual_ls_peak_hz: 0.145
```

## Method

1. Group chain records only at `chain_info` bit 15.
2. Keep complete 256-subcarrier, non-zero-I/Q groups.
3. Prefer `tx0/rx0`; otherwise select the valid chain with highest mean amplitude.
4. Reduce the selected chain to mean amplitude across 256 subcarriers.
5. Compare:
   - linear interpolation to 10 Hz followed by a Hann-Welch PSD;
   - a least-squares sinusoid fit on the original uneven timestamps;
   - unit-amplitude 0.10-0.50 Hz sinusoids sampled at the real timestamps.

The least-squares implementation is deliberately small and transparent. It is
in the Lomb-Scargle family, but this package does not claim a new statistical
significance test.

## Results

- 224 intervals exceed 0.5 s; 57 exceed 1.0 s; the maximum is 2.373 s.
- Of 6,000 uniform 10 Hz grid points, 1,823 (30.383%) lie inside an interval
  longer than 0.5 s and therefore require interpolation.
- For a known 0.25 Hz signal on the real timestamps, interpolation has
  0.099658 RMS error, or 14.094% of the signal RMS. The irregular fit returns
  0.250 Hz.
- On the real CSI amplitude feature, the interpolated Welch and irregular fits
  peak at 0.068359 Hz and 0.145 Hz respectively. Without human ground truth,
  this proves estimator sensitivity, not which peak is physiological.

## Limits

- The synthetic control tests estimator behaviour; it is not breathing data.
- A single indoor capture does not establish behaviour across rooms, clients,
  traffic profiles or hardware.
- Agreement between two estimators is not external validation.
- No person, fall, occupancy or medical state is inferred.

## License

- Analysis script: MIT.
- Derived JSON, CSV, README and figure: CC BY 4.0.
- Source CSI capture: CC BY 4.0 via the Zenodo DOI above.