Evaluation Measures

Compare categorical activity distributions with Jensen-Shannon divergence.

Compare activity transition matrices with Jensen-Shannon divergence.

Compare grouped numeric column distributions with Jensen-Shannon divergence.

Compare grouped numeric column distributions with Rust-backed Wasserstein distance.

Return the common part of commuters (CPC) between two flow arrays.

Parameters:

Returns:

Examples:

>>> from fastmob import common_part_of_commuters
>>> observed = [10, 20, 30, 40]
>>> predicted = [12, 18, 33, 37]
>>> print(round(common_part_of_commuters(observed, predicted), 3))
0.95

Return the common part of commuters by distance (CPCD).

Bins both distance arrays into histograms with bin width 2 and returns the fraction of values1 that overlaps with values2 bin-by-bin:

Parameters:

Returns:

Examples:

>>> from fastmob import common_part_of_commuters_distance
>>> observed = [1, 2, 4, 8]
>>> predicted = [1, 3, 5, 9]
>>> print(round(common_part_of_commuters_distance(observed, predicted), 3))
0.2

Return the common part of links (CPL) between two flow arrays.

CPL counts links that are active (\(> 0\)) in both arrays and normalises by the total number of active links across both arrays:

Parameters:

Returns:

Examples:

>>> from fastmob import common_part_of_links
>>> observed = [10, 0, 30, 0]
>>> predicted = [5, 7, 0, 0]
>>> print(round(common_part_of_links(observed, predicted), 3))
0.5

Compare dwell-time distributions in hours.

Bin two value arrays and return Jensen-Shannon divergence.

Return the information gain (KL divergence variant) of true over pred.

where \(N = \sum_i y_i\).

Parameters:

Returns:

Examples:

>>> from fastmob import information_gain
>>> observed = [10, 20, 30, 40]
>>> predicted = [12, 18, 33, 37]
>>> print(round(information_gain(observed, predicted), 3))
0.005

Return Jensen-Shannon divergence between two distributions.

The result matches the historical comparison behavior based on scipy.spatial.distance.jensenshannon(...) ** 2.

Return the Kullback–Leibler divergence \(D_\mathrm{KL}(\mathrm{true}\,\|\,\mathrm{pred})\).

Computed via scipy.stats.entropy.

Parameters:

Returns:

Raises:

Examples:

>>> from fastmob import kullback_leibler_divergence
>>> observed = [10, 20, 30, 40]
>>> predicted = [12, 18, 33, 37]
>>> print(round(kullback_leibler_divergence(observed, predicted), 3))
0.005

Return Jensen-Shannon divergence between two category matrices.

Return the maximum signed error max(true_i - pred_i).

Parameters:

Returns:

Examples:

>>> from fastmob import max_error
>>> observed = [10, 20, 30, 40]
>>> predicted = [12, 18, 33, 37]
>>> print(round(max_error(observed, predicted), 3))
3.0

Discover daily motifs for two visit datasets and compare motif distributions.

Return the mean squared error between true and predicted values.

Parameters:

Returns:

Examples:

>>> from fastmob import mse
>>> observed = [10, 20, 30, 40]
>>> predicted = [12, 18, 33, 37]
>>> print(round(mse(observed, predicted), 3))
6.5

Return the normalized root mean squared error (RMSE / sum(true)).

Parameters:

Returns:

Examples:

>>> from fastmob import nrmse
>>> observed = [10, 20, 30, 40]
>>> predicted = [12, 18, 33, 37]
>>> print(round(nrmse(observed, predicted), 3))
0.025

Return CPC between two OD matrices, aligning labels when available.

Return the Pearson correlation coefficient and its two-tailed p-value.

Parameters:

Returns:

Raises:

Examples:

>>> from fastmob import pearson_correlation
>>> observed = [10, 20, 30, 40]
>>> predicted = [12, 18, 33, 37]
>>> r, p_value = pearson_correlation(observed, predicted)
>>> print(round(r, 3), round(p_value, 3))
0.975 0.025

Compare a scalar profile metric column with Rust-backed Wasserstein distance.

Return the coefficient of determination R².

where

Parameters:

Returns:

Examples:

>>> from fastmob import r_squared
>>> observed = [10, 20, 30, 40]
>>> predicted = [12, 18, 33, 37]
>>> print(round(r_squared(observed, predicted), 3))
0.948

Compare radius-of-gyration distributions, optionally grouped by a column.

Return the root mean squared error between true and predicted values.

Parameters:

Returns:

Examples:

>>> from fastmob import rmse
>>> observed = [10, 20, 30, 40]
>>> predicted = [12, 18, 33, 37]
>>> print(round(rmse(observed, predicted), 3))
2.55

Return the Spearman rank-order correlation coefficient and its p-value.

Parameters:

Returns:

Raises:

Examples:

>>> from fastmob import spearman_correlation
>>> observed = [10, 20, 30, 40]
>>> predicted = [12, 18, 33, 37]
>>> rho, p_value = spearman_correlation(observed, predicted)
>>> print(round(rho, 3), round(p_value, 3))
1.0 0.0

Compute the spatio-temporal Wasserstein distance between two distributions.

Each input is a DataFrame representing a spatial-temporal distribution with columns for a time bin (HH:MM string), a weight/volume value, and a centroid geometry in a projected coordinate system. Centroids may be WKT strings ('POINT (x y)') or objects with .x / .y attributes.

Distances are computed using sliced Wasserstein over a 4D embedding (x, y, r*cos(theta), r*sin(theta)) where r = alpha * cyclical_period / (2*pi) and theta = 2*pi*(t / cyclical_period).

Parameters:

Returns:

Examples:

>>> import pandas as pd
>>> from fastmob.measures.evaluation import stvd_emd
>>> dist_a = pd.DataFrame(
...     {
...         "time_bin": ["08:00", "08:10"],
...         "mean_volume": [2.0, 1.0],
...         "centroid": ["POINT (0 0)", "POINT (100 0)"],
...     }
... )
>>> dist_b = pd.DataFrame(
...     {
...         "time_bin": ["08:00", "08:10"],
...         "mean_volume": [1.0, 2.0],
...         "centroid": ["POINT (0 0)", "POINT (200 0)"],
...     }
... )
>>> print(round(stvd_emd(dist_a, dist_b, num_projections=10), 3))
19.052

Return mean per-column Jensen-Shannon divergence for time-bin matrices.

Compute trajectory CPC from sparse H3 OD flows without materialising an OD matrix.

Rows are ordered by user and datetime. Invalid coordinates, null required fields, missing destinations, and self-loops are excluded before comparing OD edge counts.

Compute trajectory CPC at multiple H3 resolutions, preparing each trajectory's inputs only once instead of once per resolution.

Equivalent to calling :func:trajectory_common_part_of_commuters once per resolution, but the dataframe conversion, column detection, datetime casting, null-dropping, and time-ordered user-range construction done by _trajectory_cpc_inputs are resolution-independent and were otherwise being redone for every resolution -- tripling cost (or more) on large trajectories for no benefit, since only the final H3-binning kernel call actually depends on resolution.

Compare grouped visits-per-user distributions with Jensen-Shannon divergence.

Compare grouped visits-per-user distributions with Rust-backed Wasserstein distance.

Return Rust-backed 1D Wasserstein distance between empirical samples.