fit.gvf: Fit GVF Models
In DiegoZardetto/ReGenesees: R Evolved Generalized Software for Sampling Estimates and Errors in Surveys

fit.gvf

R Documentation

Fit GVF Models

Description

This function fits one or more GVF models to a set of survey statistics.

Usage

fit.gvf(gvf.input, model = NULL, weights = NULL)

## S3 method for class 'gvf.fit'
print(x, digits = max(3L, getOption("digits") - 3L), ...)
## S3 method for class 'gvf.fits'
print(x, digits = max(3L, getOption("digits") - 3L), ...)
## S3 method for class 'gvf.fit.gr'
print(x, digits = max(3L, getOption("digits") - 3L), ...)
## S3 method for class 'gvf.fits.gr'
print(x, digits = max(3L, getOption("digits") - 3L), ...)

## S3 method for class 'gvf.fits'
x[...]
## S3 method for class 'gvf.fits'
x[[...]]

## S3 method for class 'gvf.fit'
summary(object, correlation = FALSE, symbolic.cor = FALSE, ...)
## S3 method for class 'gvf.fits'
summary(object, correlation = FALSE, symbolic.cor = FALSE, ...)
## S3 method for class 'gvf.fit.gr'
summary(object, correlation = FALSE, symbolic.cor = FALSE, ...)
## S3 method for class 'gvf.fits.gr'
summary(object, correlation = FALSE, symbolic.cor = FALSE, ...)

Arguments

`gvf.input`	An object of class `gvf.input` (or `gvf.input.gr`), containing the data to fit.
`model`	The GVF model(s) to be fitted (see ‘Details’). `NULL` (the default) requires to fit all the registered GVF models currently available in `GVF.db`.
`weights`	Formula specifying the weights to be used for fitting (via weighted least squares), if any. `NULL` (the default) means that ordinary least squares will be used. See also ‘Details’.
`x`	An object of class `gvf.fits`, storing fitted GVF models.
`digits`	Minimal number of significant digits, see `print.default`.
`object`	Any output of `fit.gvf`, storing one (more than one) fitted GVF model(s).
`correlation`	Should the correlation matrix of the estimated parameters be returned and printed? Logical, with default `FALSE`.
`symbolic.cor`	Should the correlations be printed in symbolic form (see `symnum`) rather than as numbers. Logical, with default `FALSE`.
`...`	Further arguments passed to or from other methods.

Details

Function fit.gvf fits one or more GVF models to a set of survey statistics. The rationale for fitting multiple models to the same data is primarily for comparison purposes: the user is expected to eventually choose his preferred model, in order to obtain sampling errors predictions.

Argument gvf.input specifies the set of (pre computed) estimates and errors to which GVF models are to be fitted, as prepared by functions gvf.input and/or svystat.

One or more GVF models can be fitted simultaneously to the same data, depending on the way argument model is passed.

Argument model can be either:

(1) NULL (the default) meaning all the registered models currently available in GVF.db;

(2) any sub-vector of GVF.db$Model.id, i.e. an integer vector identifying an arbitrary selection of registered models;

(3) an arbitrary (single) formula, i.e. any custom, user-defined GVF model.

When model is passed via options (1) or (2), function fit.gvf can take advantage of any additional information available inside GVF.db, e.g. to warn the user in case a GVF model is not deemed to be appropriate for the kind of estimates contained into gvf.input (see ‘Examples’).

Argument weights enables fitting the specified GVF model(s) via weighted least squares. By default weights = NULL and ordinary least squares are used. The weights must be passed by a formula referencing variables belonging to gvf.input. For instance, to weight observations according to reciprocals of squared CVs, one can use weights = ~I(CV^-2).

Value

An object containing one or more fitted GVF models, depending on the way argument model was passed.

Let's first focus on input objects of class gvf.input.
If model specifies a single GVF model, the output object will be of class gvf.fit and inherit from class lm.
If model specifies many GVF models, the output object will be of class gvf.fits and inherit from class list. Hence, it will be possible to subset gvf.fits objects via methods [ and [[. Note, moreover, that each component (in the sense of class list) of a gvf.fits object will be of class gvf.fit.

When, instead, the input object has class gvf.input.gr, i.e. it stores “grouped” estimates and errors, model fitting is performed separately for different groups. Therefore, applying fit.gvf always results in many fitted GVF models.
If model specifies a single GVF model, the output object will be of class gvf.fit.gr and inherit from class list. Each slot of the list will contain the same GVF model fitted to a specific group.
If model specifies many GVF models, the output object will be of class gvf.fits.gr and again inherit from class list. Each slot of the list will now contain a second list storing different GVF models fitted to a specific group.

Author(s)

Diego Zardetto

Examples

# Load example data:
data(AF.gvf)

# Now we have at our disposal a set of estimates and errors
# of Absolute Frequencies:
str(ee.AF)

# And the available registered GVF models are listed below:
GVF.db


###########################################
# How to specify the GVF model(s) to fit? #
###########################################

## (A) How to specify a *single* GVF model ##

#### (A.1) Select one registered model using its 'Model.id' as reported in
####       the GVF.db archive
# Let's fit, for instance, the GVF model with Model.id = 1:
m <- fit.gvf(ee.AF, model = 1)

# Inspect the result:
class(m) 
m
summary(m)

# Now let's fit GVF model with Model.id = 4
m <- fit.gvf(ee.AF, model = 4)
# Beware of the NOTE reported when printing or summarizing this fitted model:
m
summary(m)


#### (A.2) Specify the GVF model to fit by providing its formula directly, e.g.
####       because it is not available in GVF.db (yet):
m <- fit.gvf(ee.AF, model = CV ~ I(1/Y^2) + I(1/Y) + Y + I(Y^2))
m
summary(m)


## (B) How to specify a *many* GVF models simultaneously ##

#### (B.1) Use a subset of column 'Model.id' of GVF.db
# Let's, for instance, fit all the available GVF models which are appropriate
# to Frequencies, as reported in column 'Estimator.kind' of GVF.db
mm <- fit.gvf(ee.AF, model = 1:3)

# Inspect the result:
class(mm)
length(mm)
mm
summary(mm)

# Note that you can subset the output fitted models as a list:
mm.31 <- mm[c(3,1)]
class(mm.31)
mm.31

# and:
mm.2 <- mm[[2]]
class(mm.2)
mm.2


#### (B.2) Not specifying any GVF model, or specifying model = NULL, causes
####       *all* the available models in GVF.db to be fitted simultaneously:
mm <- fit.gvf(ee.AF)

# Inspect the result:
class(mm)
length(mm)
mm
summary(mm)


#########################################################
# How to fit GVF model(s) via *weighted* least squares? #
#########################################################
# Weights can be specified by a formula. Of course, the 'weights' formula must
# reference variables belonging to gvf.input.

# Let's use the built-in GVF model with Model.id = 1 and weight observations
# according to reciprocals of squared CVs:
mw <- fit.gvf(ee.AF, model = 1, weights = ~I(CV^-2))
mw

# Compute ordinary least squares fit:
m <- fit.gvf(ee.AF, model = 1)
m

# Compare the results:
summary(mw)
summary(m)


#########################################################################
# Fitting GVF model(s) to "grouped" estimates and errors: a quick ride. #
#########################################################################
# Recall we have at our disposal the following survey design object 
# defined on household data:
exdes

# Now use function svystat to prepare "grouped" estimates and errors
# of counts to be fitted separately (here groups are regions):
ee.g <- svystat(exdes, y=~ind, by=~age5c:marstat:sex, combo=3, group=~regcod)
class(ee.g)
ee.g

## Fit a *single* registered GVF model separately inside groups ##
m.g <- fit.gvf(ee.g, model = 1)

# Inspect the result:
class(m.g)
length(m.g)
m.g
summary(m.g)

# Can subset the result as a list, e.g. to get the fitted model of region '7':
m.g7 <- m.g[["7"]]
class(m.g7)
summary(m.g7)


## Fit *many* registered GVF models separately inside groups ##
mm.g <- fit.gvf(ee.g, model = 1:3)

# Inspect the result:
class(mm.g)
length(mm.g)
mm.g
summary(mm.g)

# Still can subset the result as a list, but now each component is a list
# itself. To get the fitted models of region '7', simply:
mm.g7 <- mm.g[["7"]]
class(mm.g7)
summary(mm.g7)

# And to isolate GVF fitted model number 2 for region '7', simply:
mm.g7.2 <- mm.g7[[2]]
class(mm.g7.2)
summary(mm.g7.2)

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