Estimate weights for a fitting problem

Source: R/ml_fit.R, R/ml_fit_dss.R, R/ml_fit_entropy_o.R, and 3 more

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.

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

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

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

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

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

is.ml_fit(x)

Arguments

algorithm

Algorithm to use
fitting_problem

A fitting problem created by fitting_problem() or returned by flatten_ml_fit_problem().
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.
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.
x

An object

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?

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.

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(algorithm = "entropy_o", fitting_problem = readRDS(path))
fit

#> An object of class ml_fit
#>   Algorithm: entropy_o
#>   Success: TRUE
#>   Residuals (absolute): min = -1.548604e-08, max = 4.156846e-09
#>   Flat problem:
#>   An object of class flat_ml_fit_problem
#>     Dimensions: 5 groups, 8 target values
#>     Model matrix type: combined
#>     Original fitting problem:
#>     An object of class fitting_problem
#>       Reference sample: 23 observations
#>       Control totals: 1 at individual, and 1 at group level
#>       Results for algorithms: entropy_o(1,0), entropy_o(0,1), entropy_o(1,1), entropy, ml_ipf, ipu
fit$weights

#>  [1]  8.937470  8.937470  8.937470 23.448579 23.448579  2.613950  2.613950
#>  [8]  2.613950 25.899223 25.899223 25.899223 14.347802 14.347802 14.347802
#> [15] 11.009562 11.009562  2.733852  2.733852  2.733852  2.733852  2.733852
#> [22] 11.009562 11.009562
fit$tol

#> [1] 1e-06
fit$iterations

#> [1] 189
fit$flat

#> An object of class flat_ml_fit_problem
#>   Dimensions: 5 groups, 8 target values
#>   Model matrix type: combined
#>   Original fitting problem:
#>   An object of class fitting_problem
#>     Reference sample: 23 observations
#>     Control totals: 1 at individual, and 1 at group level
#>     Results for algorithms: entropy_o(1,0), entropy_o(0,1), entropy_o(1,1), entropy, ml_ipf, ipu
fit$flat_weights

#>         1         2         3         4         5         6         7         8 
#>  8.937470 23.448579  2.613950 25.899223 14.347802 11.009562  2.733852 11.009562 
fit$residuals

#> (Intercept)_g (Intercept)_i       CAR_g_1    WKSTAT_i_2    WKSTAT_i_3 
#>  2.684047e-09  4.156846e-09 -1.548604e-08  3.542056e-10 -3.012659e-09 
fit$rel_residuals

#> (Intercept)_g (Intercept)_i       CAR_g_1    WKSTAT_i_2    WKSTAT_i_3 
#>  2.684053e-11  1.598788e-11 -2.382468e-10  5.449419e-12 -2.896783e-11 
fit$success

#> [1] TRUE
ml_fit_dss(fitting_problem = readRDS(path))

#> An object of class ml_fit
#>   Algorithm: dss
#>   Success: TRUE
#>   Residuals (absolute): min = 2.338017e-08, max = 1.613564e-07
#>   Flat problem:
#>   An object of class flat_ml_fit_problem
#>     Dimensions: 5 groups, 8 target values
#>     Model matrix type: combined
#>     Original fitting problem:
#>     An object of class fitting_problem
#>       Reference sample: 23 observations
#>       Control totals: 1 at individual, and 1 at group level
#>       Results for algorithms: entropy_o(1,0), entropy_o(0,1), entropy_o(1,1), entropy, ml_ipf, ipu
ml_fit_dss(fitting_problem = readRDS(path), ginv = solve)

#> An object of class ml_fit
#>   Algorithm: dss
#>   Success: TRUE
#>   Residuals (absolute): min = 2.338015e-08, max = 1.613563e-07
#>   Flat problem:
#>   An object of class flat_ml_fit_problem
#>     Dimensions: 5 groups, 8 target values
#>     Model matrix type: combined
#>     Original fitting problem:
#>     An object of class fitting_problem
#>       Reference sample: 23 observations
#>       Control totals: 1 at individual, and 1 at group level
#>       Results for algorithms: entropy_o(1,0), entropy_o(0,1), entropy_o(1,1), entropy, ml_ipf, ipu
ml_fit_entropy_o(fitting_problem = readRDS(path))

#> An object of class ml_fit
#>   Algorithm: entropy_o
#>   Success: TRUE
#>   Residuals (absolute): min = -1.548604e-08, max = 4.156846e-09
#>   Flat problem:
#>   An object of class flat_ml_fit_problem
#>     Dimensions: 5 groups, 8 target values
#>     Model matrix type: combined
#>     Original fitting problem:
#>     An object of class fitting_problem
#>       Reference sample: 23 observations
#>       Control totals: 1 at individual, and 1 at group level
#>       Results for algorithms: entropy_o(1,0), entropy_o(0,1), entropy_o(1,1), entropy, ml_ipf, ipu
ml_fit_hipf(fitting_problem = readRDS(path))

#> An object of class ml_fit
#>   Algorithm: hipf
#>   Success: TRUE
#>   Residuals (absolute): min = -0.000103996, max = 0
#>   Flat problem:
#>   An object of class flat_ml_fit_problem
#>     Dimensions: 5 groups, 8 target values
#>     Model matrix type: combined
#>     Original fitting problem:
#>     An object of class fitting_problem
#>       Reference sample: 23 observations
#>       Control totals: 1 at individual, and 1 at group level
#>       Results for algorithms: entropy_o(1,0), entropy_o(0,1), entropy_o(1,1), entropy, ml_ipf, ipu
ml_fit_ipu(fitting_problem = readRDS(path))

#> An object of class ml_fit
#>   Algorithm: ipu
#>   Success: TRUE
#>   Residuals (absolute): min = -6.41906e-05, max = 0
#>   Flat problem:
#>   An object of class flat_ml_fit_problem
#>     Dimensions: 5 groups, 8 target values
#>     Model matrix type: separate
#>     Original fitting problem:
#>     An object of class fitting_problem
#>       Reference sample: 23 observations
#>       Control totals: 1 at individual, and 1 at group level
#>       Results for algorithms: entropy_o(1,0), entropy_o(0,1), entropy_o(1,1), entropy, ml_ipf, ipu