svyby                 package:survey                 R Documentation

_S_u_r_v_e_y _s_t_a_t_i_s_t_i_c_s _o_n _s_u_b_s_e_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     Compute survey statistics on subsets of a survey defined by
     factors.

_U_s_a_g_e:

     svyby(formula, by ,design,...)
     ## Default S3 method:
     svyby(formula, by, design, FUN, ..., deff=FALSE,keep.var = TRUE,
     keep.names = TRUE,verbose=FALSE, vartype=c("se","ci","ci","cv","cvpct","var"),
      drop.empty.groups=TRUE, covmat=FALSE, return.replicates=FALSE, multicore=getOption("survey.multicore"))
     ## S3 method for class 'svyby':
     SE(object,...)
     ## S3 method for class 'svyby':
     deff(object,...)
     ## S3 method for class 'svyby':
     coef(object,...)
     unwtd.count(x, design, ...)

_A_r_g_u_m_e_n_t_s:

formula,x: A formula specifying the variables to pass to 'FUN' (or a
          matrix, data frame, or vector)

      by: A formula specifying factors that define subsets, or a list
          of factors.

  design: A 'svydesign' or 'svrepdesign' object

     FUN: A function taking a formula and survey design object as its
          first two arguments.

     ...: Other arguments to 'FUN'

    deff: Request a design effect from 'FUN'

keep.var: If 'FUN' returns a 'svystat' object, extract standard errors
          from it

keep.names: Define row names based on the subsets

 verbose: If 'TRUE', print a label for each subset as it is processed.

 vartype: Report variability as one or more of standard error,
          confidence interval, coefficient of variation,  percent
          coefficient of variation, or variance

drop.empty.groups: If 'FALSE', report 'NA' for empty groups, if 'TRUE'
          drop them from the output

  covmat: If 'TRUE', compute covariances between estimates for
          different subsets (currently only for replicate-weight
          designs). Allows 'svycontrast' to be used on output.

return.replicates: Only for replicate-weight designs. If 'TRUE', return
          all the replicates as an attribute of the result

multicore: Use 'multicore' package to distribute subsets over multiple
          processors?

  object: An object of class '"svyby"'

_D_e_t_a_i_l_s:

     The variance type "ci" asks for confidence intervals, which are
     produced by 'confint'. In some cases additional options to 'FUN'
     will be needed to produce confidence intervals, for example,
     'svyquantile' needs 'ci=TRUE'

     'unwtd.count' is designed to be passed to 'svyby' to report the
     number of non-missing observations in each subset. Observations
     with exactly zero weight will also be counted as missing, since
     that's how subsets are implemented for some designs.

     Parallel processing with 'multicore=TRUE' is useful only for
     fairly large problems and on computers with sufficient memory. The
     'multicore' package is incompatible with some GUIs, although the
     Mac Aqua GUI appears to be safe.

_V_a_l_u_e:

     An object of class '"svyby"': a data frame showing the factors and
     the results of 'FUN'.

     For 'unwtd.count', the unweighted number of non-missing
     observations in the data matrix specified by 'x' for the design.

_N_o_t_e:

     Asking for a design effect ('deff=TRUE') from a function that does
     not produce one will cause an error or incorrect formatting of the
     output. The same will occur with 'keep.var=TRUE' if the function
     does not compute a standard error.

_S_e_e _A_l_s_o:

     'svytable' and 'ftable.svystat' for contingency tables,
     'ftable.svyby' for pretty-printing of 'svyby'

_E_x_a_m_p_l_e_s:

     data(api)
     dclus1<-svydesign(id=~dnum, weights=~pw, data=apiclus1, fpc=~fpc)

     svyby(~api99, ~stype, dclus1, svymean)
     svyby(~api99, ~stype, dclus1, svyquantile, quantiles=0.5,ci=TRUE,vartype="ci")
     ## without ci=TRUE svyquantile does not compute standard errors
     svyby(~api99, ~stype, dclus1, svyquantile, quantiles=0.5, keep.var=FALSE)
     svyby(~api99, list(school.type=apiclus1$stype), dclus1, svymean)
     svyby(~api99+api00, ~stype, dclus1, svymean, deff=TRUE,vartype="ci")
     svyby(~api99+api00, ~stype+sch.wide, dclus1, svymean, keep.var=FALSE)
     ## report raw number of observations
     svyby(~api99+api00, ~stype+sch.wide, dclus1, unwtd.count, keep.var=FALSE)

     rclus1<-as.svrepdesign(dclus1)

     svyby(~api99, ~stype, rclus1, svymean)
     svyby(~api99, ~stype, rclus1, svyquantile, quantiles=0.5)
     svyby(~api99, list(school.type=apiclus1$stype), rclus1, svymean, vartype="cv")
     svyby(~enroll,~stype, rclus1,svytotal, deff=TRUE)
     svyby(~api99+api00, ~stype+sch.wide, rclus1, svymean, keep.var=FALSE)
     ##report raw number of observations
     svyby(~api99+api00, ~stype+sch.wide, rclus1, unwtd.count, keep.var=FALSE)

     ## comparing subgroups using covmat=TRUE
     mns<-svyby(~api99, ~stype, rclus1, svymean,covmat=TRUE)
     vcov(mns)
     svycontrast(mns, c(E = 1, M = -1))

     str(svyby(~api99, ~stype, rclus1, svymean,return.replicates=TRUE))

     ## extractor functions
     (a<-svyby(~enroll, ~stype, rclus1, svytotal, deff=TRUE, verbose=TRUE, vartype=c("se","cv","cvpct","var")))
     deff(a)
     SE(a)
     cv(a)
     coef(a)

     ## ratio estimates
     svyby(~api.stu, by=~stype, denominator=~enroll, design=dclus1, svyratio)

     ## empty groups
     svyby(~api00,~comp.imp+sch.wide,design=dclus1,svymean)
     svyby(~api00,~comp.imp+sch.wide,design=dclus1,svymean,drop.empty.groups=FALSE)

