*! version 1.2O - 28 Aug 2013
help flex

Title

flex -- Flexible pseudo maximum likelihood estimation of models for doubly-bounded data

Syntax

flex
depvar
indepvars
[if] [in]
[, options]

ul(#) specifies the upper limit of the dependent variable; by default the upper limit is 1

extended estimates an extended model with two shape parameters

omega starting value for omega if one is not provided using the from option (see maximize_options); by default omega is set to 1

delta starting value for delta when the extended option is used; by default delta is set to 1

strict selects the method to exclude regressors that may cause convergence problems

keep keeps the observations that would be perfectly predicted by excluded regressors

cluster(clustvar) specifies that the standard errors allow for intragroup correlation

margins(varlist) compute average marginal effects for varlist

nose suppresses calculation of the VCE and standard errors for the margins

maximize_options control the maximization process

fweights and aweights are allowed; pweights and iweights are not allowed.
See weight for details.

Description

flex estimates flexible models for doubly-bounded data using Bernoulli pseudo maximum likelihood.
The models may have one or two shape parameters and generalize the logit specification for fractional
data suggested by Papke and Wooldridge (1996). For further details, see Santos Silva, Tenreyro, and Wei
(2012).

flex uses a simplified version of the method of Santos Silva and Tenreyro (2010) to identify and drop
regressors that may cause the non-existence of the (pseudo) maximum likelihood estimates. Notice that the user
should carefully check whether the specification resulting from dropping the problematic regressors is interesting.
If any of the regressors that are dropped is a dummy variable, by default flex will drop the observations
with the less frequent value of the excluded dummy. This is done to prevent the observations identified by the
dropped dummy from being treated as part of the base category. (This procedure can be overridden with the
option keep.) The user should ensure that this procedure is appropriate and should consider alternatives
like dropping the entire set of dummies, or recoding the variable in fewer categories. Because flex does
not check for the presence of problematic regressors after dropping these observations, there may be rare cases
in which flex tries to find estimates that actually do not exist. In these situations the estimation
procedure will not converge, or convergence is spurious.

Besides the usual table with results, flex
reports the value of the R2 (defined as the square of the correlation between the dependent variable and its
fitted values) and the log of the pseudo likelihood function evaluated at the estimates. Notice, however, that
the Log pseudo-likelihood is not particularly meaningful and cannot be used, for example, to perform likelihood
ratio tests. The command flex uses Stata's [R] ml command to perform the estimation.
Therefore, flex shares many characteristics of the ml command, including its limitations and
benefits. For example, after flex is used to estimate a model, it is possible to get predictions or
test hypotheses about the parameters exactly in the same way as it is done after estimation with ml.
Also as with ml, convergence can be difficult if the dependent variable has very large values.

flex also has an option to estimate average marginal effects. If this option is used, it is not
possible to compute predictions after the command and the tests that are performed are about the marginal
effects, not the parameters.

Options

ul(#) specifies the upper limit of the dependent variable; by default the upper limit is 1.
Stata often finds it difficult to estimate models with large values of the dependent variable.
Therefore, when convergence is difficult to achieve, it may be helpful to rescale the dependent
variable so that it is bounded between zero and 1. The estimated coefficients will not be affected
by the rescaling but the estimated marginal effects will be in the scale of the new variable.

extended estimates an extended model with two shape parameters. A test for the validity
of the simpler model with just one shape parameter can be performed by testing whether the second
parameter (delta) is equal to 1.

omega starting value for omega if one is not provided using the from option (see
maximize_options); by default omega is set to 1.

delta starting value for delta when the extended option is used; by default delta is
set to 1. The starting value of delta cannot be set using the from option (see
maximize_options).

strict by default flex uses a conservative method to exclude regressors that may cause convergence
problems. The strict option forces the exclusion of all variables that are potentially problematic. The
strict option should not be used unless convergence cannot be achieved otherwise, or if there is a warning
that the model may be overfitting observations with depvar=0.

keep if any of the regressors that are dropped to ensure the existence of the estimates is a dummy
variable, by default flex will drop the observations with the less frequent value of the excluded
dummy. The option keep overrides this and does not drop any observation

cluster(clustvar) by default flex computes heteroskedasticity robust standard errors. The cluster
option specifies that the standard errors also allow for intragroup correlation, relaxing the usual
requirement that the observations be independent. That is, the observations are independent across groups
(clusters) but not necessarily within groups. clustvar specifies to which group each observation
belongs. cluster(clustvar) affects the standard errors and variance-covariance matrix of
the estimators but not the estimated coefficients; see .

margins(varlist) compute average marginal effects for varlist. See the examples below to see how
to compute the partial effects for dummy variables.

nose suppresses calculation of the VCE and standard errors for the margins. Note that computation of
the standard errors for the margins can be very time consuming.

maximize_options:
technique(string),
iterate(#),
nolog,
trace,
difficult,
gradient,
showstep,
hessian,
showtolerance,
tolerance(#),
ltolerance(#),
nrtolerance(#),
nonrtolerance,
from(init_specs); see [R] maximize for more details.

Remarks

flex is not an official Stata command and was written by J.M.C. Santos Silva, S. Tenreyro, & K. Wei.
For further help and support, please contact jmcss@surrey.ac.uk. Please notice that this software is provided
as is, without warranty of any kind, express or implied, including but not limited to the warranties of
merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors be liable
for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from,
out of or in connection with the software or the use or other dealings in the software.

Examples

Setup - generate a discrete and a continuous regressor and then generate y bounded between 0 and 50

. clear all

. set obs 10000

. set seed 13813

. g x1=rbinomial(1,0.4)

. g x2=rnormal(0,1)

. g y=rbinomial(50,((1 - (1 + [2.5]*exp(0.25*x1+1*x2))^(-1/[2.5]))^(1)))

flex estimation (notice that estimation with just the dummy variable is not possible because the shape parameters are not identified)

. flex y x1 x2, ul(50)

Test the validity of the logit specification)

. test [omega]_cons==1

flex estimation with the margins option (notice that for the partial effect of the dummy variable to be
computed correctly it is necessary to use the factor notation in the list of regressors, but not in the list of variables for which
the partial effects will be computed)

. flex y i.x1 x2, ul(50) margins(x1 x2)

flex estimation of the model with two shape parameters)

. flex y x1 x2, ul(50) ext

Test the validity of the one-parameter model)

. test [delta]_cons==1

Saved results

The output saved in e() by flex depends on whether or not the option margins is used. By default margins
is not used and the output saved in e() is essentially the same that is saved by ml. Some of the more relevant
results are listed below and more details can be seen in maximize. When the option margins is used the output saved
in e() is the same that is saved by margins; again, some of the more relevant results are listed below
and more details can be seen in margins.

By default, the output saved in e() includes:

Scalars

e(N) number of observations

e(ic) number of iterations

e(k) number of parameters

e(converged) 1 if converged, 0 otherwise

e(rc) return code

e(ll) log likelihood

e(r2) R-squared, computed as the square of the correlation between the dependent variable and its fitted values

e(N_clust) number of clusters

e(k_eq) number of equations in e(b)

e(k_dv) number of dependent variables

e(df_m) model degrees of freedom

Macros

e(depvar) name of dependent variable

e(cmd) ml

e(predict) program used to implement predict

e(vce) vcetype specified in vce()

e(vcetype) title used to label Std. Err.

e(clustvar) name of cluster variable

e(which) max or min; whether optimizer is to perform
maximization or minimization

e(ml_method) type of ml method

e(user) name of likelihood-evaluator program

e(technique) maximization technique

e(singularHmethod) m-marquardt or hybrid; method used
when Hessian is singular

e(properties) b V

Matrices

e(b) coefficient vector

e(V) variance-covariance matrix of the estimators

e(ilog) iteration log (up to 20 iterations)

e(gradient) gradient vector

e(V_modelbased) model-based variance

Functions

e(sample) marks estimation sample

When the option margins is used, the output saved in e() includes:

Scalars

e(N) number of observations

Macros

e(cmd) margins

e(model_vce) vcetype from estimation command

e(model_vcetype) Std. Err. title from estimation command

e(vce) vcetype specified in vce()

e(vcetype) title used to label Std. Err.

e(expression) prediction expression

e(properties) b V

Matrices

e(b) estimates

e(V) variance-covariance matrix of the estimates

e(_N) sample size corresponding to each margin estimate

Functions

e(sample) marks estimation sample

References

Santos Silva, J.M.C. and Tenreyro, Silvana (2010), "On the Existence of the Maximum Likelihood Estimates in Poisson Regression," Economics Letters,
107(2), pp. 310-312.

Santos Silva, J.M.C., Tenreyro, S., and Wei, K. (2012),
"Estimating the Extensive Margin of Trade,"
Journal of International Economics, 93(1), pp. 67-75.

Papke, L.E. and Wooldridge, J.M. (1996), "Econometric Methods for Fractional Response Variables with an Application to 401(k) Plan Participation Rates,"
Journal of Applied Econometrics, 11, 619-632.

Also see

Manual: [R] ml

Last modified on 28 August 2013