ipf3.qi: Iterative Proportional Fitting Routine for the Indirect Estimation of Origin-Destination-Migrant Type Migration Flow Tables with Known Origin and Destination Margins and Diagonal Elements.

Description

This function is predominantly intended to be used within the ffs routine. The ipf3 function finds the maximum likelihood estimates for fitted values in the log-linear model:

\log y_{i j k} = \log α_{i} + \log β_{j} + \log λ_{k} + \log γ_{i k} + \log κ_{j k} + \log δ_{i j k} I (i = j) + \log m_{i j k}

where $m_{ijk}$ is a set of prior estimates for $y_{ijk}$ and is no more complex than the matrices being fitted. The $\delta_{ijk}I(i=j)$ term ensures a saturated fit on the diagonal elements of each $(i,j)$ matrix.

Usage

ipf3.qi(rtot = NULL, ctot = NULL, dtot = NULL, m = NULL, speed = TRUE, tol = 1e-05, 
        maxit = 500, verbose = TRUE)

Arguments

rtot

Matrix of origin totals (by migrant characteristic) to constrain indirect estimates to. Row of matrix corresponds to origin and column of table corresponds to migrant type/characteristic.

ctot

Matrix of destination totals (by migrant characteristic) to constrain indirect estimates to. Row of matrix corresponds to destination and column of table corresponds to migrant type/characteristic.

dtot

Array with counts on diagonal to constrain diagonal elements of the indirect estimates too. By default these are taken as their maximum possible values given the relevant margins totals in each table. If user specifies their own array of diagonal totals,

Array of auxiliary data. By default set to 1 for all origin-destination-migrant type combinations.

speed

Speeds up the IPF algorithm by minimising sufficient statistics.

tol

Tolerance level for parameter estimation.

maxit

Maximum number of verboseations for parameter estimation.

verbose

Print the parameter estimates at each verboseation. By default FALSE.

Value

Returns a list object with
muArray of indirect estimates of origin-destination matrices by migrant characteristic
itIteration count
tolTolerance level at final verboseation

Details

Iterative Proportional Fitting routine set up using the partial likelihood derivatives illustrated in Abel (2013). The arguments rtot and ctot take the row-table and column-table specific known margins. By default the diagonal values are taken as their maximum possible values given the relevant margins totals in each table. Diagonal values can be added by the user, but care must be taken to ensure resulting diagonals are feasible given the set of margins. The user must ensure that the row and column totals in each table sum to the same value. Care must also be taken to allow the dimension of the auxiliary matrix (m) equal those provided in the row and column totals.

References

Abel, G. J. (2013). Estimating Global Migration Flow Tables Using Place of Birth. Demographic Research 28, (18) 505-546

Examples

Run this code

## create row-table and column-table specific known margins.
dn <- LETTERS[1:4]
P1 <- matrix(c(1000, 100, 10, 0, 55, 555, 50, 5, 80, 40, 800, 40, 20, 25, 20, 200), 4, 4, 
        dimnames = list(pob = dn, por = dn), byrow = TRUE)
P2 <- matrix(c(950, 100, 60, 0, 80, 505, 75, 5, 90, 30, 800, 40, 40, 45, 0, 180), 4, 4, 
        dimnames = list(pob = dn, por = dn), byrow = TRUE)
# display with row and col totals
addmargins(P1)
addmargins(P2)

# run ipf
y <- ipf3.qi(rtot = t(P1), ctot = P2)
# display with row, col and table totals
round(addmargins(y$mu), 1)
# origin-destination flow table
round(fm(y$mu), 1)

## with alternative offset term
dis <- array(c(1, 2, 3, 4, 2, 1, 5, 6, 3, 4, 1, 7, 4, 6, 7, 1), c(4, 4, 4))
y <- ipf3.qi(rtot = t(P1), ctot = P2, m = dis)
# display with row, col and table totals
round(addmargins(y$mu), 1)
# origin-destination flow table
round(fm(y$mu), 1)

Run the code above in your browser using DataLab

State of Data and AI Literacy Report 2025