------------------------------------------------------------------------------- help forfactref(Roger Newson) -------------------------------------------------------------------------------

Insert new observations with reference values for factors

factrefvarlist[ifexp] [inrange] [,by(varlist)refind(newvarname)rzero(varlist)runity(varlist)]

Description

factrefis 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.factrefadds to that data set a set of additional observations with reference values for these factors, copied from theomitcharacteristic for each factor. (Theomitcharacteristic is used by the xi command to store the reference value of a categorical variable; see[R] xi.) For each factor,factrefcreates 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.factrefwill 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 theifand/orinstatements, 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

factrefis 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.factrefadds, 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 theby()option is specified. A reference observation for a factor has a value for that factor taken from theomitcharacteristic 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 optionsrzeroorrunity, respectively. Otherwise, the value of any variable in a reference observation, apart from the factors and the by-group variables specified in theby()option, is set to missing. Forfactrefto work, theomitcharacteristic for each factor must be set to the reference value for that factor. This can be done by specifying theomitcharacteristic for the factor of the same name in the original data set, and then using thechar(omit)option with descsave. (Theomitcharacteristic is used by the xi command; see[R] xi.)

ExamplesThe following example will work with the

autodata 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 characteristicmpggp[omit], used optionally by xi, must be specified iffactrefis 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 theautodata 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 characteristicrep78[omit], used optionally by xi, must be specified iffactrefis 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

factrefcan be found in Newson (2003).

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] xi,[R] pctile. On-line: help for describe, tabulate, xi, graph help for parmby, parmest, descsave, factext and factmerg if installed