Metadata-Version: 2.4
Name: comford
Version: 0.1.2
Summary: A Python framework for benchmarking indoor positioning algorithms on popular WiFi fingerprinting datasets
Author: Alessio Ferrato, Moises Ramires, Roman Klus, Antonino Crivello, Cristiano Pendão, Ivo Silva, Joaquín Torres-Sospedra, Grigorios G. Anagnostopoulos
License-Expression: MIT
Project-URL: Homepage, https://github.com/musica-maestro/comford
Project-URL: Repository, https://github.com/musica-maestro/comford
Project-URL: Issues, https://github.com/musica-maestro/comford/issues
Keywords: indoor-positioning,wifi,fingerprinting,rssi,benchmarking
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: tqdm
Requires-Dist: matplotlib
Requires-Dist: scikit-learn
Requires-Dist: openpyxl
Dynamic: license-file

# COMFORD

**COMFORD** is a Python library for benchmarking indoor positioning algorithms on popular datasets.

It currently provides two modules:

- **`comford.data`** — harmonized loading of 11 public WiFi fingerprinting datasets. Raw files are downloaded automatically, converted to a normalized intermediate format, and cached locally. A uniform interface exposes feature matrices and ground-truth coordinates as Pandas DataFrames regardless of the original file layout or coordinate system.
- **`comford.evaluation`** — standardized evaluation aligned with ISO/IEC 18305:2016 and the IPIN competition protocols. The `evaluate()` function accepts any DataFrame of predicted coordinates and returns 2-D, 3-D, floor, building, and IPIN-penalized metrics. `plot_cdf()` renders empirical CDF curves for direct visual comparison.

Training is intentionally left to the researcher: use scikit-learn, PyTorch, or any custom algorithm, then feed the predictions into the evaluation interface. The only requirement is that the output DataFrame contains the same coordinate columns as the ground truth.

---

## Overview

```
comford/
├── data/           # Dataset loading, downloading, and formatting
└── evaluation/     # Positioning error metrics and CDF visualization
examples/           # Jupyter notebooks and usage examples
```

---

## Getting Started

### Installation

```bash
pip install comford
```

Or install from source:

```bash
pip install git+https://github.com/musica-maestro/comford.git
# or, from a local clone:
pip install -e .
```


### Quick Example

Built-in datasets are downloaded automatically on first use and cached in `~/.comford/datasets/`.

```python
from comford.data import UJIDataset, TUJI1Dataset, DSIDataset

for dataset in [UJIDataset(), TUJI1Dataset(), DSIDataset()]:
    dataset.full_pipeline()
    validation_count = 0 if dataset.features_validation is None else len(dataset.features_validation)
    print(
        f"{dataset.name} — train: {len(dataset.features_train)}  validation: {validation_count}"
    )
```

See [`examples/tutorial_load_datasets.ipynb`](examples/tutorial_load_datasets.ipynb) for a walkthrough of dataset loading, and [`examples/tutorial_knn_all_datasets.ipynb`](examples/tutorial_knn_all_datasets.ipynb) for a full k-NN benchmark across all 11 datasets.

---

## Data Pipeline

COMFORD uses a three-stage data pipeline:

```
Raw Dataset  →  Intermediate Format  →  ML-Ready Format
(CSV, etc.)     (Samples, RSSI, APs)    (features + coordinates)
```

1. **Raw → Intermediate**: Parses dataset-specific raw files into a normalized relational format (three CSVs: `Samples.csv`, `RSSI.csv`, `APs.csv`).
2. **Intermediate → Final**: Reconstructs a flat feature matrix with one row per sample, one column per AP (undetected APs filled with a configurable value), plus separate coordinates columns (x, y, z, floor, building).

---

## Supported Datasets

| Class          | Source                                                                           | Description                                                       |
| -------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `UJIDataset`   | [UJIIndoorLoc (UCI)](https://archive.ics.uci.edu/ml/datasets/ujiindoorloc)       | Multi-building, multi-floor WiFi fingerprinting                   |
| `UTSDataset`   | [UTSIndoorLoc (GitHub)](https://github.com/XudongSong/UTSIndoorLoc-dataset)      | Multi-building, multi-floor WiFi fingerprinting                   |
| `TUJI1Dataset` | [TUJI1 (Zenodo 7641701)](https://zenodo.org/records/7641701)                     | Multi-device, fine-grained grid, single-floor WiFi fingerprinting |
| `DSIDataset`   | [DSI (Zenodo 3778646)](https://zenodo.org/records/3778646)                       | Radio map + trajectory WiFi fingerprinting, single-floor          |
| `TIE1Dataset`  | [TIE1 (Zenodo 5174851)](https://zenodo.org/records/5174851)                      | Heterogeneous indoor WiFi fingerprinting                          |
| `SAH1Dataset`  | [SAH1 (Zenodo 5174851)](https://zenodo.org/records/5174851)                      | Heterogeneous indoor WiFi fingerprinting                          |
| `TUT6Dataset`  | [TAU Zenodo 3819917](https://zenodo.org/records/3819917) — Building 01           | Single-floor WiFi fingerprinting (TUT campus)                     |
| `TUT7Dataset`  | [TAU Zenodo 3819917](https://zenodo.org/records/3819917) — Building 02           | Single-floor WiFi fingerprinting (TUT campus)                     |
| `SOD01Dataset` | [SODIndoorLoc (GitHub)](https://github.com/bijingxue/SODIndoorLoc) — CETC331     | Multi-floor WiFi fingerprinting                                   |
| `SOD02Dataset` | [SODIndoorLoc (GitHub)](https://github.com/bijingxue/SODIndoorLoc) — HCXY All_30 | Multi-floor WiFi fingerprinting                                   |
| `SOD06Dataset` | [SODIndoorLoc (GitHub)](https://github.com/bijingxue/SODIndoorLoc) — SYL All_30  | Multi-floor WiFi fingerprinting                                   |

---
## COMFORD Dataset Format Specification

COMFORD defines two complementary dataset formats:

- **Intermediate Format**: a canonical representation intended for data sharing, reproducibility, and interoperability.
- **ML Final Format**: a machine-learning-ready representation derived from the Intermediate Format through a deterministic transformation.
---

### 1. Intermediate Format

The Intermediate Format preserves the dataset structure without applying task-specific preprocessing. It stores samples, RSSI observations, and access point information in separate tables.

#### 1.1 `Sample.csv`

| Field | Type | Required | Description |
|---|---|:---:|---|
| `sample_id` | String | Mandatory | Unique identifier of the sample. |
| `x` | Float | Mandatory | Ground-truth x coordinate |
| `y` | Float | Mandatory | Ground-truth y coordinate |
| `z` | Float | Optional | Ground-truth height or vertical coordinate. |
| `timestamp` | UNIX | Optional | Timestamp of the measurement. |
| `test/train/val` | String | Optional | Dataset split annotation. Expected values include `train`, `validation`, or `test`. |
| `floor` | String | Optional | Floor identifier. |
| `building` | String | Optional | Building identifier. |
| `device` | String | Optional | Device used for acquisition. |
| `user` | String | Optional | User, operator, or collector identifier. |
| `configurations` | String | Optional | Acquisition configuration, such as transmission rate, calibration profile, or scan settings. |
| `orientation` | String | Optional | Device orientation during acquisition, such as north-facing, south-facing, portrait, landscape, or angle-based values. |

---

#### 1.2 `RSSI.csv`

| Field | Type | Required | Description |
|---|---|:---:|---|
| `sample_id` | String | Mandatory | Identifier of the sample to which the RSSI observation belongs. |
| `ap_id` | String | Mandatory | Identifier of the detected access point. |
| `rssi` | Float | Mandatory | Received Signal Strength Indicator, typically expressed in dBm. |
| `channel/freq` | Integer | Optional | Radio channel or frequency identifier associated with the observation. |

The Intermediate Format stores only observed RSSI measurements. Undetected access points are not represented as artificial rows at this stage.

---

#### 1.3 `AP.csv`

| Field | Type | Required | Description |
|---|---|:---:|---|
| `ap_id` | String | Mandatory | Unique access point identifier. |
| `technology` | String | Mandatory | Wireless technology, such as `WiFi`, `BLE`, or `UWB`. |
| `x` | Float | Optional | Access point x coordinate, if known. |
| `y` | Float | Optional | Access point y coordinate, if known. |
| `z` | Float | Optional | Access point height or vertical coordinate, if known. |

---

### 2. ML Final Format

The ML Final Format is derived from the Intermediate Format. It provides a fixed-dimensional representation suitable for machine learning pipelines.

#### 2.1 `Features.csv`

| Field | Type | Required | Description |
|---|---|:---:|---|
| `sample_id` | String | Mandatory | Unique sample identifier. |
| `rssi_ap1` | Float | Mandatory | RSSI value associated with the first AP in the fixed AP ordering. |
| `rssi_ap2` | Float | Mandatory | RSSI value associated with the second AP in the fixed AP ordering. |
| `...` | Float | Mandatory | Additional RSSI feature columns. |
| `rssi_apn` | Float | Mandatory | RSSI value associated with the nth AP in the fixed AP ordering. |
| `channel_1` | Integer | Optional | Channel or frequency associated with `rssi_ap1`. |
| `channel_2` | Integer | Optional | Channel or frequency associated with `rssi_ap2`. |
| `...` | Integer | Optional | Additional channel/frequency columns. |
| `channel_n` | Integer | Optional | Channel or frequency associated with `rssi_apn`. |
| `timestamp` | UNIX | Optional | Timestamp associated with the sample. |

---

#### 2.2 `Targets.csv`

| Field | Type | Required | Description |
|---|---|:---:|---|
| `sample_id` | String | Mandatory | Unique sample identifier. |
| `x` | Float | Mandatory | Ground-truth x coordinate. |
| `y` | Float | Mandatory | Ground-truth y coordinate. |
| `floor` | String | Optional | Floor identifier. |
| `building` | String | Optional | Building identifier. |
| `z` | Float | Optional | Ground-truth height or vertical coordinate. |

---

#### 2.3 `AP.csv` Optional Table

| Field | Type | Required | Description |
|---|---|:---:|---|
| `ap_id` | String | Mandatory | Unique access point identifier. |
| `technology` | String | Mandatory | Wireless technology, such as `WiFi`, `BLE`, or `UWB`. |
| `x` | Float | Optional | Access point x coordinate. |
| `y` | Float | Optional | Access point y coordinate. |
| `z` | Float | Optional | Access point height or vertical coordinate. |

This table is optional in the ML Final Format. It is included to support methods that require access point locations, such as ranging-based or hybrid localization approaches.



---
## Citation

If you use COMFORD in your research, please cite:

```bibtex
@inproceedings{comford2026,
  title={{COMFORD}: A Common Data Format for {RSSI}-based Indoor Localization},
  author={Ferrato, Alessio and Ramires, Moises and Klus, Roman and Crivello, Antonino and Pend{\~a}o, Cristiano and Silva, Ivo and Torres-Sospedra, Joaqu{\'\i}n and Anagnostopoulos, Grigorios G.},
  booktitle={2026 International Conference on Indoor Positioning and Indoor Navigation (IPIN)},
  pages={1--6},
  year={2026},
  organization={IEEE}
}
```

---

## Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.
