bgnx 0.0.2__tar.gz

bgnx-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BGNX Project
+
+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.

bgnx-0.0.2/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: bgnx
+Version: 0.0.2
+Summary: BGNX: a framework for travel time prediction (early alpha: evaluation utilities).
+Author: BGNX Project
+License: MIT
+Keywords: travel time,ETA,transportation,evaluation,machine learning
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.8
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == "torch"
+Dynamic: license-file
+
+# BGNX
+
+**BGNX** is a framework for travel time prediction, under development.
+
+This early alpha (0.0.x) ships only general evaluation utilities. The models and the full documentation will be
+released with the accompanying publications.
+
+```bash
+pip install bgnx            # metrics and paired comparison
+pip install "bgnx[torch]"   # + CPU/GPU device helper
+```
+
+```python
+import numpy as np
+from bgnx import metrics, paired_comparison
+
+y  = np.array([10.0, 12.5, 30.0, 7.0])    # observed durations (minutes)
+pa = np.array([11.0, 12.0, 27.0, 8.0])    # model A
+pb = np.array([ 9.0, 15.0, 25.0, 9.5])    # model B
+
+print(metrics(y, pa))                     # MAE, MedAE, MAPE, MARE, RMSLE, R2, EV
+print(paired_comparison(y, pa, pb))       # MAE difference (B - A), bootstrap 95% CI, Wilcoxon p-value
+```
+
+`paired_comparison` compares two models on the **same** observations: the 95% interval of the MAE difference comes
+from a paired bootstrap (resampling observations), and the paired absolute errors are compared with the Wilcoxon
+signed-rank test.
+
+License: MIT.

bgnx-0.0.2/README.md

@@ -0,0 +1,29 @@
+# BGNX
+
+**BGNX** is a framework for travel time prediction, under development.
+
+This early alpha (0.0.x) ships only general evaluation utilities. The models and the full documentation will be
+released with the accompanying publications.
+
+```bash
+pip install bgnx            # metrics and paired comparison
+pip install "bgnx[torch]"   # + CPU/GPU device helper
+```
+
+```python
+import numpy as np
+from bgnx import metrics, paired_comparison
+
+y  = np.array([10.0, 12.5, 30.0, 7.0])    # observed durations (minutes)
+pa = np.array([11.0, 12.0, 27.0, 8.0])    # model A
+pb = np.array([ 9.0, 15.0, 25.0, 9.5])    # model B
+
+print(metrics(y, pa))                     # MAE, MedAE, MAPE, MARE, RMSLE, R2, EV
+print(paired_comparison(y, pa, pb))       # MAE difference (B - A), bootstrap 95% CI, Wilcoxon p-value
+```
+
+`paired_comparison` compares two models on the **same** observations: the 95% interval of the MAE difference comes
+from a paired bootstrap (resampling observations), and the paired absolute errors are compared with the Wilcoxon
+signed-rank test.
+
+License: MIT.

bgnx-0.0.2/bgnx/__init__.py

@@ -0,0 +1,7 @@
+"""BGNX: a framework for travel time prediction (early alpha: evaluation utilities only).
+"""
+from .metrics import metrics
+from .stats import paired_comparison
+
+__version__ = '0.0.2'
+__all__ = ['metrics', 'paired_comparison', '__version__']

bgnx-0.0.2/bgnx/device.py

@@ -0,0 +1,49 @@
+"""Training device helper (needs PyTorch: pip install "bgnx[torch]"): CPU or GPU, batch size and learning rate from a
+JSON file, with environment overrides.
+
+    from bgnx.device import configure_device, move
+    dev, cfg = configure_device()       # picks the device and prints the choice
+    tensors = move(tensors, dev, cfg)   # whole training set on the GPU if it fits (data_on_gpu = auto)
+
+Settings: defaults below, then the JSON in BGNX_DEVICE_CONFIG (if set), then BGNX_DEVICE=cpu|cuda|auto.
+"""
+import json, os
+from pathlib import Path
+
+DEFAULTS = {'device': 'auto', 'cpu_threads': 8, 'data_on_gpu': 'auto', 'batch': None, 'lr': None, 'predict_batch': 32768}
+
+def _torch():
+    try:
+        import torch
+    except ImportError as e:
+        raise ImportError('bgnx.device needs PyTorch: pip install "bgnx[torch]"') from e
+    return torch
+
+def read_device_config():
+    """Defaults, then the JSON file, then the environment variable."""
+    cfg = dict(DEFAULTS)
+    path = os.environ.get('BGNX_DEVICE_CONFIG')
+    if path and Path(path).exists():
+        cfg.update({k: v for k, v in json.loads(Path(path).read_text(encoding='utf-8')).items() if k in DEFAULTS})
+    if os.environ.get('BGNX_DEVICE'): cfg['device'] = os.environ['BGNX_DEVICE']
+    return cfg
+
+def configure_device():
+    """Returns (torch.device, config dict)."""
+    torch = _torch(); cfg = read_device_config()
+    torch.set_num_threads(int(cfg['cpu_threads']))
+    wanted = str(cfg['device']).lower()
+    if wanted not in ('auto', 'cuda', 'cpu'): raise ValueError(f'invalid device: {wanted}')
+    if wanted == 'cuda' and not torch.cuda.is_available(): print('warning: cuda requested but unavailable; using cpu', flush=True)
+    dev = torch.device('cuda' if wanted != 'cpu' and torch.cuda.is_available() else 'cpu')
+    name = torch.cuda.get_device_name(dev) if dev.type == 'cuda' else f'{torch.get_num_threads()} threads'
+    print(f'device: {dev} ({name})', flush=True)
+    return dev, cfg
+
+def move(tensors, dev, cfg, headroom=1.5):
+    """Copies a tuple of tensors to the GPU if `data_on_gpu` allows and it fits (with headroom); otherwise returns it as is."""
+    torch = _torch()
+    if dev.type != 'cuda' or cfg['data_on_gpu'] in (False, 'false'): return tensors
+    size = sum(t.element_size()*t.nelement() for t in tensors)
+    if cfg['data_on_gpu'] == 'auto' and size*headroom > torch.cuda.mem_get_info(dev)[0]: return tensors
+    return tuple(t.to(dev) for t in tensors)

bgnx-0.0.2/bgnx/metrics.py

@@ -0,0 +1,12 @@
+"""Error metrics for travel time prediction. Units follow the inputs (e.g. minutes); predictions are clipped at zero.
+"""
+import numpy as np
+
+def metrics(y, p):
+    """MAE, MedAE, MAPE (%), MARE (sum|e| / sum y), RMSLE, R2 and explained variance (EV)."""
+    y = np.asarray(y, dtype=float); p = np.maximum(np.asarray(p, dtype=float), 0)
+    if y.shape != p.shape: raise ValueError(f'y and p differ in shape: {y.shape} vs {p.shape}')
+    e = y - p; a = np.abs(e); var = y.var()
+    return {'MAE': a.mean(), 'MedAE': float(np.median(a)), 'MAPE_%': 100*np.mean(a/y), 'MARE': a.sum()/y.sum(),
+            'RMSLE': float(np.sqrt(np.mean((np.log1p(p) - np.log1p(y))**2))),
+            'R2': 1 - np.mean(e**2)/var, 'EV': 1 - e.var()/var}

bgnx-0.0.2/bgnx/stats.py

@@ -0,0 +1,17 @@
+"""Paired comparison of two models on the SAME observations: bootstrap interval of the MAE difference and the Wilcoxon
+signed-rank test on the paired absolute errors.
+"""
+import numpy as np
+from scipy.stats import wilcoxon
+
+def paired_comparison(y, pred_a, pred_b, replicas=2000, seed=42, level=0.95):
+    """Difference = MAE(B) - MAE(A) (positive = A is better), its bootstrap interval and the Wilcoxon p-value."""
+    y = np.asarray(y, dtype=float)
+    ea = np.abs(np.asarray(pred_a, dtype=float) - y); eb = np.abs(np.asarray(pred_b, dtype=float) - y)
+    if not (ea.shape == eb.shape == y.shape): raise ValueError('y, pred_a and pred_b must have the same shape')
+    d = eb - ea; n = len(d); rng = np.random.default_rng(seed)
+    boot = np.array([d[rng.integers(0, n, n)].mean() for _ in range(replicas)])
+    lo, hi = np.percentile(boot, [100*(1 - level)/2, 100*(1 + level)/2])
+    p = float(wilcoxon(ea, eb).pvalue) if np.any(d != 0) else 1.0
+    return {'mae_a': ea.mean(), 'mae_b': eb.mean(), 'difference': d.mean(), 'ci_low': lo, 'ci_high': hi,
+            'level': level, 'wilcoxon_p': p, 'n': n}

bgnx-0.0.2/bgnx.egg-info/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: bgnx
+Version: 0.0.2
+Summary: BGNX: a framework for travel time prediction (early alpha: evaluation utilities).
+Author: BGNX Project
+License: MIT
+Keywords: travel time,ETA,transportation,evaluation,machine learning
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.8
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == "torch"
+Dynamic: license-file
+
+# BGNX
+
+**BGNX** is a framework for travel time prediction, under development.
+
+This early alpha (0.0.x) ships only general evaluation utilities. The models and the full documentation will be
+released with the accompanying publications.
+
+```bash
+pip install bgnx            # metrics and paired comparison
+pip install "bgnx[torch]"   # + CPU/GPU device helper
+```
+
+```python
+import numpy as np
+from bgnx import metrics, paired_comparison
+
+y  = np.array([10.0, 12.5, 30.0, 7.0])    # observed durations (minutes)
+pa = np.array([11.0, 12.0, 27.0, 8.0])    # model A
+pb = np.array([ 9.0, 15.0, 25.0, 9.5])    # model B
+
+print(metrics(y, pa))                     # MAE, MedAE, MAPE, MARE, RMSLE, R2, EV
+print(paired_comparison(y, pa, pb))       # MAE difference (B - A), bootstrap 95% CI, Wilcoxon p-value
+```
+
+`paired_comparison` compares two models on the **same** observations: the 95% interval of the MAE difference comes
+from a paired bootstrap (resampling observations), and the paired absolute errors are compared with the Wilcoxon
+signed-rank test.
+
+License: MIT.

bgnx-0.0.2/bgnx.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+bgnx/__init__.py
+bgnx/device.py
+bgnx/metrics.py
+bgnx/stats.py
+bgnx.egg-info/PKG-INFO
+bgnx.egg-info/SOURCES.txt
+bgnx.egg-info/dependency_links.txt
+bgnx.egg-info/requires.txt
+bgnx.egg-info/top_level.txt

bgnx-0.0.2/bgnx.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bgnx-0.0.2/bgnx.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy>=1.22
+scipy>=1.8
+
+[torch]
+torch>=2.0

bgnx-0.0.2/bgnx.egg-info/top_level.txt

@@ -0,0 +1 @@
+bgnx

bgnx-0.0.2/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bgnx"
+version = "0.0.2"
+description = "BGNX: a framework for travel time prediction (early alpha: evaluation utilities)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "BGNX Project" }]
+keywords = ["travel time", "ETA", "transportation", "evaluation", "machine learning"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = ["numpy>=1.22", "scipy>=1.8"]
+
+[project.optional-dependencies]
+torch = ["torch>=2.0"]
+
+[tool.setuptools.packages.find]
+include = ["bgnx*"]

bgnx-0.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+