| Title: | City-Adaptive Distance Modelling Utilities |
|---|---|
| Description: | Tools for distribution-aware and city-adaptive analysis of learning-based road-network distance estimates. Provides detour-factor diagnostics, a Topological Predictability Index, upper-tail summaries, modular robust losses, hybrid objective components, adaptive validation weights, and multi-criteria model evaluation. The functions are designed as reusable building blocks rather than a fixed model specification. |
| Authors: | Elif Kozan [aut, cre, cph] |
| Maintainer: | Elif Kozan <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-10-11 12:36:33 UTC |
| Source: | https://github.com/cran/citydistR |
Combines normalized MAE, normalized P95 absolute error, and Spearman rank correlation. Lower values indicate better validation performance.
adaptive_validation_score( true_distance, pred_distance, tail95_value, tpi_value, tail95_sat = 2, lambda_max = 1, gamma_max = 1, eps = 1e-08 )adaptive_validation_score( true_distance, pred_distance, tail95_value, tpi_value, tail95_sat = 2, lambda_max = 1, gamma_max = 1, eps = 1e-08 )
true_distance |
Numeric vector of true distances. |
pred_distance |
Numeric vector of predicted distances. |
tail95_value |
Numeric Tail95 value computed from training data. |
tpi_value |
Numeric TPI value computed from training data. |
tail95_sat |
Tail95 saturation constant. |
lambda_max |
Maximum tail-risk weight. |
gamma_max |
Maximum ranking-consistency weight. |
eps |
Small positive constant. |
A named numeric vector containing the score and its components.
adaptive_validation_score( c(10, 20, 30), c(11, 19, 32), tail95_value = 1.5, tpi_value = 0.8 )adaptive_validation_score( c(10, 20, 30), c(11, 19, 32), tail95_value = 1.5, tpi_value = 0.8 )
Computes tail-risk and ranking-consistency weights from Tail95 and TPI.
adaptive_weights( tail95_value, tpi_value, tail95_sat = 2, lambda_max = 1, gamma_max = 1 )adaptive_weights( tail95_value, tpi_value, tail95_sat = 2, lambda_max = 1, gamma_max = 1 )
tail95_value |
Numeric Tail95 value. |
tpi_value |
Numeric TPI value. |
tail95_sat |
Tail95 saturation constant; must exceed 1. |
lambda_max |
Maximum tail-risk weight. |
gamma_max |
Maximum ranking-consistency weight. |
A named numeric vector containing lambda, gamma, and normalized_tail.
adaptive_weights(1.6, 0.78)adaptive_weights(1.6, 0.78)
Returns TPI, Tail95, and descriptive statistics for detour factors.
city_indices( network_distance = NULL, euclidean_distance = NULL, detour = NULL, eps = 1e-08, na.rm = TRUE )city_indices( network_distance = NULL, euclidean_distance = NULL, detour = NULL, eps = 1e-08, na.rm = TRUE )
network_distance |
Optional numeric vector of network distances. |
euclidean_distance |
Optional numeric vector of Euclidean distances. |
detour |
Optional numeric vector of pre-computed detour factors. |
eps |
Small positive constant. |
na.rm |
Logical; remove missing and non-finite values. |
A one-row data frame containing city-level diagnostics.
city_indices(detour = c(1.0, 1.1, 1.2, 1.4, 2.5))city_indices(detour = c(1.0, 1.1, 1.2, 1.4, 2.5))
Combines scalar objective components with configurable weights.
combine_objectives(components, weights = NULL)combine_objectives(components, weights = NULL)
components |
Named or unnamed numeric vector of scalar objective components. |
weights |
Optional named or positional numeric vector of weights. |
A single weighted objective value.
combine_objectives(c(a = 1, b = 2), c(a = 2, b = 3))combine_objectives(c(a = 1, b = 2), c(a = 2, b = 3))
Evaluates multiple named prediction vectors using a common metric set.
compare_distance_models(true_distance, predictions, p = 0.95)compare_distance_models(true_distance, predictions, p = 0.95)
true_distance |
Numeric vector of true distances. |
predictions |
Named list of numeric prediction vectors. |
p |
Tail probability for high-quantile absolute error. |
A data frame containing one row per model.
compare_distance_models( c(10, 20, 30), list(a = c(11, 19, 31), b = c(12, 18, 32)) )compare_distance_models( c(10, 20, 30), list(a = c(11, 19, 31), b = c(12, 18, 32)) )
Computes the ratio between network distance and Euclidean distance.
detour_factor( network_distance, euclidean_distance, eps = 1e-08, min_df = 0, max_df = Inf, invalid = c("na", "error") )detour_factor( network_distance, euclidean_distance, eps = 1e-08, min_df = 0, max_df = Inf, invalid = c("na", "error") )
network_distance |
Numeric vector of network or shortest-path distances. |
euclidean_distance |
Numeric vector of Euclidean distances. |
eps |
Small positive constant used for numerical protection. |
min_df |
Lower clipping bound for valid detour factors. |
max_df |
Upper clipping bound for valid detour factors. |
invalid |
How to handle non-positive Euclidean distances: |
A numeric vector of detour factors.
detour_factor(c(12, 25), c(10, 20))detour_factor(c(12, 25), c(10, 20))
Computes average, tail, bias, and ranking metrics for distance predictions.
evaluate_distance_model(true_distance, pred_distance, p = 0.95)evaluate_distance_model(true_distance, pred_distance, p = 0.95)
true_distance |
Numeric vector of true distances. |
pred_distance |
Numeric vector of predicted distances. |
p |
Tail probability used for the high-quantile absolute error. |
A one-row data frame with sample size, MAE, RMSE, P95, bias, and Spearman correlation.
evaluate_distance_model(c(10, 20, 30), c(11, 18, 33))evaluate_distance_model(c(10, 20, 30), c(11, 18, 33))
Combines distance loss, log-detour loss, and median-based detour regularization. The point-loss family is configurable.
hybrid_objective( true_distance, pred_distance, euclidean_distance, beta_logdf = 1, beta_median = 0.1, loss = c("auto", "mse", "mae", "huber", "logcosh"), tail95_value = NULL, robust_threshold = 1.35, delta = 1, standardize = TRUE, eps = 1e-08, df_min = 1e-08, df_max = Inf )hybrid_objective( true_distance, pred_distance, euclidean_distance, beta_logdf = 1, beta_median = 0.1, loss = c("auto", "mse", "mae", "huber", "logcosh"), tail95_value = NULL, robust_threshold = 1.35, delta = 1, standardize = TRUE, eps = 1e-08, df_min = 1e-08, df_max = Inf )
true_distance |
Numeric vector of true network distances. |
pred_distance |
Numeric vector of predicted network distances. |
euclidean_distance |
Numeric vector of Euclidean distances. |
beta_logdf |
Weight for the log-detour objective component. |
beta_median |
Weight for the median regularization component. |
loss |
Point-loss choice: |
tail95_value |
Optional Tail95 value used when |
robust_threshold |
Tail95 threshold used for automatic Huber activation. |
delta |
Positive Huber transition parameter. |
standardize |
Logical; standardize distance and log-detour targets before point-loss calculation. |
eps |
Small positive constant. |
df_min |
Lower clipping bound for detour factors. |
df_max |
Upper clipping bound for detour factors. |
A list containing total loss, component losses, and the selected point-loss method.
hybrid_objective( c(12, 18, 31), c(11, 20, 29), c(10, 15, 25), loss = "mse" )hybrid_objective( c(12, 18, 31), c(11, 20, 29), c(10, 15, 25), loss = "mse" )
Penalizes dispersion of predicted detour factors around their median.
median_df_regularization( pred_distance, euclidean_distance, eps = 1e-08, df_min = 0, df_max = Inf )median_df_regularization( pred_distance, euclidean_distance, eps = 1e-08, df_min = 0, df_max = Inf )
pred_distance |
Numeric vector of predicted network distances. |
euclidean_distance |
Numeric vector of Euclidean distances. |
eps |
Small positive constant. |
df_min |
Lower clipping bound for predicted detour factors. |
df_max |
Upper clipping bound for predicted detour factors. |
A single numeric regularization value.
median_df_regularization(c(12, 18, 26), c(10, 15, 20))median_df_regularization(c(12, 18, 26), c(10, 15, 20))
Computes a mean pointwise loss from residuals using a selectable loss family.
point_loss( residuals, method = c("mse", "mae", "huber", "logcosh"), delta = 1, na.rm = TRUE )point_loss( residuals, method = c("mse", "mae", "huber", "logcosh"), delta = 1, na.rm = TRUE )
residuals |
Numeric residual vector. |
method |
Loss family: |
delta |
Positive Huber transition parameter. |
na.rm |
Logical; remove missing and non-finite residuals. |
A single numeric loss value.
point_loss(c(-2, -1, 0, 1, 2), "huber", delta = 1)point_loss(c(-2, -1, 0, 1, 2), "huber", delta = 1)
Checks whether Tail95 reaches a configurable robust-loss activation threshold.
robust_loss_active(tail95_value, threshold = 1.35)robust_loss_active(tail95_value, threshold = 1.35)
tail95_value |
Numeric Tail95 value. |
threshold |
Numeric activation threshold. |
A logical value.
robust_loss_active(1.42)robust_loss_active(1.42)
Computes an upper-quantile detour-factor summary relative to the median.
tail95(detour, prob = 0.95, eps = 1e-08, na.rm = TRUE)tail95(detour, prob = 0.95, eps = 1e-08, na.rm = TRUE)
detour |
Numeric vector of detour factors. |
prob |
Quantile probability. |
eps |
Small positive constant for numerical protection. |
na.rm |
Logical; remove missing and non-finite values. |
A single numeric tail-heaviness value.
tail95(c(1.0, 1.1, 1.2, 1.4, 2.5))tail95(c(1.0, 1.1, 1.2, 1.4, 2.5))
Computes the Topological Predictability Index (TPI) from detour factors.
tpi(detour, eps = 1e-08, na.rm = TRUE)tpi(detour, eps = 1e-08, na.rm = TRUE)
detour |
Numeric vector of detour factors. |
eps |
Small positive constant. |
na.rm |
Logical; remove missing and non-finite values. |
A single numeric TPI value.
tpi(c(1.0, 1.1, 1.3, 1.8))tpi(c(1.0, 1.1, 1.3, 1.8))