{"id":47309101,"url":"https://github.com/sharan-naribole/wlan_localization","last_synced_at":"2026-03-17T09:53:33.534Z","repository":{"id":77841679,"uuid":"85651271","full_name":"sharan-naribole/wlan_localization","owner":"sharan-naribole","description":"A Machine Learning Approach to WLAN Fingerprinting based Localization","archived":false,"fork":false,"pushed_at":"2026-01-16T21:11:58.000Z","size":55031,"stargazers_count":31,"open_issues_count":1,"forks_count":18,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-01-17T09:24:18.759Z","etag":null,"topics":["data-science","localization","machine-learning","wi-fi"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sharan-naribole.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-03-21T02:43:59.000Z","updated_at":"2026-01-16T21:12:01.000Z","dependencies_parsed_at":"2023-06-05T06:00:08.730Z","dependency_job_id":null,"html_url":"https://github.com/sharan-naribole/wlan_localization","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sharan-naribole/wlan_localization","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharan-naribole%2Fwlan_localization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharan-naribole%2Fwlan_localization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharan-naribole%2Fwlan_localization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharan-naribole%2Fwlan_localization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sharan-naribole","download_url":"https://codeload.github.com/sharan-naribole/wlan_localization/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sharan-naribole%2Fwlan_localization/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30621360,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T08:10:05.930Z","status":"ssl_error","status_checked_at":"2026-03-17T08:10:04.972Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-science","localization","machine-learning","wi-fi"],"created_at":"2026-03-17T09:53:32.629Z","updated_at":"2026-03-17T09:53:33.518Z","avatar_url":"https://github.com/sharan-naribole.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WLAN Indoor Localization using Machine Learning\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\nA production-ready machine learning system for Wi-Fi fingerprint-based indoor positioning using a novel cascaded architecture. Achieves 2.6-8.2m positioning accuracy across multiple buildings and floors.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Key Results](#key-results)\n- [Methodology](#methodology)\n- [Quick Start](#quick-start)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Dataset](#dataset)\n- [Project Structure](#project-structure)\n- [Technical Details](#technical-details)\n- [Development](#development)\n- [Citation](#citation)\n- [License](#license)\n\n## Overview\n\nIndoor localization remains a challenging problem due to GPS signal loss in enclosed environments. This project implements a sophisticated machine learning solution for Wi-Fi fingerprint-based positioning that:\n\n- **Handles complex multi-building, multi-floor environments** with a cascaded classification-regression approach\n- **Achieves competitive accuracy** (2.6-8.2m RMSE) on the benchmark UJIIndoorLoc dataset\n- **Implements modern ML engineering practices** with modular code, comprehensive testing, and experiment tracking\n- **Addresses real-world challenges** including 96% data sparsity, class imbalance, and high dimensionality (520 Wi-Fi access points)\n\n### Business Value\n\nIndoor positioning enables critical applications including:\n- **Navigation**: Indoor navigation in airports, malls, hospitals\n- **Asset Tracking**: Real-time equipment and inventory tracking in warehouses\n- **Emergency Response**: First responder location tracking in buildings\n- **Analytics**: Customer behavior analysis in retail environments\n\n## Key Results\n\n### Positioning Accuracy\n\n| Metric | Value |\n|--------|-------|\n| **Building Classification** | 99.4% accuracy |\n| **Floor Classification** | 94-98% accuracy (per-building models) |\n| **Best Position Accuracy** | 2.65m RMSE (Building 1, Floor 2) |\n| **Average Position Accuracy** | 3-8m RMSE (varies by location) |\n| **Global Positioning Error** | 5.28m (including building/floor penalties) |\n\n### Performance by Location\n\n```\nBuilding 0:\n├── Floor 0: 3.72m RMSE\n├── Floor 1: 3.18m RMSE\n├── Floor 2: 3.71m RMSE\n└── Floor 3: 3.32m RMSE\n\nBuilding 1:\n├── Floor 0: 4.07m RMSE\n├── Floor 1: 5.28m RMSE\n├── Floor 2: 2.65m RMSE (best)\n└── Floor 3: 4.79m RMSE\n\nBuilding 2:\n├── Floor 0: 4.06m RMSE\n├── Floor 1: 4.06m RMSE\n├── Floor 2: 3.76m RMSE\n├── Floor 3: 2.77m RMSE\n└── Floor 4: 6.76m RMSE\n```\n\n## Methodology\n\n### Cascaded ML Architecture\n\nOur approach uses a three-stage cascade pipeline that dramatically outperforms global models:\n\n```\n┌─────────────────────────────────────────────────┐\n│  Stage 1: Building Classification               │\n│  Algorithm: Random Forest (100 trees)           │\n│  Class Balancing: NearMiss undersampling        │\n│  Accuracy: 99.4%                                │\n└────────────────┬────────────────────────────────┘\n                 │\n                 ▼\n┌─────────────────────────────────────────────────┐\n│  Stage 2: Per-Building Floor Classification     │\n│  Algorithm: Weighted KNN (k=3, manhattan)       │\n│  Separate model per building                    │\n│  Accuracy: 94-98% per building                  │\n└────────────────┬────────────────────────────────┘\n                 │\n                 ▼\n┌─────────────────────────────────────────────────┐\n│  Stage 3: Per-Building-Floor Position Regression│\n│  Algorithm: Weighted KNN (k=3, distance-weighted)│\n│  13 separate models (per building-floor combo)  │\n│  Output: Latitude, Longitude                    │\n└─────────────────────────────────────────────────┘\n```\n\n### Why Cascade Outperforms Global Models\n\nThe cascade approach provides:\n1. **Specialized models** tuned to each building's unique RF characteristics\n2. **Better handling of spatial variation** across different floors\n3. **Interpretable predictions** with confidence at each stage\n4. **Custom error metric** that penalizes building/floor misclassification:\n\n```\npositioning_error = euclidean_distance + 50 × building_error + 4 × floor_error\n```\n\n### Data Processing Pipeline\n\n1. **Missing Value Handling**: RSSI signals have 96% sparsity (out-of-range = 100 dBm)\n2. **Dimensionality Reduction**: PCA reduces 520 AP features → 150 components (95% variance)\n3. **Box-Cox Transformation**: Addresses right-skewed RSSI distributions\n4. **Feature Engineering**: Statistical features (skewness, kurtosis) for signal quality\n\n### Model Selection Process\n\nComprehensive comparison of algorithms:\n- **Linear Models**: Ridge, Lasso (baseline: ~25m RMSE)\n- **Polynomial Regression**: Quadratic/cubic features\n- **K-Nearest Neighbors**: ✅ Selected (5.69m RMSE, best for spatial data)\n- **Random Forests**: 6.78m RMSE\n- **Extra Trees**: 8.89m RMSE\n- **XGBoost**: Evaluated but KNN superior for this problem\n\n**KNN won** due to:\n- Natural fit for spatial similarity\n- No overfitting on high-dimensional sparse data\n- Fast inference with distance weighting\n- Interpretable neighbor-based predictions\n\n## Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/wlan_localization\ncd wlan_localization\n\n# Create virtual environment (Python 3.11+)\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install package\npip install -e .\n\n# Download UJIIndoorLoc dataset\npython scripts/download_data.py\n\n# Train the cascade model\nwlan-train --config configs/cascade_optimal.yaml\n\n# Evaluate on test set\nwlan-evaluate --model models/cascade_best.pkl --data data/processed/test.csv\n\n# Make predictions\nwlan-predict --model models/cascade_best.pkl --rssi \"[-90,-85,-92,...]\"\n```\n\n## Installation\n\n### Requirements\n\n- Python 3.11 or higher\n- 4GB RAM minimum (8GB recommended for training)\n- 500MB disk space for data and models\n\n### From Source\n\n```bash\n# Clone repository\ngit clone https://github.com/yourusername/wlan_localization\ncd wlan_localization\n\n# Install in development mode with all dependencies\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Dependencies\n\nCore dependencies:\n- `scikit-learn\u003e=1.4.0` - Machine learning algorithms\n- `pandas\u003e=2.2.0` - Data manipulation\n- `numpy\u003e=1.26.0` - Numerical operations\n- `imbalanced-learn\u003e=0.12.0` - Class balancing (SMOTE, NearMiss)\n- `mlflow\u003e=2.10.0` - Experiment tracking\n- `optuna\u003e=3.5.0` - Hyperparameter optimization\n\nSee `pyproject.toml` for complete dependency list.\n\n## Usage\n\n### Python API\n\n```python\nfrom wlan_localization import CascadePipeline\nfrom wlan_localization.data import load_ujiindoorloc\nimport numpy as np\n\n# Load data\nX_train, y_train, X_test, y_test = load_ujiindoorloc()\n\n# Initialize and train cascade pipeline\npipeline = CascadePipeline.from_config('configs/cascade_optimal.yaml')\npipeline.fit(X_train, y_train)\n\n# Make predictions\npredictions = pipeline.predict(X_test)\nprint(f\"Building: {predictions['building']}\")\nprint(f\"Floor: {predictions['floor']}\")\nprint(f\"Position: ({predictions['latitude']}, {predictions['longitude']})\")\n\n# Evaluate\nmetrics = pipeline.evaluate(X_test, y_test)\nprint(f\"Mean positioning error: {metrics['positioning_error']:.2f}m\")\nprint(f\"Building accuracy: {metrics['building_accuracy']:.1%}\")\nprint(f\"Floor accuracy: {metrics['floor_accuracy']:.1%}\")\n```\n\n### Command Line Interface\n\n```bash\n# Train with custom configuration\nwlan-train \\\n    --config configs/my_experiment.yaml \\\n    --data data/processed/train.csv \\\n    --output models/my_model.pkl\n\n# Evaluate with detailed metrics\nwlan-evaluate \\\n    --model models/cascade_best.pkl \\\n    --data data/processed/test.csv \\\n    --output reports/metrics/evaluation.json \\\n    --plot-roc \\\n    --plot-confusion\n\n# Predict single sample\nwlan-predict \\\n    --model models/cascade_best.pkl \\\n    --rssi-file data/samples/single_measurement.csv \\\n    --format json\n```\n\n### Jupyter Notebooks\n\nExplore the analysis notebooks:\n\n1. **01_exploratory_data_analysis.ipynb** - Dataset exploration and visualization\n2. **02_data_preprocessing.ipynb** - Feature engineering and PCA\n3. **03_model_development.ipynb** - Model comparison and selection\n4. **04_cascade_pipeline.ipynb** - Building the cascade system\n5. **05_results_analysis.ipynb** - Performance evaluation and visualization\n\n```bash\n# Launch Jupyter\njupyter notebook notebooks/\n```\n\n## Dataset\n\n### UJIIndoorLoc\n\nThe [UJIIndoorLoc dataset](https://archive.ics.uci.edu/ml/datasets/UJIIndoorLoc) is a benchmark for indoor localization research from the Universitat Jaume I.\n\n**Dataset Statistics:**\n- **Training samples**: 19,937\n- **Test samples**: 1,111\n- **Wi-Fi Access Points**: 520\n- **Buildings**: 3\n- **Floors**: 5 (0-4, not all in every building)\n- **Coverage area**: ~108,703 m²\n- **Devices**: 25 different smartphones\n\n**Features:**\n- **RSSI values**: Signal strength in dBm (range: -104 to 0, missing = 100)\n- **Location labels**: Building ID, Floor ID, Latitude, Longitude\n- **Metadata**: User ID, Phone ID, Timestamp, Space ID, Relative Position\n\n**Data Characteristics:**\n- **High sparsity**: 96% of RSSI values are out-of-range\n- **Class imbalance**: Building 2 has 43% of samples, Buildings 0 \u0026 1 have ~28% each\n- **Spatial heterogeneity**: Different RF characteristics per building/floor\n\n### Download Instructions\n\n```bash\n# Automated download (recommended)\npython scripts/download_data.py\n\n# Manual download\n# 1. Visit: https://archive.ics.uci.edu/ml/datasets/UJIIndoorLoc\n# 2. Download trainingData.csv and validationData.csv\n# 3. Place in data/raw/\n```\n\n## Project Structure\n\n```\nwlan_localization/\n├── configs/                      # Experiment configurations\n│   ├── default.yaml             # Default hyperparameters\n│   └── cascade_optimal.yaml     # Best performing configuration\n├── data/                        # Data directory (not in git)\n│   ├── raw/                     # Original UCI dataset\n│   ├── processed/               # Preprocessed features\n│   └── splits/                  # Train/val/test splits\n├── docs/                        # Extended documentation\n│   ├── methodology.md           # Detailed ML methodology\n│   ├── experiments.md           # Experiment tracking\n│   └── api/                     # API documentation\n├── models/                      # Trained models (not in git)\n│   ├── building_classifier/\n│   ├── floor_classifiers/\n│   └── position_regressors/\n├── notebooks/                   # Jupyter notebooks\n│   ├── 01_exploratory_data_analysis.ipynb\n│   ├── 02_data_preprocessing.ipynb\n│   ├── 03_model_development.ipynb\n│   ├── 04_cascade_pipeline.ipynb\n│   └── 05_results_analysis.ipynb\n├── reports/                     # Generated reports\n│   ├── figures/                 # Visualizations\n│   └── metrics/                 # Evaluation metrics\n├── scripts/                     # Utility scripts\n│   ├── train.py                # Training script\n│   ├── evaluate.py             # Evaluation script\n│   ├── predict.py              # Inference script\n│   └── download_data.py        # Data download\n├── src/wlan_localization/      # Source code\n│   ├── __init__.py\n│   ├── cli/                    # Command-line interfaces\n│   ├── data/                   # Data loading and preprocessing\n│   │   ├── loader.py\n│   │   ├── preprocessor.py\n│   │   └── validator.py\n│   ├── evaluation/             # Metrics and visualization\n│   │   ├── metrics.py\n│   │   └── visualizations.py\n│   ├── features/               # Feature engineering\n│   │   ├── engineering.py\n│   │   └── selection.py\n│   ├── models/                 # ML models\n│   │   ├── base.py\n│   │   ├── building_classifier.py\n│   │   ├── cascade.py\n│   │   ├── floor_classifier.py\n│   │   └── position_regressor.py\n│   └── utils/                  # Utilities\n│       ├── config.py\n│       ├── logger.py\n│       └── paths.py\n├── tests/                      # Test suite\n│   ├── test_data/\n│   ├── test_features/\n│   ├── test_models/\n│   └── conftest.py\n├── .github/workflows/          # CI/CD pipelines\n│   └── ci.yml\n├── .gitignore\n├── .pre-commit-config.yaml     # Pre-commit hooks\n├── LICENSE                     # MIT License\n├── pyproject.toml             # Project configuration\n└── README.md                  # This file\n```\n\n## Technical Details\n\n### Machine Learning Pipeline\n\n**1. Data Preprocessing**\n- Missing value imputation (100 dBm → out-of-range handling)\n- Box-Cox transformation for normality\n- PCA dimensionality reduction (520 → 150 features)\n- Standard scaling for KNN distance metrics\n\n**2. Building Classification**\n- Algorithm: Random Forest (100 estimators)\n- Class balancing: NearMiss-2 undersampling\n- Cross-validation: 5-fold stratified\n- Metric: Accuracy, ROC-AUC per class\n\n**3. Floor Classification (Per-Building)**\n- Algorithm: Weighted KNN (k=3, manhattan distance)\n- 3 separate models (one per building)\n- Improves accuracy from ~85% (global) to 94-98% (local)\n- Handles different floor counts per building\n\n**4. Position Regression (Per-Building-Floor)**\n- Algorithm: Weighted KNN (k=3, distance-weighted)\n- 13 separate models (one per building-floor combination)\n- Multivariate output: (latitude, longitude)\n- Improves RMSE from 5.69m (global) to 2.65-8.17m (local)\n\n**5. Model Selection**\n- Nested cross-validation (outer: 5-fold, inner: 2-fold)\n- Grid search hyperparameter tuning\n- Evaluation: RMSE, MAE, R² for regression; Accuracy, F1 for classification\n\n### Experiments and Reproducibility\n\nAll experiments tracked with MLflow:\n\n```bash\n# View experiment results\nmlflow ui\n\n# Compare runs\nmlflow experiments list\n```\n\nConfiguration-driven experiments:\n```yaml\n# configs/cascade_optimal.yaml\nmodels:\n  building_classifier:\n    type: \"RandomForest\"\n    n_estimators: 100\n    class_balancing: \"NearMiss\"\n\n  floor_classifier:\n    type: \"KNN\"\n    k: 3\n    metric: \"manhattan\"\n    weights: \"distance\"\n\n  position_regressor:\n    type: \"WeightedKNN\"\n    k: 3\n```\n\n### Performance Optimization\n\n- **Training time**: ~15 minutes on CPU (MacBook Pro M1)\n- **Inference time**: \u003c10ms per prediction\n- **Model size**: ~500MB (13 KNN models + training data)\n- **Memory footprint**: ~2GB during training\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone and install with dev dependencies\ngit clone https://github.com/yourusername/wlan_localization\ncd wlan_localization\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=wlan_localization --cov-report=html\n\n# Run specific test file\npytest tests/test_models/test_cascade.py\n\n# Run tests in parallel\npytest -n auto\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/ tests/\n\n# Sort imports\nisort src/ tests/\n\n# Lint\nflake8 src/ tests/\n\n# Type check\nmypy src/\n```\n\n### Pre-commit Hooks\n\nAutomatically run on every commit:\n- `black` - Code formatting\n- `isort` - Import sorting\n- `flake8` - Linting\n- `mypy` - Type checking\n\n```bash\n# Run manually\npre-commit run --all-files\n```\n\n### Continuous Integration\n\nGitHub Actions automatically:\n- Runs test suite on Python 3.11 \u0026 3.12\n- Checks code formatting and linting\n- Runs type checking\n- Generates coverage reports\n- Deploys documentation\n\n## Citation\n\nIf you use the UJIIndoorLoc dataset, please cite:\n\n```bibtex\n@inproceedings{torres2014ujiindoorloc,\n  title={UJIIndoorLoc: A new multi-building and multi-floor database for WLAN fingerprint-based indoor localization problems},\n  author={Torres-Sospedra, Joaqu{\\'\\i}n and Montoliu, Ra{\\'u}l and Mart{\\'\\i}nez-Us{\\'o}, Adolfo and Avariento, Joan P and Arnau, Tom{\\'a}s J and Benedito-Bordonau, Mauri and Huerta, Joaqu{\\'\\i}n},\n  booktitle={2014 international conference on indoor positioning and indoor navigation (IPIN)},\n  pages={261--270},\n  year={2014},\n  organization={IEEE}\n}\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- **UJIIndoorLoc Dataset**: Universitat Jaume I for providing the benchmark dataset\n- **Scikit-learn**: Machine learning library\n- **MLflow**: Experiment tracking platform\n- **Community**: Open-source ML community for tools and inspiration\n\n---\n\n**For questions or collaboration:** [Open an issue](https://github.com/yourusername/wlan_localization/issues)\n\n**Star this repo** if you found it useful!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsharan-naribole%2Fwlan_localization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsharan-naribole%2Fwlan_localization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsharan-naribole%2Fwlan_localization/lists"}