------------------------------------------------------------------------------- help forfactext(Roger Newson) -------------------------------------------------------------------------------

Extract factor values from alabelvariable created byparmestorparmby

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

Description

factextis 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.factextis 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 thelabelvariable in the data set created by parmby or parmest. If the model contains categorical factors, then thelabelvariable 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

newvarlistif it is present, and otherwise are specified by thefactor_names. The factor values are specified in thevalues.

Options

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

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

dofile(dofilename)specifies a Stata do-file to be called byfactextafter 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 thefrom()option. Thisparse_stringseparates thefactor_names from thevalues. 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

factextis 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 offactextin combination with parmest and descsave can be found in Newson (2003). In its default setting, with nofrom()option,factextcan 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 oflabelmay 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

labelinto 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 offactextto extract thevalues. (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.

factextsaves the returned resultr(faclist), containing the list of factors cr > eated.

ExamplesThe following examples will work with the

autodata if parmest is installed. They will create confidence interval plots of the parameters corresponding to values of the factorrep78.. 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

autodata if descsave is installed in addition to parmest. The reconstructed categorical variablesrep78andforeignwill 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

autodata 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.

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

ReferencesNewson, R. 2003. Confidence intervals and

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

Also seeManual:

[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