Fitting an underlying continuous process to areal data

Usage

fit_spm(x, ...)

# S3 method for class 'spm'
fit_spm(
  x,
  model,
  theta_st,
  nu = NULL,
  tr = NULL,
  kappa = 1,
  mu2 = 1.5,
  apply_exp = FALSE,
  opt_method = "Nelder-Mead",
  control_opt = list(),
  comp_hess = TRUE,
  ...
)

fit_spm2(
  x,
  model,
  nu,
  tr,
  kappa = 1,
  mu2 = 1.5,
  comp_hess = TRUE,
  phi_min,
  phi_max,
  nphi = 10,
  cores = getOption("mc.cores", 1L)
)

Arguments

x: an object of type spm. Note that, the dimension of theta_st depends on the 2 factors. 1) the number of variables being analyzed, and 2) if the input is a spm object.
...: additional parameters, either passed to stats::optim.
model: a character scalar indicating the family of the covariance function to be used. The options are c("matern", "pexp", "gaussian", "spherical", "gw").
theta_st: a numeric (named) vector containing the initial parameters.
nu: a numeric value indicating either the \(\nu\) parameter from the Matern covariance function (controlling the process differentiability), or the "pexp" for the Powered Exponential family. If the model chosen by the user is Matern and nu is not informed, it is automatically set to .5. On the other hand, if the user chooses the Powered Exponential family and do not inform nu, then it is set to 1. In both cases, the covariance function becomes the so called exponential covariance function.
tr: tapper range
kappa: \(\kappa \in \{0, \ldots, 3 \}\) parameter for the GW cov function.
mu2: the smoothness parameter \(\mu\) for the GW function.
apply_exp: a logical scalar indicating whether the parameters that cannot assume negative values should be exponentiate or not.
opt_method: a character scalar indicating the optimization algorithm to be used. For details, see stats::optim.
control_opt: a named list containing the control arguments for the optimization algorithm to be used. For details, see stats::optim.
comp_hess: a boolean indicating whether the Hessian matrix should be computed.
phi_min: a numeric scalar representing the minimum \(phi\) value to look for.
phi_max: a numeric scalar representing the maximum \(phi\) value to look for.
nphi: a numeric scalar indicating the number of values to compute a grid-search over \(phi\).
cores: a integer scalar indicating number of cores to be used. Default is getOption("mc.cores"). No effect on Windows.

Value

a spm_fit object containing the information about the estimation of the model parameters.

Details

This function uses the stats::optim function optimization algorithms to find the Maximum Likelihood estimators, and their standard errors, from a model adapted from. The function allows the user to input the control parameters from the stats::optim function through the argument control_opt, which is a named list. Additionally, the one can input lower and upper boundaries for the optimization problem, as well as the preferred optimization algorithm (as long as it is available for stats::optim). The preferred algorithm is selected by the argument opt_method. In addition to the control of the optimization, the user can select a covariance function among the following: Matern, Exponential, Powered Exponential, Gaussian, and Spherical. The parameter apply_exp is a logical scalar such that, if set to TRUE, the \(\exp\) function is applied to the nonnegative parameters, allowing the optimization algorithm to search for all the parameters over the real numbers.

The model assumes \deqn{Y(\mathbf{s}) = \mu + S(\mathbf{s})} at the
point level.  Where \eqn{S ~ GP(0, \sigma^2 C(\lVert \mathbf{s} -
    \mathbf{s}_2 \rVert; \theta))}.  Further, the observed data is supposed
to be \eqn{Y(B) = \lvert B \rvert^{-1} \int_{B} Y(\mathbf{s}) \,
    \textrm{d} \mathbf{s}}.

Examples


data(liv_lsoa) ## loading the LSOA data

msoa_spm <- sf_to_spm(sf_obj = liv_msoa, n_pts = 500,
                      type = "regular", by_polygon = FALSE,
                      poly_ids = "msoa11cd",
                      var_ids = "leb_est")
## fitting model
theta_st_msoa <- c("phi" = 1) # initial value for the range parameter

fit_msoa <-
   fit_spm(x = msoa_spm,
           theta_st = theta_st_msoa,
           model = "matern",
           nu = .5,
           apply_exp  = TRUE,
           opt_method = "L-BFGS-B",
           control    = list(maxit = 500))

AIC(fit_msoa)
#> [1] 295.2008

summary_spm_fit(fit_msoa, sig = .05)
#> 
#>  optimization algorithm converged: yes 
#>  
#>     par   estimate        se               ci
#> 1    mu 75.9479977 0.8112112 [74.358; 77.538]
#> 2 sigsq 23.0875619 4.1812494 [14.892; 31.283]
#> 3   phi  0.8370629 0.2183420   [0.409; 1.265]