NSconvo_fit {convoSPAT}

Fit the nonstationary spatial model

Description

NSconvo_fit estimates the parameters of the nonstationary convolution-based spatial model. Required inputs are the observed data and locations. Optional inputs include mixture component locations (if not provided, the number of mixture component locations are required), the fit radius, the covariance model (exponential is the default), and whether or not the nugget and process variance will be spatially-varying.

Usage

NSconvo_fit(
  sp.SPDF = NULL,
  coords = NULL,
  data = NULL,
  cov.model = "exponential",
  mean.model = data ~ 1,
  mc.locations = NULL,
  N.mc = NULL,
  lambda.w = NULL,
  fixed.nugg2.var = NULL,
  mean.model.df = NULL,
  mc.kernels = NULL,
  fit.radius = NULL,
  ns.nugget = FALSE,
  ns.variance = FALSE,
  ns.mean = FALSE,
  local.aniso = TRUE,
  fix.tausq = FALSE,
  tausq = 0,
  fix.kappa = FALSE,
  kappa = 0.5,
  method = "reml",
  print.progress = TRUE,
  local.pars.LB = NULL,
  local.pars.UB = NULL,
  global.pars.LB = NULL,
  global.pars.UB = NULL,
  local.ini.pars = NULL,
  global.ini.pars = NULL
)

Arguments

sp.SPDF

A "SpatialPointsDataFrame" object, which contains the spatial coordinates and additional attribute variables corresponding to the spatoal coordinates

coords

An N x 2 matrix where each row has the two-dimensional coordinates of the N data locations.

data

A vector or matrix with N rows, containing the data values. Inputting a vector corresponds to a single replicate of data, while inputting a matrix corresponds to replicates. In the case of replicates, the model assumes the replicates are independent and identically distributed.

cov.model

A string specifying the model for the correlation function; defaults to "exponential". Options available in this package are: "exponential", "matern", and "gaussian".

mean.model

An object of class formula, specifying the mean model to be used. Defaults to an intercept only.

mc.locations

Optional; matrix of mixture component locations.

N.mc

Optional; if mc.locations is not specified, the function will create a rectangular grid of size N.mc over the spatial domain.

lambda.w

Scalar; tuning parameter for the weight function. Defaults to be the square of one-half of the minimum distance between mixture component locations.

fixed.nugg2.var

Optional; describes the variance/covariance for a fixed (second) nugget term (represents a known error term). Either a vector of length N containing a station-specific variances (implying independent error) or an NxN covariance matrix (implying dependent error). Defaults to zero.

mean.model.df

Optional data frame; refers to the variables used in mean.model. Important when using categorical variables in mean.model, as a subset of the full design matrix will likely be rank deficient. Specifying mean.model.df allows NSconvo_fit to calculate a design matrix specific to the points used to fit each local model.

mc.kernels

Optional specification of mixture component kernel matrices (based on expert opinion, etc.).

fit.radius

Scalar; specifies the fit radius or neighborhood size for the local likelihood estimation.

ns.nugget

Logical; indicates if the nugget variance (tausq) should be spatially-varying (TRUE) or constant (FALSE).

ns.variance

Logical; indicates if the process variance (sigmasq) should be spatially-varying (TRUE) or constant (FALSE).

ns.mean

Logical; indicates if the mean coefficeints (beta) should be spatially-varying (TRUE) or constant (FALSE).

local.aniso

Logical; indicates if the local covariance should be anisotropic (TRUE) or isotropic (FALSE). Defaults to TRUE. In the case of a locally isotropic model, the bounds and initial values for lam will default to the first element of local.pars.LB, local.pars.UB, and local.ini.pars (while still required, the second and third elements of these vectors will be ignored.)

fix.tausq

Logical; indicates whether the default nugget term (tau^2) should be fixed (TRUE) or estimated (FALSE). Defaults to FALSE.

tausq

Scalar; fixed value for the nugget variance (when fix.tausq = TRUE).

fix.kappa

Logical; indicates if the kappa parameter should be fixed (TRUE) or estimated (FALSE). Defaults to FALSE (only valid for cov.model = "matern" and cov.model = "cauchy").

kappa

Scalar; value of the kappa parameter. Only used if fix.kappa = TRUE.

method

Indicates the estimation method, either maximum likelihood ("ml") or restricted maximum likelihood ("reml").

print.progress

Logical; if TRUE, text indicating the progress of local model fitting in real time.

local.pars.LB, local.pars.UB

Optional vectors of lower and upper bounds, respectively, used by the "L-BFGS-B" method option in the optim function for the local parameter estimation. Each vector must be of length five, containing values for lam1, lam2, tausq, sigmasq, and nu. Default for local.pars.LB is rep(1e-05,5); default for local.pars.UB is c(max.distance/2, max.distance/2, 4*resid.var, 4*resid.var, 100), where max.distance is the maximum interpoint distance of the observed data and resid.var is the residual variance from using lm with mean.model.

global.pars.LB, global.pars.UB

Optional vectors of lower and upper bounds, respectively, used by the "L-BFGS-B" method option in the optim function for the global parameter estimation. Each vector must be of length three, containing values for tausq, sigmasq, and nu. Default for global.pars.LB is rep(1e-05,3); default for global.pars.UB is c(4*resid.var, 4*resid.var, 100), where resid.var is the residual variance from using lm with mean.model.

local.ini.pars

Optional vector of initial values used by the "L-BFGS-B" method option in the optim function for the local parameter estimation. The vector must be of length five, containing values for lam1, lam2, tausq, sigmasq, and nu. Defaults to c(max.distance/10, max.distance/10, 0.1*resid.var, 0.9*resid.var, 1), where max.distance is the maximum interpoint distance of the observed data and resid.var is the residual variance from using lm with mean.model.

global.ini.pars

Optional vector of initial values used by the "L-BFGS-B" method option in the optim function for the global parameter estimation. The vector must be of length three, containing values for tausq, sigmasq, and nu. Defaults to c(0.1*resid.var, 0.9*resid.var, 1), where resid.var is the residual variance from using lm with mean.model.

Value

A "NSconvo" object, with the following components:

mc.locations

Mixture component locations used for the simulated data.

mc.kernels

Mixture component kernel matrices used for the simulated data.

MLEs.save

Table of local maximum likelihood estimates for each mixture component location.

kernel.ellipses

N.obs x 2 x 2 array, containing the kernel matrices corresponding to each of the simulated values.

data

Observed data values.

beta.GLS

Generalized least squares estimates of beta, the mean coefficients. For ns.mean = FALSE, this is a vector (containing the global mean coefficients); for ns.mean = TRUE, this is a matrix (one column for each mixture component location).

beta.cov

Covariance matrix of the generalized least squares estimate of beta. For ns.mean = FALSE, this is a matrix (containing the covariance of theglobal mean coefficients); for ns.mean = TRUE, this is an array (one matrix for each mixture component location).

Mean.coefs

"Regression table" for the mean coefficient estimates, listing the estimate, standard error, and t-value (for ns.mean = FALSE only).

tausq.est

Estimate of tausq (nugget variance), either scalar (when ns.nugget = "FALSE") or a vector of length N (when ns.nugget = "TRUE"), which contains the estimated nugget variance for each observation location.

sigmasq.est

Estimate of sigmasq (process variance), either scalar (when ns.variance = "FALSE") or a vector of length N (when ns.variance = "TRUE"), which contains the estimated process variance for each observation location.

beta.est

Estimate of beta (mean coefficients), either a vector (when ns.mean = "FALSE") or a matrix with N rows (when ns.mean = "TRUE"), each row of which contains the estimated (smoothed) mean coefficients for each observation location.

kappa.MLE

Scalar maximum likelihood estimate for kappa (when applicable).

Cov.mat

Estimated covariance matrix (N.obs x N.obs) using all relevant parameter estimates.

Cov.mat.chol

Cholesky of Cov.mat (i.e., chol(Cov.mat)), the estimated covariance matrix (N.obs x N.obs).

cov.model

String; the correlation model used for estimation.

ns.nugget

Logical, indicating if the nugget variance was estimated as spatially-varing (TRUE) or constant (FALSE).

ns.variance

Logical, indicating if the process variance was estimated as spatially-varying (TRUE) or constant (FALSE).

fixed.nugg2.var

N x N matrix with the fixed variance/covariance for the second (measurement error) nugget term (defaults to zero).

coords

N x 2 matrix of observation locations.

global.loglik

Scalar value of the maximized likelihood from the global optimization (if available).

Xmat

Design matrix, obtained from using lm with mean.model.

lambda.w

Tuning parameter for the weight function.

fix.kappa

Logical, indicating if kappa was fixed (TRUE) or estimated (FALSE).

kappa

Scalar; fixed value of kappa.

Examples

## Not run: 
# Using white noise data
fit.model <- NSconvo_fit( coords = cbind( runif(100), runif(100)),
data = rnorm(100), fit.radius = 0.4, N.mc = 4 )

## End(Not run)