eblupSTFH: EBLUPs based on a spatio-temporal Fay-Herriot model.
In sae: Small Area Estimation

Description Usage Arguments Details Value Author(s) References See Also Examples

Fits a spatio-temporal Fay-Herriot model with area effects following a SAR(1) process and with either uncorrelated or AR(1) time effects.

eblupSTFH(formula, D, T, vardir, proxmat, model = "ST", MAXITER = 100, 
          PRECISION = 0.0001, theta_iter = FALSE,
          sigma21_start = 0.5 * median(vardir), rho1_start = 0.5, 
          sigma22_start = 0.5 * median(vardir), rho2_start = 0.5, 
          data)

`formula`	an object of class `formula` (or one that can be coerced to that class): a symbolic description of the model to be fitted. The variables included in `formula` must have a length equal to `D*T` and sorted in the ascending order by the time instant within each domain. Details of model specification are given under Details.
`D`	total number of domains.
`T`	total number of time instants (constant for all domains).
`vardir`	vector containing the `D*T` sampling variances of direct estimators for each domain and time instant. The values must be sorted as the variables in `formula`.
`proxmat`	`D*D` proximity matrix or data frame with values in the interval `[0,1]` containing the proximities between the row and column domains. The rows add up to 1. The rows and columns of this matrix must be sorted by domain as the variables in `formula`.
`model`	type of model to be chosen between `"ST"` (AR(1) time-effects within each domain) or `"S"` (uncorrelated time effects within each domain). Default model is "ST".
`MAXITER`	maximum number of iterations allowed for the Fisher-scoring algorithm. Default value is `100`.
`PRECISION`	convergence tolerance limit for the Fisher-scoring algorithm. Default value is `0.0001`.
`theta_iter`	If `TRUE` the estimated values of area effects variance, area effects spatial autocorrelation, area-time effects variance and time autocorrelation parameter of the area-time effects of each iteration of the fitting algorithm are returned in `estvarcomp_iterations` variable.
`sigma21_start`	Starting value of the area effects variance in the fitting algorithm. Default value is `0.5*median(vardir)`.
`rho1_start`	Starting value of the area effects spatial autocorrelation parameter in the fitting algorithm. Default value is `0.5`.
`sigma22_start`	Starting value of the area-time effects variance in the fitting algorithm. Default value is `0.5*median(vardir)`.
`rho2_start`	Starting value of the time autocorrelation parameter of the area-time effects in the fitting algorithm. Default value is `0.5`.
`data`	optional data frame containing the variables named in `formula` and `vardir`. By default the variables are taken from the environment from which `eblupSTFH` is called.

A typical model has the form response ~ terms where response is the (numeric) response vector and terms is a series of terms which specifies a linear predictor for response. A terms specification of the form first + second indicates all the terms in first together with all the terms in second with duplicates removed.

A formula has an implied intercept term. To remove this use either y ~ x - 1 or y ~ 0 + x. See formula for more details of allowed formulae.

The function returns a list with the following objects:

eblup

a column vector with length D*T with the values of the estimators for the D domains and T time instants.

fit

a list containing the following objects:

model: type of model "S" or "ST".
convergence: a logical value equal to TRUE if Fisher-scoring algorithm converges in less than MAXITER iterations.
iterations: number of iterations performed by the Fisher-scoring algorithm.
estcoef: a data frame with the estimated model coefficients in the first column (beta), their asymptotic standard errors in the second column (std.error), the t statistics in the third column (tvalue) and the p-values of the significance of each coefficient in last column (pvalue).
estvarcomp: a data frame with the estimated values of the variances and correlation coefficients in the first column (estimate) and their asymptotic standard errors in the second column (std.error).
estvarcomp_iterations: if theta_iter=TRUE, this component contains a data frame with the estimated values of the variances and correlation coefficients obtained for each iteration of the fitting algorithm.
goodness: vector containing three goodness-of-fit measures: loglikehood, AIC and BIC.

In case that formula, vardir or proxmat contain NA values a message is printed and no action is done.

Yolanda Marhuenda, Isabel Molina and Domingo Morales.

- Small Area Methods for Poverty and Living Conditions Estimates (SAMPLE), funded by European Commission, Collaborative Project 217565, Call identifier FP7-SSH-2007-1.

- Marhuenda, Y., Molina, I. and Morales, D. (2013). Small area estimation with spatio-temporal Fay-Herriot models. Computational Statistics and Data Analysis 58, 308-325.

pbmseSTFH

data(spacetime)      # Load data set 
data(spacetimeprox)  # Load proximity matrix 

D <- nrow(spacetimeprox)            # number of domains
T <- length(unique(spacetime$Time)) # number of time instant

# Fit model S with uncorrelated time effects for each domain
resultS <- eblupSTFH(Y ~ X1 + X2, D, T, Var, spacetimeprox, "S",
                     theta_iter=TRUE, data=spacetime)
rowsT <- seq(T, T*D, by=T)
data.frame(Domain=spacetime$Area[rowsT], EBLUP_S=resultS$eblup[rowsT])
resultS$fit

# Fit model ST with AR(1) time effects for each domain
resultST <- eblupSTFH(Y ~ X1 + X2, D, T, Var, spacetimeprox,
                      theta_iter=TRUE, data=spacetime)
data.frame(Domain=spacetime$Area[rowsT], EBLUP_ST=resultS$eblup[rowsT])
resultST$fit