Skip to content

Fitting

Fastmob includes fitting utilities for common empirical mobility laws, including truncated power laws, visitation laws, and daily-location distributions. Use these functions after preparing the corresponding trajectory-derived data.

For an end-to-end example, see the fit and evaluate guide.

API

fastmob.measures.fitting.VisitationLawFit dataclass

Fitted universal visitation law and the data used to estimate it.

data contains per-user, per-H3-cell observations. spectrum holds the aggregate rf and rho values that were fitted.

fastmob.measures.fitting.fit_daily_location_lognormal(staypoints, *, locations=None, user_id_col=None, location_id_col=None, timestamp_col=None)

Fit a lognormal distribution to per-user daily distinct-location counts.

staypoints may be a :class:~fastmob.core.Staypoints object or an eager dataframe. When a :class:~fastmob.core.Locations catalogue is supplied, its global or user-scoped location identities are validated before fitting. Timezone-aware starts are bucketed by their local wall-clock calendar day.

fastmob.measures.fitting.fit_values_to_truncated_powerlaw(values, bins=100)

Fit a truncated power law to positive values using a log histogram.

Fitting uses a deterministic, parallel coarse-to-fine grid search over (r0, beta, kappa) implemented in Rust; the optimal c is solved in closed form in log space for every candidate. The log-spaced histogram the search optimizes over is also computed in Rust and returned alongside the fitted parameters.

fastmob.measures.fitting.fit_visitation_law(staypoints, *, locations=None, h3_resolution=9, user_id_col=None, timestamp_col=None, lat_col=None, lng_col=None, start_night=22, end_night=7, min_rf=None, max_rf=None, n_bins=30, distance_bin_width_km=1.0)

Fit the universal visitation law from staypoints.

Uses supplied global locations directly, or assigns shared H3 cells when no catalogue is supplied; it then fits rho = mu * rf**(-eta).

Returns:

Type Description
VisitationLawFit

data has one row per user and H3 cell with r_km, distinct-day frequency f, rf, and n_staypoints. spectrum contains the fitted rf/rho points; eta, mu, and r2 are the fitted parameters.

fastmob.measures.fitting.log_truncated_powerlaw(x, c, r0, beta, kappa)

Evaluate log(c * (x + r0)**(-beta) * exp(-x / kappa)).