help for factmerg (Roger Newson)

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

factmerg [varlist] [if exp] [in range] [ ,

fvalue(newvarname [, msdecode_options])

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)
]

where msdecode_options is a list of any options
used by the msdecode module of the sdecode package,
apart from generate(), replace and delimiters().

Description

factmerg takes, as input, a list of variables (numeric or string), representing discrete factors.
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 requires the SSC package sdecode in order to work.

Options

fvalue(newvarname [, msdecode_options]) 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.
These values are derived by the rules used by the msdecode module of the SSC package sdecode,
specified in the msdecode_options.
Values from string input variables are copied.
Values from numeric input variables are decoded.

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 fname(), flabel() and fvalue(),
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 fvregen or factext,
which are used with parmby, parmest and descsave
to create a list of factors in the output dataset (or resultsset).
The output fvalue() variable created by factmerg
may be output using outsheet or listtab 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 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, fvregen, factext, listtab,
parmby, parmest, sencode and sdecode
can be installed from SSC.

For more about the use of factmerg with these SSC packages to create tables and plots,
see Newson (2012), Newson(2010), Newson (2008), Newson (2006), Newson (2004), Newson (2003) and Newson (2002).

Examples

The following example will work with the auto data,
if the SSC packages descsave, parmest
and fvregen are installed.

. sysuse auto, clear

. tempfile tf0

. descsave rep78 foreign, do(`"`tf0'"',replace)

. parmby "regress mpg i.rep78 i.foreign, robust", norestore omit format(estimate min* max* %8.2f p %8.2g)

. fvregen, do(`"`tf0'"')

. describe

. list

. factmerg foreign rep78, fn(faname) fl(falab) fv(faval)

. describe

. list parm rep78 foreign faname falab faval, abbr(32) noobs sepby(falab)

The following example will work with the auto data,
if the SSC package xcontract is installed.
It creates an output dataset (or resultsset) in the memory,
with 1 observation per value per factor,
and data on frequencies of the value for the factor,
overwriting the original dataset.
It then uses factmerg to create string variables,
containing, in each observation, the name, label and value of the factor.

. sysuse auto, clear

. tempfile tf1 tf2

. xcontract foreign, nomiss saving(`"`tf1'"', replace)

. xcontract rep78, nomiss saving(`"`tf2'"', replace)

. clear

. append using `"`tf1'"' `"`tf2'"'

. sort foreign rep78

. order foreign rep78

. describe

. list

. factmerg foreign rep78, fname(myfaname) flab(myfalab) fval(myfaval)

. describe

. list myfaname myfalab myfaval _freq _percent, abbr(32) sepby(myfaname)

Author

Roger Newson, King's College London, UK.
Email: roger.newson@kcl.ac.uk

References

Newson, R. B. 2012.
From resultssets to resultstables in Stata.
The Stata Journal 12(2): 191-213.
Download from The Stata Journal website.

Newson, R. B. 2010. Post-parmest peripherals: fvregen, invcise, and qqvalue.
Presented at the 16th United Kingdom Stata Users' Group Meeting, London, 9-10 September, 2010.

Newson, R. B. 2008. parmest and extensions.
Presented at the 14th United Kingdom Stata Users' Group Meeting, London, 8-9 September, 2008.

Newson, R. 2006. Resultssets, resultsspreadsheets, and resultsplots in Stata.
Presented at the 4th German Stata Users' Group Meeting, Mannheim, 31 March, 2006.

Newson, R. 2004. From datasets to resultssets in Stata.
Presented at the 10th United Kingdom Stata Users' Group Meeting, London, 29-30 June, 2004.

Newson, R. 2003. Confidence intervals and p-values for delivery to the end user.
The Stata Journal 3(3): 245-269.

Newson, R. 2002. Creating plots and tables of estimation results using parmest and friends.
Presented at the 8th United Kingdom Stata Users' Group Meeting, 20-21 May, 2002.

Also see

On-line: help for describe, list, sort, order

help for descsave, eclplot, factext, fvregen, listtab, parmby, parmest, sdecode, sencode, xcontract if installed