help for fvregen (Roger Newson)

Regenerate factor variables in a parmest output dataset

fvregen [newvarlist] [if] [in] [ ,
from(varlist)
dofile(dofilename)
fmissing(newvarname) fast ]

Description

fvregen is intended for use in output datasets (or resultssets) created by the programs parmest or parmby.
These are part of the parmest package, which can be downloaded from SSC,
and which create output datasets (or resultssets),
with one observation per estimated parameter of a model fitted to an original dataset.
fvregen regenerates factor variables included in the model,
using information from the parameter names.
Each regenerated factor variable has non-missing values in observations corresponding to parameters
corresponding to levels of that factor,
or to combinations of levels of that factor and other factors in products or interactions.
In each observation,
the regenerated factors with non-missing values are the factors involved in the parameter corresponding to that observation,
and their values are the values of the levels of these factors corresponding to that parameter.
The regenerated factors may have the same storage types, display formats,
value labels, variable labels
and variable characteristics as the factor variables of the same names in the original dataset,
in which the model parameters were estimated.
This is made possible by running do-files created by the descsave package.
After the factors are generated, they can be listed,
and/or used in confidence interval plots generated by the eclplot package,
and/or merged to create a table row variable using the factmerg package.
The descsave, eclplot and factmerg package
can all be downloaded from SSC.

Options

from(varlist) specifies a list of one or more input string variables,
containing parameter names in the form of expanded specific factor varlist elements,
from which the factors and their values are extracted.
If this option is absent, then fvregen attempts to extract the
factors from a single string variable named parm,
which is the default name of the parameter name variable produced by the parmest and parmby modules
of the parmest package.

dofile(dofilename) specifies a Stata do-file to be called by fvregen after 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 dataset.

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.

fast is an option for programmers working with very large datasets.
It specifies that fvregen will not do any extra work to restore the existing dataset in memory,
if the user presses Break.

Remarks

fvregen is typically used with the parmest and descsave packages to create a new dataset
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 tables and/or plots.
Confidence interval plots are often produced using the eclplot package.
To merge multiple factor variabless and generate string variables containing the factor values, names and/or labels,
use the factmerg package.
The parmest, descsave, eclplot and factmerg packages
can be downloaded from SSC.

In Stata versions 7 to 10,
factors were included in models using the xi command,
and factor variables in parmest resultssets were regenerated using the factext package,
which used information in the variable labels of the indicator variables generated by xi.
When Stata version 11 became available,
it became possible to use factor variable lists in estimation commands,
and the fvregen package was written to supersede factext.

Examples

The following examples will work with the auto data if the SSC packages parmest and eclplot are installed.
They will create confidence
interval plots of the parameters corresponding to values of the factor rep78.
Note that the first example produces a plot of mean mileages for each repair record group,
whereas the second example produces a plot of mean differences in mileage
between each repair record group and the reference repair record group,
including a zero-width confidence interval around a zero mean difference for the reference repair record group itself.

. sysuse auto, clear

. parmby "regress mpg ibn.rep78, noconst", label norestore

. fvregen rep78

. eclplot estimate min95 max95 rep78

. sysuse auto, clear

. regress mpg i.rep78

. parmest, label norestore

. fvregen

. eclplot estimate min95 max95 rep78, yline(0)

The following example will work with the auto data if descsave is installed in addition
to parmest and eclplot.
The reconstructed categorical variables rep78 and foreign will have
the variable and value labels belonging to the variables of the same names in the original dataset.

. sysuse auto, clear

. tab foreign,gene(orig_) nolab

. tempfile tf1

. descsave, do(`"`tf1'"', replace)

. parmby "regress mpg ibn.foreign i.rep78, noconst", label norestore

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

. describe

. eclplot estimate min95 max95 rep78, yline(0)

. eclplot estimate min95 max95 foreign, xlab(0 1)

. list foreign rep78 estimate min95 max95 p

The following example demonstrates higher order interactions.
It will work with the auto data
if descsave is installed in addition to parmest.

. sysuse auto, clear

. tempfile tf1

. descsave, do(`"`tf1'"', replace)

. parmby "regress mpg i.foreign#i.rep78", label norestore

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

. list foreign rep78 parm estimate min95 max95 p, nodisp

The parmest, descsave and eclplot packages can be installed from SSC.

Saved results

fvregen saves the following results in r():

Macros

r(varlist) list of factor variables created

Author

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

Also see

Manual: , [P] fvexpand, [D] describe, [D] label, [G] graph, [R] xi

Help: [U] 11.4.3 Factor variables, [P] fvexpand, [D] describe, [D] label, [G] graph, [R] xi

parmest, descsave, eclplot, factmerg, factext if installed