-------------------------------------------------------------------------------
help for factext                                                 (Roger Newson)
-------------------------------------------------------------------------------


Extract factor values from a label variable created by parmest or parmby

        factext [newvarlist] [if] [in] [ , from(varlist) string
               dofile(dofilename) parse(parse_string) fmissing(newvarname{)} ]


Description

factext is intended for use after the programs parmest or parmby, which form
the parmest package and create data sets with one observation per parameter of
the most recently fitted model.  It is used when the fitted model contains
factors (categorical variables), in which case some of the parameters
correspond to dummy variables in the original data set, indicating individual
values of these factors. These dummy variables are usually created by xi, by 
tabulate or by John Hendrickx's desmat package.  factext is used to create new
factors with the same names in the new data set created by parmest.  These new
factors can be used to make confidence interval plots and/or tables. Each new
factor is assigned the appropriate value in observations belonging to
parameters belonging to the factor, and missing values in other observations.
The values of these factors are usually extracted from the label variable in
the data set created by parmby or parmest. If the model contains categorical
factors, then the label variable will have values of the form

"factor_name==value"

in observations belonging to parameters belonging to these factors. The names
of the factors to be re-created are specified in the newvarlist if it is
present, and otherwise are specified by the factor_names. The factor values are
specified in the values.


Options

from(varlist) specifies a list of input string variables, from which the
    factors and their values are extracted. If this option is absent, then
    factext attempts to extract the factors from a single string variable named
    label. The from() option is used when the fitted model contains
    interactions, in which case the user must create a list of new string
    variables from label and specify these as the from() option (see Remarks).
    Factor values found in later variables in the from() list overwrite values
    for the same factors found in earlier variables in the from() list.

string specifies that the factors generated will be string variables. Otherwise
    they will be numeric variables.

dofile(dofilename) specifies a Stata do-file to be called by factext after the
    new factors have been created. This do-file is usually created by descsave,
    and contains commands to reconstruct the new factors with the storage
    types, display formats, value labels, variable labels and selected
    characteristics of the old factors with the same names in the original data
    set.

parse(parse_string) specifies the string used to parse the input string
    variables specified in the from() option. This parse_string separates the
    factor_names from the values. If absent, it defaults to "==".

fmissing(newvarname) specifies the name of a new binary variable to be
    generated, containing missing values for observations excluded by the if
    and in qualifiers, 1 for other observations in which all the generated
    factors are missing, and 0 for other observations in which at least one of
    the generated factors is nonmissing.


Remarks

factext is typically used with the parmest and descsave packages to create a
new data set with one observation per parameter of the most recently fitted
model, and data on the estimates, confidence intervals, P-values and other
attributes of these parameters. These data are used to create plots and/or
tables.  More information about the use of factext in combination with parmest
and descsave can be found in Newson (2003).  In its default setting, with no
from() option, factext can only handle labels for dummy variables corresponding
to single factors, and cannot extract higher-order interactions. If there are
higher-order interactions in the fitted model, then some of the values of label
may be of a form such as

"factor_name1==value1 & factor_name2==value2"

or

"(factor_name==value)*varname"

(as created by xi). In this case, the user may use the split package to split
the variable label into two or more string variables, each possibly containing
values of the form

"factor_name==value"

These new string variables may then be input as the from() option of factext to
extract the values. (See Examples below.)

To add extra observations to the data set containing reference levels for the
factors created by factext, use the factref package.  To merge multiple factors
and generate string variables containing the factor values, names and labels,
use the factmerg package.

factext saves the returned result r(faclist), containing the list of factors cr
> eated.


Examples

The following examples will work with the auto data if parmest is installed.
They will create confidence interval plots of the parameters corresponding to
values of the factor rep78.

                . tab rep78, gene(rep_)
                . parmby "regress mpg rep_*, noconst", label norestore
                . factext rep78
                . version 7: graph estimate min95 max95 rep78, s(O..) c(.II)
                    xlabel

                . xi: regress mpg i.rep78
                . parmest, label norestore
                . factext
                . version 7: graph estimate min95 max95 rep78, s(O..) c(.II)
                    xlabel ylabel yline(0)

The following example will work with the auto data if descsave is installed in
addition to parmest. The reconstructed categorical variables rep78 and foreign
will have the variable and value labels belonging to the variables of the same
names in the original data set.

                . tab foreign,gene(orig_) nolab
                . tempfile tf1
                . descsave, do(`"`tf1'"', replace)
                . parmby "xi: regress mpg orig_* i.rep78, noconst", label
                    norestore
                . factext, do(`tf1')
                . describe
                . version 7: graph estimate min95 max95 rep78, s(O..) c(.II)
                    xlab ylab yline(0)
                . version 7: graph estimate min95 max95 foreign, s(O..) c(.II)
                    xlab(0 1) ylab
                . list foreign rep78 estimate min95 max95 p

The following example demonstrates higher order interactions. It will work with
the auto data if descsave and split are both installed in addition to parmest.

                . tempfile tf1
                . descsave, do(`"`tf1'"', replace)
                . parmby "xi: regress mpg i.foreign*i.rep78", label norestore
                . split label, parse(" & ") gene(s_)
                . factext, from(s_*) do(`tf1')
                . list foreign rep78 parm estimate min95 max95 p, nodisp

The parmest and descsave packages, and the Stata 7 split package written by
Nick Cox, can be installed from SSC.  From Stata 8, the split package has been
distributed as part of official Stata.


Author

Roger Newson, Imperial College London, UK.  Email: r.newson@imperial.ac.uk


References

Newson, R. 2003. Confidence intervals and p-values for delivery to the end
user.  The Stata Journal 3(3): 245-269. A pre-publication draft is downloadable
from Roger Newson's website at http://www.imperial.ac.uk/nhli/r.newson/


Also see

 Manual:  [R] describe, [R] label, [R] tabulate, [R] xi, [G] connect, [G]
          symbol.
On-line:  help for describe, tabulate, xi, graph
          help for parmest, descsave, split, desmat, factref and/or factmerg if
          installed