net_matrix_entropy: 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)

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.

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 length(net_tot) × length(net_tot).
zero_mask: A logical matrix of the same dimensions as m, where TRUE indicates forbidden (structurally zero) flows. Defaults to disallowing diagonal flows.
tol: Numeric tolerance for checking whether sum(net_tot) == 0. Default is 1e-6.
verbose: Logical flag to print solver diagnostics from CVXR. Default is FALSE.

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.

Examples

Run this code

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)