SII-kejia/AirFM-DDA-dataset

---
pretty_name: AirFM-DDA Dataset
size_categories:
- 10K<n<100K
tags:
- wireless
- csi
- deepmimo
- pytorch
---

# AirFM-DDA Dataset

## Dataset Summary

This repository contains the precomputed CSI evaluation set used by the AirFM-DDA validation pipeline.

The data is derived from the processed DeepMIMO `test` split and stores binary PyTorch sample files under `samples/`, together with a root-level `manifest.json` that records sample ordering, split metadata, and per-sample paths.

This repository is intended to be used together with the model checkpoints in:

- `https://huggingface.co/SII-kejia/AirFM-DDA-Model`

## What Is Included

Current repository contents:

- `samples/`: precomputed CSI samples stored as `.pt` files
- `manifest.json`: dataset manifest used by the released validation loader
- `.gitattributes`: Hugging Face LFS tracking metadata
- `README.md`: this dataset card

Dataset scale:

- Total saved samples: `47,256`
- Approximate on-disk size: `122 GB`
- Save dtype: `float32`
- Maximum temporal length (`T`): `80`
- Maximum subcarrier coverage (`K`): `128`

Per-folder counts:

| Folder | Samples |
|---|---:|
| `samples/city_18_denver_3p5/cfg1` | 8,863 |
| `samples/city_18_denver_3p5/cfg2` | 8,863 |
| `samples/city_19_oklahoma_3p5/cfg1` | 8,222 |
| `samples/city_19_oklahoma_3p5/cfg2` | 8,222 |
| `samples/city_23_beijing_3p5/cfg1` | 4,570 |
| `samples/city_23_beijing_3p5/cfg2` | 4,570 |
| `samples/city_27_rio_de_janeiro_3p5/cfg1` | 1,973 |
| `samples/city_27_rio_de_janeiro_3p5/cfg2` | 1,973 |

## Source and Generation Settings

The current release was generated with the following recorded settings from `manifest.json`:

- Source multipath root: processed DeepMIMO `test` data
- Frame configuration file: `frame_structure_configs_test2.yaml`
- Validation ratio: `0.1`
- Split seed: `42`
- CSI generation seed: `59`
- Number of paths used in CSI generation: `25`
- Storage layout: `samples/<city_folder>/<cfg_name>/csi_sample_XXXXXXXX.pt`

This repository stores precomputed evaluation artifacts, not the original raw DeepMIMO source files.

## Directory Layout

```text
AirFM-DDA-dataset/
├── README.md
├── manifest.json
└── samples/
├── city_18_denver_3p5/
│ ├── cfg1/
│ └── cfg2/
├── city_19_oklahoma_3p5/
│ ├── cfg1/
│ └── cfg2/
├── city_23_beijing_3p5/
│ ├── cfg1/
│ └── cfg2/
└── city_27_rio_de_janeiro_3p5/
├── cfg1/
└── cfg2/
```

## Sample Format

Each `.pt` file stores one serialized PyTorch dictionary with the following keys:

- `CSI_sample`: saved CSI tensor
- `mask_TK`: boolean mask tensor
- `Rx_ant_ind`: receive-antenna index tensor
- `cfg_tensor`: frame/configuration tensor
- `meta`: per-sample metadata dictionary

The released validation code expects:

- `CSI_sample` to have shape `[2, T, K, S]`
- `manifest.json` to exist at the dataset root
- `manifest["samples"][i]["relative_path"]` to point to the corresponding `.pt` file

The manifest additionally records, for every sample:

- `sample_index`
- `relative_path`
- `source_val_index`
- `source_batch_index`
- `source_in_batch`
- `shape_key`
- `city_folder`
- `cfg_name`
- `row_index`
- `cfg_index`

## Recommended Usage

### Option 1: Download with Hugging Face CLI

```bash
hf download SII-kejia/AirFM-DDA-dataset --repo-type dataset --local-dir ./AirFM-DDA-dataset
```

After downloading, the local directory should contain both:

- `./AirFM-DDA-dataset/manifest.json`
- `./AirFM-DDA-dataset/samples/`

### Option 2: Download from Python

```python
from huggingface_hub import snapshot_download

snapshot_download(
repo_id="SII-kejia/AirFM-DDA-dataset",
repo_type="dataset",
local_dir="./AirFM-DDA-dataset",
)
```

### Option 3: Load One Sample with PyTorch

```python
import json
from pathlib import Path
import torch

root = Path("./AirFM-DDA-dataset")
manifest = json.loads((root / "manifest.json").read_text(encoding="utf-8"))
first_rel_path = manifest["samples"][0]["relative_path"]
sample = torch.load(root / first_rel_path, map_location="cpu", weights_only=False)

print(sample.keys())
print(sample["CSI_sample"].shape)
print(sample["mask_TK"].dtype)
```

## Using with the Released Validation Pipeline

The AirFM-DDA validation pipeline in the released codebase expects a dataset root containing `manifest.json` and `samples/` exactly as provided here.

A matching loader looks up the root manifest and then loads individual files using `relative_path`. In other words, point the validation code to the dataset root, not directly to `samples/`.

## Notes and Limitations

- This is a binary artifact dataset composed of `.pt` files, so the Hugging Face dataset viewer is not expected to provide an interactive table preview.
- This release is designed for AirFM-DDA evaluation and reproducible validation, not as a raw-source DeepMIMO redistribution.
- The repository currently contains the precomputed evaluation split used by the AirFM-DDA workflow; it is not presented as a full train/val/test benchmark package.