*! version 1.0.0 18nov2017

Title

[sae] sim lmm -- simulate sae data with linear mixed model

Syntax

sae sim lmm depvar indepvars [if] [in] [weight] , area(varname numeric) varest(string)
eta(string) epsilon(string) uniqid(varname numeric)
[zvar(varlist) yhat(varlist) yhat2(varlist) vce(string)
psu(varname numeric) matin(string)
pwcensus(string) rep(integer 1) seed(integer 123456789) bootstrap ebest
colprocess(integer 1) lny addvars(string) ydump(string) plinevar(varname numeric)
plines(numlist sort) aggids(numlist sort) indicators(string) results(string) allmata]

Description

This sae sim lmm export is useful for bringing in the simulated vectors created by sae into Stata.
It provides the user the ability to further manipulate these vectors. Due to the unique structure of the Mata data, this command will only
work with data created in the simulation stage.

Options

Required

area(varname numeric): The area option is necessary and specifies at which level the clustering is done, it indicates
at which level the eta_c is obtained at. The only constraint is that the variable must be numeric and
should match across datasets, although it is recommended it follows a hierarchical structure similar to
the one proposed by Zhao (2006).

Note: The hierarchical id should be of the same length for all observations, for example: AAMMEEE. In the case this were done for a specific country, AA stands for the highest aggregation level, MM stands for the second
highest aggregation level, and EEE, stands for the lowest aggregation level.

varest(string): The varest option allows the user to select between H3 or ELL methods for obtaining the
variance of the decomposed first stage residuals. The selection has repercussions on the options available
afterwards. For example, if the the user selects H3, parameters must be obtained via bootstrapping.

eta(string): The eta option allows users to specify how they would like to draw eta_c for the different clusters
in the second stage of the analysis. The available options are normal and non-normal. If non-normal is chosen empirical Bayes is not available to users.

epsilon(string): The epsilon option allows users to specify how they would like to draw epsilon_ch for the
different observations in the second stage of the analysis. The available options are normal and nonnormal. If non-normal is chosen empirical Bayes is not available to users.

uniqid(varname numeric): The uniqid option specifies the numeric variable that indicates the unique identifiers in
the source and target dataset. This is necessary to ensure replicability of the analysis.

Optional

vce(string): The vce option allows users to replicate the variance covariance matrix from the OLS in the
PovMap 2.5 software. The default option is the variance covariance matrix from the PovMap software,
vce(ell), the user may specify robust or clustered variance covariance matrix to replicate the results
from the regress command.

zvar(varlist): The zvar option is necessary for specifying the alpha model, the user must place the independent
variables under the option

yhat(varlist): The yhat option is also a part of the alpha model. Variables listed here will be interacted
with the predicted y_hat = X*beta from the OLS model.

yhat2(varlist): The yhat2 option is also a part of the alpha model. Variables listed here will be interacted
with the predicted y2_hat = (X*beta)^2 from the OLS model.

psu(varname numeric): The psu option indicates the numeric variable in the source data for the level at which bootstrapped
samples are to be obtained. This option is required for the cases when obtaining bootstrapped
parameters is necessary. If not specified, the level defaults to the cluster level, that is the level specified
in the area option.

matin(string): The matin option indicates the path and filename of the Mata format target dataset. The
dataset is created from the sae data import command; it is necessary for the second stage.

pwcensus(string): The pwcensus option indicates the variable which corresponds to the expansion factors
to be used in the target dataset, it must always be specified for the second stage. The user must have
added the variable to the imported data (sae data import) i.e. the target data.

rep(integer 1): The rep option is necessary for the second stage, and indicates the number of Monte-Carlo
simulations to be done in the second stage of the procedure.

seed(integer 123456789): The seed option is necessary for the second stage of the analysis and ensures replicability.
Users should be aware that Stata’s default pseudo-random number generator in Stata 14 is different
than that of previous versions.

bootstrap: The bootstrap option indicates that the parameters used for the second stage of the
analysis are to be obtained via bootstrap methods. If this option is not specified the default method
is parametric drawing of the parameters.

ebest: The ebest option indicates that empirical Bayes methods are to be used for the second
stage. If this option is used, it is necessary that eta(normal), epsilon(normal), and bootsrap
options be used.

colprocess(integer 1): The colprocess option is related to the processing of the second stage. Because of
the potential large size of the target data set the default is one column at a time, this however may be
increased with potential gains in speed.

lny: The lny option indicates that the dependent variable in the welfare model is in log form. This
is relevant for the second stage of the analysis in order to get appropriate simulated values.

addvars(string): The addvars option allows users to add variables to the dataset created from the simulations.
These variables must have been included into the target dataset created with the sae data
import command.

ydump(string): The ydump option is necessary for the second stage of the analysis. The user must provide
path and filename for a Mata format dataset to be created with the simulated dependent variables.

plinevar(varname numeric): The plinevar option allows users to indicate a variable in the target data set which is
to be used as the threshold for the Foster Greer Thorbeck indexes (Foster, Greer, and Thorbeck 1984)
to be predicted from the second stage simulations. The user must have added the variable in the sae
data import command when preparing the target dataset. Only one variable may be specified.

plines(numlist sort): The plines option allows users to explicitly indicate the threshold to be used, this option
is preferred when the threshold is constant across all observations. Additionally, it is possible to specify
multiple lines, separated by a space.

indicators(string): The indicators option is used to request the indicators to be estimated from the
simulated vectors of welfare. The list of possible indicators is:
– The set of Foster Greer Thorbeck indexes (Foster, Greer, and Thorbeck 1984) FGT0, FGT1, and
FGT2 ; also known as poverty head count, poverty gap, and poverty severity respectively.
– The set of inequality indexes: Gini, and Generalized Entropy Index with alpha = 0, 1, 2
– Set of Atkinson indexes

aggids(numlist sort): The aggids option indicates the different aggregation levels for which the indicators are
to be obtained, values placed here tell the command how many digits to the left to move to get the
indicators at that level. Using the same hierarchical id specified in the area option, AAMMEEE, if
the user specifies 0, 3, 5, and 7 would lead to aggregates at the each of the levels E, M, A and the
national level.

results(string): The results option specifies the path and filename for users to save as a txt file the
results the analysis specified in the indicators option.

allmata: The allmata option skips use of the plugin and does all poverty calculations in Mata.

Saved Results

sae sim returns results in e() format. By typing return list, the following results are reported:

Scalars

e(cmdline) the code line used in the session

Examples

Due to the unique structure of the Mata data, this command will only work with data created in the simulation stage.

References

Bedi, T., A. Coudouel, and K. Simler (2007). More than a pretty picture: using poverty maps to design
better policies and interventions. World Bank Publications.

Demombynes, G., C. Elbers, J. O. Lanjouw, and P. Lanjouw (2008). How good is a map? putting small
area estimation to the test. Rivista Internazionale di Scienze Sociali, 465–494.

Elbers, C., J. O. Lanjouw, and P. Lanjouw (2002). Micro-level estimation of welfare. 2911.

Elbers, C., J. O. Lanjouw, and P. Lanjouw (2003). Micro–level estimation of poverty and inequality. Econometrica
71 (1), 355–364.

Foster, J., J. Greer, and E. Thorbecke (1984). A class of decomposable poverty measures. Econometrica:
Journal of the Econometric Society, 761–766.

Harvey, A. C. (1976). Estimating regression models with multiplicative heteroscedasticity. Econometrica:
Journal of the Econometric Society, 461–465.

Haslett, S., M. Isidro, and G. Jones (2010). Comparison of survey regression techniques in the context of
small area estimation of poverty. Survey Methodology 36 (2), 157–170.

Henderson, C. R. (1953). Estimation of variance and covariance components. Biometrics 9 (2), 226–252.

Huang, R. and M. Hidiroglou (2003). Design consistent estimators for a mixed linear model on survey data.

Proceedings of the Survey Research Methods Section, American Statistical Association (2003), 1897–1904.

Molina, I. and J. Rao (2010). Small area estimation of poverty indicators. Canadian Journal of Statistics
38 (3), 369–385.

Rao, J. N. and I. Molina (2015). Small area estimation. John Wiley & Sons.

Tarozzi, A. and A. Deaton (2009). Using census and survey data to estimate poverty and inequality for
small areas. The review of economics and statistics 91 (4), 773–792.

Van der Weide, R. (2014). GLS estimation and empirical bayes prediction for linear mixed models with
heteroskedasticity and sampling weights: a background study for the povmap project. World Bank Policy
Research Working Paper (7028).

Zhao, Q. (2006). User manual for povmap. World Bank. http://siteresources.worldbank.org/INTPGI/
Resources/342674-1092157888460/Zhao_ManualPovMap.pdf .

Authors

Minh Cong Nguyen, mnguyen3@worldbank.org

Paul Andres Corral Rodas, pcorralrodas@worldbank.org

Joao Pedro Azevedo, jazevedo@worldbank.org

Qinghua Zhao, qzhao@worldbank.org

World Bank

Thanks for citing sae as follows

sae is a user-written program that is freely distributed to the research community.

Please use the following citation:

World Bank. (2017). “Small Area Estimation: An extended ELL approach.”. World Bank.

Acknowledgements

We would like to thank all the users for their comments during the initial development of the codes.
All errors and ommissions are exclusively our responsibility.