This function estimates mobility flows using different distribution laws and models. As described in Lenormand et al. (2016), 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 based on this law. This function only uses the second step to generate mobility flow based on a matrix of probabilities using different models.
run_model(
proba,
model = "UM",
nb_trips = 1000,
out_trips = NULL,
in_trips = out_trips,
average = FALSE,
nbrep = 3,
maxiter = 50,
mindiff = 0.01,
check_names = FALSE
)An object of class TDLM. A list of matrices containing the nbrep
simulated matrices.
A squared matrix of probability. The sum of the matrix element
must be equal to 1. It will be normalized automatically if it is not the
case.
A character indicating which model to use.
A numeric value indicating the total number of trips. Must
be an integer if average = FALSE (see Details).
A numeric vector representing the number of outgoing
trips per location. Must be a vector of integers if average = FALSE
(see Details).
A numeric vector representing the number of incoming
trips per location. Must be a vector of integers if average = FALSE
(see Details).
A boolean indicating if the average mobility flow matrix
should be generated instead of the nbrep matrices based on random draws
(see Details).
An integer indicating the number of replications
associated with the model run. Note that nbrep = 1 if average = TRUE
(see Details).
An integer indicating the maximal number of iterations for
adjusting the Doubly Constrained Model (see Details).
A numeric strictly positive value indicating the
stopping criterion for adjusting the Doubly Constrained Model (see Details).
A boolean indicating whether the location IDs used as
matrix rownames and colnames should be checked for consistency
(see Note).
Maxime Lenormand (maxime.lenormand@inrae.fr)
We propose four constrained models to generate the flows from these
distribution of probability as described in Lenromand et al. (2016).
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 (argument out_trips) AND/OR the number of in-coming
(argument in_trips) according to the model. The sum of out-going trips
should be equal to the sum of in-coming trips.
Unconstrained model (model = "UM"). Only nb_trips will be preserved
(arguments out_trips and in_trips will not be used).
Production constrained model (model = "PCM"). Only out_trips will be
preserved (arguments nb_trips and in_trips will not be used).
Attraction constrained model (model = "ACM"). Only in_trips will be
preserved (arguments nb_trips and out_trips will not be used).
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 (Deming & Stephan, 1940). 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.
Deming WE & Stephan FF (1940) On a Least Squares Adjustment of a Sample Frequency Table When the Expected Marginal Totals Are Known. Annals of Mathematical Statistics 11, 427-444.
Lenormand M, Bassolas A, Ramasco JJ (2016) Systematic comparison of trip distribution laws and models. Journal of Transport Geography 51, 158-169.
For more details illustrated with a practical example, see the vignette: https://epivec.github.io/TDLM/articles/TDLM.html#run-functions.
Associated functions:
run_law_model(), run_law(), gof().
data(mass)
data(od)
proba <- od / sum(od)
Oi <- as.numeric(mass[, 2])
Dj <- as.numeric(mass[, 3])
res <- run_model(
proba = proba,
model = "DCM", nb_trips = NULL, out_trips = Oi, in_trips = Dj,
average = FALSE, nbrep = 3, maxiter = 50, mindiff = 0.01,
check_names = FALSE
)
# print(res)
Run the code above in your browser using DataLab