Construct a "template" data frame to store known population totals for a calibration problem.

pop.template(data, calmodel, partition = FALSE)

Arguments

data

Data frame of survey data.

calmodel

Formula defining the linear structure of the calibration model.

partition

Formula specifying the variables that define the "calibration domains" for the model. FALSE (the default) implies no calibration domains.

Details

This function creates an object of class pop.totals. A pop.totals object is made up by the union of a data frame whose structure conforms to the standard required by kottcalibrate for the known totals and the metadata describing the calibration problem.

The mandatory argument data must identify the survey data frame on which the calibration problem is defined (or, as an alternative, a kott.design object built upon that data frame).

The mandatory argument calmodel symbolically defines the calibration model you want to use: it identifies the auxiliary variables and the constraints for the calibration problem. The deskott variables referenced by calmodel must be numeric or factor and must not contain any missing value (NA).

The optional argument partition specifies the variables that define the calibration domains for the model. The default value (FALSE) means either that there are not calibration domains or that you want to solve the problem globally (even though it could be factorised). If a formula is passed through the partition argument the program checks that calmodel actually describes a "reduced model", that is it does not reference any of the partition variables; if this is not the case, the program stops and prints an error message. The deskott variables referenced by partition (if any) must be factor and must not contain any missing value (NA).

Value

An object of class pop.totals. The data frame it contains is a "template" in the sense that all the known totals it must be able to store are missing (NA). However, this data frame has a structure that complies with the standard required by kottcalibrate (provided the latter is invoked with the same calmodel and partition values used to create the template).
The operation of filling the template's NAs with the actual values of the corresponding population totals is, obviously, to be done by the user.

The pop.totals class is a specialisation of the data.frame class; this means that an object built by pop.template inherits from the data.frame class and you can use on it every method defined on that class.

See also

kottcalibrate for calibrating replicate weights, population.check to check that the known totals data frame satisfies the standard required by kottcalibrate.

Examples

# Creation of population totals template data frames for different # calibration problems (if the calibration models can be factorised # both a global and an iterative solution are given): data(data.examples) # 1) Calibration on the total number of units in the population: pop.template(data=example,calmodel=~1)
#> (Intercept) #> 1 NA
# 2) Calibration on the total number of units in the population # and on the marginal distribution of marstat (notice that the # total for the first level "married" of the marstat factor # variable is missing because it can be deduced from # the remaining totals): pop.template(data=example,calmodel=~marstat)
#> (Intercept) marstatunmarried marstatwidowed #> 1 NA NA NA
# 3) Calibration on the marginal distribution of marstat (you # must explicitly remove the intercept term in the # calibration model adding -1 to the calmodel formula): pop.template(data=example,calmodel=~marstat-1)
#> marstatmarried marstatunmarried marstatwidowed #> 1 NA NA NA
# 4) Calibration (global solution) on the joint distribution of sex # and marstat: pop.template(data=example,calmodel=~sex:marstat-1)
#> sexf:marstatmarried sexm:marstatmarried sexf:marstatunmarried #> 1 NA NA NA #> sexm:marstatunmarried sexf:marstatwidowed sexm:marstatwidowed #> 1 NA NA NA
# 4.1) Calibration (iterative solution) on the joint distribution # of sex and marstat: # 4.1.1) Using sex to define calibration domains: pop.template(data=example,calmodel=~marstat-1,partition=~sex)
#> sex marstatmarried marstatunmarried marstatwidowed #> 1 f NA NA NA #> 2 m NA NA NA
# 4.1.2) Using marstat to define calibration domains: pop.template(data=example,calmodel=~sex-1,partition=~marstat)
#> marstat sexf sexm #> 1 married NA NA #> 2 unmarried NA NA #> 3 widowed NA NA
# 5) Calibration (global solution) on the total for the quantitative # variable x1 and on the marginal distribution of the qualitative # variable age5c, in the subpopulations defined by crossing sex # and marstat: pop.template(data=example,calmodel=~(age5c+x1-1):sex:marstat)
#> age5c1:sexf:marstatmarried age5c2:sexf:marstatmarried #> 1 NA NA #> age5c3:sexf:marstatmarried age5c4:sexf:marstatmarried #> 1 NA NA #> age5c5:sexf:marstatmarried age5c1:sexm:marstatmarried #> 1 NA NA #> age5c2:sexm:marstatmarried age5c3:sexm:marstatmarried #> 1 NA NA #> age5c4:sexm:marstatmarried age5c5:sexm:marstatmarried #> 1 NA NA #> age5c1:sexf:marstatunmarried age5c2:sexf:marstatunmarried #> 1 NA NA #> age5c3:sexf:marstatunmarried age5c4:sexf:marstatunmarried #> 1 NA NA #> age5c5:sexf:marstatunmarried age5c1:sexm:marstatunmarried #> 1 NA NA #> age5c2:sexm:marstatunmarried age5c3:sexm:marstatunmarried #> 1 NA NA #> age5c4:sexm:marstatunmarried age5c5:sexm:marstatunmarried #> 1 NA NA #> age5c1:sexf:marstatwidowed age5c2:sexf:marstatwidowed #> 1 NA NA #> age5c3:sexf:marstatwidowed age5c4:sexf:marstatwidowed #> 1 NA NA #> age5c5:sexf:marstatwidowed age5c1:sexm:marstatwidowed #> 1 NA NA #> age5c2:sexm:marstatwidowed age5c3:sexm:marstatwidowed #> 1 NA NA #> age5c4:sexm:marstatwidowed age5c5:sexm:marstatwidowed x1:sexf:marstatmarried #> 1 NA NA NA #> x1:sexm:marstatmarried x1:sexf:marstatunmarried x1:sexm:marstatunmarried #> 1 NA NA NA #> x1:sexf:marstatwidowed x1:sexm:marstatwidowed #> 1 NA NA
# 5.1) The same problem with iterative solutions: # 5.1.1) Using sex to define calibration domains: pop.template(data=example,calmodel=~(age5c+x1-1):marstat,partition=~sex)
#> sex age5c1:marstatmarried age5c2:marstatmarried age5c3:marstatmarried #> 1 f NA NA NA #> 2 m NA NA NA #> age5c4:marstatmarried age5c5:marstatmarried age5c1:marstatunmarried #> 1 NA NA NA #> 2 NA NA NA #> age5c2:marstatunmarried age5c3:marstatunmarried age5c4:marstatunmarried #> 1 NA NA NA #> 2 NA NA NA #> age5c5:marstatunmarried age5c1:marstatwidowed age5c2:marstatwidowed #> 1 NA NA NA #> 2 NA NA NA #> age5c3:marstatwidowed age5c4:marstatwidowed age5c5:marstatwidowed #> 1 NA NA NA #> 2 NA NA NA #> x1:marstatmarried x1:marstatunmarried x1:marstatwidowed #> 1 NA NA NA #> 2 NA NA NA
# 5.1.2) Using marstat to define calibration domains: pop.template(data=example,calmodel=~(age5c+x1-1):sex,partition=~marstat)
#> marstat age5c1:sexf age5c2:sexf age5c3:sexf age5c4:sexf age5c5:sexf #> 1 married NA NA NA NA NA #> 2 unmarried NA NA NA NA NA #> 3 widowed NA NA NA NA NA #> age5c1:sexm age5c2:sexm age5c3:sexm age5c4:sexm age5c5:sexm x1:sexf x1:sexm #> 1 NA NA NA NA NA NA NA #> 2 NA NA NA NA NA NA NA #> 3 NA NA NA NA NA NA NA
# 5.1.3) Using sex and marstat to define calibration domains: pop.template(data=example,calmodel=~age5c+x1-1,partition=~sex:marstat)
#> sex marstat age5c1 age5c2 age5c3 age5c4 age5c5 x1 #> 1 f married NA NA NA NA NA NA #> 2 f unmarried NA NA NA NA NA NA #> 3 f widowed NA NA NA NA NA NA #> 4 m married NA NA NA NA NA NA #> 5 m unmarried NA NA NA NA NA NA #> 6 m widowed NA NA NA NA NA NA