# Estimate mobility flows based on different trip distribution laws and models

Source:`R/run_law_model.R`

`run_law_model.Rd`

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 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
)
```

## 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).

## 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.

## Details

First, we compute the matrix `proba`

estimating the probability
\(p_{ij}\) to observe a trip from location \(i\) to
another location \(j\)
(\(\sum_{i}\sum_{j} p_{ij}=1\)). This
probability is based on the demand \(m_{i}\)
(argument `mass_origin`

) and the attractiveness
\(m_{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_{ij}\) between locations (argument `distance`

) OR
the number of opportunities \(s_{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 Lenormand et al. (2016) . Four gravity laws (Carey 1858; Zipf 1946; Barthelemy 2011; Lenormand et al. 2016) , three intervening opportunity laws (Schneider 1959; Simini et al. 2012; Yang et al. 2014) and a uniform law.

Gravity law with an exponential distance decay function (

`law = "GravExp"`

). The arguments`mass_origin`

,`mass_destination`

(optional),`distance`

and`param`

will be used.Normalized gravity law with an exponential distance decay function (

`law = "NGravExp"`

). The arguments`mass_origin`

,`mass_destination`

(optional),`distance`

and`param`

will be used.Gravity law with a power distance decay function (

`law = "GravPow"`

). The arguments`mass_origin`

,`mass_destination`

(optional),`distance`

and`param`

will be used.Normalized gravity law with a power distance decay function (

`law = "NGravPow"`

). The arguments`mass_origin`

,`mass_destination`

(optional),`distance`

and`param`

will be used.Schneider's intervening opportunities law (

`law = "Schneider"`

). The arguments`mass_origin`

,`mass_destination`

(optional),`opportunity`

and`param`

will be used.Radiation law (

`law = "Rad"`

). The arguments`mass_origin`

,`mass_destination`

(optional) and`opportunity`

will be used.Extended radiation law (

`law = "RadExt"`

). The arguments`mass_origin`

,`mass_destination`

(optional),`opportunity`

and`param`

will be used.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_{i}\) (argument `out_trips`

) AND/OR the number of in-coming
\(D_{j}\) (argument `in_trips`

) according to the model. The sum of
out-going trips \(\sum_{i} O_{i}\) should be equal to the
sum of in-coming trips \(\sum_{j} D_{j}\).

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_trips`

will not be used). The doubly constrained model is based on an Iterative Proportional Fitting process (Deming and 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.

## Note

All the inputs should be based on the same number of
locations sorted in the same order. It is recommended to use the location ID
as vector names, matrix rownames and matrix colnames and to set
`check_names = TRUE`

to verify that everything is in order before running
this function (`check_names = FALSE`

by default). Note that the function
`check_format_names()`

can be used to control the validity of all the inputs
before running the main package's functions.

## References

Lenormand M, Bassolas A, Ramasco JJ (2016).
“Systematic comparison of trip distribution laws and models.”
*Journal of Transport Geography*, **51**, 158-169.

Carey HC (1858).
*Principles of Social Science*.
Lippincott.

Zipf GK (1946).
“The P1 P2/D Hypothesis: On the Intercity Movement of Persons.”
*American Sociological Review*, **11**(6), 677--686.

Barthelemy M (2011).
“Spatial Networks.”
*Physics Reports*, **499**, 1-101.

Schneider M (1959).
“Gravity models and trip distribution theory.”
*Papers of the regional science association*, **5**, 51-58.

Simini F, González MC, Maritan A, Barabasi A (2012).
“A universal model for mobility and migration patterns.”
*Nature*, **484**, 96-100.

Yang Y, Herrera C, Eagle N, González MC (2014).
“Limits of Predictability in Commuting Flows in the Absence of Data for Calibration.”
*Scientific Reports*, **4**(5662), 5662.

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.

## Author

Maxime Lenormand (maxime.lenormand@inrae.fr)

## Examples

```
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)
#> Argument Value
#> 1 Law GravExp
#> 2 Model DCM
#> 3 #Replications 3
#> 4 #Parameters 1
#> 5 Parameter 0.01
```