Skip to content

Generation Models

API Description
Gravity Gravity model compatible with original scikit-mobility generation APIs.
Radiation Radiation model compatible with original scikit-mobility generation APIs.
compute_distance_matrix Compute pairwise Haversine distances for tessellation locations.
exponential_deterrence_func Compute exponential distance deterrence values.
powerlaw_deterrence_func Compute power-law distance deterrence values.
EPR Exploration and Preferential Return trajectory generator.
DensityEPR EPR generator using location relevance from density.
SpatialEPR EPR generator using a spatial origin-destination matrix.
Ditras DITRAS trajectory generator combining EPR with mobility diaries.
MarkovDiaryGenerator Markov Diary Learner and Generator compatible with scikit-mobility.
GeoSim Social trajectory generator based on GeoSim dynamics.
STS_epr Spatial-temporal social EPR trajectory generator.
compute_od_matrix Compute an OD probability matrix from a singly constrained gravity model.

The fastmob.models package mirrors the original scikit-mobility generation API. Model implementations accept pandas or Narwhals-compatible eager dataframes and may convert inputs to pandas internally.

Install the generation dependencies with:

pip install "fastmob[generation]"

Flow Models

fastmob.models.gravity.Gravity

Gravity model.

The Gravity model of human migration. In its original formulation, the probability \(T_{ij}\) of moving from location \(i\) to location \(j\) is proportional to [Z1946]_:

\[ T_{ij} \propto \frac{P_i P_j}{r_{ij}} \]

where \(P_i\) and \(P_j\) are the populations (or relevances) of locations \(i\) and \(j\) and \(r_{ij}\) is the distance between them. The general form is [BBGJLLMRST2018]_:

\[ T_{ij} = K m_i m_j f(r_{ij}) \]

where \(K\) is a constant and \(f(r_{ij})\) is a deterrence function — a decreasing function of distance commonly modelled as a power law or exponential.

Singly constrained variant. When the total outflow \(O_i\) from each origin is known, the model estimates destinations only:

\[ T_{ij} = O_i \frac{m_j f(r_{ij})}{\sum_k m_k f(r_{ik})}. \]

Globally constrained variant. Both origin and destination totals are fixed via balancing factors \(K_i\) and \(L_j\):

\[ T_{ij} = K_i O_i L_j D_j f(r_{ij}). \]

Parameters:

Name Type Description Default
deterrence_func_type str

The deterrence function to use. Accepted values: "power_law" and "exponential". The default is "power_law".

 'power_law'
deterrence_func_args list

Arguments for the deterrence function. For "power_law" this is the exponent; for "exponential" it is the decay rate. The default is [-2.0].

 [-2.0]
origin_exp float

Exponent applied to the origin's relevance (only used in the globally constrained model). The default is 1.0.

 1.0
destination_exp float

Exponent applied to the destination's relevance. The default is 1.0.

 1.0
gravity_type str

The model variant. Accepted values: "singly constrained" and "globally constrained". The default is "singly constrained".

 'singly constrained'
name str

Human-readable label for this model instance. The default is "Gravity model".

 'Gravity model'

Attributes:

Name Type Description
deterrence_func_type str

The deterrence function in use.
deterrence_func_args list

Arguments for the deterrence function.
origin_exp float

Exponent applied to the origin's relevance.
destination_exp float

Exponent applied to the destination's relevance.
gravity_type str

The model variant ("singly constrained" or "globally constrained").
name str

Human-readable label of this model instance.
Notes

spatial_tessellation accepts any pandas-compatible eager dataframe. It must contain a tile_id column (or whichever name is passed as tile_id_column) and either a geometry column (GeoPandas GeoDataFrame) or explicit lat / lng columns from which tile centroids are derived.

Examples:

>>> import pandas as pd
>>> import numpy as np
>>> from fastmob.models import Gravity
>>> tessellation = pd.DataFrame({
...     "tile_id": [0, 1, 2, 3],
...     "lat": [40.71, 41.88, 37.77, 33.44],
...     "lng": [-74.01, -87.62, -122.42, -112.07],
...     "relevance": [1_000_000, 2_700_000, 880_000, 1_600_000],
...     "tot_outflow": [100_000, 250_000, 90_000, 150_000],
... })
>>> np.random.seed(0)
>>> gravity = Gravity(gravity_type="singly constrained")
>>> print(gravity)
Gravity(name="Gravity model", deterrence_func_type="power_law", deterrence_func_args=[-2.0], origin_exp=1.0, destination_exp=1.0, gravity_type="singly constrained")
>>> fdf = gravity.generate(tessellation, tile_id_column="tile_id",
...                        tot_outflows_column="tot_outflow",
...                        relevance_column="relevance", out_format="flows")
>>> print(fdf.head())
References

.. [Z1946] Zipf, G. K. (1946). The P1 P2/D Hypothesis: On the Intercity Movement of Persons. American Sociological Review, 11(6), 677–686. .. [W1971] Wilson, A. G. (1971). A family of spatial interaction models, and associated developments. Environment and Planning A, 3(1), 1–32. .. [BBGJLLMRST2018] Barbosa, H. et al. (2018). Human mobility: Models and applications. Physics Reports, 734, 1–74.

See Also

Radiation

fit(flow_df, relevance_column=RELEVANCE)

Fit the Gravity model parameters to observed flows via Poisson regression.

Uses a Generalised Linear Model (GLM) with a Poisson family and log link to estimate destination_exp and deterrence_func_args (and origin_exp for the globally constrained variant) from real flows [FM1982]_.

Parameters:

Name Type Description Default
flow_df DataFrame with tessellation attribute

Observed flows. Must expose a .tessellation attribute (e.g. the FlowDataFrame returned by Gravity.generate() or Radiation.generate()) and contain origin, destination, and flow columns.

 required
relevance_column str

Name of the column in flow_df.tessellation that holds the location relevance (e.g. population). The default is "relevance".

 RELEVANCE
Notes

Modifies deterrence_func_args, destination_exp, and (for the globally constrained variant) origin_exp in-place.

References

.. [FM1982] Flowerdew, R. & Murray, A. (1982). A method of fitting the gravity model based on the Poisson distribution. Journal of Regional Science, 22(2), 191–202.

generate(spatial_tessellation, tile_id_column=TILE_ID, tot_outflows_column=TOT_OUTFLOW, relevance_column=RELEVANCE, out_format='flows')

Generate synthetic flows with the Gravity model.

Parameters:

Name Type Description Default
spatial_tessellation DataFrame or GeoDataFrame

The spatial tessellation on which to run the model. Must include a tile identifier column, a relevance column, and (for "flows" and "flows_sample" output) a total-outflow column.

 required
tile_id_column str

Name of the column containing the location identifier. The default is "tile_id".

 TILE_ID
tot_outflows_column str

Name of the column containing the total outflow per location. Required when out_format is "flows" or "flows_sample". The default is "tot_outflow".

 TOT_OUTFLOW
relevance_column str

Name of the column containing the location relevance (e.g. population). The default is "relevance".

 RELEVANCE
out_format str

Format of the output. Accepted values:

  • "flows" — expected (average) flows between each pair of locations.
  • "flows_sample" — randomly sampled integer flows.
  • "probabilities" — probability of a trip from each origin to each destination (does not require tot_outflows_column).

The default is "flows".

 'flows'

Returns:

Type Description
DataFrame

A dataframe with columns origin, destination, and flow (or probability). A to_matrix() method converts this to a 2-D numpy array.

Raises:

Type Description
KeyError

If out_format requires a total-outflow column but it is absent from spatial_tessellation.

fastmob.models.radiation.Radiation

Radiation model.

The radiation model for human migration. The model assumes that a traveller's destination choice follows two steps: each opportunity at every location is assigned a random fitness drawn from a distribution \(P(z)\), and the traveller accepts the closest opportunity whose fitness exceeds a threshold drawn from the same distribution. The resulting average flow from \(i\) to \(j\) is [SGMB2012]_:

\[ T_{ij} = O_i \frac{1}{1 - \frac{m_i}{M}} \frac{m_i m_j}{(m_i + s_{ij})(m_i + m_j + s_{ij})} \]

where \(O_i\) is the total outflow from location \(i\), \(m_i\) (\(m_j\)) is the relevance (e.g. population) at the origin (destination), \(s_{ij}\) is the total relevance within the circle of radius \(r_{ij}\) centred on \(i\) excluding origin and destination, and \(M = \sum_i m_i\) is the total system relevance.

Parameters:

Name Type Description Default
name str

Human-readable label for this model instance. The default is "Radiation model".

 'Radiation model'

Attributes:

Name Type Description
name str

Human-readable label of this model instance.
Notes

spatial_tessellation accepts any pandas-compatible eager dataframe. It must contain a tile_id column and either a geometry column or explicit lat / lng columns from which tile centroids are derived.

Examples:

>>> import pandas as pd
>>> import numpy as np
>>> from fastmob.models import Radiation
>>> tessellation = pd.DataFrame({
...     "tile_id": [0, 1, 2, 3],
...     "lat": [40.71, 41.88, 37.77, 33.44],
...     "lng": [-74.01, -87.62, -122.42, -112.07],
...     "relevance": [1_000_000, 2_700_000, 880_000, 1_600_000],
...     "tot_outflow": [100_000, 250_000, 90_000, 150_000],
... })
>>> np.random.seed(0)
>>> radiation = Radiation()
>>> rad_flows = radiation.generate(tessellation, tile_id_column="tile_id",
...                                tot_outflows_column="tot_outflow",
...                                relevance_column="relevance",
...                                out_format="flows_sample")
>>> print(rad_flows.head())
References

.. [SGMB2012] Simini, F., González, M. C., Maritan, A. & Barabási, A.-L. (2012). A universal model for mobility and migration patterns. Nature, 484(7392), 96–100. .. [MSJB2013] Masucci, A. P., Serras, J., Johansson, A. & Batty, M. (2013). Gravity versus radiation models: On the importance of scale and heterogeneity in commuting flows. Physical Review E, 88(2), 022812.

See Also

Gravity

generate(spatial_tessellation, tile_id_column=TILE_ID, tot_outflows_column=TOT_OUTFLOW, relevance_column=RELEVANCE, out_format='flows')

Generate synthetic flows with the Radiation model.

Parameters:

Name Type Description Default
spatial_tessellation DataFrame or GeoDataFrame

The spatial tessellation on which to run the model. Must include a tile identifier column and a relevance column; the total-outflow column is required when out_format is "flows" or "flows_sample".

 required
tile_id_column str

Name of the column containing the location identifier. The default is "tile_id".

 TILE_ID
tot_outflows_column str

Name of the column containing the total outflow per location. Required when out_format is "flows" or "flows_sample". The default is "tot_outflow".

 TOT_OUTFLOW
relevance_column str

Name of the column containing the location relevance (e.g. population). The default is "relevance".

 RELEVANCE
out_format str

Format of the output. Accepted values:

  • "flows" — expected (average) flows between each pair of locations.
  • "flows_sample" — randomly sampled integer flows drawn from a multinomial distribution.
  • "probabilities" — raw trip probability from each origin to each destination (does not require tot_outflows_column).

The default is "flows".

 'flows'

Returns:

Type Description
DataFrame

A dataframe with columns origin, destination, and flow (or probability). A to_matrix() method converts this to a 2-D numpy array indexed by tessellation order.

Raises:

Type Description
KeyError

If out_format requires a total-outflow column but it is absent from spatial_tessellation.
ValueError

If out_format is not one of the accepted values.

fastmob.models.gravity.compute_distance_matrix(spatial_tessellation, origins)

Compute pairwise Haversine distances for tessellation locations.

Parameters:

Name Type Description Default
spatial_tessellation DataFrame or GeoDataFrame

The spatial tessellation. Must include either a geometry column or explicit lat / lng columns so that tile centroids can be derived.

 required
origins list or array-like of int

Indices of the origin locations for which to populate the distance matrix.

 required

Returns:

Type Description
ndarray

Symmetric (n, n) matrix of Haversine distances in kilometres, where n is the number of tiles in spatial_tessellation.

fastmob.models.gravity.exponential_deterrence_func(x, R)

Compute the exponential deterrence \(e^{-xR}\).

Parameters:

Name Type Description Default
x float or ndarray

Distance values.

 required
R float

Decay rate (positive). Larger values penalise longer distances more strongly.

 required

Returns:

Type Description
float or ndarray

Deterrence values in the range (0, 1].

fastmob.models.gravity.powerlaw_deterrence_func(x, exponent)

Compute the power-law deterrence \(x^{\text{exponent}}\).

Parameters:

Name Type Description Default
x float or ndarray

Distance values (in kilometres).

 required
exponent float

Power-law exponent. Typically a negative number (e.g. -2.0) so that the function decreases with distance.

 required

Returns:

Type Description
float or ndarray

Deterrence values.

Individual Trajectory Models

fastmob.models.epr.EPR

Exploration and Preferential Return (EPR) trajectory generator.

The EPR model generates synthetic individual mobility trajectories based on two competing mechanisms drawn from empirical observations of human travel patterns [SKWB2010]_:

Waiting time choice. The time \(\Delta t\) between consecutive moves is drawn from a truncated power law:

\[ P(\Delta t) \sim \Delta t^{-1-\beta} \exp(-\Delta t / \tau). \]

Action selection. With probability \(P_{\text{new}} = \rho S^{-\gamma}\), where \(S\) is the number of distinct previously visited locations, the agent explores a new location; otherwise it returns to a previously visited one.

Exploration. The new location \(j \neq i\) is chosen with probability proportional to the gravity-model score \(p_{ij}\) derived from gravity_singly.

Return. A previously visited location \(i\) is chosen with probability \(\Pi_i = f_i\), proportional to its visitation frequency.

This class is the base for :class:DensityEPR, :class:SpatialEPR, and :class:Ditras.

Parameters:

Name Type Description Default
name str

Human-readable label for this model instance. The default is "EPR model".

 'EPR model'
rho float

Exploration parameter \(\rho \in (0, 1]\) in \(P_{\text{new}} = \rho S^{-\gamma}\). Controls the overall tendency to explore new locations. The default is 0.6 [SKWB2010]_.

 0.6
gamma float

Return-penalty exponent \(\gamma \geq 0\) in \(P_{\text{new}} = \rho S^{-\gamma}\). Larger values cause agents to return more frequently as they accumulate visited locations. The default is 0.21 [SKWB2010]_.

 0.21
beta float

Tail exponent \(\beta\) of the waiting-time distribution. The default is 0.8 [SKWB2010]_.

 0.8
tau int

Characteristic time scale \(\tau\) (in hours) of the waiting-time distribution. The default is 17 [SKWB2010]_.

 17
min_wait_time_minutes int

Minimum waiting time between two moves, in minutes. The default is 20.

 20

Attributes:

Name Type Description
name str

Human-readable label of this model instance.
rho float

The exploration parameter \(\rho\).
gamma float

The return-penalty exponent \(\gamma\).
beta float

The waiting-time tail exponent \(\beta\).
tau int

The waiting-time scale \(\tau\) (in hours).
min_wait_time float

Minimum waiting time in hours (min_wait_time_minutes / 60).
spatial_tessellation_ DataFrame or None

The tessellation used in the last generate() call.
trajectories_ list

Raw trajectory records produced by the last generate() call.
References

.. [SKWB2010] Song, C., Koren, T., Wang, P. & Barabási, A.-L. (2010). Modelling the scaling properties of human mobility. Nature Physics, 6, 818–823.

See Also

DensityEPR, SpatialEPR, Ditras

generate(start_date, end_date, spatial_tessellation, gravity_singly=None, n_agents=1, starting_locations=None, relevance_column=RELEVANCE, random_state=None, log_file=None, show_progress=False)

Simulate agents from start_date to end_date.

Parameters:

Name Type Description Default
start_date Timestamp or datetime

Start time of the simulation.

 required
end_date Timestamp or datetime

End time of the simulation.

 required
spatial_tessellation DataFrame or GeoDataFrame

Division of the territory into locations. Must include either a geometry column or explicit lat / lng columns.

 required
gravity_singly Gravity or None

A singly constrained :class:Gravity model used to derive origin–destination trip probabilities. If None, a default Gravity(gravity_type="singly constrained") is created automatically. The default is None.

 None
n_agents int

Number of agents to simulate. The default is 1.

 1
starting_locations list of int or None

One starting tessellation index per agent. Length must equal n_agents. If None, starting locations are chosen uniformly at random. The default is None.

 None
relevance_column str

Name of the column in spatial_tessellation used as location relevance for the gravity model. The default is "relevance".

 RELEVANCE
random_state int or None

Seed for the random number generator, enabling reproducible results. The default is None (non-deterministic).

 None
log_file str or None

Unused in fastmob (retained for API compatibility). The default is None.

 None
show_progress bool

Unused in fastmob (retained for API compatibility). The default is False.

 False

Returns:

Type Description
DataFrame

Synthetic trajectories with columns uid, datetime, lat, and lng. One row per recorded position.

Raises:

Type Description
IndexError

If starting_locations is provided and has fewer entries than n_agents.
TypeError

If gravity_singly is not a :class:Gravity instance.
AttributeError

If gravity_singly is a :class:Gravity instance but its gravity_type is not "singly constrained".

fastmob.models.epr.DensityEPR

Bases: EPR

Density-EPR (d-EPR) trajectory generator.

The d-EPR model extends :class:EPR by weighting exploratory moves according to a gravity model that accounts for location relevance (e.g. population density) [PSRPGB2015] [PSR2016]. The four mechanisms are:

Waiting time choice. The waiting time \(\Delta t\) between two moves is drawn from \(P(\Delta t) \sim \Delta t^{-1-\beta} \exp(-\Delta t/\tau)\).

Action selection. With probability \(P_{\text{new}} = \rho S^{-\gamma}\), where \(S\) is the number of distinct previously visited locations, the agent explores a new location; otherwise it returns to a previously visited one.

Exploration. If the agent at location \(i\) explores, the destination \(j \neq i\) is selected with probability proportional to the gravity score:

\[ p_{ij} = \frac{n_i n_j}{r_{ij}^2} \]

where \(n_{i(j)}\) is the relevance of location \(i(j)\) and \(r_{ij}\) is their Haversine distance. The set of visited locations \(S\) grows by 1.

Return. A previously visited location \(i\) is chosen with probability proportional to its visitation frequency: \(\Pi_i = f_i\).

Parameters:

Name Type Description Default
name str

Human-readable label. The default is "Density EPR model".

 'Density EPR model'
rho float

Exploration parameter \(\rho \in (0, 1]\). The default is 0.6 [SKWB2010]_.

 0.6
gamma float

Return-penalty exponent \(\gamma \geq 0\). The default is 0.21 [SKWB2010]_.

 0.21
beta float

Waiting-time tail exponent \(\beta\). The default is 0.8 [SKWB2010]_.

 0.8
tau int

Waiting-time scale \(\tau\) in hours. The default is 17 [SKWB2010]_.

 17
min_wait_time_minutes int

Minimum waiting time between moves, in minutes. The default is 20.

 20

Attributes:

Name Type Description
name str

Human-readable label of this model instance.
rho float

The exploration parameter \(\rho\).
gamma float

The return-penalty exponent \(\gamma\).
beta float

The waiting-time tail exponent \(\beta\).
tau int

The waiting-time scale \(\tau\) (in hours).
min_wait_time float

Minimum waiting time in hours.
Notes

spatial_tessellation accepts any eager dataframe (pandas, polars, …). If a relevance column is absent, all locations are treated as equally relevant.

Examples:

>>> import pandas as pd
>>> from fastmob.models import DensityEPR
>>> tessellation = pd.DataFrame({
...     "tile_id": [0, 1, 2, 3],
...     "lat": [40.71, 41.88, 37.77, 33.44],
...     "lng": [-74.01, -87.62, -122.42, -112.07],
...     "relevance": [0.40, 0.30, 0.18, 0.12],
... })
>>> start = pd.Timestamp("2020-01-01 08:00:00")
>>> end   = pd.Timestamp("2020-01-14 08:00:00")
>>> tdf = DensityEPR().generate(start, end, tessellation, n_agents=2, random_state=0)
>>> print(tdf.head())
References

.. [PSRPGB2015] Pappalardo, L. et al. (2015). Returners and Explorers dichotomy in human mobility. Nature Communications, 6, 8166. .. [PSR2016] Pappalardo, L., Simini, F. & Rinzivillo, S. (2016). Human Mobility Modelling: exploration and preferential return meet the gravity model. Procedia Computer Science, 83. .. [SKWB2010] Song, C., Koren, T., Wang, P. & Barabási, A.-L. (2010). Modelling the scaling properties of human mobility. Nature Physics, 6, 818–823.

See Also

EPR, SpatialEPR, Ditras

generate(start_date, end_date, spatial_tessellation, gravity_singly=None, n_agents=1, starting_locations=None, relevance_column=RELEVANCE, random_state=None, log_file=None, show_progress=False)

Simulate agents from start_date to end_date.

Parameters:

Name Type Description Default
start_date Timestamp or datetime

Start time of the simulation.

 required
end_date Timestamp or datetime

End time of the simulation.

 required
spatial_tessellation DataFrame or GeoDataFrame

Division of the territory into locations. Must include either a geometry column or explicit lat / lng columns.

 required
gravity_singly Gravity or None

A singly constrained :class:Gravity model for the exploration phase. If None, a default Gravity(gravity_type="singly constrained") is used. The default is None.

 None
n_agents int

Number of agents to simulate. The default is 1.

 1
starting_locations list of int or None

One tessellation index per agent as the starting position. If None, chosen uniformly at random. The default is None.

 None
relevance_column str

Column in spatial_tessellation used as location relevance for the gravity model. The default is "relevance".

 RELEVANCE
random_state int or None

Random seed for reproducibility. The default is None.

 None
log_file str or None

Unused (retained for API compatibility). The default is None.

 None
show_progress bool

Unused (retained for API compatibility). The default is False.

 False

Returns:

Type Description
DataFrame

Synthetic trajectories with columns uid, datetime, lat, and lng.

fastmob.models.epr.SpatialEPR

Bases: EPR

Spatial-EPR (s-EPR) trajectory generator.

The s-EPR model is a distance-only variant of :class:DensityEPR that ignores location relevance during exploration [PSRPGB2015] [PSR2016] [SKWB2010]_. The four mechanisms are:

Waiting time choice. The waiting time \(\Delta t\) between two moves is drawn from \(P(\Delta t) \sim \Delta t^{-1-\beta} \exp(-\Delta t/\tau)\).

Action selection. With probability \(P_{\text{new}} = \rho S^{-\gamma}\), where \(S\) is the number of distinct previously visited locations, the agent explores a new location; otherwise it returns to a previously visited one.

Exploration. If the agent at location \(i\) explores, the unvisited destination \(j \neq i\) is selected inversely proportional to squared distance only:

\[ p_{ij} = \frac{1}{r_{ij}^2}. \]

Return. A previously visited location \(i\) is chosen with probability proportional to its visitation frequency: \(\Pi_i = f_i\).

Parameters:

Name Type Description Default
name str

Human-readable label. The default is "Spatial EPR model".

 'Spatial EPR model'
rho float

Exploration parameter \(\rho \in (0, 1]\). The default is 0.6 [SKWB2010]_.

 0.6
gamma float

Return-penalty exponent \(\gamma \geq 0\). The default is 0.21 [SKWB2010]_.

 0.21
beta float

Waiting-time tail exponent \(\beta\). The default is 0.8 [SKWB2010]_.

 0.8
tau int

Waiting-time scale \(\tau\) in hours. The default is 17 [SKWB2010]_.

 17
min_wait_time_minutes int

Minimum waiting time between moves, in minutes. The default is 20.

 20

Attributes:

Name Type Description
name str

Human-readable label of this model instance.
rho float

The exploration parameter \(\rho\).
gamma float

The return-penalty exponent \(\gamma\).
beta float

The waiting-time tail exponent \(\beta\).
tau int

The waiting-time scale \(\tau\) (in hours).
min_wait_time float

Minimum waiting time in hours.
Notes

spatial_tessellation accepts any eager dataframe (pandas, polars, …). The relevance_column parameter is accepted for API compatibility but is not used — all location relevances are treated as equal in the spatial phase.

Examples:

>>> import pandas as pd
>>> from fastmob.models import SpatialEPR
>>> tessellation = pd.DataFrame({
...     "tile_id": [0, 1, 2, 3],
...     "lat": [40.71, 41.88, 37.77, 33.44],
...     "lng": [-74.01, -87.62, -122.42, -112.07],
... })
>>> start = pd.Timestamp("2020-01-01 08:00:00")
>>> end   = pd.Timestamp("2020-01-14 08:00:00")
>>> tdf = SpatialEPR().generate(start, end, tessellation, n_agents=2, random_state=0)
>>> print(tdf.head())
References

.. [PSRPGB2015] Pappalardo, L. et al. (2015). Returners and Explorers dichotomy in human mobility. Nature Communications, 6, 8166. .. [PSR2016] Pappalardo, L., Simini, F. & Rinzivillo, S. (2016). Human Mobility Modelling: exploration and preferential return meet the gravity model. Procedia Computer Science, 83. .. [SKWB2010] Song, C., Koren, T., Wang, P. & Barabási, A.-L. (2010). Modelling the scaling properties of human mobility. Nature Physics, 6, 818–823.

See Also

EPR, DensityEPR, Ditras

generate(start_date, end_date, spatial_tessellation, gravity_singly=None, n_agents=1, starting_locations=None, random_state=None, log_file=None, show_progress=False)

Simulate agents from start_date to end_date.

Parameters:

Name Type Description Default
start_date Timestamp or datetime

Start time of the simulation.

 required
end_date Timestamp or datetime

End time of the simulation.

 required
spatial_tessellation DataFrame or GeoDataFrame

Division of the territory into locations.

 required
gravity_singly Gravity or None

A singly constrained :class:Gravity model. The relevance column is ignored; only distances affect exploration probabilities. If None, a default Gravity(gravity_type="singly constrained") is created. The default is None.

 None
n_agents int

Number of agents to simulate. The default is 1.

 1
starting_locations list of int or None

One tessellation index per agent as the starting position. The default is None (chosen uniformly at random).

 None
random_state int or None

Random seed for reproducibility. The default is None.

 None
log_file str or None

Unused (retained for API compatibility). The default is None.

 None
show_progress bool

Unused (retained for API compatibility). The default is False.

 False

Returns:

Type Description
DataFrame

Synthetic trajectories with columns uid, datetime, lat, and lng.

fastmob.models.epr.Ditras

Bases: EPR

DITRAS (DIary-based TRAjectory Simulator) modelling framework.

DITRAS simulates spatio-temporal mobility patterns by combining two probabilistic models [PS2018]_:

Phase 1 — Mobility Diary Generation. A :class:MarkovDiaryGenerator produces a mobility diary \(D(t)\) that encodes the temporal pattern of an agent's routine (home vs. away at each hour).

Phase 2 — Trajectory Generation. The mobility diary drives a :class:DensityEPR-like spatial mechanism: diary slots labelled 0 map the agent back to its home location; other slots trigger an EPR exploration/return step to assign a physical location.

Parameters:

Name Type Description Default
diary_generator MarkovDiaryGenerator

A fitted :class:MarkovDiaryGenerator used to produce mobility diaries.

 required
name str

Human-readable label. The default is "Ditras model".

 'Ditras model'
rho float

Exploration parameter \(\rho \in (0, 1]\) for the spatial phase. The default is 0.3 [PS2018]_.

 0.3
gamma float

Return-penalty exponent \(\gamma \geq 0\) for the spatial phase. The default is 0.21 [PS2018]_.

 0.21

Attributes:

Name Type Description
name str

Human-readable label of this model instance.
rho float

The exploration parameter \(\rho\).
gamma float

The return-penalty exponent \(\gamma\).
Notes

spatial_tessellation accepts any eager dataframe (pandas, polars, …). The diary generator must be fitted via :meth:MarkovDiaryGenerator.fit before passing it to this class.

Examples:

>>> import pandas as pd
>>> from fastmob.models import Ditras
>>> from fastmob.models import MarkovDiaryGenerator
>>> # Build a minimal diary generator (normally trained on real trajectories)
>>> mdg = MarkovDiaryGenerator()
>>> tessellation = pd.DataFrame({
...     "tile_id": [0, 1, 2, 3],
...     "lat": [40.71, 41.88, 37.77, 33.44],
...     "lng": [-74.01, -87.62, -122.42, -112.07],
...     "relevance": [0.40, 0.30, 0.18, 0.12],
... })
>>> start = pd.Timestamp("2020-01-01 08:00:00")
>>> end   = pd.Timestamp("2020-01-14 08:00:00")
>>> ditras = Ditras(mdg)
>>> tdf = ditras.generate(start, end, tessellation,
...                       relevance_column="relevance", n_agents=2,
...                       random_state=0)
>>> print(tdf.head())
References

.. [PS2018] Pappalardo, L. & Simini, F. (2018). Data-driven generation of spatio-temporal routines in human mobility. Data Mining and Knowledge Discovery, 32, 787–829.

See Also

DensityEPR, MarkovDiaryGenerator

generate(start_date, end_date, spatial_tessellation, gravity_singly=None, n_agents=1, starting_locations=None, relevance_column=RELEVANCE, random_state=None, log_file=None, show_progress=False)

Simulate agents from start_date to end_date.

Parameters:

Name Type Description Default
start_date Timestamp or datetime

Start time of the simulation.

 required
end_date Timestamp or datetime

End time of the simulation.

 required
spatial_tessellation DataFrame or GeoDataFrame

Division of the territory into locations. Must include either a geometry column or explicit lat / lng columns.

 required
gravity_singly Gravity or None

A singly constrained :class:Gravity model for the exploration phase. If None, a default Gravity(gravity_type="singly constrained") is used. The default is None.

 None
n_agents int

Number of agents to simulate. The default is 1.

 1
starting_locations list of int or None

One tessellation index per agent as the starting (home) location. If None, chosen uniformly at random. The default is None.

 None
relevance_column str

Column in spatial_tessellation used as location relevance for the gravity exploration phase. The default is "relevance".

 RELEVANCE
random_state int or None

Random seed for reproducibility. The default is None.

 None
log_file str or None

Unused (retained for API compatibility). The default is None.

 None
show_progress bool

Unused (retained for API compatibility). The default is False.

 False

Returns:

Type Description
DataFrame

Synthetic trajectories with columns uid, datetime, lat, and lng.

fastmob.models.markov_diary_generator.MarkovDiaryGenerator

Markov Diary Learner and Generator.

A Mobility Diary Learner (MDL) learns hourly temporal mobility patterns from real individual trajectories and then synthesises new mobility diaries [PS2018]_. A diary \(D(t)\) is a sequence of abstract locations (0 = home, 1, 2, … = non-home destinations in decreasing visitation-frequency order) at hourly resolution.

The learner translates each individual's trajectory into an abstract time series and builds a Markov chain \(MD(t)\) over 48 states: 24 hours of the day \(\times\) 2 typicality values (1 = at the typical/home location, 0 = away). Transition probabilities are estimated by counting state-to-state transitions across all individuals.

A fitted MarkovDiaryGenerator can be passed to :class:Ditras or :class:STS_epr to drive their temporal pattern.

Parameters:

Name Type Description Default
name str

Human-readable label for this instance. The default is "Markov diary".

 'Markov diary'
granularity_minutes int

Temporal resolution of a diary slot, in minutes. Must be a positive divisor of 1440. The default is 60 (hourly, 24 slots/day); 15 gives 96 slots/day and 5 gives 288 slots/day.

 60

Attributes:

Name Type Description
name str

Human-readable label of this instance.
markov_chain_ ndarray or None

Flattened CDF matrix built after :meth:fit. Shape (48 * 48,). None before fitting.
time_slot_length str

Length of each time slot (fixed at "1h").
Notes

The fit method accepts any pandas-compatible dataframe. The trajectory must contain a datetime column (auto-detected) and a user-ID column (uid by default).

Examples:

>>> import pandas as pd
>>> from fastmob.models import MarkovDiaryGenerator
>>> # Normally you would pass a real trajectory TrajDataFrame here.
>>> # This example uses an unfitted generator (home-only diary).
>>> mdg = MarkovDiaryGenerator()
>>> diary = mdg.generate(72, pd.Timestamp("2020-01-01 00:00:00"), random_state=0)
>>> print(diary.head())
References

.. [PS2018] Pappalardo, L. & Simini, F. (2018). Data-driven generation of spatio-temporal routines in human mobility. Data Mining and Knowledge Discovery, 32, 787–829.

See Also

Ditras, STS_epr

fit(traj, n_individuals, lid='location')

Learn the Markov mobility diary from real trajectories.

Builds a 48-state Markov chain from the first n_individuals users in traj. Each state encodes an hour of the day (0–23) and a typicality value (1 = home, 0 = away). The resulting transition probabilities are stored in markov_chain_.

Parameters:

Name Type Description Default
traj DataFrame

Mobility trajectories. Must contain a datetime column and a uid column (auto-detected), plus the location column specified by lid.

 required
n_individuals int

Number of individuals from traj to use for training.

 required
lid str

Name of the column containing the location cluster identifier. The default is "location".

 'location'
Notes

Modifies the internal Markov chain in-place. Call before passing this instance to :class:Ditras or :class:STS_epr.

generate(diary_length, start_date, random_state=None)

Generate a synthetic mobility diary.

Samples a sequence of hourly abstract locations from the fitted Markov chain and returns a compact representation where consecutive identical locations are collapsed to a single row.

Parameters:

Name Type Description Default
diary_length int

Length of the diary in time slots (equal to hours when granularity_minutes=60; e.g. 96 slots = one day at 15-min granularity).

 required
start_date Timestamp or datetime

Starting timestamp for the diary.

 required
random_state int or None

Random seed for reproducibility. The default is None.

 None

Returns:

Type Description
DataFrame

A dataframe with columns:

  • datetime — timestamp of each location change.
  • abstract_location — abstract location identifier (0 = home, 1, 2, … = non-home locations in order of decreasing frequency as learned from real data).
Notes

If :meth:fit has not been called, a trivial diary is generated where the agent stays at home (abstract_location == 0) for the entire period.

Social Trajectory Models

fastmob.models.geosim.GeoSim

GeoSim social trajectory generator.

GeoSim generates synthetic individual mobility trajectories by combining the EPR exploration/return mechanism with a social influence layer [THSG2015]_. Each agent is embedded in a social network, and with probability \(\alpha\) it consults a social contact when choosing its next location.

Waiting time choice. The time \(\Delta t\) between moves is drawn from:

\[ P(\Delta t) \sim \Delta t^{-1-\beta} \exp(-\Delta t/\tau). \]

Action selection. With probability \(P_{\text{exp}} = \rho S^{-\gamma}\), where \(S\) is the number of distinct previously visited locations, the agent explores a new location; otherwise it returns. At that point, with probability \(\alpha\) a social contact influences the location choice (Social); with probability \(1 - \alpha\) the agent acts alone (Individual).

Individual Exploration. An unvisited location is selected uniformly at random from the set \(\text{exp}(a)\) of all unvisited locations for agent \(a\). The set \(S\) grows by 1.

Social Exploration. A social contact \(c\) is selected with probability proportional to the cosine mobility similarity between \(a\) and \(c\). A location is then selected from \(\text{exp}(a) \cap \text{ret}(c)\) with probability proportional to \(c\)'s visitation frequency. The set \(S\) grows by 1.

Individual Return. A previously visited location \(j \in \text{ret}(a)\) is selected with probability proportional to its visitation frequency \(\Pi_j = f_j\).

Social Return. A social contact \(c\) is selected (as in Social Exploration). A location from \(\text{ret}(a) \cap \text{ret}(c)\) is selected proportionally to \(c\)'s visitation frequency.

Parameters:

Name Type Description Default
name str

Human-readable label. The default is "GeoSim".

 'GeoSim'
rho float

Exploration parameter \(\rho \in (0, 1]\). The default is 0.6 [SKWB2010]_.

 0.6
gamma float

Return-penalty exponent \(\gamma \geq 0\). The default is 0.21 [SKWB2010]_.

 0.21
alpha float

Social influence probability \(\alpha \in [0, 1]\). The default is 0.2 [THSG2015]_.

 0.2
beta float

Waiting-time tail exponent \(\beta\). The default is 0.8 [SKWB2010]_.

 0.8
tau int

Waiting-time scale \(\tau\) in hours. The default is 17 [SKWB2010]_.

 17
min_wait_time_hours float

Minimum waiting time between moves, in hours. The default is 1.

 1

Attributes:

Name Type Description
name str

Human-readable label of this model instance.
rho float

The exploration parameter \(\rho\).
gamma float

The return-penalty exponent \(\gamma\).
alpha float

The social influence probability \(\alpha\).
beta float

The waiting-time tail exponent \(\beta\).
tau int

The waiting-time scale \(\tau\) (in hours).
min_wait_time_hours float

Minimum waiting time in hours.
Notes

spatial_tessellation accepts any pandas-compatible eager dataframe. It must contain either a geometry column or explicit lat / lng columns. When social_graph="random" a random geometric graph is generated automatically; alternatively, pass an edge list to define specific social connections.

References

.. [PSRPGB2015] Pappalardo, L. et al. (2015). Returners and Explorers dichotomy in human mobility. Nature Communications, 6, 8166. .. [PSR2016] Pappalardo, L., Simini, F. & Rinzivillo, S. (2016). Human Mobility Modelling: exploration and preferential return meet the gravity model. Procedia Computer Science, 83. .. [SKWB2010] Song, C., Koren, T., Wang, P. & Barabási, A.-L. (2010). Modelling the scaling properties of human mobility. Nature Physics, 6, 818–823. .. [THSG2015] Toole, J. et al. (2015). Coupling Human Mobility and Social Ties. Journal of the Royal Society Interface, 12, 20141128.

See Also

EPR, SpatialEPR, Ditras, STS_epr

generate(start_date, end_date, spatial_tessellation, social_graph='random', n_agents=500, dt_update_mobSim=24 * 7, indipendency_window=0.5, random_state=None, log_file=None, verbose=0, show_progress=False)

Simulate a socially connected population from start_date to end_date.

Parameters:

Name Type Description Default
start_date Timestamp or datetime

Start time of the simulation.

 required
end_date Timestamp or datetime

End time of the simulation.

 required
spatial_tessellation DataFrame or GeoDataFrame

Division of the territory into locations. Must include either a geometry column or explicit lat / lng columns. Must contain at least 2 tiles.

 required
social_graph ``"random"`` or list of (uid, uid) tuples

Social network for the simulated agents.

  • "random" — a random geometric graph on n_agents nodes is generated automatically.
  • A list of (uid_a, uid_b) edge tuples — the number of agents is inferred from the unique node set; n_agents is ignored.

The default is "random".

 'random'
n_agents int

Number of agents when social_graph="random". The default is 500.

 500
dt_update_mobSim float

Interval in hours between social-graph mobility-similarity updates. The default is 168 (one week).

 24 * 7
indipendency_window float

Time window in hours that must elapse before an agent's move can affect other agents' social choices. The default is 0.5.

 0.5
random_state int or None

Random seed for reproducibility. The default is None.

 None
log_file str or None

Unused (retained for API compatibility). The default is None.

 None
verbose int

Unused (retained for API compatibility). The default is 0.

 0
show_progress bool

Unused (retained for API compatibility). The default is False.

 False

Returns:

Type Description
DataFrame

Synthetic trajectories with columns uid, datetime, lat, and lng.

Raises:

Type Description
ValueError

If n_agents <= 0, start_date > end_date, social_graph is an empty list, or social_graph is a string other than "random".
TypeError

If social_graph is neither a string nor a list.

fastmob.models.sts_epr.STS_epr

STS-EPR (Spatial, Temporal, and Social EPR) trajectory generator.

STS-EPR extends :class:GeoSim by incorporating a temporal diary (via :class:MarkovDiaryGenerator) and a gravity-weighted individual exploration mechanism [CRP2020]_. Each agent follows a pre-generated mobility diary that dictates when to move (home vs. away), while the social and EPR mechanisms determine where to go.

Action selection. With probability \(P_{\text{exp}} = \rho S^{-\gamma}\) the agent explores a new location; otherwise it returns. With probability \(\alpha\) a social contact influences the destination (Social); with probability \(1 - \alpha\) the agent acts alone (Individual). Diary entries with abstract_location == 0 always force a return to the home location.

Individual Exploration. An unvisited location \(j \neq i\) is selected with probability proportional to the gravity score:

\[ p_{ij} = \frac{r_i r_j}{d_{ij}^2} \]

where \(r_{i(j)}\) is location relevance and \(d_{ij}\) is the Haversine distance.

Social Exploration. A social contact \(c\) is selected with probability proportional to cosine mobility similarity. A location from \(\text{exp}(a) \cap \text{ret}(c)\) is chosen proportionally to \(c\)'s visitation frequency.

Individual Return. A previously visited location \(j \in \text{ret}(a)\) is chosen with probability \(\Pi_j = f_j\).

Social Return. As in Social Exploration, but from \(\text{ret}(a) \cap \text{ret}(c)\).

Parameters:

Name Type Description Default
name str

Human-readable label. The default is "STS-EPR".

 'STS-EPR'
rho float

Exploration parameter \(\rho \in (0, 1]\). The default is 0.6 [SKWB2010]_.

 0.6
gamma float

Return-penalty exponent \(\gamma \geq 0\). The default is 0.21 [SKWB2010]_.

 0.21
alpha float

Social influence probability \(\alpha \in [0, 1]\). The default is 0.2 [THSG2015]_.

 0.2

Attributes:

Name Type Description
name str

Human-readable label of this model instance.
rho float

The exploration parameter \(\rho\).
gamma float

The return-penalty exponent \(\gamma\).
alpha float

The social influence probability \(\alpha\).
Notes

spatial_tessellation must contain at least 3 tiles and a relevance column. The :class:MarkovDiaryGenerator must be fitted before being passed to :meth:generate.

References

.. [PSRPGB2015] Pappalardo, L. et al. (2015). Returners and Explorers dichotomy in human mobility. Nature Communications, 6, 8166. .. [PSR2016] Pappalardo, L., Simini, F. & Rinzivillo, S. (2016). Human Mobility Modelling: exploration and preferential return meet the gravity model. Procedia Computer Science, 83. .. [SKWB2010] Song, C., Koren, T., Wang, P. & Barabási, A.-L. (2010). Modelling the scaling properties of human mobility. Nature Physics, 6, 818–823. .. [THSG2015] Toole, J. et al. (2015). Coupling Human Mobility and Social Ties. Journal of the Royal Society Interface, 12, 20141128. .. [CRP2020] Cornacchia, G., Rossetti, G. & Pappalardo, L. (2020). Modelling Human Mobility considering Spatial, Temporal and Social Dimensions. .. [PS2018] Pappalardo, L. & Simini, F. (2018). Data-driven generation of spatio-temporal routines in human mobility. Data Mining and Knowledge Discovery, 32, 787–829.

See Also

GeoSim, Ditras, MarkovDiaryGenerator

generate(start_date, end_date, spatial_tessellation, diary_generator, social_graph='random', n_agents=500, rsl=False, distance_matrix=None, relevance_column=None, min_relevance=0.1, dt_update_mobSim=24 * 7, indipendency_window=0.5, random_state=None, log_file=None, verbose=0, show_progress=False)

Simulate a socially connected population from start_date to end_date.

Parameters:

Name Type Description Default
start_date Timestamp or datetime

Start time of the simulation.

 required
end_date Timestamp or datetime

End time of the simulation.

 required
spatial_tessellation DataFrame or GeoDataFrame

Division of the territory into locations. Must include either a geometry column or explicit lat / lng columns, and a relevance column. Must contain at least 3 tiles.

 required
diary_generator MarkovDiaryGenerator

A fitted :class:MarkovDiaryGenerator that supplies the temporal mobility diary for each agent.

 required
social_graph ``"random"`` or list of (uid, uid) tuples

Social network for the agents.

  • "random" — a random geometric graph is generated automatically.
  • A list of (uid_a, uid_b) edge tuples — the number of agents is inferred from the unique node set.

The default is "random".

 'random'
n_agents int

Number of agents when social_graph="random". The default is 500.

 500
rsl bool

If True, the starting location for each agent is sampled with probability proportional to the location's relevance. If False, it is chosen uniformly at random. The default is False.

 False
distance_matrix ndarray or None

Pre-computed (n_locs, n_locs) distance matrix in kilometres. If None, the Rust simulator uses cached gravity OD rows instead of a full matrix. The default is None.

 None
relevance_column str or None

Name of the column in spatial_tessellation used as location relevance. The default is None (falls back to "relevance").

 None
min_relevance float

Value substituted for any zero-relevance location to avoid division by zero. The default is 0.1.

 0.1
dt_update_mobSim float

Interval in hours between social-graph mobility-similarity updates. The default is 168 (one week).

 24 * 7
indipendency_window float

Time window in hours before an agent's move can influence others. The default is 0.5.

 0.5
random_state int or None

Random seed for reproducibility. The default is None.

 None
log_file str or None

Unused (retained for API compatibility). The default is None.

 None
verbose int

Unused (retained for API compatibility). The default is 0.

 0
show_progress bool

Unused (retained for API compatibility). The default is False.

 False

Returns:

Type Description
DataFrame

Synthetic trajectories with columns uid, datetime, lat, and lng.

Raises:

Type Description
TypeError

If diary_generator is not a :class:MarkovDiaryGenerator or rsl is not a bool.
ValueError

If n_agents <= 0, start_date > end_date, social_graph is an empty list, or the social graph string is not "random".
IndexError

If relevance_column is not found in spatial_tessellation.

Helpers

fastmob.models.epr.compute_od_matrix(gravity_singly, spatial_tessellation, tile_id_column='tile_id', relevance_column=RELEVANCE)

Compute an OD probability matrix from a singly constrained gravity model.

Returns a 2-D numpy array M where element M[i, j] is the probability \(p_{ij}\) of moving from location i to location j, as predicted by the singly constrained Gravity model applied to spatial_tessellation.

Parameters:

Name Type Description Default
gravity_singly Gravity

A :class:Gravity instance with gravity_type="singly constrained".

 required
spatial_tessellation DataFrame or GeoDataFrame

The spatial tessellation describing the division of the territory into locations.

 required
tile_id_column str

Name of the column containing the location identifier. The default is "tile_id".

 'tile_id'
relevance_column str

Name of the column containing the location relevance. The default is "relevance".

 RELEVANCE

Returns:

Type Description
ndarray

A (n_locs, n_locs) array of trip probabilities. Each row sums to 1.