.-
help for ^svyprop^
.-

Estimation of proportions (one-way tabulations) for sample-survey data
----------------------------------------------------------------------

	^svyprop^ varlist [weight] [^if^ exp] [^in^ range] [^,^
			^str^ata^(^varname^)^ ^psu(^varname^)^ ^fpc(^varname^)^
			^by(^varlist^)^ ^sub^pop^(^expression^)^ ^nolab^el
			^for^mat^(^%fmt^)^ ]


^pweight^s and ^iweight^s are allowed; see help ^weights^.

Warning:  Use of ^if^ or ^in^ restrictions will not produce correct variance
estimates for subpopulations in many cases.  To compute proportions for
subpopulations, use the ^by()^ or ^subpop()^ options.


Description
-----------

This command produces estimates of finite-population proportions for complex
survey data with any or all of the following: probability sampling weights,
stratification, and clustering.  Estimates for the standard errors of the
proportions are also computed.

The population proportions estimated are proportions of the categories formed
by the unique values of the varlist.  For example, if the varlist is ^sex race^,
with ^sex^ having 2 values and ^race^ having 3, then proportions will be estimated
for the 6 ^sex^ by ^race^ groups and displayed in a single one-way tabulation.

The ^svymean^ command can also be used to estimate proportions; however, it
requires as input 0/1 variables for each category to be estimated.  ^svymean^
must be used if you wish to obtain covariance estimates or to test proportions;
see help @svymean@.

^svyprop^ is a convenience command that does not require 0/1 variables (nor 
does it create them internally; thus, it will work when there are hundreds of
categories).

To estimate proportions within a single subpopulation, use the ^subpop()^ option.
To estimate proportions within multiple subpopulations, either use the ^subpop()^
option repeatedly or else use ^svymean^ with the ^by()^ option.

To display numbers of PSUs per stratum and detect strata that cause the error
message "stratum with only one PSU detected", see help @svydes@.


Options
-------

^strata(^varname^)^ specifies the name of the variable (numeric or string) that
    contains stratum identifiers.  ^strata()^ can also be specified with the
    ^varset^ command; see examples below and help @varset@.

^psu(^varname^)^ specifies the name of the variable (numeric or string) that
    contains identifiers for the primary sampling unit (i.e., the cluster).
    ^psu()^ can also be specified with the ^varset^ command; see examples below
    and help @varset@.

^fpc(^varname^)^ requests a finite population correction for the variance
    estimates.  If the variable specified has values less than or equal to 1,
    it is interpreted as a stratum sampling rate f_h = n_h/N_h, where n_h =
    number of PSUs sampled from stratum h and N_h = total number of PSUs in
    the population belonging to stratum h.  If the variable specified has
    values greater than or equal to n_h, it is interpreted as containing N_h.
    ^fpc()^ can also be specified with the ^varset^ command; see examples
    below and help @varset@.

^by(^varlist^)^ specifies that estimates be computed for the subpopulations
    defined by different values of the variable(s) in the specified varlist.

^subpop(^expression^)^ specifies that estimates be computed for the single
    subpopulation defined by the observations for which the specified
    expression is true.  Note that observations with missing values for the
    variable(s) in this expression may have to be omitted explicitly using an
    ^if^ statement.  See examples below.

^nolabel^ requests that numeric values rather than value labels be used to
    label output.  By default, value labels are used.

^format(^%fmt^)^ specifies the display format for the proportion estimates and
    their standard errors.  The default is ^%9.6f^.


Examples
--------

Specifying ^strata()^, ^psu()^, ^fpc()^, and ^pweight^ variables
--------------------------------------------------------

The ^varset^ command can be used to set the ^strata()^, ^psu()^, ^fpc()^, and ^pweight^
variables:

 . ^varset strata strn^
 . ^varset psu clustid^
 . ^varset fpc pop^
 . ^varset pweight wgt^

Once these are set, ^strata()^, ^psu()^, and weights ^[pweight=^...^]^ do not have to
be specified when issuing a ^svy^ command:

 . ^svyprop sex race^

Alternatively, without using ^varset^, we could have typed

 . ^svyprop sex race [pweight=wgt], strata(strn) psu(clustid) fpc(pop)^

Note that no matter which of these methods are used initially to set ^strata()^,
^psu()^, ^fpc()^, and ^pweight^, the settings are remembered and do not have to be
specified in subsequent use of any of the ^svy^ commands.  For more information,
see help @varset@.


Command use
-----------

Assuming that any or all of ^strata()^, ^psu()^, ^fpc()^, and ^pweight^ have been
specified:

 . ^svyprop sex race^
 . ^svyprop agecat, nolabel^
 . ^svyprop sex race agecat region^

Proportions within a subpopulation can be estimated using the ^by()^ or
^subpop()^ options:

 . ^svyprop agecat, by(sex)^
 . ^svyprop agecat race, by(sex)^
 . ^svyprop heartatk, by(sex agecat race)^

 . ^svyprop agecat, subpop(race==1)^
 . ^svyprop sex race agecat, subpop(region==1)^
 . ^svyprop agecar, by(sex) subpop(race==2)^
 . ^svyprop sex race, subpop(age < 40)^

When the subpop() option is used, observations with missing values for the 
subpopulation variable(s) must be explicitly omitted using an ^if^ statement:

 . ^svyprop sex race if age~=., subpop(age < 40)^
 . ^svyprop sex race if age~=. & region~=., subpop(age < 40 & region==1)^

To estimate proportions within multiple subpopulations, either use the ^subpop()^
option repeatedly or else use ^svymean^ with the ^by()^ option.


Also see
--------

On-line:  help for @svymean@, @svydes@, @svyreg@, @varset@