ipf: Iterative proportional fitting
In travelr: Functions for Travel Demand Modeling

Description Usage Arguments Details Value Author(s) References Examples

Perform iterative proportional fitting of a matrix using the “Fratar” method

1
2
3

ipf(mtx, factors, method = NULL, max.rmse = 1e-07, max.iter = 50)
## S3 method for class 'iterative.fit'
print(x, ...)

`mtx`	A matrix or array with at least two dimensions that will be expanded to match the margins contained in `factors`
`factors`	A vector, list, or `data.frame` of factors indicating how to grow the matri; See details
`method`	How to interpret the factors. Choices are “absolute”, “fraction” or “percent”; See details
`max.rmse`	Convergence limit. Terminate fitting when the root mean square error between the expanded array margins and the target factors is less than `max.rmse`.
`max.iter`	Convergence limit. Terminate after this number of row and column iterations if the
`x`	An `iterative.fit` object returned from `ipf` describing convergence results
`...`	Additional arguments to pass on to print methods

ipf will iteratively adjust the matrix margins until they match the corresponding element of the factors.

The factors element is either a vector, a list or a data.frame, with one element or column per dimension of mtx. A vector or two-column data.frame is appropriate if mtx is a square matrix, otherwise factors must be a list.

The first element of factors corresponds to the desired row sums of the matrix, and the second element corresponds to the desired column sums of the matrix. Likewise if mtx has additional dimensions. If factors is a vector, the same vector will be used to establish the sums in all dimensions, but in that case all the dimensions must have the same lengths (so that is typically only useful for two-dimensional matrices).

The elements of factors must each be the same length as the corresponding dimension of the input matrix.

The method parameter indicates how the factors are interpreted. The method may be “absolute”, “fraction”, or “percent”. If method is “absolute”, the factors are taken to be the new margins, and the array is iteratively expanded until the margins match the new totals. If method is “fraction” or “percent” methods, the supplied factors are converted to absolute values by multiplying the corresponding row or column sums of the matrix by the corresponding factors.

Note that the factors must yield the same grand total for all dimensions of mtx, which will be the same as sum(mtx) once the function is complete. After the absolute factors have been prepared according to the chosen method, if the sum of the any of the sets of growth factors is not the same, the second and subsequent growth factor s(column) will itself be factored to match the total of the first growth factor and a warning will be issued.

The print method shows computed array margins and convergence statistics.

Function ipf returns a matrix with the same dimensions and dimnames as the input matrix, but with a class of iterative.fit. The resulting object has the following attributes:

Converged: TRUE if max.rmse was achieved
RMSE: The root mean square error after the final iteration
Iteration: How many row and column iterations were executed

The attributes of the iterative.fit object are printed along with the matrix margins (built using addmargins when the class-specific print method is invoked.

Jeremy Raw

T.J. Fratar, 1954. “Vehicular trip distribution by successive approximation.” Traffic Quart. 8 (1954), pp. 53-65

m<-matrix(c(5,50,100,200,
            50,5,100,300,
            50,100,5,100,
            100,200,250,20),
			nrow=4,ncol=4,byrow=TRUE)
dimnames(m)<-list(Rows=c("R1","R2","R3","R4"),Cols=c("C1","C2","C3","C4"))
print(addmargins(m))
f<-c(400,460,400,702)

mf.vector<-ipf(m,f,"absolute")
print(mf.vector)

f.1<-list(rows=c(400,460,400,702))
mf.list.1<-ipf(m,f.1,"absolute")
print(mf.list.1)

f.2<-list(rows=c(400,460,400,702),cols=c(260,400,500,802))
mf.list.2<-ipf(m,f.2,"absolute")
print(mf.list.2)

df.1<-data.frame(rows=c(400,460,400,702),cols=c(260,400,500,802))
mf.df.1<-ipf(m,df.1,"absolute")
print(mf.df.1)

f.pct<-c(102,105,110,95)
mf.pct<-ipf(m,f.pct,"percent")
print(mf.pct)