net_matrix_optim: Estimate Migration Flows to Match Net Totals via Quadratic Optimization

Description

Solves for an origin–destination flow matrix that satisfies directional net migration constraints while minimizing squared deviation from a prior matrix.

Usage

net_matrix_optim(net_tot, m, zero_mask = NULL, maxit = 500, tol = 1e-06)

Value

A named list with components:

n: Estimated matrix of flows satisfying the net constraints.
it: Number of optimization iterations (if available).
tol: Tolerance used for the net flow balance check.
value: Objective function value (sum of squared deviations).
convergence: Logical indicating successful convergence.
message: Solver message or status.

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.
maxit: Maximum number of iterations to perform. Default is 500.
tol: Numeric tolerance for checking whether sum(net_tot) == 0. Default is 1e-6.

Details

The function minimizes: $$\sum_{i,j} (y_{ij} - m_{ij})^2$$ subject to directional net flow constraints: $$\sum_j y_{ji} - \sum_j y_{ij} = \text{net}_i$$ and non-negativity constraints on all flows. Structural zeros are enforced using zero_mask. Internally uses optim() or a constrained quadratic programming solver.

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_optim(net_tot = net, m = m)
result$n |>
  addmargins() |>
  round(2)
sum_region(result$n)