geofusion 0.1.0__tar.gz

geofusion-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Basant Mounir, Amr T. Abdel-Hamid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geofusion-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: geofusion
+Version: 0.1.0
+Summary: Uncertain machine learning framework for GPS/GNSS sensor fusion
+Author-email: Basant Mounir <basant.mounir@gmail.com>, "Amr T. Abdel-Hamid" <amr.abdelhamid@kaust.edu.sa>
+License: MIT License
+        
+        Copyright (c) 2026 Basant Mounir, Amr T. Abdel-Hamid
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Dataset, https://www.kaggle.com/code/basantmounir/geofusion-dataset
+Keywords: GPS,GNSS,sensor fusion,uncertain clustering,machine learning,positioning,GeoFusion
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# GeoFusion
+
+An uncertain machine learning framework for GPS/GNSS sensor fusion.
+
+GeoFusion estimates true location events from noisy phone-reported GPS coordinates by modelling each observation as an uncertain object, clustering by location event, and fusing the cluster into a refined position estimate.
+
+## Installation
+
+```bash
+pip install geofusion
+```
+
+## Quick start
+
+```python
+import pandas as pd
+from geofusion import run_geofusion
+
+df = pd.read_csv("sample_top100_groups.csv")
+
+# UK-medoids (mountain uncertainty model) + Kalman filter
+result = run_geofusion(
+    df          = df,
+    model       = "mountain",
+    algorithm   = "ukmedoids",
+    algo_params = dict(k=100, random_state=42, n_init=10, n_samples=50),
+    estimator   = "kf",
+)
+print(result)
+# GeoFusionResult(
+#   model='mountain'  algorithm='ukmedoids'  estimator='kf'
+#   nc=100  V=2.75m  H=1.54m  MAE=3.43m
+#   runtime=4.5s  peak_RAM=152.1MB
+# )
+
+# Access the output dataframe and metrics
+df_out  = result.df_out       # original columns + predicted_cluster + predicted_location
+metrics = result.metrics       # {'V': ..., 'H': ..., 'MAE': ...}
+```
+
+## Uncertainty models
+
+| `model`    | Description | Compatible algorithms |
+|------------|-------------|----------------------|
+| `certain`  | Raw phone coordinates, no uncertainty | `kmeans`, `kmedoids`, `sdsgc` |
+| `volcano`  | Isotropic sigma from satellite geometry cost J_avg (El Abbous & Samanta, 2017) | `ukmeans`, `ukmedoids` |
+| `mountain` | Directional Student-t scale from multivariate regression on GSDC dataset | `ukmeans`, `ukmedoids` |
+
+## Clustering algorithms
+
+| `algorithm`  | Description |
+|--------------|-------------|
+| `kmeans`     | k-means++ (sklearn) |
+| `kmedoids`   | k-medoids with k-medoids++ initialisation |
+| `ukmeans`    | UK-means (Chau et al., 2006) — provably equivalent to k-means on GPS data |
+| `ukmedoids`  | UK-medoids (Gullo et al., 2008) with Monte Carlo expected-distance estimation |
+| `sdsgc`      | Structured Doubly Stochastic Graph-Based Clustering (Wang et al., TNNLS 2025) |
+
+## Estimators
+
+| `estimator` | Description |
+|-------------|-------------|
+| `rep`       | Cluster representative (centroid or medoid) |
+| `kf`        | Linear Kalman filter (static target, degree space) |
+| `ekf`       | Extended Kalman filter (local metre space — corrects degree-space distortion) |
+| `pf`        | Sequential Importance Resampling particle filter |
+| `dnn`       | Post-clustering MLP predicting a position correction from cluster-level GNSS features |
+
+## Required dataset columns
+
+| Column | Description |
+|--------|-------------|
+| `collectionName` | Drive identifier (used for DNN drive-level split) |
+| `latDeg_gt` | NovAtel reference latitude (degrees) |
+| `lngDeg_gt` | NovAtel reference longitude (degrees) |
+| `latDeg_phone` | Phone-reported latitude (degrees) |
+| `lngDeg_phone` | Phone-reported longitude (degrees) |
+| `j_avg` | Average satellite geometry cost |
+| `speedMps` | Vehicle speed (m/s) |
+| `n_signals` | Number of satellite signals |
+| `avg_rawPrUnc` | Average pseudorange uncertainty (m) |
+| `hDop` | Horizontal dilution of precision |
+| `vDop` | Vertical dilution of precision |
+| `avg_iono` | Average ionospheric delay (m) |
+| `avg_tropo` | Average tropospheric delay (m) |
+
+The dataset is publicly available on [Kaggle](https://www.kaggle.com/code/basantmounir/geofusion-dataset).
+
+## algo_params reference
+
+All algorithms accept `k`, `random_state`, `n_init`, `max_iter`.
+
+Additional parameters:
+- **`ukmedoids`**: `n_samples` (Monte Carlo samples for expected distance, default 50)
+- **`sdsgc`**: `nn` (nearest neighbours, default 5 for k≤50, 4 for k≥100), `strategy` (`early_stop` / `best_of_n` / `threshold`), `threshold` (W-matrix threshold for component extraction), `eigsh_tol`, `eigsh_maxiter`
+
+## estimator_params reference
+
+- **`pf`**: `n_particles` (default 500)
+- **`dnn`**: `test_drives` (required), `val_drives` (required), `max_epochs` (200), `patience` (20), `random_state` (42), `subprocess` (False — set True for clean RAM measurement)
+
+## DNN example
+
+```python
+result = run_geofusion(
+    df               = df,
+    model            = "mountain",
+    algorithm        = "ukmedoids",
+    algo_params      = dict(k=300, random_state=42, n_init=10, n_samples=50),
+    estimator        = "dnn",
+    estimator_params = dict(
+        test_drives = ["2020-08-03-US-MTV-1", "2020-07-08-US-MTV-1", "2021-04-15-US-MTV-1"],
+        val_drives  = ["2021-04-28-US-MTV-1", "2021-04-28-US-SJC-1"],
+        max_epochs  = 200,
+        patience    = 20,
+    ),
+)
+# DNN metrics are evaluated on test-drive clusters only
+print(result.metrics)   # {'V': 2.05, 'H': 1.40, 'MAE': 2.71, 'n_test_clusters': 69}
+```
+
+## License
+
+MIT

geofusion-0.1.0/README.md

@@ -0,0 +1,124 @@
+# GeoFusion
+
+An uncertain machine learning framework for GPS/GNSS sensor fusion.
+
+GeoFusion estimates true location events from noisy phone-reported GPS coordinates by modelling each observation as an uncertain object, clustering by location event, and fusing the cluster into a refined position estimate.
+
+## Installation
+
+```bash
+pip install geofusion
+```
+
+## Quick start
+
+```python
+import pandas as pd
+from geofusion import run_geofusion
+
+df = pd.read_csv("sample_top100_groups.csv")
+
+# UK-medoids (mountain uncertainty model) + Kalman filter
+result = run_geofusion(
+    df          = df,
+    model       = "mountain",
+    algorithm   = "ukmedoids",
+    algo_params = dict(k=100, random_state=42, n_init=10, n_samples=50),
+    estimator   = "kf",
+)
+print(result)
+# GeoFusionResult(
+#   model='mountain'  algorithm='ukmedoids'  estimator='kf'
+#   nc=100  V=2.75m  H=1.54m  MAE=3.43m
+#   runtime=4.5s  peak_RAM=152.1MB
+# )
+
+# Access the output dataframe and metrics
+df_out  = result.df_out       # original columns + predicted_cluster + predicted_location
+metrics = result.metrics       # {'V': ..., 'H': ..., 'MAE': ...}
+```
+
+## Uncertainty models
+
+| `model`    | Description | Compatible algorithms |
+|------------|-------------|----------------------|
+| `certain`  | Raw phone coordinates, no uncertainty | `kmeans`, `kmedoids`, `sdsgc` |
+| `volcano`  | Isotropic sigma from satellite geometry cost J_avg (El Abbous & Samanta, 2017) | `ukmeans`, `ukmedoids` |
+| `mountain` | Directional Student-t scale from multivariate regression on GSDC dataset | `ukmeans`, `ukmedoids` |
+
+## Clustering algorithms
+
+| `algorithm`  | Description |
+|--------------|-------------|
+| `kmeans`     | k-means++ (sklearn) |
+| `kmedoids`   | k-medoids with k-medoids++ initialisation |
+| `ukmeans`    | UK-means (Chau et al., 2006) — provably equivalent to k-means on GPS data |
+| `ukmedoids`  | UK-medoids (Gullo et al., 2008) with Monte Carlo expected-distance estimation |
+| `sdsgc`      | Structured Doubly Stochastic Graph-Based Clustering (Wang et al., TNNLS 2025) |
+
+## Estimators
+
+| `estimator` | Description |
+|-------------|-------------|
+| `rep`       | Cluster representative (centroid or medoid) |
+| `kf`        | Linear Kalman filter (static target, degree space) |
+| `ekf`       | Extended Kalman filter (local metre space — corrects degree-space distortion) |
+| `pf`        | Sequential Importance Resampling particle filter |
+| `dnn`       | Post-clustering MLP predicting a position correction from cluster-level GNSS features |
+
+## Required dataset columns
+
+| Column | Description |
+|--------|-------------|
+| `collectionName` | Drive identifier (used for DNN drive-level split) |
+| `latDeg_gt` | NovAtel reference latitude (degrees) |
+| `lngDeg_gt` | NovAtel reference longitude (degrees) |
+| `latDeg_phone` | Phone-reported latitude (degrees) |
+| `lngDeg_phone` | Phone-reported longitude (degrees) |
+| `j_avg` | Average satellite geometry cost |
+| `speedMps` | Vehicle speed (m/s) |
+| `n_signals` | Number of satellite signals |
+| `avg_rawPrUnc` | Average pseudorange uncertainty (m) |
+| `hDop` | Horizontal dilution of precision |
+| `vDop` | Vertical dilution of precision |
+| `avg_iono` | Average ionospheric delay (m) |
+| `avg_tropo` | Average tropospheric delay (m) |
+
+The dataset is publicly available on [Kaggle](https://www.kaggle.com/code/basantmounir/geofusion-dataset).
+
+## algo_params reference
+
+All algorithms accept `k`, `random_state`, `n_init`, `max_iter`.
+
+Additional parameters:
+- **`ukmedoids`**: `n_samples` (Monte Carlo samples for expected distance, default 50)
+- **`sdsgc`**: `nn` (nearest neighbours, default 5 for k≤50, 4 for k≥100), `strategy` (`early_stop` / `best_of_n` / `threshold`), `threshold` (W-matrix threshold for component extraction), `eigsh_tol`, `eigsh_maxiter`
+
+## estimator_params reference
+
+- **`pf`**: `n_particles` (default 500)
+- **`dnn`**: `test_drives` (required), `val_drives` (required), `max_epochs` (200), `patience` (20), `random_state` (42), `subprocess` (False — set True for clean RAM measurement)
+
+## DNN example
+
+```python
+result = run_geofusion(
+    df               = df,
+    model            = "mountain",
+    algorithm        = "ukmedoids",
+    algo_params      = dict(k=300, random_state=42, n_init=10, n_samples=50),
+    estimator        = "dnn",
+    estimator_params = dict(
+        test_drives = ["2020-08-03-US-MTV-1", "2020-07-08-US-MTV-1", "2021-04-15-US-MTV-1"],
+        val_drives  = ["2021-04-28-US-MTV-1", "2021-04-28-US-SJC-1"],
+        max_epochs  = 200,
+        patience    = 20,
+    ),
+)
+# DNN metrics are evaluated on test-drive clusters only
+print(result.metrics)   # {'V': 2.05, 'H': 1.40, 'MAE': 2.71, 'n_test_clusters': 69}
+```
+
+## License
+
+MIT

geofusion-0.1.0/geofusion/__init__.py

@@ -0,0 +1,139 @@
+"""
+GeoFusion
+=========
+
+An uncertain machine learning framework for GPS/GNSS sensor fusion.
+
+Implements the two-phase pipeline from Mounir & Abdel-Hamid (IEEE Access):
+
+    1. **Representation** — each GPS observation is modelled as an uncertain
+       object (volcano model or mountain model) reflecting the positional
+       uncertainty given satellite geometry, speed, and signal quality.
+
+    2. **Clustering** — observations are grouped by location event using
+       either certain or uncertain clustering algorithms.
+
+    3. **Estimation** — observations within each cluster are fused into a
+       single refined position estimate.
+
+Quick start
+-----------
+    import pandas as pd
+    from geofusion import run_geofusion
+
+    df = pd.read_csv("sample_top100_groups.csv")
+
+    # UK-medoids (mountain) + Kalman filter
+    result = run_geofusion(
+        df          = df,
+        model       = "mountain",
+        algorithm   = "ukmedoids",
+        algo_params = dict(k=100, random_state=42, n_init=10, n_samples=50),
+        estimator   = "kf",
+    )
+    print(result)
+    # GeoFusionResult(
+    #   model='mountain'  algorithm='ukmedoids'  estimator='kf'
+    #   nc=100  V=2.75m  H=1.54m  MAE=3.43m
+    #   runtime=4.5s  peak_RAM=152.1MB
+    # )
+
+    # SDSGC (certain) + particle filter
+    result = run_geofusion(
+        df          = df,
+        model       = "certain",
+        algorithm   = "sdsgc",
+        algo_params = dict(k=100, nn=4, strategy="threshold", threshold=0.1),
+        estimator   = "pf",
+    )
+
+    # Post-clustering DNN (test-drive evaluation)
+    result = run_geofusion(
+        df               = df,
+        model            = "mountain",
+        algorithm        = "ukmedoids",
+        algo_params      = dict(k=100, random_state=42, n_init=10, n_samples=50),
+        estimator        = "dnn",
+        estimator_params = dict(
+            test_drives = ["2020-08-03-US-MTV-1", "2020-07-08-US-MTV-1"],
+            val_drives  = ["2021-04-28-US-MTV-1"],
+        ),
+    )
+
+Uncertainty models
+------------------
+    certain   No uncertainty. Raw phone coordinates.
+              Algorithms: kmeans, kmedoids, sdsgc
+
+    volcano   Model A — isotropic sigma from satellite geometry cost J_avg
+              (El Abbous & Samanta, 2017). Zero-shot transfer, no fitting.
+              sigma = max(0.787 * j_avg + 2.192, 0.01)
+              Algorithms: ukmeans, ukmedoids
+
+    mountain  Model B — directional Student-t scale from multivariate
+              regression on the GSDC dataset (Eqs 11-12 in the paper).
+              Sigma floor: max(s, 0.01) — NOT abs(s).
+              Algorithms: ukmeans, ukmedoids
+
+Clustering algorithms
+---------------------
+    kmeans    k-means++ (sklearn) — certain only
+    kmedoids  k-medoids (Lloyd-style, k-medoids++ init) — certain only
+    ukmeans   UK-means (Chau et al., 2006) — volcano or mountain
+              Note: provably equivalent to k-means on GPS data
+    ukmedoids UK-medoids (Gullo et al., 2008) — volcano or mountain
+    sdsgc     Structured Doubly Stochastic Graph-Based Clustering
+              (Wang et al., TNNLS 2025) — certain only
+
+Estimators
+----------
+    rep   Cluster representative (centroid or medoid) — no post-processing
+    kf    Linear Kalman filter (degree-space, static target)
+    ekf   Extended Kalman filter (local metre-space, corrects degree distortion)
+    pf    Sequential Importance Resampling particle filter
+    dnn   Post-clustering MLP (Siemuri et al., 2021, adapted for GeoFusion)
+          Requires 'test_drives' and 'val_drives' in estimator_params.
+
+Required dataset columns
+------------------------
+    collectionName   drive identifier (used for DNN drive-level split)
+    latDeg_gt        NovAtel reference latitude (degrees)
+    lngDeg_gt        NovAtel reference longitude (degrees)
+    latDeg_phone     phone-reported latitude (degrees)
+    lngDeg_phone     phone-reported longitude (degrees)
+    j_avg            average satellite geometry cost
+    speedMps         vehicle speed (m/s)
+    n_signals        number of satellite signals
+    avg_rawPrUnc     average pseudorange uncertainty (m)
+    hDop             horizontal dilution of precision
+    vDop             vertical dilution of precision
+    avg_iono         average ionospheric delay (m)
+    avg_tropo        average tropospheric delay (m)
+
+References
+----------
+    Mounir, B. & Abdel-Hamid, A.T. (2025). GeoFusion: An Uncertain Machine
+        Learning Framework for Sensor Fusion. IEEE Access.
+    El Abbous, A. & Samanta, N. (2017). A Modeling of GPS Error Distributions.
+        EURONAV. DOI: 10.1109/EURONAV.2017.7954200
+    Chau, M. et al. (2006). Uncertain Data Mining: An Example in Clustering
+        Location Data. PAKDD. DOI: 10.1007/11731139_24
+    Gullo, F. et al. (2008). Clustering Uncertain Data Via K-Medoids. MDAI.
+        DOI: 10.1007/978-3-540-87993-0_19
+    Wang, N. et al. (2025). Structured Doubly Stochastic Graph-Based
+        Clustering. IEEE TNNLS. DOI: 10.1109/TNNLS.2025.3531987
+    Siemuri, A. et al. (2021). Improving Precision GNSS Positioning and
+        Navigation Accuracy on Smartphones Using Machine Learning. ION GNSS+.
+"""
+
+from .core import run_geofusion, GeoFusionResult
+from .core import _REQUIRED_COLS as REQUIRED_COLS
+
+__all__ = [
+    "run_geofusion",
+    "GeoFusionResult",
+    "REQUIRED_COLS",
+]
+
+__version__ = "0.1.0"
+__author__  = "Basant Mounir, Amr T. Abdel-Hamid"

geofusion-0.1.0/geofusion/clustering/__init__.py

@@ -0,0 +1,13 @@
+from .kmeans_clustering   import run_kmeans
+from .kmedoids_clustering import run_kmedoids
+from .ukmeans_clustering  import run_ukmeans
+from .ukmedoids_clustering import run_ukmedoids
+from .sdsgc_clustering    import (
+    run_sdsgc,
+    _l2_distance, _sym_neighbors, _eig_laplacian, _proj_simplex,
+)
+
+__all__ = [
+    "run_kmeans", "run_kmedoids", "run_ukmeans", "run_ukmedoids", "run_sdsgc",
+    "_l2_distance", "_sym_neighbors", "_eig_laplacian", "_proj_simplex",
+]

geofusion-0.1.0/geofusion/clustering/kmeans_clustering.py

@@ -0,0 +1,81 @@
+"""
+k-means clustering for GeoFusion.
+
+Wraps sklearn's KMeans with k-means++ initialization and the standard
+GeoFusion function signature, for a clean like-for-like comparison with
+all other clustering methods in the framework.
+
+The cluster representative is the centroid (mean) of reported locations
+within each cluster -- a computed average, not an actual data point.
+This is what distinguishes k-means from k-medoids in terms of the
+representative: centroids may not correspond to any real observation.
+
+Usage (in a notebook cell):
+    df_out = run_kmeans(
+        "real_data_sample_10events_5mapart.csv",
+        "real_data_sample_10events_kmeans.csv",
+        columns=("reported_location_lat", "reported_location_lon"),
+        k=10,
+        random_state=42,
+    )
+"""
+
+import numpy as np
+import pandas as pd
+from sklearn.cluster import KMeans
+
+
+def run_kmeans(
+    input_path: str,
+    output_path: str,
+    columns=("reported_location_lat", "reported_location_lon"),
+    k: int = 10,
+    random_state: int = 42,
+    n_init: int = 10,
+) -> pd.DataFrame:
+    """
+    Run k-means clustering on the given columns of a CSV file and write
+    the result (original data + predicted_cluster + predicted_location)
+    to output_path.
+
+    Parameters
+    ----------
+    input_path : str
+        Path to the input CSV file.
+    output_path : str
+        Path to write the output CSV file to.
+    columns : tuple of str
+        Column names to cluster on.
+    k : int
+        Number of clusters, default 10.
+    random_state : int
+        Seed for reproducibility (passed to sklearn KMeans).
+    n_init : int
+        Number of k-means++ initializations; best run by inertia is kept.
+        Default 10, matching sklearn's default and all other GeoFusion
+        algorithms for a fair comparison.
+
+    Returns
+    -------
+    pd.DataFrame
+        The output dataframe (also written to output_path).
+    """
+    df = pd.read_csv(input_path)
+
+    missing = [c for c in columns if c not in df.columns]
+    if missing:
+        raise ValueError(f"Column(s) not found in input data: {missing}")
+
+    X = df[list(columns)].to_numpy(dtype=float)
+
+    model = KMeans(n_clusters=k, random_state=random_state, n_init=n_init)
+    labels = model.fit_predict(X)
+    centroids = model.cluster_centers_
+
+    df["predicted_cluster"] = labels
+    df["predicted_location"] = [
+        tuple(float(v) for v in centroids[lbl]) for lbl in labels
+    ]
+
+    df.to_csv(output_path, index=False)
+    return df

geofusion-0.1.0/geofusion/clustering/kmedoids_clustering.py

@@ -0,0 +1,57 @@
+import numpy as np
+import pandas as pd
+from scipy.spatial.distance import cdist
+
+def _kmeans_plusplus_init(X, k, rng):
+    n = X.shape[0]
+    first_idx = rng.integers(n)
+    center_indices = [first_idx]
+    closest_sq_dist = np.sum((X - X[first_idx])**2, axis=1)
+    for _ in range(1, k):
+        probs = closest_sq_dist / closest_sq_dist.sum()
+        idx = rng.choice(n, p=probs)
+        center_indices.append(idx)
+        new_sq = np.sum((X - X[idx])**2, axis=1)
+        closest_sq_dist = np.minimum(closest_sq_dist, new_sq)
+    return np.array(center_indices)
+
+def _lloyd_kmedoids_single(X, k, rng, max_iter):
+    n = X.shape[0]
+    medoid_idx = _kmeans_plusplus_init(X, k, rng)
+    labels = np.zeros(n, dtype=int)
+    for _ in range(max_iter):
+        d_to_medoids = cdist(X, X[medoid_idx], metric='euclidean')
+        new_labels = np.argmin(d_to_medoids, axis=1)
+        new_medoid_idx = medoid_idx.copy()
+        for c in range(k):
+            members = np.where(new_labels == c)[0]
+            if len(members) == 0: continue
+            if len(members) == 1: new_medoid_idx[c] = members[0]; continue
+            sub_dist = cdist(X[members], X[members], metric='euclidean')
+            new_medoid_idx[c] = members[np.argmin(sub_dist.sum(axis=1))]
+        if np.array_equal(new_labels, labels) and np.array_equal(np.sort(new_medoid_idx), np.sort(medoid_idx)):
+            labels = new_labels; medoid_idx = new_medoid_idx; break
+        labels = new_labels; medoid_idx = new_medoid_idx
+    d_final = cdist(X, X[medoid_idx], metric='euclidean')
+    total_cost = d_final[np.arange(n), labels].sum()
+    return labels, medoid_idx, total_cost
+
+def _lloyd_kmedoids(X, k, random_state, n_init, max_iter):
+    rng = np.random.default_rng(random_state)
+    best_labels, best_medoid_idx, best_cost = None, None, np.inf
+    for _ in range(n_init):
+        labels, medoid_idx, cost = _lloyd_kmedoids_single(X, k, rng, max_iter)
+        if cost < best_cost:
+            best_labels, best_medoid_idx, best_cost = labels, medoid_idx, cost
+    return best_labels, best_medoid_idx
+
+def run_kmedoids(input_path, output_path, columns=("reported_location_lat","reported_location_lon"),
+                 k=10, random_state=42, n_init=10, max_iter=300):
+    df = pd.read_csv(input_path)
+    X = df[list(columns)].to_numpy(dtype=float)
+    labels, medoid_indices = _lloyd_kmedoids(X, k=k, random_state=random_state, n_init=n_init, max_iter=max_iter)
+    medoids = X[medoid_indices]
+    df["predicted_cluster"] = labels
+    df["predicted_location"] = [tuple(float(v) for v in medoids[lbl]) for lbl in labels]
+    df.to_csv(output_path, index=False)
+    return df