excursions is one of the main functions in the package with the same name.
The function is used for calculating excursion sets, contour credible regions,
and contour avoiding sets for latent Gaussian models. Details on the function and the
package are given in the sections below.
excursions(alpha, u, mu, Q, type, n.iter = 10000, Q.chol, F.limit, vars, rho,
reo, method = "EB", ind, max.size, verbose = 0, max.threads = 0, seed)Error probability for the excursion set.
Excursion or contour level.
Expectation vector.
Precision matrix.
Type of region:
'>' positive excursion region
'<' negative excursion region
'!=' contour avoiding region
'=' contour credibility region
Number or iterations in the MC sampler that is used for approximating probabilities. The default value is 10000.
The Cholesky factor of the precision matrix (optional).
The limit value for the computation of the F function. F is set to NA for all nodes where F<1-F.limit. Default is F.limit = alpha.
Precomputed marginal variances (optional).
Marginal excursion probabilities (optional). For contour regions, provide \(P(X>u)\).
Reordering (optional).
Method for handeling the latent Gaussian structure:
'EB' Empirical Bayes (default)
'QC' Quantile correction, rho must be provided if QC is used.
Indices of the nodes that should be analysed (optional).
Maximum number of nodes to include in the set of interest (optional).
Set to TRUE for verbose mode (optional).
Decides the number of threads the program can use. Set to 0 for using the maximum number of threads allowed by the system (default).
Random seed (optional).
excursions returns an object of class "excurobj". This is a list that contains the following arguments:
Excursion set, contour credible region, or contour avoiding set
Contour map set. \(G=1\) for all nodes where the \(mu > u\).
Contour avoiding set. \(M=-1\) for all non-significant nodes. \(M=0\) for nodes where the process is significantly below u and \(M=1\) for all nodes where the field is significantly above u. Which values that should be present depends on what type of set that is calculated.
The excursion function corresponding to the set E calculated or values up to F.limit
Marginal excursion probabilities
The mean mu.
Marginal variances.
A list containing various information about the calculation.
excursions contains functions that compute probabilistic excursion sets,
contour credibility regions, contour avoiding regions, contour map quality measures,
and simultaneous confidence bands for latent Gaussian
random processes and fields.
Excursion sets, contour credibility regions, and contour avoiding regions
The main functions for computing excursion sets, contour credibility regions, and contour avoiding regions are
excursions The main function for Gaussian models.
excursions.inla Interface for latent Gaussian models estimated using INLA.
excursions.mc Function for analyzing models that have been
estimated using Monte Carlo methods.
The output from the functions above provides a discrete domain estimate of the regions.
Based on this estimate, the function continuous computes a continuous
domain estimate.
The main reference for these functions is Bolin, D. and Lindgren, F. (2015) Excursion and contour uncertainty regions for latent Gaussian models, JRSS-series B, vol 77, no 1, pp 85-106.
Contour map quality measures
The package provides several functions for computing contour maps and their quality measures. These quality measures can be used to decide on an appropriate number of contours to use for the contour map.
The main functions for computing contour maps and the corresponding quality measures are
contourmap The main function for Gaussian models.
contourmap.inla Interface for latent Gaussian models estimated
using INLA.
contourmap.mc Function for analyzing models that have been
estimated using Monte Carlo methods.
Other noteworthy functions relating to contourmaps are tricontour and
tricontourmap, which compute contour curves for functinos defined on
triangulations, as well as contourmap.colors which can be used to
compute appropriate colors for displaying contour maps.
The main reference for these functions is Bolin, D. and Lindgren, F. (2017) Quantifying the uncertainty of contour maps, Journal of Computational and Graphical Statistics, 26:3, 513-524.
Simultaneous confidence bands
The main functions for computing simultaneous confidence bands are
simconf.inla Function for analyzing latent Gaussian models
estimated using INLA.
simconf.mc Function for analyzing models estimated using Monte
Carlo methods.
simconf.mixture Function for analyzing Gaussian mixture models.
The main reference for these functions is Bolin et al. (2015) Statistical prediction of global sea level from global temperature, Statistica Sinica, Vol 25, pp 351-367.
The estimation of the region is done using sequential importance sampling with
n.iter samples. The procedure requires computing the marginal variances of
the field, which should be supplied if available. If not, they are computed using
the Cholesky factor of the precision matrix. The cost of this step can therefore be
reduced by supplying the Cholesky factor if it is available.
The latent structure in the latent Gaussian model can be handled in several different
ways. The default strategy is the EB method, which is
exact for problems with Gaussian posterior distributions. For problems with
non-Gaussian posteriors, the QC method can be used for improved results. In order to use
the QC method, the true marginal excursion probabilities must be supplied using the
argument rho.
Other more
complicated methods for handling non-Gaussian posteriors must be implemented manually
unless INLA is used to fit the model. If the model is fitted using INLA,
the method excursions.inla can be used. See the Package section for further details
about the different options.
Bolin, D. and Lindgren, F. (2015) Excursion and contour uncertainty regions for latent Gaussian models, JRSS-series B, vol 77, no 1, pp 85-106.
# NOT RUN {
## Create a tridiagonal precision matrix
n = 21
Q.x = sparseMatrix(i=c(1:n, 2:n), j=c(1:n, 1:(n-1)), x=c(rep(1, n), rep(-0.1, n-1)),
dims=c(n, n), symmetric=TRUE)
## Set the mean value function
mu.x = seq(-5, 5, length=n)
## calculate the level 0 positive excursion function
res.x = excursions(alpha=1, u=0, mu=mu.x, Q=Q.x,
type='>', verbose=1, max.threads=2)
## Plot the excursion function and the marginal excursion probabilities
plot(res.x$F, type="l",
main='Excursion function (black) and marginal probabilites (red)')
lines(res.x$rho, col=2)
# }
Run the code above in your browser using DataLab