ml_fit {mlfit}

Estimate weights for a fitting problem

Description

These functions reweight a reference sample to match constraints given by aggregate controls.

ml_fit() accepts an algorithm as argument and calls the corresponding function. This is useful if the result of multiple algorithms are compared to each other.

Usage

ml_fit(
  ml_problem,
  algorithm = c("entropy_o", "dss", "ipu", "hipf"),
  verbose = FALSE,
  ...,
  tol = 1e-06
)

is_ml_fit(x)

## S3 method for class 'ml_fit'
format(x, ...)

## S3 method for class 'ml_fit'
print(x, ...)

ml_fit_dss(
  ml_problem,
  method = c("raking", "linear", "logit"),
  ginv = gginv(),
  tol = 1e-06,
  verbose = FALSE
)

ml_fit_entropy_o(
  ml_problem,
  verbose = FALSE,
  tol = 1e-06,
  dfsane_args = list()
)

ml_fit_hipf(
  ml_problem,
  diff_tol = 16 * .Machine$double.eps,
  tol = 1e-06,
  maxiter = 2000,
  verbose = FALSE
)

ml_fit_ipu(
  ml_problem,
  diff_tol = 16 * .Machine$double.eps,
  tol = 1e-06,
  maxiter = 2000,
  verbose = FALSE
)

Arguments

ml_problem

A fitting problem created by ml_problem() or returned by flatten_ml_fit_problem().

algorithm

Algorithm to use

verbose

If TRUE, print diagnostic output.

...

Further parameters passed to the algorithm

tol

Tolerance, the algorithm has succeeded when all target values are reached within this tolerance.

x

An object

method

Calibration method, one of "raking" (default), "linear", or "logit"

ginv

Function that computes the Moore-Penrose pseudoinverse.

dfsane_args

Additional arguments (as a named list) passed to the BB::dfsane() function used internally for the optimization.

diff_tol

Tolerance, the algorithm stops when relative difference of control values between iterations drops below this value

maxiter

Maximum number of iterations.

Value

All functions return an object of class ml_fit, which is a named list under the hood. The class matches the function called, e.g., the return value of the ml_fit_ipu function also is of class ml_fit_ipu.

All returned objects contain at least the following components, which can be accessed with $ or [[:

• weights: Resulting weights, compatible to the original reference sample

• tol: The input tolerance

• iterations: The actual number of iterations required to obtain the result

• flat: The flattened fitting problem, see flatten_ml_fit_problem()

• flat_weights: Weights in terms of the flattened fitting problem

• residuals: Absolute residuals

• rel_residuals: Relative residuals

• success: Are the residuals within the tolerance?

is_ml_fit() returns a logical.

References

Deville, J.-C. and Särndal, C.-E. (1992) Calibration estimators in survey sampling. Journal of the American Statistical Association, 87 (418), 376–382.

Deville, J.-C., Särndal, C.-E. and Sautory, O. (1993) Generalized raking procedures in survey sampling. Journal of the American Statistical Association, 88 (423), 1013–1020.

Bar-Gera, H., Konduri, K. C., Sana, B., Ye, X., & Pendyala, R. M. (2009, January). Estimating survey weights with multiple constraints using entropy optimization methods. In 88th Annual Meeting of the Transportation Research Board, Washington, DC.

Müller, K. and Axhausen, K. W. (2011), Hierarchical IPF: Generating a synthetic population for Switzerland, paper presented at the 51st Congress of the European Regional Science Association, University of Barcelona, Barcelona.

Ye, X., K. Konduri, R. M. Pendyala, B. Sana and P. A. Waddell (2009) A methodology to match distributions of both household and person attributes in the generation of synthetic populations, paper presented at the 88th Annual Meeting of the Transportation Research Board, Washington, D.C., January 2009.

See Also

dss(), gginv()

BB::dfsane()

Examples

path <- toy_example("Tiny")
fit <- ml_fit(ml_problem = readRDS(path), algorithm = "entropy_o")
fit
fit$weights
fit$tol
fit$iterations
fit$flat
fit$flat_weights
fit$residuals
fit$rel_residuals
fit$success
ml_fit_dss(ml_problem = readRDS(path))
ml_fit_dss(ml_problem = readRDS(path), ginv = solve)
ml_fit_entropy_o(ml_problem = readRDS(path))
ml_fit_hipf(ml_problem = readRDS(path))
ml_fit_ipu(ml_problem = readRDS(path))