bgnx 0.0.1__py3-none-any.whl

bgnx/__init__.py

@@ -0,0 +1,9 @@
+"""BGNX: a framework for travel time prediction (early alpha: evaluation utilities only).
+
+PT: BGNX: framework de previsão do tempo de viagem (alfa inicial: só utilitários de avaliação).
+"""
+from .metrics import metrics
+from .stats import paired_comparison
+
+__version__ = '0.0.1'
+__all__ = ['metrics', 'paired_comparison', '__version__']

bgnx/device.py

@@ -0,0 +1,54 @@
+"""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.
+
+PT: Ajuda para o dispositivo de treino (precisa do PyTorch): CPU ou GPU, lote e taxa de aprendizado lidos de um JSON,
+com variáveis de ambiente por cima (BGNX_DEVICE_CONFIG aponta o JSON; 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. PT: padrões, depois o JSON, depois a variável."""
+    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). PT: devolve (dispositivo, configuração)."""
+    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.
+
+    PT: Copia os tensores para a GPU se `data_on_gpu` permitir e couber (com folga); senão devolve como está."""
+    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/metrics.py

@@ -0,0 +1,16 @@
+"""Error metrics for travel time prediction. Units follow the inputs (e.g. minutes); predictions are clipped at zero.
+
+PT: Métricas de erro para previsão do tempo de viagem. As unidades seguem as entradas; previsões negativas viram zero.
+"""
+import numpy as np
+
+def metrics(y, p):
+    """MAE, MedAE, MAPE (%), MARE (sum|e| / sum y), RMSLE, R2 and explained variance (EV).
+
+    PT: MAE, MedAE, MAPE (%), MARE (soma|e| / soma y), RMSLE, R2 e variância explicada (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/stats.py

@@ -0,0 +1,22 @@
+"""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.
+
+PT: Comparação pareada de dois modelos nas MESMAS observações: intervalo bootstrap da diferença de MAE e o teste de
+Wilcoxon nos erros absolutos pareados.
+"""
+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.
+
+    PT: diferença = MAE(B) - MAE(A) (positiva = A é melhor), o intervalo bootstrap e o p-valor de Wilcoxon."""
+    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.1.dist-info/METADATA

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: bgnx
+Version: 0.0.1
+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.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+bgnx/__init__.py,sha256=xrx7dDb0LMZL5uC6zWNOhoclXJUBoNi7Ti1ldH1xZ-s,343
+bgnx/device.py,sha256=B50vIhmoBQpUBqoERUJ6UbYgBWEfq5fNKS5AbWMH-V4,2879
+bgnx/metrics.py,sha256=rkXbfur2T72a6vV4HFsaSlLZbntryfwvDb1H6jVEZ00,949
+bgnx/stats.py,sha256=pVUQ6XH5242wpeB1AlpwyQruVWN3eEu_Sjdz3S2VQSQ,1378
+bgnx-0.0.1.dist-info/licenses/LICENSE,sha256=sWcrjQfZ83woHz_3zPw3Djxzj86cdOv2GCKRHoLpFNY,1069
+bgnx-0.0.1.dist-info/METADATA,sha256=kkYAXsghHNIgMdlTfQtpvQOiV7RXxqZuPfinPy-7KwM,1828
+bgnx-0.0.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+bgnx-0.0.1.dist-info/top_level.txt,sha256=YONYQUA389AY3UKVxSIRF-x_0BKqKg-lv81j8mvpX3A,5
+bgnx-0.0.1.dist-info/RECORD,,

bgnx-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bgnx-0.0.1.dist-info/licenses/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.1.dist-info/top_level.txt

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