{smcl}
{* 27jul2004}{...}
{hline}
help for {hi:mrtab}{right:(SJ5-1: st0082)}
{hline}

{title:One- and two-way tables of multiple responses}

{p 4 4 2} One-way tables:

{p 8 15 2}
{cmd:mrtab} {it:varlist} [{it:weight}] [{cmd:if} {it:exp}]
 [{cmd:in} {it:range}] [{cmd:,}
  {cmdab:p:oly}
  {cmdab:r:esponse:(}{it:numlist}{cmd:)}
  {cmdab:count:all}
  {cmdab:in:clude}
  {cmdab:includem:issing}
  {cmdab:case:wise}
  {cmdab:ti:tle:(}{it:string}{cmd:)}
  {cmdab:w:idth:(}{it:#}{cmd:)}
  {cmdab:ab:brev}
  {cmdab:nol:abel}
  {cmdab:non:ames}
  {cmdab:f:ormat:(}{it:%fmt}{cmd:)}
  {cmdab:int:eger}
  {cmd:sort}[{cmd:(}{it:#}{cmd:)}]
  {cmdab:des:cending}
  {cmdab:g:enerate:(}{it:prefix}{cmd:)}
  {cmdab:nof:req} ]

{p 4 4 2} Two-way tables:

{p 8 15 2}
{cmd:mrtab} {it:varlist} [{it:weight}] [{cmd:if} {it:exp}]
 [{cmd:in} {it:range}] {cmd:,} {cmd:by(}{it:varname}{cmd:)}
 [ {cmdab:col:umn}
   {cmd:row}
   {cmdab:ce:ll}
   {cmdab:rcol:umn}
   {cmdab:rce:ll}
   {cmdab:ch:i2}
   {cmdab:lr:chi2}
   {cmdab:m:test}[{cmd:(}{it:spec}{cmd:)}]
   {cmdab:mlr:chi2}
   {cmdab:w:rap}
   {it:one-way_options} ]

{p 4 4 2} {cmd:by} {it:...} {cmd::} may be used with {cmd:mrtab}; see help
{help by}.

{p 4 4 2} {cmd:fweight}s and {cmd:aweight}s are allowed with {cmd:mrtab}; see
help {help weights}.


{title:Description}

{p 4 4 2} {cmd:mrtab} tabulates multiple responses which are stored as a set of
variables. For example, a survey question might be: "Which of the following
devices do you have in your home?" The respondent is then given a list like "1.
Television, 2. Dishwasher, 3. Computer, 4. Dry cleaner ..." and may mark any
number of devices. Such information can be stored in several ways. Two of them
can be handled by {cmd:mrtab}:

{p 4 8 2} Indicator mode: Each item in the list is represented by
an integer indicator variable (e.g., 1 = item was marked by the respondent, 0 =
item was not marked).

{p 4 8 2} Polytomous mode (option {cmd:poly}): Each response is represented by
a polytomous variable (first response, second response, third response, ...;
this is convenient if the list of possible response categories is open or
half-open). With the polytomous approach, the response variables may take on
either integer or string values.

{p 4 4 2} In either case, {cmd:mrtab} will compute a one-way or a two-way table
of the frequency distribution of the responses. For two-way tables {cmd:mrtab}
also offers significance tests.

{p 4 4 2} If the data are stored in numeric format according to
the polytomous mode, the labels of the response categories are taken from the value
labels of the {it:first} variable. It is therefore crucial that the first
variable contain labels for all possible items.

{p 4 4 2} There are several ways to determine the number of valid observations.
By default, all cases with at least one valid response (as specified by
{cmd:response()}) are taken into account. All other observations are treated as
missing. In some situations, however, it is appropriate to include cases with
zero responses (see the {cmd:include} and the {cmd:includemissing} option).
Furthermore, one might want to consider cases with complete information only
and neglect all cases with one or more missing values (option {cmd:casewise}).

{p 4 8 2}Use {help mrgraph} to produce plots of multiple response distributions.


{title:Options}

{p 4 8 2} {cmd:abbrev} specifies that long response labels be
abbreviated rather than wrapped.

{p 4 8 2} {cmd:by(}{it:varname}{cmd:)} tabulates the distribution of responses
against the categories of {it:varname} (two-way table). The by-variable may be
string or numeric.

{p 4 8 2} {cmd:casewise} specifies that cases with missing values for at least
one of the response variables should be excluded listwise.

{p 4 8 2} {cmd:cell} displays the relative frequency of each cell in a two-way
table (base: total number of valid observations).

{p 4 8 2} {cmd:chi2} requests the calculation of an overall Pearson chi-square
statistic for the hypothesis that the distribution of response patterns is
independent from the values of the by-variable (not allowed if {cmd:aweight}s
are specified). That is: A standard chi2 test is applied to an expanded two-way
table, where the rows represent unique combinations of responses.

{p 4 8 2} {cmd:column} displays in each cell of a two-way table the relative
frequency of that cell within its column (base: column total of observations).

{p 4 8 2} {cmd:countall} requests that repeated identical responses be
added up (allowed only for polytomous response variables, see {cmd:poly}). By
default, repeated identical responses will only be counted once per case.
Notes: Significance tests may not be requested if {cmd:countall} is specified.
Be careful with interpreting results that are labeled "percentage of cases";
though they reflect the mean number of responses per case, they cannot be
interpreted as proportions.

{p 4 8 2} {cmd:descending} specifies that the sort order be descending. The
default is to sort in ascending order. This is only relevant if {cmd:sort} is
specified.

{p 4 8 2} {cmd:format(}{it:%fmt}{cmd:)} specifies the display format for
relative frequencies.

{p 4 8 2} {cmd:generate(}{it:prefix}{cmd:)} creates a set of indicator
variables reflecting the observed responses. The variables will be labeled and
named according to the {it:prefix} provided. If {cmd:name(}{it:string}{cmd:)}
is specified, the first eight characters of {it:string} are inserted into the
variable labels. If the {cmd:chi2} and/or {cmd:lrchi2} options are specified,
{cmd:generate} will additionally return a composite string variable,
{it:prefix}rp, which reflects response patterns (each unique combination of
responses is represented by a string of zeros and ones).

{p 4 8 2} {cmd:include} specifies that observations composed of zero responses be
treated as valid. Only cases with "real" missings (., .a, .b, .c, ...) for all
response variables will be excluded. Note that {cmd:include} will affect only
the number of valid cases, i.e. both the absolute distribution of responses and
the distribution relative to the total of responses will remain unchanged. In
the case of string response variables, {cmd:include} specifies that cases with
only empty strings ("") be treated as valid.

{p 4 8 2} {cmd:includemissing} is an enhancement to {cmd:include} and specifies
that cases be treated as valid even if all response variables are missing.
{cmd:includemissing} implies {cmd:include}. Specifying {cmd:includemissing} in
connection with {cmd:casewise} has the effect that cases with missing values
for at least one of the response variables will be treated as valid cases
composed of zero responses.

{p 4 8 2} {cmd:integer} specifies the display of frequencies as integers even
if {cmd:aweight}s are applied.

{p 4 8 2} {cmd:lrchi2} requests the calculation of an overall likelihood-ratio
chi-square statistic (as an alternative to {cmd:chi2}). Note that the
{cmd:lrchi2} option is not allowed if {cmd:aweight}s are specified and that
the statistic will not be calculated if there are empty cells.

{p 4 8 2} {cmd:mtest} requests the calculation of separate Pearson chi-square
statistics for each response response category. That
is, a test is carried out for each response category to establish whether the
probability of observing the response depends on the values of the by-variable
(this option is not allowed if {cmd:aweight}s are specified). Multiple-test
adjustments may be requested by specifying the method in brackets
(e.g. {cmd:mtest(bonferroni)}). See help {help _mtest}.

{p 4 8 2} {cmd:mlrchi2} requests {cmd:mtest} to use the likelihood-ratio
chi-square statistics instead of Pearson chi-square.

{p 4 8 2} {cmd:nofreq} suppresses printing the frequencies (i.e., the whole
frequency table will be suppressed unless {cmd:cell}, {cmd:column}, {cmd:row},
{cmd:rcell} or {cmd:rcolumn} is specified for two-way tables).

{p 4 8 2} {cmd:nolabel} suppresses the printing of labels.

{p 4 8 2} {cmd:nonames} suppresses the printing of variable names or category
values in the left stub of the table, i.e. only the labels will be printed.
(This option has no effect if the response variables are string variables.) Not
allowed if the response variables are unlabeled or the {cmd:nolabel} option is
specified.

{p 4 8 2} {cmd:poly} specifies that the responses are stored according to the
polytomous mode. If {cmd:poly} is not specified, {cmd:mrtab} assumes that the
responses are stored according to the indicator mode. However, string response
variables imply {cmd:poly}.

{p 4 8 2} {cmd:rcell} displays the relative frequency of each cell in a two-way
table (base: total number of responses).

{p 4 8 2} {cmd:rcolumn} displays in each cell of a two-way table the relative
frequency of that cell within its column (base: column total of responses).

{p 4 8 2} {cmd:response(}{it:numlist}{cmd:)} specifies the (range of) response
values. If the data are stored according to the indicator mode,
{cmd:response()} specifies the value which indicates a response to the item.
{cmd:response()} defaults to 1 in this case. Note that the indicator variables
do not necessarily have to be dichotomous since a list or range of values may
be specified. If the data are stored according to the polytomous
mode, {cmd:response()} specifies the list or range of responses that are
to be tabulated. The default is to tabulate every value observed for the
response variables (except for missing values). In the case of string
variables, the {cmd:response()} option is obsolete.

{p 4 8 2} {cmd:row} displays in each cell of a two-way table the relative
frequency of that cell within its row (base: row total of responses; this is
equal to the row total of observations unless {cmd:countall} is specified).

{p 4 8 2} {cmd:title(}{it:string}{cmd:)} may be used to label the multiple
response set. {it:string} will be printed at the head of the table.

{p 4 8 2} {cmd:sort} displays the table rows in ascending order of frequency.
In the case of a two-way table the sorting will correspond to the row totals
unless a reference column is specified in parentheses. That is, {cmd:sort(1)}
will sort in order of the frequencies in the first column (first by-group),
{cmd:sort(2)} in order of the frequencies in the second column, and so on. Specify
the {cmd:descending} option to sort in descending order.

{p 4 8 2} {cmdab:width(}{it:#}{cmd:)} specifies the maximum width (number of
chars) used to display the labels of the responses. Labels that are too wide
are wrapped (or abbreviated if the {cmd:abbrev} option is specified). The
default width is 30. The minimum width is 11.

{p 4 8 2} {cmd:wrap} requests that Stata take no action on wide two-way tables
to make them readable. Unless {cmd:wrap} is specified, wide tables are broken
into pieces to enhance readability.


{title:Examples}

{p 4 4 2} Indicator mode:

{p 8 12 2}{cmd:. use http://fmwww.bc.edu/RePEc/bocode/d/drugs.dta}{p_end}
{p 8 12 2}{cmd:. mrtab inco1-inco7, include title(Sources of income) width(24)}

{p 4 4 2} Polytomous mode:

{p 8 12 2}{cmd:. mrtab pinco1-pinco6, poly response(1/7) include title(Sources of income) width(27)}

{p 4 4 2} The {cmd:response()} option in indicator mode:

{p 8 12 2}{cmd:. codebook crime1}{p_end}
{p 8 12 2}{cmd:. mrtab crime1-crime5, include response(2 3) title(Crime (as victim)) nonames}

{p 4 4 2} Two-way table incl. tests:

{p 8 12 2}{cmd:. mrtab crime1-crime5, include response(2 3) title(Crime (as victim)) nonames width(18) by(sex) column mtest(bonferroni)}


{title:Saved Results}

{p 4 4 2} Scalars:

{p 4 17 2} {cmd:r(N)}{space 9}number of valid cases{p_end}
{p 4 17 2} {cmd:r(N_miss)}{space 4}number of missing cases{p_end}
{p 4 17 2} {cmd:r(r)}{space 9}number of response categories{p_end}
{p 4 17 2} {cmd:r(c)}{space 9}number of by-groups if {cmd:by()} is
            specified{p_end}
{p 4 17 2} {cmd:r(chi2)}{space 6}overall Pearson chi-squared if {cmd:chi2} is
           specified{p_end}
{p 4 17 2} {cmd:r(p)}{space 9}p-value of the overall Pearson chi-squared{p_end}
{p 4 17 2} {cmd:r(chi2_lr)}{space 3}overall likelihood-ratio chi-squared if
           {cmd:lrchi2} is specified{p_end}
{p 4 17 2} {cmd:r(p_lr)}{space 6}p-value of the overall likelihood-ratio
           chi-squared{p_end}
{p 4 17 2} {cmd:r(df)}{space 8}degrees of freedom of the overall
           chi2 tests{p_end}

{p 4 4 2} Macros:

{p 4 17 2} {cmd:r(list)}{space 6}list of the labels of the responses if
           available{p_end}
{p 4 17 2} {cmd:r(mode)}{space 6}either "indicator" or "poly" depending on the
           mode of the multiple response variables{p_end}
{p 4 17 2} {cmd:r(type)}{space 6}either "numeric" or "string" depending on the
           storage type of the multiple response variables{p_end}
{p 4 17 2} {cmd:r(bylist)}{space 4}list of the labels of the by-groups if
           available{p_end}
{p 4 17 2} {cmd:r(bytype)}{space 4}either "numeric" or "string" depending on the
           storage type of the by-variable{p_end}

{p 4 4 2} Matrices:

{p 4 17 2} {cmd:r(responses)}{space 1}frequencies of responses{p_end}
{p 4 17 2} {cmd:r(cases)}{space 5}cases in by-groups if {cmd:by()} is
           specified{p_end}
{p 4 17 2} {cmd:r(mchi2)}{space 5}Pearson chi-squared and (adjusted) p-values of
           the separate tests if {cmd:mtest} is specified{p_end}
{p 4 17 2} {cmd:r(mchi2_lr)}{space 2}likelihood-ratio chi-squared and (adjusted)
           p-values of the separate tests if {cmd:mtest} and {cmd:mlrchi2} are
           specified{p_end}


{title:Authors}

{p 4 4 2} Ben Jann, ETH Zurich, jann@soz.gess.ethz.ch

{p 4 4 2} Hilde Schaeper, HIS, Hannover, schaeper@his.de


{title:Also see}

{p 4 13 2} Manual:  {hi:[R] tabulate}

{p 4 13 2} Online:  help for {help mrgraph}, {help _mrsvmat}, {help tabulate},
{help _mtest}

{p 4 13 2} FAQ:
{browse "http://www.stata.com/support/faqs/data/multresp.html":How do I deal with multiple responses?}