describe: Natural Language Description of Known Totals Templates

In DiegoZardetto/ReGenesees: R Evolved Generalized Software for Sampling Estimates and Errors in Surveys

Natural Language Description of Known Totals Templates

Description

Provides a natural language description of a known totals data frame to be used for a calibration task.

Usage

pop.desc(pop.totals, ...)

## S3 method for class 'pop.totals'
pop.desc(pop.totals, ...)

## S3 method for class 'spc.pop'
pop.desc(pop.totals, verbose = FALSE, ...)

Arguments

pop.totals	An object of class pop.totals, be it a template or the actual known totals data frame for the calibration task.
verbose	Fully describe the control totals of a special purpose calibration task?
...	Parameters for future extensions (currently unused).

Details

Function pop.template generates a template (i.e. empty) data frame of class pop.totals, which is appropriate to store the known totals of a given calibration task. Afterwards, the template data frame must be filled with actual figures.

When the sampling frame of the survey is available and the actual population totals can be calculated from this source, function fill.template (i) automatically computes the totals of the auxiliary variables from the sampling frame, (ii) safely arranges and formats these values according to the template structure. Therefore, function fill.template avoids any need for the user to understand, comply with, or even be aware of, the structure of the template that is being filled.

On the contrary, when the population totals are available to the user as such, that is in the form of already computed aggregated values (e.g. because they come from an external source, like a Population Census), it is up to the user to correctly fill the template, that is to put the right values in the right slots of the prepared template.

Function pop.desc has been designed for users who cannot take advantage of function fill.template, to help them understand the structure of the known totals template, in order to safely fill it with actual figures.

Invoking pop.desc will print on screen a detailed natural language description of the structure of the input pop.totals object. Such description will clarify how known totals are organized inside the template slots.

Value

The main purpose of the function is to print on screen, anyway it returns invisibly the input pop.totals object (as print would do).

Author(s)

Diego Zardetto

See Also

e.calibrate for calibrating weights, pop.template for the definition of the class pop.totals and to build a template data frame for known population totals, fill.template to automatically fill the template when a sampling frame is available.

Examples

## First prepare some design objects to work with:

# Load household data:
data(data.examples)
# Build a design object:
exdes<-e.svydesign(data=example,ids=~towcod+famcod,strata=~SUPERSTRATUM,
       weights=~weight)

# Load sbs data:
data(sbs)
# Build a design object:
sbsdes<-e.svydesign(data=sbs,ids=~id,strata=~strata,weights=~weight,fpc=~fpc)

## Now build some known totals templates that (after having been filled by
## actual figures) could be used to calibrate the design objects above,
## and explore the corresponding natural language description:

  ####################################
  ## Some simple and small examples ##
  ####################################
expop<-pop.template(exdes,calmodel=~1)
expop
pop.desc(expop)

expop<-pop.template(exdes,calmodel=~sex)
expop
pop.desc(expop)

# equivalent to the one above
expop<-pop.template(exdes,calmodel=~sex-1)
expop
pop.desc(expop)

expop<-pop.template(exdes,calmodel=~x1+x2+x3,partition=~procod)
expop
pop.desc(expop)

expop<-pop.template(exdes,calmodel=~sex:marstat-1)
expop
pop.desc(expop)

# equivalent to the one above
expop<-pop.template(exdes,calmodel=~sex*marstat-1)
expop
pop.desc(expop)

# equivalent to the one above
expop<-pop.template(exdes,calmodel=~1,partition=~sex:marstat)
expop
pop.desc(expop)

expop<-pop.template(exdes,calmodel=~x1+age5c:marstat-1,partition=~regcod:sex)
expop
pop.desc(expop)


  ############################################
  ## Some more involved and bigger examples ##
  ############################################
expop<-pop.template(exdes,calmodel=~sex:age10c:regcod + sex:age5c:procod - 1)
expop
pop.desc(expop)

# equivalent to the one above (because procod is nested into regcod and
# age10c is nested into age5c)
expop<-pop.template(exdes,calmodel=~age10c+procod-1,
       partition=~regcod:sex:age5c)
expop
pop.desc(expop)
# NOTE: Most of the entries of the template above will be structural zeros,
#       as can be seen in what follows:
expop.HT<-aux.estimates(exdes, template=expop)
expop.HT
sum(expop.HT==0)


# Switch to sbs data
sbspop<-pop.template(sbsdes,
        calmodel=~(emp.num + ent):(nace.macro + emp.cl) - 1, partition=~region)
 
# Can fill the template using the sampling frame...
sbspop<-fill.template(universe=sbs.frame,template=sbspop)
sbspop

# ...and invoke function pop.desc on the filled known totals data frame:
pop.desc(sbspop)

sbspop <- pop.template(data=sbsdes,
                       calmodel=~((emp.num + ent):(nace2 + emp.cl:nace.macro))-1,
                       partition=~region:public)
sbspop
pop.desc(sbspop)

DiegoZardetto/ReGenesees documentation built on Dec. 16, 2024, 2:03 p.m.