Package {citydistR}

Type: Package
Title: City-Adaptive Distance Modelling Utilities
Version: 0.1.0
Author: Elif Kozan [aut, cre, cph]
Maintainer: Elif Kozan <elif.kozan@ege.edu.tr>
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.
License: MIT + file LICENSE
Encoding: UTF-8
Depends: R (≥ 4.1.0)
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-09-26 20:25:59 UTC; 1986elifgmail.com
Repository: CRAN
Date/Publication: 2026-10-07 08:10:07 UTC

City-Adaptive Validation Score

Description

Combines normalized MAE, normalized P95 absolute error, and Spearman rank correlation. Lower values indicate better validation performance.

Usage

adaptive_validation_score(
  true_distance,
  pred_distance,
  tail95_value,
  tpi_value,
  tail95_sat = 2,
  lambda_max = 1,
  gamma_max = 1,
  eps = 1e-08
)

Arguments

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.

Value

A named numeric vector containing the score and its components.

Examples

adaptive_validation_score(
  c(10, 20, 30),
  c(11, 19, 32),
  tail95_value = 1.5,
  tpi_value = 0.8
)

City-Adaptive Validation Weights

Description

Computes tail-risk and ranking-consistency weights from Tail95 and TPI.

Usage

adaptive_weights(
  tail95_value,
  tpi_value,
  tail95_sat = 2,
  lambda_max = 1,
  gamma_max = 1
)

Arguments

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.

Value

A named numeric vector containing lambda, gamma, and normalized_tail.

Examples

adaptive_weights(1.6, 0.78)

City-Level Detour Diagnostics

Description

Returns TPI, Tail95, and descriptive statistics for detour factors.

Usage

city_indices(
  network_distance = NULL,
  euclidean_distance = NULL,
  detour = NULL,
  eps = 1e-08,
  na.rm = TRUE
)

Arguments

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.

Value

A one-row data frame containing city-level diagnostics.

Examples

city_indices(detour = c(1.0, 1.1, 1.2, 1.4, 2.5))

Combine Objective Components

Description

Combines scalar objective components with configurable weights.

Usage

combine_objectives(components, weights = NULL)

Arguments

components

Named or unnamed numeric vector of scalar objective components.

weights

Optional named or positional numeric vector of weights.

Value

A single weighted objective value.

Examples

combine_objectives(c(a = 1, b = 2), c(a = 2, b = 3))

Compare Distance-Prediction Models

Description

Evaluates multiple named prediction vectors using a common metric set.

Usage

compare_distance_models(true_distance, predictions, p = 0.95)

Arguments

true_distance

Numeric vector of true distances.

predictions

Named list of numeric prediction vectors.

p

Tail probability for high-quantile absolute error.

Value

A data frame containing one row per model.

Examples

compare_distance_models(
  c(10, 20, 30),
  list(a = c(11, 19, 31), b = c(12, 18, 32))
)

Compute Detour Factors

Description

Computes the ratio between network distance and Euclidean distance.

Usage

detour_factor(
  network_distance,
  euclidean_distance,
  eps = 1e-08,
  min_df = 0,
  max_df = Inf,
  invalid = c("na", "error")
)

Arguments

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: "na" or "error".

Value

A numeric vector of detour factors.

Examples

detour_factor(c(12, 25), c(10, 20))

Evaluate Distance Predictions

Description

Computes average, tail, bias, and ranking metrics for distance predictions.

Usage

evaluate_distance_model(true_distance, pred_distance, p = 0.95)

Arguments

true_distance

Numeric vector of true distances.

pred_distance

Numeric vector of predicted distances.

p

Tail probability used for the high-quantile absolute error.

Value

A one-row data frame with sample size, MAE, RMSE, P95, bias, and Spearman correlation.

Examples

evaluate_distance_model(c(10, 20, 30), c(11, 18, 33))

Modular Hybrid Objective

Description

Combines distance loss, log-detour loss, and median-based detour regularization. The point-loss family is configurable.

Usage

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
)

Arguments

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: "auto", "mse", "mae", "huber", or "logcosh".

tail95_value

Optional Tail95 value used when loss = "auto".

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.

Value

A list containing total loss, component losses, and the selected point-loss method.

Examples

hybrid_objective(
  c(12, 18, 31),
  c(11, 20, 29),
  c(10, 15, 25),
  loss = "mse"
)

Median-Based Detour Regularization

Description

Penalizes dispersion of predicted detour factors around their median.

Usage

median_df_regularization(
  pred_distance,
  euclidean_distance,
  eps = 1e-08,
  df_min = 0,
  df_max = Inf
)

Arguments

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.

Value

A single numeric regularization value.

Examples

median_df_regularization(c(12, 18, 26), c(10, 15, 20))

Pointwise Loss Aggregator

Description

Computes a mean pointwise loss from residuals using a selectable loss family.

Usage

point_loss(
  residuals,
  method = c("mse", "mae", "huber", "logcosh"),
  delta = 1,
  na.rm = TRUE
)

Arguments

residuals

Numeric residual vector.

method

Loss family: "mse", "mae", "huber", or "logcosh".

delta

Positive Huber transition parameter.

na.rm

Logical; remove missing and non-finite residuals.

Value

A single numeric loss value.

Examples

point_loss(c(-2, -1, 0, 1, 2), "huber", delta = 1)

Robust-Loss Activation Rule

Description

Checks whether Tail95 reaches a configurable robust-loss activation threshold.

Usage

robust_loss_active(tail95_value, threshold = 1.35)

Arguments

tail95_value

Numeric Tail95 value.

threshold

Numeric activation threshold.

Value

A logical value.

Examples

robust_loss_active(1.42)

Tail95 Detour-Heaviness Index

Description

Computes an upper-quantile detour-factor summary relative to the median.

Usage

tail95(detour, prob = 0.95, eps = 1e-08, na.rm = TRUE)

Arguments

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.

Value

A single numeric tail-heaviness value.

Examples

tail95(c(1.0, 1.1, 1.2, 1.4, 2.5))

Topological Predictability Index

Description

Computes the Topological Predictability Index (TPI) from detour factors.

Usage

tpi(detour, eps = 1e-08, na.rm = TRUE)

Arguments

detour

Numeric vector of detour factors.

eps

Small positive constant.

na.rm

Logical; remove missing and non-finite values.

Value

A single numeric TPI value.

Examples

tpi(c(1.0, 1.1, 1.3, 1.8))