README.md

---
title: README
emoji: 📚
colorFrom: yellow
colorTo: red
sdk: static
pinned: false
license: apache-2.0
---

# CSI-4CAST Organization

Welcome to the CSI-4CAST organization on Hugging Face! This organization hosts datasets for CSI prediction research.
This dataset is originally created for our research paper: [CSI-4CAST: A Hybrid Deep Learning Model for CSI Prediction with Comprehensive Robustness and Generalization Testing](https://arxiv.org/abs/2510.12996). The corresponding code and implementation are available in our [GitHub repo](https://github.com/AI4OPT/CSI-4CAST).

## TL;DR

**Quick Start Options:**

- **For specific datasets**: Use the `snapshot_download` command to download individual datasets you need
- **For all datasets with original structure**: Run [`download.py`](https://huggingface.co/spaces/CSI-4CAST/README/blob/main/download.py)  followed by [`reconstruction.py`](https://huggingface.co/spaces/CSI-4CAST/README/blob/main/reconstruction.py) to get the complete, well-structured dataset

See the **Usage** section below for detailed instructions.

## Dataset Structure

The datasets are organized in the following structure:

```
data/
├── stats/
│   ├── fdd/
│   │   └── normalization_stats.pkl
│   └── tdd/
│       └── normalization_stats.pkl
├── test/
│   ├── generalization/
│   │   ├── cm_A_ds_030_ms_001/
│   │   │   ├── H_D_pred.pt
│   │   │   ├── H_U_hist.pt
│   │   │   └── H_U_pred.pt
│   │   ├── cm_B_ds_030_ms_001/
│   │   ├── cm_C_ds_030_ms_001/
│   │   ├── cm_D_ds_030_ms_001/
│   │   ├── cm_E_ds_030_ms_001/
│   │   └── ...
│   └── regular/
│       ├── cm_A_ds_030_ms_001/
│       │   ├── H_D_pred.pt
│       │   ├── H_U_hist.pt
│       │   └── H_U_pred.pt
│       ├── cm_C_ds_030_ms_001/
│       ├── cm_D_ds_030_ms_001/
│       └── ...
└── train/
    └── regular/
        ├── cm_A_ds_030_ms_001/
        │   ├── H_D_pred.pt
        │   ├── H_U_hist.pt
        │   └── H_U_pred.pt
        ├── cm_C_ds_030_ms_001/
        ├── cm_D_ds_030_ms_001/
        └── ...
```

## Dataset Organization Strategy

Our datasets are organized using a **convenience-first naming strategy** on Hugging Face. Instead of uploading the entire data folder as one large dataset, we've split it into individual datasets with descriptive names. This approach allows users to:

- **Download only the specific data they need** (e.g., just one configuration or test type)
- **Easily identify datasets** by their purpose and configuration
- **Reduce download time and storage** by avoiding unnecessary data
- **Enable selective loading** for different research scenarios

### Available Datasets

#### Statistics Dataset
- **stats**: Contains normalization statistics for FDD and TDD configurations

#### Test Datasets  
- **test_regular_***: Regular test data for various configurations
- **test_generalization_***: Generalization test data with extended parameter ranges

#### Training Datasets
- **train_regular_***: Training data for various configurations

### Dataset Naming Convention

The datasets follow this naming pattern:
- `[train/test]_[regular/generalization]_cm_[A/B/C/D/E]`: Dataset type and channel model
- `cm_[A/B/C/D/E]`: Channel models CDL-A, CDL-B, CDL-C, CDL-D, CDL-E
- `ds_[030/050/100/200/300/400]`: Delay spreads with values in ns
- `ms_[001/003/006/009/010/012/015/018/021/024/027/030/033/036/039/042/045]`: User speed with values in m/s

**Examples:**
- `test_regular_cm_A_ds_030_ms_001`: Regular test data for CDL-A model, 30ns delay spread, 1 m/s speed
- `train_regular_cm_C_ds_100_ms_030`: Training data for CDL-C model, 100ns delay spread, 30 m/s speed
- `test_generalization_cm_B_ds_200_ms_015`: Generalization test data for CDL-B model, 200ns delay spread, 15 m/s speed

## Usage

### Downloading Datasets

You can download individual datasets using the Hugging Face Hub:

```python
from huggingface_hub import snapshot_download

# Download the stats dataset
snapshot_download(repo_id="CSI-4CAST/stats", repo_type="dataset")

# Download a specific CSI prediction dataset
snapshot_download(repo_id="CSI-4CAST/test_regular_cm_A_ds_030_ms_001", repo_type="dataset")
```

### Downloading All Datasets

To download all available datasets at once, use the provided [`download.py`](https://huggingface.co/spaces/CSI-4CAST/README/blob/main/download.py) script:

```bash
# Download all datasets to a 'datasets' folder
python3 download.py

# Download to a custom directory
python3 download.py --output-dir my_datasets

# Dry run to test without downloading (creates empty placeholder files)
python3 download.py --dry-run
```

The script will automatically:
- Check for all possible dataset combinations
- Download only the datasets that exist on Hugging Face
- Create organized folder structure with descriptive names

### Reconstructing Original Folder Structure

While our naming strategy makes it easy to download specific datasets, you might want to work with the complete dataset in its original folder structure. For this purpose, we provide the [`reconstruction.py`](https://huggingface.co/spaces/CSI-4CAST/README/blob/main/reconstruction.py) script that restores the original organization:

```bash
python3 reconstruction.py --input-dir datasets --output-dir data
```

This script will:
1. Remove the prefixes (test_regular_, test_generalization_, train_regular_)
2. Organize the folders back into the original data structure
3. Create the proper hierarchy: data/stats/, data/test/regular/, data/test/generalization/, data/train/regular/

**When to use reconstruction:**
- You want to replicate the exact structure used in the original CSI-4CAST paper
- Your existing code expects the original folder organization
- You need the complete dataset in the original research structure

**Note:** Reconstruction is only necessary if you need to replicate the CSI-4CAST paper's results exactly. If you're working with individual datasets or don't need the specific folder structure, you can skip reconstruction and work directly with the downloaded datasets.

## File Types

Each dataset folder contains:
- `H_D_pred.pt`: Predicted H_D values (PyTorch tensor)
- `H_U_hist.pt`: Historical H_U values (PyTorch tensor)  
- `H_U_pred.pt`: Predicted H_U values (PyTorch tensor)

## Questions & Contributions

For further questions or any contribution suggestions, you can create pull requests here or to the [GitHub homepage](https://github.com/AI4OPT/CSI-4CAST) of this organization.

## Citation

```bibtex
@misc{cheng2025csi4casthybriddeeplearning,
      title={CSI-4CAST: A Hybrid Deep Learning Model for CSI Prediction with Comprehensive Robustness and Generalization Testing}, 
      author={Sikai Cheng and Reza Zandehshahvar and Haoruo Zhao and Daniel A. Garcia-Ulloa and Alejandro Villena-Rodriguez and Carles Navarro Manchón and Pascal Van Hentenryck},
      year={2025},
      eprint={2510.12996},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2510.12996}, 
}
```