Learn R Programming

TDLM (version 1.0.0)

run_law_model: Estimate mobility flows based on different trip distribution laws and models

Description

This function estimates mobility flows using different distribution laws and models. As described in Lenormand2016;textualTDLM, the function uses a two-step approach to generate mobility flows by separating the trip distribution law, gravity or intervening opportunities, from the modeling approach used to generate the flows from this law.

Usage

run_law_model(
  law = "Unif",
  mass_origin,
  mass_destination = mass_origin,
  distance = NULL,
  opportunity = NULL,
  param = NULL,
  model = "UM",
  nb_trips = 1000,
  out_trips = NULL,
  in_trips = out_trips,
  average = FALSE,
  nbrep = 3,
  maxiter = 50,
  mindiff = 0.01,
  write_proba = FALSE,
  check_names = FALSE
)

Value

An object of class TDLM. A list of list of matrices containing for each parameter value the nbrep simulated matrices and the matrix of probabilities (called proba) if write_proba = TRUE. If length(param) = 1 or law = "Rad" or law = "Unif only a list of matrices will be returned.

Arguments

law

a character indicating which law to use (see Details).

mass_origin

a numeric vector representing the mass at origin (i.e. demand).

mass_destination

a numeric vector representing the mass at destination (i.e. attractiveness).

distance

a squared matrix representing the distance between locations (see Details).

opportunity

a squared matrix representing the number of opportunities between locations (see Details). Can be easily computed with extract_opportunities().

param

a vector of numeric value(s) used to adjust the importance of distance or opportunity associated with the chosen law. A single value or a vector of several parameter values can be used (see Return). Not necessary for the original radiation law or the uniform law (see Details).

model

a character indicating which model to use.

nb_trips

a numeric value indicating the total number of trips. Must be an integer if average = FALSE (see Details).

out_trips

a numeric vector representing the number of outgoing trips per location. Must be a vector of integers if average = FALSE (see Details).

in_trips

a numeric vector representing the number of incoming trips per location. Must be a vector of integers if average = FALSE (see Details).

average

a boolean indicating if the average mobility flow matrix should be generated instead of the nbrep matrices based on random draws (see Details).

nbrep

an integer indicating the number of replications associated to the model run. Note that nbrep = 1 if average = TRUE (see Details).

maxiter

an integer indicating the maximal number of iterations for adjusting the Doubly Constrained Model (see Details).

mindiff

a numeric strictly positive value indicating the stopping criterion for adjusting the Doubly Constrained Model (see Details).

write_proba

a boolean indicating if the estimation of the probability to move from one location to another obtained with the distribution law should be returned along with the flows estimations.

check_names

a boolean indicating if the ID location are used as vector names, matrix rownames and colnames and if they should be checked (see Note).

Author

Maxime Lenormand (maxime.lenormand@inrae.fr)

Details

First, we compute the matrix proba estimating the probability p_ijp_ij to observe a trip from location ii to another location jj (_i_j p_ij=1_i_j p_ij=1). This probability is based on the demand m_im_i (argument mass_origin) and the attractiveness m_jm_j (argument mass_destination). Note that the population is typically used as a surrogate for both quantities (this is why mass_destination = mass_origin by default). It also depends on the distance d_ijd_ij between locations (argument distance) OR the number of opportunities s_ijs_ij between locations (argument opportunity) depending on the chosen law. Both the effect of the distance and the number of opportunities can be adjusted with a parameter (argument param) except for the original radiation law and the uniform law.

In this package we consider eight probabilistic laws described in details in Lenormand2016;textualTDLM. Four gravity laws Carey1858,Zipf1946,Barthelemy2011,Lenormand2016TDLM, three intervening opportunity laws Schneider1959,Simini2012,Yang2014TDLM and a uniform law.

  1. Gravity law with an exponential distance decay function (law = "GravExp"). The arguments mass_origin, mass_destination (optional), distance and param will be used.

  2. Normalized gravity law with an exponential distance decay function (law = "NGravExp"). The arguments mass_origin, mass_destination (optional), distance and param will be used.

  3. Gravity law with a power distance decay function (law = "GravPow"). The arguments mass_origin, mass_destination (optional), distance and param will be used.

  4. Normalized gravity law with a power distance decay function (law = "NGravPow"). The arguments mass_origin, mass_destination (optional), distance and param will be used.

  5. Schneider's intervening opportunities law (law = "Schneider"). The arguments mass_origin, mass_destination (optional), opportunity and param will be used.

  6. Radiation law (law = "Rad"). The arguments mass_origin, mass_destination (optional) and opportunity will be used.

  7. Extended radiation law (law = "RadExt"). The arguments mass_origin, mass_destination (optional), opportunity and param will be used.

  8. Uniform law (law = "Unif"). The argument mass_origin will be used to extract the number of locations.

Second, we propose four constrained models to generate the flows from these distribution of probability. These models respect different level of constraints. These constraints can preserve the total number of trips (argument nb_trips) OR the number of out-going trips O_iO_i (argument out_trips) AND/OR the number of in-coming D_jD_j (argument in_trips) according to the model. The sum of out-going trips _i O_i_i O_i should be equal to the sum of in-coming trips _j D_j_j D_j.

  1. Unconstrained model (model = "UM"). Only nb_trips will be preserved (arguments out_trips and in_trips will not be used).

  2. Production constrained model (model = "PCM"). Only out_trips will be preserved (arguments nb_trips and in_trips will not be used).

  3. Attraction constrained model (model = "ACM"). Only in_trips will be preserved (arguments nb_trips and out_trips will not be used).

  4. Doubly constrained model (model = "DCM"). Both out_trips and in_trips will be preserved (arguments nb_tripswill not be used). The doubly constrained model is based on an Iterative Proportional Fitting process Deming1940TDLM. The arguments maxiter (50 by default) and mindiff (0.01 by default) can be used to tune the model. mindiff is the minimal tolerated relative error between the simulated and observed marginals. maxiter ensures that the algorithm stops even if it has not converged toward the mindiff wanted value.

By default, when average = FALSE, nbrep matrices are generated from proba with multinomial random draws that will take different forms according to the model used. In this case, the models will deal with positive integers as inputs and outputs. Nevertheless, it is also possible to generate an average matrix based on a multinomial distribution (based on an infinite number of drawings). In this case, the models' inputs can be either positive integer or real numbers and the output (nbrep = 1 in this case) will be a matrix of positive real numbers.

References

Lenormand2016TDLM

Carey1858TDLM

Zipf1946TDLM

Barthelemy2011TDLM

Schneider1959TDLM

Simini2012TDLM

Yang2014TDLM

Deming1940TDLM

See Also

gof() run_law() run_model() extract_opportunities() check_format_names()

Examples

Run this code
data(mass)
data(distance)

mi <- as.numeric(mass[, 1])
mj <- mi
Oi <- as.numeric(mass[, 2])
Dj <- as.numeric(mass[, 3])

res <- run_law_model(
  law = "GravExp", mass_origin = mi, mass_destination = mj,
  distance = distance, opportunity = NULL, param = 0.01,
  model = "DCM", nb_trips = NULL, out_trips = Oi, in_trips = Dj,
  average = FALSE, nbrep = 3, maxiter = 50, mindiff = 0.01,
  write_proba = FALSE,
  check_names = FALSE
)

print(res)

Run the code above in your browser using DataLab