gvf.input: Prepare Input Data to Fit GVF Models

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

Prepare Input Data to Fit GVF Models

Description

Transforms a set of computed survey statistics into a suitable (data.frame-like) data structure, in order to fit a Generalized Variance Function model.

Usage

gvf.input(design, ..., stats = list(...))

## S3 method for class 'gvf.input'
plot(x, ...)

Arguments

design	The design object (of class analytic or inheriting from it) from which the input survey statics are supposed to have been derived.
...	For function gvf.input, objects containing survey statistics. For plot, further arguments passed to or from other methods.
stats	A list storing survey statistic objects (see ‘Details’).
x	The object of class gvf.input to plot.

Details

Given a set of survey statistic objects (via arguments ‘...’ or stats) and a design object (design) from which those statics are supposed to have been derived, function gvf.input builds a data structure that can be fed to ReGenesees GVF model fitting function fit.gvf.

Argument ‘...’ can be bound to an arbitrary number of objects. These objects must be output of survey statistics functions, i.e. svystatTM, svystatR, svystatS, svystatSR, svystatB, svystatQ, svystatL, svySigma, and svySigma2.
All input objects passed to ‘...’ must derive from estimators of the same kind (as returned by function estimator.kind). For the same reason, objects of mixed kind (see estimator.kind) are not allowed. Since function svystatL can actually handle estimators of different kinds, objects of kind ‘Complex Estimator’ are the only exception to the rule.

Argument stats can be used as an alternative to argument ‘...’: one has only to store the survey statistic objects into a list and bind such list to stats. Note that, if both are passed, argument stats will prevail on ‘...’ (see ‘Examples’).

Should any input object be a survey statistic derived from a design object other than design, the function would raise an error.

The plot method for gvf.input objects produces a matrix of scatterplots with polynomial smoothers.

Value

An object of class gvf.input, inheriting from class data.frame: basically a data frame supplied with appropriate attributes.
Each row of the data frame contains an estimate along with its estimated sampling error, expressed in terms of standard error, coefficient of variation, variance, and - whenever available - design effect.
The data frame has the following structure:

name

The name of the original estimate, factor.

Y

The value of the original estimate, numeric.

SE

The standard error of the original estimate, numeric.

CV

The coefficient of variation of the original estimate, numeric.

VAR

The variance of the original estimate, numeric.

DEFF

The design effect of the original estimate (if available), numeric.

Note that by inspecting the attributes of a gvf.input object, one can always identify which design object and which kind of estimator generated that object (see ‘Examples’).

Author(s)

Diego Zardetto

See Also

estimator.kind to assess what kind of estimates are stored inside a survey statistic object, svystat as a useful alternative to prepare the input for GVF model fitting, GVF.db to manage ReGenesees archive of registered GVF models, fit.gvf to fit GVF models, plot.gvf.fit to get diagnostic plots for fitted GVF models, drop.gvf.points to drop alleged outliers from a fitted GVF model and simultaneously refit it, and predictCV to predict CV values via fitted GVF models.

Examples

# Load sbs data:
data(sbs)

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

# ...and use it to compute some survey statistics:
va<-svystatTM(sbsdes,~va.imp2)
va.reg<-svystatTM(sbsdes,~va.imp2,~region)
va.area<-svystatTM(sbsdes,~va.imp2,~area)

# Now suppose you want to fit a GVF model on the estimates and errors computed
# above: you must prepare your input as follows:
ee<-gvf.input(sbsdes,va,va.reg,va.area)

# Inspect the obtained data structure:
ee
str(ee)   # Note the "design" and "stats.kind" attributes
plot(ee)

# Note that, instead of argument '...', you could have used argument 'stats'
# as follows:
va.list<-list(va,va.reg,va.area)
ee2<-gvf.input(sbsdes,stats=va.list)

# ...obtaining exactly the same result:
identical(ee,ee2)

# Note also that, if both are passed, argument 'stats' prevails on '...':
  # indeed, while:
  gvf.input(sbsdes,va.reg)
  # we would get again:
  gvf.input(sbsdes,va.reg,stats=va.list)

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