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

pip install comford

Or install from source:

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/.

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 for a walkthrough of dataset loading, and 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)	Multi-building, multi-floor WiFi fingerprinting
UTSDataset	UTSIndoorLoc (GitHub)	Multi-building, multi-floor WiFi fingerprinting
TUJI1Dataset	TUJI1 (Zenodo 7641701)	Multi-device, fine-grained grid, single-floor WiFi fingerprinting
DSIDataset	DSI (Zenodo 3778646)	Radio map + trajectory WiFi fingerprinting, single-floor
TIE1Dataset	TIE1 (Zenodo 5174851)	Heterogeneous indoor WiFi fingerprinting
SAH1Dataset	SAH1 (Zenodo 5174851)	Heterogeneous indoor WiFi fingerprinting
TUT6Dataset	TAU Zenodo 3819917 — Building 01	Single-floor WiFi fingerprinting (TUT campus)
TUT7Dataset	TAU Zenodo 3819917 — Building 02	Single-floor WiFi fingerprinting (TUT campus)
SOD01Dataset	SODIndoorLoc (GitHub) — CETC331	Multi-floor WiFi fingerprinting
SOD02Dataset	SODIndoorLoc (GitHub) — HCXY All_30	Multi-floor WiFi fingerprinting
SOD06Dataset	SODIndoorLoc (GitHub) — 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:

@inproceedings{comford2025,
  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.