QUICKSTART TUTORIAL

Convert one WiFi sensing dataset into research-ready tensors.

This tutorial starts with a zero-download synthetic fixture, then shows the same command pattern for real official releases. The output is compressed NumPy .npz plus provenance, quality, and split manifests.

Run zero-download demo View embedded notebook Download notebook

Install

Create a clean Python environment and install WiSenseHub in editable mode.

Prepare

Put an official dataset release under data/<dataset-id>/original/ without renaming files.

Convert

Run one unified prepare command while choosing split and view settings.

Inspect

Load the generated .npz arrays and check metadata before training a model.

STEP 1

Run the zero-download demo

This proves the standardization pipeline works before you touch a large research dataset.

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

python examples/make_synthetic_input.py
python -m wifi_datahub standardize \
  --input examples/data/synthetic_csi.csv \
  --output examples/data/standardized/synthetic_csi.npz \
  --dataset-id synthetic-demo \
  --sample-rate 100 \
  --duration 4

python -m wifi_datahub quality \
  --input examples/data/standardized/synthetic_csi.npz \
  --output examples/data/standardized/synthetic_csi.quality.json

STEP 2

Use a real dataset release

Download from the official source, extract it into the expected folder, then let the dataset adapter handle discovery.

data/ut-har/
├── original/       # official downloaded files
├── standardized/   # generated native NPZ tensors
├── standardized/views/  # optional fixed-shape derived views
├── reports/        # quality reports
├── splits/         # train/val/test manifests
└── prepare-manifest.json

python -m wifi_datahub settings ut-har

python -m wifi_datahub prepare ut-har \
  --setting official \
  --data-root data \
  --target-length 128 \
  --layout link-subcarrier \
  --interpolation linear

STEP 3

Choose split and tensor settings

WiSenseHub keeps native standardized data and optionally derives fixed-size views for model training.

Option	Purpose	Example
`--setting`	Evaluation protocol such as official, random, cross-subject, or cross-device.	`--setting cross_subject --holdout 3`
`--target-rate`	Resample a derived view to a fixed Hz when timestamps support it.	`--target-rate 100`
`--target-length`	Pad/crop/interpolate to a fixed number of time steps.	`--target-length 128`
`--interpolation`	Select none, nearest, or linear interpolation.	`--interpolation linear`
`--layout`	Keep canonical axes or flatten link/subcarrier dimensions.	`--layout flat`

STEP 4

Load the output in Python

The model-facing artifact is NumPy, not a hidden framework tensor. You can convert it to PyTorch, TensorFlow, or JAX later.

import json
import numpy as np

sample = np.load("data/ut-har/standardized/views/example.view.npz")
print(sample.files)
print(sample["amplitude"].shape)
print(sample["valid_mask"].mean())

with open("data/ut-har/prepare-manifest.json") as f:
    manifest = json.load(f)
print(manifest["split"]["partition_counts"])

Key idea

Native files preserve dataset-specific information; derived views make training convenient. This separation prevents the hub from pretending all WiFi datasets are naturally collected with the same sampling rate, antennas, or subcarriers.

NOTEBOOK

When should we use Jupyter?

Use the notebook for an interactive demo or interview walkthrough; keep the web tutorial as stable public documentation.

GitHub Pages tutorial

Best for quick review, copy-paste commands, and explaining the hub structure to new users.

Embedded notebook

Best for showing code cells, expected outputs, and the NumPy tensor contract directly inside the website.

Open full notebook view

IN-PAGE NOTEBOOK

Notebook preview embedded in the Hub

This static viewer renders the checked-in Jupyter notebook on GitHub Pages. It is visualization-first; live execution can be added later with JupyterLite or Binder.