-------------------------------------------------------------------------------
help for factmerg                                                (Roger Newson)
-------------------------------------------------------------------------------


Merge factors to create string variables containing values, names and labels

        factmerg [varlist] [if exp] [in range] [ , fvalue(newvarname)
               fname(newvarname) flabel(newvarname) mvalue(string_expression)
               mname(string_expression) mlabel(string_expression)
               fmissing(newvarname) xmlsub pvalue(string) pname(string)
               plabel(string) svalue(string) sname(string) slabel(string) ]


Description

factmerg takes, as input, a list of variables (numeric or string), representing
discrete factors in a model.  It creates, as output, one to three string
variables, containing, in each observation, a value, a factor name or a factor
variable label, respectively, copied from the first factor variable in the
input variable list with a non-missing value for that observation.  factmerg is
intended for use with a list of input variables created by factext after a call
to parmby or parmest. The output variables are intended to be used in creating
row labels for output tables and/or plots, possibly using the sencode package.
The input factors are usually either created in a parmest or parmby output data
set by using the factext package, or are in a data set created by concatenating
multiple xcontract output data sets using the dsconcat package.


Options

    fvalue(newvarname) specifies a string output variable containing, in each
        observation, a value derived from the first variable in the input
        varlist with a non-missing value for that observation. Values from
        string input variables are copied.  Values from numeric input
        variables are decoded using value labels if these are present, or
        using formats otherwise.

    fname(newvarname) specifies a string output variable containing, in each
        observation, the name of the input variable from which the value of
        the fvalue() variable is copied for that observation.

    flabel(newvarname) specifies a string output variable containing, in each
        observation, the variable label of the input variable from which the
        value of the fvalue() variable is copied for that observation.

    mvalue(string_expression) specifies a string expression, used to define
        values for the fvalue() variable for observations with missing values
        for all variables in the input varlist.

    mname(string_expression) specifies a string expression, used to define
        values for the fname() variable for observations with missing values
        for all variables in the input varlist.

    mlabel(string_expression) specifies a string expression, used to define
        values for the flabel() variable for observations with missing values
        for all variables in the input varlist.

    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 input
        factors are missing, and 0 for other observations in which at least
        one of the input factors is nonmissing.

    xmlsub specifies that, in the string output variables indicated by the
        options fvalue() and flabel(), the substrings "&", "<" and ">" will
        be replaced throughout with the XML entity references "&amp;", "&lt;"
        and "&gt;", respectively.  This is useful if the string output
        variables are intended for output to a table in a document in XHTML,
        or in other XML-based languages.

    pvalue(string) specifies a prefix to be added to the fvalue() output
        variable.

    pname(string) specifies a prefix to be added to the fname() output
        variable.

    plabel(string) specifies a prefix to be added to the flabel() output
        variable.

    svalue(string) specifies a suffix to be added to the fvalue() output
        variable.

    sname(string) specifies a suffix to be added to the fname() output
        variable.

    slabel(string) specifies a suffix to be added to the flabel() output
        variable.


Remarks

factmerg is typically used with factext, which is used with parmby, parmest and
descsave to create a list of factors. The output fvalue() variable created by
factmerg may be output using outsheet or listtex to create a table with one row
per model parameter and data on the estimates, confidence limits and/or
P-values.  Alternatively, the fvalue() variable may be encoded to a numeric
variable using sencode and then plotted, using graph, hplot or eclplot, to
create a confidence interval plot with one axis label per model parameter.  The
fvalue, fname and/or flabel variables may be used in string expressions to
generate labels for the rows of the table, or for positions on the axis of a
confidence interval plot, specifying the parameters in a human-readable format.
The packages descsave, eclplot, factext, factref, hplot, listtex, parmby, 
parmest, sdecode and sencode are not supplied with official Stata, but can be
installed from SSC.  Further information on the use of some of these packages
can be found in Newson (2003).


Examples

The following example will work with the auto data if descsave, parmest, parmby
and factext are installed.

                . tempfile tf0
                . descsave rep78 foreign, do(`"`tf0'"',replace)
                . parmby "xi: regress mpg weight i.rep78 i.foreign, robust",
                    label norestore format(estimate min* max* %8.2f p %8.2g)
                . factext, do(`"`tf0'"')
                . factmerg foreign rep78, fn(faname) fl(falab) fv(faval)
                    mn(parm) ml(label)
                . list parm label rep78 foreign faname falab faval


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.  Download from the Stata Journal
website.


Also see

On-line:  help for describe, tabulate, xi, graph
          help for descsave, eclplot, factext, factref, hplot, listtex, parmby,
          parmest, sdecode, sencode, xcontract if installed