Insert new observations with reference values for factors
factref varlist [if exp] [in range] [ , by(varlist) refind(newvarname) rzero(varlist) runity(varlist) ]
Description
factref is used with factext, descsave, parmby and parmest. It takes, as input, a data set created by parmby or parmest, in which factors have been created by descsave and factext. These factors are variables (numeric or string) representing categorical variables in the fitted model, represented by dummy variables such as those created by xi. factref adds to that data set a set of additional observations with reference values for these factors, copied from the omit characteristic for each factor. (The omit characteristic is used by the xi command to store the reference value of a categorical variable; see [R] xi.) For each factor, factref creates one reference observation if there are non-missing values for the factor and there is no by-variable list, or one reference observation for each by-group where there are non-missing values of the factor if there is a by-variable list. After the reference observations have been added, the user may create a plot or table of confidence intervals for factor effects.
Options
by(varlist) specifies a list of by-variables. factref will create a reference observation for each factor for each by-group containing non-missing values of that factor.
refind(newvarname) specifies an output variable indicating, in each observation, whether that observation is a reference observation. It contains a missing value if that observation is excluded by the if and/or in statements, a value of 1 if that observation is a reference observation, and a value of 0 otherwise.
rzero(varlist) specifies a list of existing variables whose values in the reference observations are to be set to 0 (if the variable is numeric) or "0" (if the variable is string). These variables might represent estimates and confidence limits for difference parameters, eg additive factor effects such as mean differences between factor levels.
runity(varlist) specifies a list of existing variables whose values in the reference observations are to be set to 1 (if the variable is numeric) or "1" (if the variable is string). These variables might represent estimates and confidence limits for ratio parameters, eg multiplicative factor effects such as relative risks between factor levels.
Remarks
factref is typically used with factext, which is used with parmby, parmest and descsave to create a data set with one observation per model parameter and data on confidence intervals and P-values. factref adds, to such a data set, a set of reference observations, one for each factor, or one for each by-group containing at least one non-missing value of each factor if the by() option is specified. A reference observation for a factor has a value for that factor taken from the omit characteristic for that factor. The other variables in a reference observation may have values reset to zero or one if the variable is listed in the options rzero or runity, respectively. Otherwise, the value of any variable in a reference observation, apart from the factors and the by-group variables specified in the by() option, is set to missing. For factref to work, the omit characteristic for each factor must be set to the reference value for that factor. This can be done by specifying the omit characteristic for the factor of the same name in the original data set, and then using the char(omit) option with descsave. (The omit characteristic is used by the xi command; see [R] xi.)
Examples
The following example will work with the auto data if parmest, parmby, descsave and factext are installed. A logistic regression is carried out, comparing the odds of non-US origin between 3 tertiles of mileage, created by the xtile command. The odds ratios (with confidence limits) are plotted against mileage tertile. Note that the characteristic mpggp[omit], used optionally by xi, must be specified if factref is to work.
. xtile mpggp=mpg, nq(3) . char mpggp[omit] 1 . tempfile tf0 . descsave ,char(omit) do(`"`tf0'"', replace) . parmby "xi: logit foreign i.mpggp,or", label norestore eform format(estimate min* max* %8.2f p %8.1e) . factext, do(`"`tf0'"') . factref mpggp, ru(estimate min* max*) . list . version 7: graph estimate min95 max95 mpggp, s(O..) c(.II) xlab(1 2 3) ylab ylin(1)
The following example illustrates the by() option, and will work with the auto data if parmest, parmby, descsave and factext are installed. It will add reference observations to the parmby output data set and create a graph of confidence intervals. Note that the characteristic rep78[omit], used optionally by xi, must be specified if factref is to work.
. char rep78[omit] 1 . tempfile tf0 . descsave, char(omit) do(`"`tf0'"', replace) . parmby "xi:regress mpg i.rep78", label by(foreign) norestore format(estimate min* max* %8.2f p %8.1e) . factext, do(`"`tf0'"') . factref rep78, by(foreign) rz(estimate stderr min* max*) refind(refcat) . list . version 7: graph estimate min95 max95 rep78, s(O..) c(.II) by(foreign) xlab ylab ylin(0)
Another example of the use of factref can be found in Newson (2003).
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] xi, [R] pctile. On-line: help for describe, tabulate, xi, graph help for parmby, parmest, descsave, factext and factmerg if installed