eco (version 3.0-1)

ecoML: Fitting Parametric Models and Quantifying Missing Information for Ecological Inference in 2x2 Tables

Description

ecoML is used to fit parametric models for ecological inference in $2 \times 2$ tables via Expectation Maximization (EM) algorithms. It gives the point estimates of the parameters for models based on different assumptions. The standard errors of the point estimates are also computed via Supplemented EM algorithms. Moreover, ecoML quantifies the amount of missing information associated with each parameter and allows researcher to examine the impact of missing information on parameter estimation in ecological inference. The models and algorithms are described in Imai, Lu and Strauss(2006).

Usage

ecoML(formula, data = parent.frame(), N = NULL, supplement = NULL, 
         theta.start = c(0,0,1,1,0), fix.rho = FALSE,
         context = FALSE, sem = TRUE, epsilon = 10^(-10), 
     maxit = 1000, loglik = TRUE, hyptest = FALSE, verbose = TRUE)

Arguments

formula

A symbolic description of the model to be fit, specifying the column and row margins of $2 \times 2$ ecological tables. Y ~ X specifies Y as the column margin and X as the row margin. Details and specif

data

An optional data frame in which to interpret the variables in formula. The default is the environment in which ecoML is called.

N

An optional variable representing the size of the unit; e.g., the total number of voters.

supplement

An optional matrix of supplemental data. The matrix has two columns, which contain additional individual-level data such as survey data for $W_1$ and $W_2$, respectively. If NULL, no additional individual-level data are included

fix.rho

Logical. If TRUE, the correlation (when context=TRUE) or the partial correlation (when context=FALSE) between $W_1$ and $W_2$ is fixed through the estimation. For details, see Imai, Lu and Strauss(2

context

Logical. If TRUE, the contextual effect is also modeled. See Imai, Lu and Strauss (2006) for details. The default is FALSE.

sem

Logical. If TRUE, the standard errors of parameter estimates are estimated via SEM algorithm. The default is TRUE.

theta.start

A numeric vector that specifies the starting values for the mean, variance, and covariance. When context = FALSE, the elements of theta.start correspond to ($E(W_1)$, $E(W_2)$, $var(W_1)$, $var(W_2)$, $cor(W_1,W_2

epsilon

A positive number that specifies the convergence criterion for EM algorithm. The square root of epsilon is the convergence criterion for SEM algorithm. The default is 10^(-10).

maxit

A positive integer specifies the maximum number of iterations before the convergence criterion is met. The default is 1000.

loglik

Logical. If TRUE, the value of the log-likelihood function at each iteration of EM is saved. The default is TRUE.

hyptest

Logical. If TRUE, model is estimated under the null hypothesis that mean of $W1$ and $W2$ is the same. The default is FALSE.

verbose

Logical. If TRUE, the progress of the EM and SEM algorithms is printed to the screen. The default is FALSE.

Value

• An object of class ecoML containing the following elements:
• call
  The matched call.
• X
  The row margin, $X$.
• Y
  The column margin, $Y$.
• N
  The size of each table, $N$.
• context
  The assumption under which model is estimated. If context = FALSE, CAR assumption is adopted and no contextual effect is modeled. If context = TRUE, NCAR assumption is adopted, and contextual effect is modeled.
• sem
  Whether SEM algorithm is used to estimate the standard errors and observed information matrix for the parameter estimates.
• fix.rho
  Whether the correlation or the partial correlation between $W_1$ an $W_2$ is fixed in the estimation.
• r12
  If fix.rho = TRUE, the value that $corr(W_1, W_2)$ is fixed to.
• epsilon
  The precision criterion for EM convergence. $\sqrt{\epsilon}$ is the precision criterion for SEM convergence.
• theta.sem
  The ML estimates of $E(W_1)$,$E(W_2)$, $var(W_1)$,$var(W_2)$, and $cov(W_1,W_2)$. If context = TRUE, $E(X)$,$cov(W_1,X)$, $cov(W_2,X)$ are also reported.
• W
  In-sample estimation of $W_1$ and $W_2$.
• suff.stat
  The sufficient statistics for theta.em.
• iters.em
  Number of EM iterations before convergence is achieved.
• iters.sem
  Number of SEM iterations before convergence is achieved.
• loglik
  The log-likelihood of the model when convergence is achieved.
• loglik.log.em
  A vector saving the value of the log-likelihood function at each iteration of the EM algorithm.
• mu.log.em
  A matrix saving the mean estimation at each iteration of EM.
• Sigma.log.em
  A matrix saving the variance-covariance estimation at each iteration of EM.
• Moreover, when sem=TRUE, ecoML also output the following values:
• DM
  The matrix characterizing the rates of convergence of the EM algorithms. Such information is also used to calculate the observed-data information matrix
• Icom
  The (expected) complete data information matrix estimated via SEM algorithm. When context=FALSE, fix.rho=TRUE, Icom is 4 by 4. When context=FALSE, fix.rho=FALSE, Icom is 5 by 5. When context=TRUE, Icom is 9 by 9.
• Iobs
  The observed information matrix. The dimension of Iobs is same as Icom.
• Imiss
  The difference between Icom and Iobs. The dimension of Imiss is same as miss.
• Vobs
  The (symmetrized) variance-covariance matrix of the ML parameter estimates. The dimension of Vobs is same as Icom.
• Iobs
  The (expected) complete-data variance-covariance matrix. The dimension of Iobs is same as Icom.
• Vobs.original
  The estimated variance-covariance matrix of the ML parameter estimates. The dimension of Vobs is same as Icom.
• Fmis
  The fraction of missing information associated with each parameter estimation.
• VFmis
  The proportion of increased variance associated with each parameter estimation due to observed data.
• Ieigen
  The largest eigen value of Imiss.
• DM
  The rate-of-convergence matrix of the SEM algorithm.
• Icom.trans
  The complete data information matrix for the fisher transformed parameters.
• Iobs.trans
  The observed data information matrix for the fisher transformed parameters.
• Fmis.trans
  The fractions of missing information associated with the fisher transformed parameters.

Details

When SEM is TRUE, ecoML computes the observed-data information matrix for the parameters of interest based on Supplemented-EM algorithm. The inverse of the observed-data information matrix can be used to estimate the variance-covariance matrix for the parameters estimated from EM algorithms. In addition, it also computes the expected complete-data information matrix. Based on these two measures, one can further calculate the fraction of missing information associated with each parameter. See Imai, Lu and Strauss (2006) for more details about fraction of missing information. Moreover, when hytest=TRUE, ecoML allows to estimate the parametric model under the null hypothesis that mu_1=mu_2. One can then construct the likelihood ratio test to assess the hypothesis of equal means. The associated fraction of missing information for the test statistic can be also calculated. For details, see Imai, Lu and Strauss (2006) for details.

References

Imai, Kosuke, Ying Lu and Aaron Strauss. (2006) Bayesian and Likelihood Inference for 2 x 2 Ecological Tables: An Incomplete Data Approach Technical Report, Princeton University, available at http://imai.princeton.edu/research/eiall.html

See Also

eco, ecoNP, summary.ecoML

Examples

## load the census data
data(census)

## NOTE: convergence has not been properly assessed for the following
## examples. See Imai, Lu and Strauss (2006) for more complete analyses.
## In the first example below, in the interest of time, only part of the
## data set is analyzed and the convergence requirement is less stringent
## than the default setting.

## In the second example, the program is arbitrarily halted 100 iterations
## into the simulation, before convergence.

## load the Robinson's census data
data(census)

## fit the parametric model with the default model specifications
res <- ecoML(Y ~ X, data = census[1:100,],epsilon=10^(-6), verbose = TRUE)
## summarize the results
summary(res)

## obtain out-of-sample prediction
out <- predict(res, verbose = TRUE)
## summarize the results
summary(out)

## fit the parametric model with some individual 
## level data using the default prior specification
surv <- 1:600
res1 <- ecoML(Y ~ X, context = TRUE, data = census[-surv,], 
                   supplement = census[surv,c(4:5,1)], maxit=100, verbose = TRUE)
## summarize the results
summary(res1)