Dream FAIRer: FAIRification of Data Augmentation for Localization Systems - Enhancing Reproducibility and Reusability (Supplementary Material: Code)

Overview

This repository provides an updated, FAIR- and FAIR4RS-oriented version of the ProxyFAUG code, extending the supplementary material originally published in:

Anagnostopoulos, G. (2024). Efficient Fingerprint Augmentation Evaluation on the Antwerp LoRaWAN Setting (Supplementary Material: Code). Zenodo. https://doi.org/10.5281/zenodo.13145395

This version is developed in the context of the DreamFAIRer project, which focuses on improving the reproducibility, reusability, and FAIR/FAIR4RS alignment of research software for data augmentation in localization systems.

The core ProxyFAUG augmentation method was originally introduced in:

Anagnostopoulos, G., & Kalousis, A. (2021). ProxyFAUG: Proximity-based Fingerprint Augmentation. Proceedings of the 2021 International Conference on Indoor Positioning and Indoor Navigation (IPIN).

What Is New in This Version

This version does not modify the core ProxyFAUG algorithm, but significantly improves reproducibility, clarity, and reusability:

• Clearer input specification: Formal documentation of expected data structures, with examples and parameter descriptions (see ProxyFAUG_INPUT_SPEC.md)
• Flexible subset splitting strategies: Introduces temporal train/validation/test splitting as an alternative to random splitting, with configurable options to reduce information leakage between subsets
• Explicit dataset lineage and versioning: Clarifies the relationships between the primary dataset, previously published derived subsets, and newly introduced splitting strategies
• Improved reproducibility: Conda environment file (environment.yml) specifying exact dependency versions
• Enhanced documentation: Clarified code/data provenance, subset splitting rationale, and relation to associated publications

Repository Structure

Core Implementation

• ProxyFAUG.py: Core implementation of the ProxyFAUG augmentation method
• run_ProxyFAUG.py: Utility functions for augmentation workflows, including parameter definition, fingerprint generation, dataset merging, and performance computation
• haversine_script.py: Helper functions for geographic distance calculations using the Haversine formula
• preprocessing.py: Preprocessing utilities for dataset handling, measurement date extraction, temporal and random splitting strategies, and feature/target array construction

Documentation and Specification

• ProxyFAUG_INPUT_SPEC.md: Detailed specification of ProxyFAUG input requirements, parameter dictionary structure, array shapes, alignment constraints, and usage examples

Experimental Notebooks

• Benchmarking_ProxyFAUG_LoRaWAN_Antwerp_v2_3.ipynb: Original benchmarking notebook from the released supplement, evaluating ProxyFAUG performance on the LoRaWAN dataset with the established random split protocol.
• Temporal_Split_Visualization.ipynb: Preprocessing demonstration notebook. Implements chronological temporal splitting (70/15/15), visualizes spatial distribution of training, validation, and test subsets colored by acquisition date, and verifies temporal coherence of subsets

Configuration

• environment.yml: Conda environment specification with pinned dependency versions for reproducible execution

Quick Start

For full usage details, see ProxyFAUG_INPUT_SPEC.md. The method can be used in a simple manner, as demonstrated below.

from run_ProxyFAUG import augment_and_merge_ProxyFAUG, define_ProxyFAUG_hp

# Define augmentation parameters
ProxyFAUG_hp_dict = define_ProxyFAUG_hp(
    range_th=20,                      # proximity threshold (meters)
    maximum_points_per_cluster=2,     # cluster size limit
    p=0.3,                            # mutation probability
    crossovers_per_pair=15,           # synthetic samples per parent pair
)

# Augment and merge with original training set
x_train_aug_m, y_train_aug_m = augment_and_merge_ProxyFAUG(
    x_train, y_train, ProxyFAUG_hp_dict
)

Input:

• x_train: NumPy array, shape (n_samples, n_features) — fingerprint feature matrix
• y_train: NumPy array, shape (n_samples, 2) — location coordinates (latitude, longitude)

Output:

• x_train_aug_m: Original + augmented features
• y_train_aug_m: Original + augmented locations

Datasets

All experiments are based on publicly available LoRaWAN localization data:

Primary Dataset

Aernouts, M., Berkvens, R., Van Vlaenderen, K., & Weyn, M. (2019). Sigfox and LoRaWAN Datasets for Fingerprint Localization in Large Urban and Rural Areas (Version 1.3) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.3904158

This dataset is an updated version (a new survey, with new data, collected in the same region) of the initial dataset described in detail in:

Aernouts, M., Berkvens, R., Van Vlaenderen, K., & Weyn, M. (2018). Sigfox and LoRaWAN Datasets for Fingerprint Localization in Large Urban and Rural Areas. Data, 3(2), 13. https://doi.org/10.3390/data3020013

The LoRaWAN experiments use version 1.3 of this dataset, filtered to retain messages received by at least three gateways.

Derived Subsets

Previous work produced preprocessed train/validation/test subsets from the primary dataset. These subsets were introduced in:

Anagnostopoulos, G., & Kalousis, A. (2021). Analysing the Data-Driven Approach of Dynamically Estimating Positioning Accuracy. ICC 2021 - IEEE International Conference on Communications. https://doi.org/10.1109/ICC42927.2021.9500369

The corresponding derived dataset was published as:

Anagnostopoulos, G., & Kalousis, A. (2020). Analysing the data-driven approach of dynamically estimating positioning accuracy (data) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.4117818

These derived subsets use a random split strategy and were subsequently reused in later studies, including the LoRaWAN evaluation presented in Anagnostopoulos (2024), to ensure continuity with earlier publications and direct comparability with previously reported results.

Splitting Strategies

This version clarifies and extends subset splitting:

• Random Split (70/15/15): Sample-level random assignment to train/validation/test. Preserved from previous work for backward compatibility
• Temporal Split (70/15/15): Chronological grouping by acquisition date, with entire days assigned to subsets. Reduces information leakage from temporally adjacent, near-duplicate measurements

Both strategies are implemented in preprocessing.py with configurable parameters. The temporal split is introduced as an additional evaluation configuration, not a replacement, allowing researchers to evaluate the impact of the splitting strategy on augmentation efficacy.

Dataset Lineage and Versioning

To support reproducibility and clarity, this repository explicitly documents the relationship between datasets and code:

1. Primary dataset (Aernouts et al., 2019, version 1.3): Raw LoRaWAN measurements with message counts per location
2. Derived random split subsets (Anagnostopoulos & Kalousis, 2020): Preprocessed train/validation/test sets created via random sample allocation
3. Derived temporal split subsets (code introduced in this version): Preprocessed train/validation/test sets can be created with the code of this repository, based on chronological day-level grouping

This explicit lineage clarifies which data are used, how previous work relates to the present version, and how results under different splitting strategies should be interpreted.

Execution Environment

Dependencies (libraries and versions) are specified in environment.yml and include:

• Python 3.11.5
• Pandas, NumPy, Matplotlib
• Scikit-learn
• SciPy
• Jupyter, JupyterLab
• Haversine (geographic distance calculations)

To reproduce the execution environment:

conda env create -f environment.yml
conda activate proxyfaug

Code and Data References

Original ProxyFAUG (2021)

• Paper: Anagnostopoulos, G., & Kalousis, A. (2021). ProxyFAUG: Proximity-based Fingerprint Augmentation. IPIN 2021
• Code: https://doi.org/10.5281/zenodo.4457353
• Data: https://doi.org/10.5281/zenodo.4457391

Original 2024 LoRaWAN Evaluation

• Code: https://doi.org/10.5281/zenodo.13145395
• Data:  https://doi.org/10.5281/zenodo.4117818
• Paper: Anagnostopoulos, G. (2024). Efficient Fingerprint Augmentation Evaluation on the Antwerp LoRaWAN Setting. IPIN 2024

Primary LoRaWAN Dataset

• Dataset: https://doi.org/10.5281/zenodo.3904158
• Paper: Aernouts et al. (2019). Sigfox and LoRaWAN Datasets for Fingerprint Localization in Large Urban and Rural Areas. Data, 3(2), 13. https://doi.org/10.3390/data3020013

Citation

If you use this repository, please cite:

1. This repository:

   • Anagnostopoulos, G. (2026). Dream FAIRer: FAIRification of Data Augmentation for Localization Systems - Enhancing Reproducibility and Reusability (Supplementary Material: Code). Zenodo. https://doi.org/10.5281/zenodo.19893581 

2. The original ProxyFAUG method:

   • Anagnostopoulos, G., & Kalousis, A. (2021). ProxyFAUG: Proximity-based Fingerprint Augmentation. Proceedings of the 2021 International Conference on Indoor Positioning and Indoor Navigation (IPIN).

3. The primary LoRaWAN dataset:

   • Aernouts, M., Berkvens, R., Van Vlaenderen, K., & Weyn, M. (2019). Sigfox and LoRaWAN Datasets for Fingerprint Localization in Large Urban and Rural Areas (Version 1.3) [Data set]. Zenodo. https://doi.org/10.5281/zenodo.3904158