svystatSR: Estimation of Share Ratios in Subpopulations
In DiegoZardetto/ReGenesees: R Evolved Generalized Software for Sampling Estimates and Errors in Surveys

svystatSR

R Documentation

Estimation of Share Ratios in Subpopulations

Description

Calculates estimates, standard errors and confidence intervals for Ratios between Shares of a numeric variables in subpopulations.

Usage

svystatSR(design, y, classes, by = NULL,
          vartype = c("se", "cv", "cvpct", "var"),
          conf.int = FALSE, conf.lev = 0.95, deff = FALSE,
          na.rm = FALSE)

## S3 method for class 'svystatSR'
coef(object, ...)
## S3 method for class 'svystatSR'
SE(object, ...)
## S3 method for class 'svystatSR'
VAR(object, ...)
## S3 method for class 'svystatSR'
cv(object, ...)
## S3 method for class 'svystatSR'
deff(object, ...)
## S3 method for class 'svystatSR'
confint(object, ...)

Arguments

`design`	Object of class `analytic` (or inheriting from it) containing survey data and sampling design metadata.
`y`	Formula defining the interest variable.
`classes`	Formula defining the population groups among which ratios of `y` shares must be estimated.
`by`	Formula specifying the variables that define the "estimation domains". If `NULL` (the default option) estimates refer to the whole population.
`vartype`	`character` vector specifying the desired variability estimators. It is possible to choose one or more of: standard error (`'se'`, the default), coefficient of variation (`'cv'`), percent coefficient of variation (`'cvpct'`), or variance (`'var'`).
`conf.int`	Compute confidence intervals for the estimates? The default is `FALSE`.
`conf.lev`	Probability specifying the desired confidence level: the default value is `0.95`.
`deff`	Should the design effect be computed? The default is `FALSE` (see ‘Details’).
`na.rm`	Should missing values (if any) be removed from the variables of interest? The default is `FALSE` (see ‘Details’).
`object`	An object of class `svystatSR`.
`...`	Additional arguments to `coef`, ..., `confint` methods (if any).

Details

This function computes weighted estimates for Ratios between Shares of a numeric variable, using suitable weights depending on the class of design: calibrated weights for class cal.analytic and direct weights otherwise. Standard errors are calculated using the Taylor linearization technique.

Ratios of Shares are a special case of Ratios. Therefore, at the price of some additional and heavy data preparation effort, ratios of shares could also be estimated using function svystatR. However, svystatSR makes estimation by far easier, in particular when share ratios have to be estimated for many population groups and/or within many domains.

The mandatory argument classes identifies population groups whose ratios of y shares have to be estimated. Note that ratios of shares will be estimated and returned for all the ordered pairs of population groups defined by classes. Therefore, if classes defines G groups, svystatSR will have to compute estimates and sampling errors for G * (G - 1) share ratios. To prevent combinatorial explosions (e.g. G = 20 would generate 380 share ratios), classes formula can reference just a single design variable, which must be a factor.

The optional argument by specifies the variables that define the "estimation domains", that is the subpopulations for which the estimates are to be calculated. If by=NULL (the default option), the estimates produced by svystatSR refer to the whole population. Estimation domains must be defined by a formula: for example the statement by=~B1:B2 selects as estimation domains the subpopulations determined by crossing the modalities of variables B1 and B2. Notice that a formula like by=~B1+B2 will be automatically translated into the factor-crossing formula by=~B1:B2: if you need to compute estimates for domains B1 and B2 separately, you have to call svystatSR twice. The design variables referenced by by (if any) should be of type factor, otherwise they will be coerced.

The conf.int argument allows to request the confidence intervals for the estimates. By default conf.int=FALSE, that is the confidence intervals are not provided.

Whenever confidence intervals are requested (i.e. conf.int=TRUE), the desired confidence level can be specified by means of the conf.lev argument. The conf.lev value must represent a probability (0<=conf.lev<=1) and its default is chosen to be 0.95.

The optional argument deff allows to request the design effect [Kish 1995] for the estimates. By default deff=FALSE, that is the design effect is not provided. The design effect of an estimator is defined as the ratio between the variance of the estimator under the actual sampling design and the variance that would be obtained for an 'equivalent' estimator under a hypothetical simple random sampling without replacement of the same size. To obtain an estimate of the design effect comparing to simple random sampling “with replacement”, one must use deff="replace".
Being Ratios nonlinear estimators, the design effect is estimated on the linearized version of the estimator (that is: for the estimator of the total of the linearized variable, aka "Woodruff transform").
When dealing with domain estimation, the design effects referring to a given subpopulation are currently computed by taking the ratios between the actual variance estimates and those that would have been obtained if a simple random sampling were carried out within that subpopulation. This is the same as the srssubpop option for Stata's function estat.

Missing values (NA) in interest variables should be avoided. If na.rm=FALSE (the default) they generate NAs in estimates (or even an error, if design is calibrated). If na.rm=TRUE, observations containing NAs are dropped, and estimates get computed on non missing values only. This implicitly assumes that missing values hit interest variables completely at random: should this not be the case, computed estimates would be biased.

Value

An object inheriting from the data.frame class, whose detailed structure depends on input parameters' values.

Author(s)

Diego Zardetto

References

Sarndal, C.E., Swensson, B., Wretman, J. (1992) “Model Assisted Survey Sampling”, Springer Verlag.

Kish, L. (1995). “Methods for design effects”. Journal of Official Statistics, Vol. 11, pp. 55-77.

European Commission, Eurostat, (2013). “Handbook on precision requirements and variance estimation for ESS households surveys: 2013 edition”, Publications Office. doi: 10.2785/13579

Examples

# Load household data:
data(data.examples)

# Create a design object:
des<-e.svydesign(data=example,ids=~towcod+famcod,strata=~SUPERSTRATUM,
        weights=~weight)

# Add convenience variable 'ones' to estimate counts:
des<-des.addvars(des,ones=1)

### Simple examples to illustrate the syntax:
# Population sex ratios:
svystatSR(des, y=~ones, classes=~sex, vartype="cvpct")

# Population sex ratios within provinces:
svystatSR(des, y=~ones, classes=~sex, by=~procod, vartype="cvpct")

# Ratios of population shares for 5 age classes:
# NOTE: This yields 5*(5-1)=20 ratios
svystatSR(des, y=~ones, classes=~age5c, vartype="cvpct")


### One more complicated example:
#######################################################################
# Ratios between shares of income held by people for income quintiles #
#######################################################################
    # First: estimate income quintiles
inc.Q5 <- svystatQ(des, y=~income, probs=seq(0.2, 0.8, 0.2), ties="rounded")
inc.Q5

    # Second: add a convenience factor variable classifying people by income
    # quintiles 
des<-des.addvars(des, quintile = cut(income, breaks = c(0, coef(inc.Q5), Inf),
                                     labels = 1:5, include.lowest=TRUE)
                    )

    # Third: estimate income shares by income quintiles
QS5 <- svystatSR(des, y=~income, classes=~quintile, vartype="cvpct")
QS5

### Therefore, for instance, the *S80/S20 income quintile share ratio* is:
S80.20 <- QS5["quintile5/quintile1",]
S80.20

### NOTE: Procedure above yields *correct point estimates* of income quintile
###       share ratios, while *variance estimation is approximated* since
###       we neglected the sampling variability of the estimated quintiles.

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