WIPF (version 0.1.0-3)

WIPF2: Weighted Iterative Proportional Fitting (WIPF) in two dimensions

Description

Implements WIPF in two dimensions. This function updates an initial 2-dimensional array (a matrix, referred to as the seed) using a matrix of weights to align with a set of two vectors (referred to as the margins), where one of them can be missing. When margin1 and margin2 are compatible given the weights, the updated values ensure that the weighted sum across columns matches margin1 and the weighted sum across rows matches margin2. If the margins are incompatible given the weights, the function WIPF1 is applied to the initial margins to make them compatible. In those cases, margins are updated (are made compatible) in increasing order of sub-indices (i.e., margin2 is adjusted to make it compatible with margin1).

Usage

WIPF2(
  seed,
  weights,
  margin1,
  margin2,
  normalize = TRUE,
  tol = 10^-6,
  maxit = 1000,
  full = FALSE,
  ...
)

Value

When full = FALSE an object similar to seed with the solution reached when the algorithm stops. When full = TRUE a list with the following components:

sol

An object similar to seed with the solution reached at convergence (or when the maximum number of iterations is reached).

iter

Number of iterations when the algorithm stops.

dev.margins

A list with a set of objects similar to the margins with absolute maximum deviations between the values in margins and the corresponding weighted sums of the values in sol.

margin1

A R-length vector of positive values with the actual margin1 object used to reach the solution. This coincides with margin1 even when all the margins are not compatible given the weights.

margin2

A C-length vector of positive values with the actual margin2 object used to reach the solution. This coincides with margin2 when all the margins are compatible given the weights.

inputs

A list containing all the objects with the values used as arguments by the function.

Arguments

seed

A (RxC) matrix of non-negative values with the initial values.

weights

A (RxC) matrix of non-negative values with the weights associated to each entry of the matrix.

margin1

A R-length vector of positive values with the target (weighted) marginal sums across columns to be fitted.

margin2

A C-length vector of positive values with the target (weighted) marginal sums across rows to be fitted.

normalize

TRUE/FALSE argument indicating whether the weights should be normalized (across all dimensions, for either row or column weights to sum 1) before constructing the weighted sums for comparison with the margin values. Default, TRUE. Normalization is essential when adjusting a set of indexes where the margins represent theoretical convex combinations of the inner indexes. This characterizes a typical context where WIPF could be of value.

tol

Stopping criterion. The algorithm stops when the maximum difference between the weighted sum(s) of the values to be fitted and the margin(s) is lower than the value specified by tol. Default, 0.000001.

maxit

Stopping criterion. A positive integer number indicating the maximum number of iterations allowed. Default, 1000. The algorithm will stop if the values to be fitted still has not converged after this many iterations.

full

TRUE/FALSE argument indicating if either only the solution should be shown or a more complete output.

...

Other arguments to be passed to the function. Not currently used.

Author

Jose M. Pavia,

Examples

s <- structure(c(1.1279, 1.1304, 1.0304, 0.8554, 1.5606, 1.4171, 1.2862,
                 1.2472, 1.0746, 1.0796, 0.9806, 0.928, 1.1607, 1.2436, 1.2191,
                 1.0786, 1.0194, 1.1716, 0.9937, 0.8611, 1.0172, 1.2511, 1.1606,
                 1.1959), .Dim = c(4L, 6L))
w <- structure(c(72161.97, 93725.94, 84408.83, 172774.13, 52875.08,
                 31936.92, 14191.44, 12595.46, 291698.94, 231408.32,
                 221763.43, 235217.74, 42028.56, 64458.09, 93443.13,
                 60348.74, 222482.04, 103695.94, 57066.82, 48657.48,
                 9572.75, 75745.02, 83912.38, 94019.92), .Dim = c(4L, 6L))
m1 <- c(1.110737, 1.029947, 0.934799, 0.906475)
m2 <- c(0.810992, 1.375921, 1.071519, 1.045006, 0.949938, 0.915762)
example <- WIPF2(seed = s, weights = w, margin1 = m1, margin2 = m2, full = TRUE)