*! version 0.1.0 August 14, 2023 J. N. Luchman
help fitdom

Title

Wrapper program for domin to obtain fit statistics from postestimation commands

Syntax

fitdom depvar indepvars if [weight] ,
postestimation(command, command_options)
reg_fd(command, command_options)
fitstat_fd(scalar)

Factor and time series variables are allowed for commands in reg_fd()
that accept them. aweight, iweights, pweights, and fweights are also allowed
(see help weights) for commands in reg_fd() that accept them.

Description

fitdom adds an additional layer to domin in which the user calls the fitdom program in
domin and the fitdom program calls the desired regression model for use in the dominance analysis.

This wrapper command is intended to simplify and extend how domin can be used with official and
user-contributed commands. fitdom extends the capabilities of domin by allowing for
any postestimation command that returns a scalar-valued fit statistic to be used in the dominance
analysis. The intention of this wrapper command is to provide a tool that can assist the user in
avoiding the need for programming a wrapper command to apply a non-built-in fit statistic.

This wrapper command takes inspration from the R package
domir and its adaptation of the fitstat concept from Stata's
domin command.

Options

postestimation() is name of the postestimation command called by fitdom. The command
called by this option can also be called with its own options.

reg_fd() is the contents of the reg() option that would normally be supplied to domin.

fitstat_fd() is the contents of the fitstat() option that would normally be supplied
to domin.

Saved results

fitdom retains all the results from the command in reg_fd() and adds the following results to e():

scalars

e(fitstat) The value of the fit statistic called by postestimation

Usage and Examples

Usage Principles

fitdom is only intended for use as an entry to the reg() option of domin. In situations
where the user would like to implement fitdom it is used in place of the regression model as the entry
to the reg() option in domin. The usual entries to domin are submitted as options to the
fitdom command along with the name of the postestimation command.

e(fitstat) is always used as the entry to the fitstat() option of domin.

Entries in fitstat_fd() can be ereturned, returned, or other matrcies in memory so long as they are
subscripted to select a specific scalar from the matrix.

Detailed Example

fitdom offers additional flexibility in using official and user-contributed fit statistic-generating
commands in domin while avoiding programming your own wrapper command when you would like to use a
fit statistic that is not returned by the command itself.

To illustrate the use of the wrapper command, imagine you were interested in testing a model such as:

logit foreign length turn displacement

with the sysuse auto data and applying the user contributed command on SSC r2o
(see findit r2o) as an alternative fit statistic for the logit model. Hence, the
sequence of steps the user wants to do is something like:

logit foreign length turn displacement

r2o

This would run the original model and then call the fit statistic-generating postestimation command. Encoding
this into domin to run the dominance analysis with the above logit model but using the r2o fit
statistic would result in a domin command like:

domin foreign length turn displacement, reg(fitdom, reg_fd(ologit) fitstat_fd(r(r2o)) postestimation(r2o)) fitstat(e(fitstat))

A key first point of note is that the command submitted to domin is fitdom and not logit.
Rather, logit is submitted as the option reg_fd() to fitdom. Similarly, note that the
fitstat() submitted to domin is e(fitstat), the returned value from fitdom, and not
the returned value from the r2o command we seek to use.

In order to use the r2o postestimation command, it has to be put into the
postestimation() option of fitdom. This tells fitdom to, after running the command in
the reg_fd() option, use the command in the postestimation() option. The entry in the
fitstat_fd() option points fitdom to the name of the scalar-valued fit statistic
to rename and return as e(fitstat) so domin can use it in the dominance analysis.

Imagine the analysis also calls for dominance analyzing the Akaike information criterion/AIC with estat ic.
An approach using the AIC would look something like:

domin foreign length turn displacement, reg(fitdom, reg_fd(logit) fitstat_fd(r(S)[1,6]) postestimation(estat ic)) fitstat(e(fitstat)) reverse consmodel

Because estat ic does not return a single value, but a matrix, the user has to submit not only the returned
matrix name (i.e., r(S)) but also the matrix subscript selecting the AIC in the first row and sixth column.

Author

Joseph N. Luchman

Research Fellow

Fors Marsh

Arlington, VA

jluchman@forsmarsh.com