net_matrix_entropy {migest} | R Documentation |
Estimate Migration Flows to Match Net Totals via Entropy Minimization
Description
Solves for an origin–destination flow matrix that satisfies directional net migration constraints while minimizing Kullback–Leibler (KL) divergence from a prior matrix. This yields a smooth, information-theoretically regularized solution that balances fidelity to prior patterns with net flow requirements.
Usage
net_matrix_entropy(net_tot, m, zero_mask = NULL, tol = 1e-06, verbose = FALSE)
Arguments
net_tot |
A numeric vector of net migration totals for each region. Must sum to zero. |
m |
A square numeric matrix providing prior flow estimates. Must have dimensions |
zero_mask |
A logical matrix of the same dimensions as |
tol |
Numeric tolerance for checking whether |
verbose |
Logical flag to print solver diagnostics from |
Details
This function minimizes the KL divergence between the estimated matrix y_{ij}
and the prior matrix m_{ij}
:
\sum_{i,j} \left[y_{ij} \log\left(\frac{y_{ij}}{m_{ij}}\right) - y_{ij} + m_{ij}\right]
subject to directional net flow constraints:
\sum_j y_{ji} - \sum_j y_{ij} = \text{net}_i
All flows are constrained to be non-negative. Structural zeros are enforced via zero_mask
.
Internally uses CVXR::kl_div()
for DCP-compliant KL minimization.
Value
A named list with components:
n
Estimated matrix of flows satisfying the net constraints.
it
Number of iterations (always
1
for this solver).tol
Tolerance used for the net flow balance check.
value
Sum of squared deviation from target net flows.
convergence
Logical indicating successful optimization.
message
Solver message returned by
CVXR
.
See Also
net_matrix_lp()
for linear programming using L1 loss,
net_matrix_ipf()
for iterative proportional fitting with multiplicative scaling,
and net_matrix_optim()
for quadratic loss minimization.
Examples
m <- matrix(c(0, 100, 30, 70,
50, 0, 45, 5,
60, 35, 0, 40,
20, 25, 20, 0),
nrow = 4, byrow = TRUE,
dimnames = list(orig = LETTERS[1:4], dest = LETTERS[1:4]))
addmargins(m)
sum_region(m)
net <- c(30, 40, -15, -55)
result <- net_matrix_entropy(net_tot = net, m = m)
result$n |>
addmargins() |>
round(2)
sum_region(result$n)