pop.fuse.RdAllows to solve jointly a special purpose calibration task and an ordinary calibration task by fusing their respective control totals.
pop.fuse(spc.pop, pop, design)
| spc.pop | A control totals data frame prepared for a special purpose calibration task. Must be of class |
|---|---|
| pop | A known totals data frame for an ordinary calibration task. Must be of class |
| design | A design object prepared for a special purpose calibration task. |
ReGenesees 2.1 introduced support for ‘special purpose calibration’ tasks, i.e. facilities to calibrate survey weights so as to match complex, non-linear population parameters, instead of ordinary population totals.
Currently, ReGenesees' support for special purpose calibration tasks is limited to Multiple Regression Coefficients (see prep.calBeta and pop.calBeta), which includes calibration on Means as a notable special case. Further support will likely be provided in future extensions.
Function pop.fuse allows you to run a calibration task that simultaneously involves as benchmarks:
Complex population parameters (e.g. multiple regression coefficients).
Ordinary population totals.
To achieve this goal, pop.fuse simply “fuses” the corresponding control totals data frames. The resulting fused control totals data frame is indeed enough to automatically instruct function e.calibrate to run the joint calibration task.
Argument spc.pop must be an object of class spc.pop, namely a control totals data frame prepared for a special purpose calibration task (e.g. via function pop.calBeta for the case of calibration on multiple regression coefficients).
Argument pop must be an object of class pop.totals, namely a known totals data frame for an ordinary calibration task (e.g. generated using functions pop.template and fill.template).
Argument design must be the survey design object that:
(i) was already prepared for the special purpose calibration task at hand, and
(ii) you want to calibrate simultaneously also on the ordinary population totals at hand.
Note that condition (i) requires that object design has actually been used to build object spc.pop (see the ‘Examples’ section). Note, moreover, that condition (ii) requires that you eventually run e.calibrate on object design (see the ‘Examples’ section).
A fused data frame, with class spc.pop, encompassing control totals for both the special purpose calibration task and the ordinary calibration task.
Note that printing this control totals data frame might not be very telling: to better understand its structure you should instead leverage function pop.desc, for which a method dedicated to class spc.pop is available.
e.calibrate to calibrate weights, functions prep.calBeta and pop.calBeta to prepare survey data and control totals for calibration on multiple regression coefficients, functions pop.template and fill.template to generate and fill population totals templates for ordinary calibration tasks, pop.desc to obtain a natural language description of control totals data frames.
# Function pop.fuse allows you to run a calibration task that simultaneously # involves as benchmarks: # (A) complex population parameters (e.g. multiple regression coefficients) # (B) ordinary population totals # You just have to: ## 1) prepare the survey desing and control totals data frame for (A) ## 2) create and fill the known totals data frame for (B) ## 3) fuse the control totals data frames produced in steps 1) and 2)! # Load sbs data: data(sbs) # Create a design object: sbsdes <- e.svydesign(data = sbs, ids = ~id, strata = ~strata, weights = ~weight, fpc = ~fpc) # (A) Suppose you know with satisfactory accuracy from some external source # the regression coefficients of the following model: model <- va.imp2 ~ emp.num + emp.cl # Here, use the sbs sampling frame available in ReGenesees to simulate the # external source and compute the values of the regression coefficients: Beta <- coef(lm(model, data = sbs.frame)) Beta#> (Intercept) emp.num emp.cl(9,19] emp.cl(19,49] emp.cl(49,99] #> 1089.38458 11.08138 326.33374 1150.02177 2429.47373 #> emp.cl(99,Inf] #> 7601.21526## 1) Prepare the survey design and control totals for calibration (A): sbsdes.A <- prep.calBeta(sbsdes, model, Beta) pop.A <- pop.calBeta(sbsdes.A) # (B) Suppose you know the number of enterprises and employees by economic # activity macro sectors ## 2) Create and fill the known totals data frame for calibration (B) pop.B <- pop.template(sbsdes.A, calmodel = ~(ent + emp.num):nace.macro - 1) # Note that, to create the template above, you could have used equally well # the original object sbsdes. pop.B <- fill.template(pop.B, universe = sbs.frame)#> #> # Coherence check between 'universe' and 'template': OK #>## 3) Lastly, fuse the control totals data frames produced in steps 1) and 2) pop.AB <- pop.fuse(pop.A, pop.B, sbsdes.A)#> #> # Checking Known Totals dataframe: OK #># Note that, to create the fused control totals data frame above, you *MUST USE* # the *PREPARED* design object sbsdes.A # Have a look: pop.desc(pop.AB)#> # Data frame of control totals for a *special purpose calibration* task #> - Benchmark parameters: Regression Coefficients #> - Benchmarks known at level: Overall Population #> - Calibration task: Global #> #> ## Regression models #> #> va.imp2 ~ emp.num + emp.cl #> #> ## Benchmark vectors (Beta) #> #> (Intercept) emp.num emp.cl(9,19] emp.cl(19,49] emp.cl(49,99] #> 1089.38458 11.08138 326.33374 1150.02177 2429.47373 #> emp.cl(99,Inf] #> 7601.21526 #> #> ## NOTE: This is a *fused* known totals dataframe (see ?pop.fuse) #> ## Specify verbose = TRUE to learn about its *ordinary calibration* totals! #># ...and recall you can set verbose = TRUE to see the full structure # pop.desc(pop.AB, verbose = TRUE) # Now you are ready to calibrate simultaneously on (A) and (B) sbscal.AB <- e.calibrate(sbsdes.A, pop.AB) # Note again that, to run the calibration on the *fused* control totals, you # *MUST USE* the *PREPARED* design object sbsdes.A # Now, check that all the benchmarks are indeed matched: # (A) Multiple regression cofficients: svystatB(sbscal.AB, model)#> RegCoef.va.imp2 SE #> (Intercept) 1089.38458 5.478504e-14 #> emp.num 11.08138 1.251929e-15 #> emp.cl(9,19] 326.33374 3.070152e-13 #> emp.cl(19,49] 1150.02177 4.822061e-13 #> emp.cl(49,99] 2429.47373 3.317874e-13 #> emp.cl(99,Inf] 7601.21526 1.434845e-12Beta#> (Intercept) emp.num emp.cl(9,19] emp.cl(19,49] emp.cl(49,99] #> 1089.38458 11.08138 326.33374 1150.02177 2429.47373 #> emp.cl(99,Inf] #> 7601.21526#> nace.macro Total.ent Total.emp.num SE.Total.ent SE.Total.emp.num #> Agriculture Agriculture 458 17168 2.222306e-14 6.652474e-12 #> Industry Industry 9295 579580 3.417057e-14 3.083888e-12 #> Commerce Commerce 3060 69525 6.375634e-14 4.646905e-12 #> Services Services 4505 318121 2.509948e-13 2.128873e-11pop.B#> ent:nace.macroAgriculture ent:nace.macroIndustry ent:nace.macroCommerce #> 1 458 9295 3060 #> ent:nace.macroServices emp.num:nace.macroAgriculture #> 1 4505 17168 #> emp.num:nace.macroIndustry emp.num:nace.macroCommerce #> 1 579580 69525 #> emp.num:nace.macroServices #> 1 318121# OK