excursions Research Resources latent Gaussian models spatial statistics applied statistics bayesian inference R-INLA Gaussian random fields excursion sets excursions: A Framework for Probabilistic Excursion Sets and Contour Inference OverviewThe R package excursions provides computational tools for joint probabilistic inference in spatial statistics, with a focus on excursion sets, contour credibility regions, and simultaneous confidence bands for latent Gaussian models. These tools allow users to identify regions where a latent field exceeds or falls below a given threshold with controlled joint probability, assess the uncertainty of level curves, and construct confidence bands over time or space. The methods are applicable in a wide range of scientific domains, including neuroimaging, environmental monitoring, spatial ecology, and climate modeling, where one often seeks to make spatially structured statements under uncertainty. The excursion set framework implemented in the package addresses the shortcomings of traditional pointwise inference by accounting for spatial dependence and controlling the joint probability of exceedance across the domain, providing global coverage guarantees.The methodology implemented in excursions is based on a sequence of theoretical contributions by Bolin and Lindgren. A framework for defining and estimating excursion sets and contour uncertainty regions under latent Gaussian models was introduced in Bolin and Lindgren (2015, Journal of the Royal Statistical Society: Series B), using parametric families of candidate sets and a sequential importance sampling algorithm to compute joint exceedance probabilities. This work was extended to the problem of contour map uncertainty and optimal selection of contour levels in Bolin and Lindgren (2017, Journal of Computational and Graphical Statistics), which introduced formal quality measures (P0, P1, and P2) for evaluating how well a set of contours represents the latent field under uncertainty. A complete description of the computational algorithms and their implementation in R is provided in Bolin and Lindgren (2018, Journal of Statistical Software).The package supports several types of inference problems for latent Gaussian models, including the computation of excursion sets, construction of contour credibility regions, and evaluation of contour map quality. Excursion sets are defined as regions where the latent process exceeds or falls below a specified level with a given joint probability, and are useful in settings where one seeks to identify spatial features with strong probabilistic guarantees. Contour credibility regions quantify the uncertainty in the location of level curves and provide statistical guarantees for contour-based interpretations. Figure 1 illustrates the fundamental structure of a contour map with K contour levels u₁ < u₂ < ... < uK. The contour curves (black lines) separate the spatial domain into level sets Gₖ = {s : uₖ < f(s) < uₖ₊₁}, which are the colored regions between consecutive contour levels. This visualization forms the basis for understanding how the excursions package quantifies contour map uncertainty. Figure 1: Contour Map Structure and Level SetsIn addition, the package includes functionality to construct and assess contour maps, using measures that evaluate how faithfully a given set of contour levels represents the underlying process.excursions is designed to be flexible in terms of input structure. It supports three main types of input: direct specification of the mean and precision matrix of a Gaussian field; posterior samples from arbitrary models, including hierarchical Bayesian models; and fitted models from R-INLA, which are handled automatically via the excursions.inla() interface. The package also integrates with inlabru, allowing for joint inference on spatial point process models such as log-Gaussian Cox processes. This makes it possible to apply excursion set methods to a wide range of spatial and spatiotemporal models.The package includes tools for visualization and post-processing. The continuous() function constructs a continuous domain estimate through spatial interpolation of the excursion field over the mesh, as described in Bolin and Lindgren (2018, Journal of Statistical Software), which enhances the visualization of excursion set boundaries. The tricontour() and tricontourmap() functions generate triangulation-based contour maps suitable for plotting and GIS applications. These tools enable high-quality representations of spatial uncertainty.A distinctive feature of excursions is its focus on contour map uncertainty. While contour maps are widely used in scientific communication, their statistical properties are often overlooked. The contourmap() function constructs contour maps and evaluates their statistical reliability through three quality measures introduced by Bolin and Lindgren (2017, Journal of Computational and Graphical Statistics). P0 quantifies the proportion of the spatial domain where the contour map statement holds with the specified probability. P1 measures the probability that all level crossings of the field fall within the union of their two adjacent contour levels. P2, the most restrictive measure, represents the joint probability that the midpoint level crossings lie within their respective individual contour bands, making it particularly useful for determining the appropriate number of contour levels. Figure 2 demonstrates how the three quality measures guide the selection of an appropriate number of contour levels. The left panel shows a model without fixed effects, where high uncertainty limits reliable representation to approximately 3 contours (P₂ ≈ 0.95). The right panel shows a model incorporating elevation as a fixed effect, where reduced uncertainty supports up to 10 contour levels while maintaining P₂ ≈ 0.95. The divergence between P₀, P₁, and P₂ as the number of contours increases reveals the increasing difficulty of maintaining joint probabilistic guarantees with denser contour spacing. This analysis demonstrates how model complexity directly affects the information that can be reliably communicated through contour maps. Figure 2: Quality Measures versus Number of Contour LevelsTogether, these measures provide rigorous probabilistic guarantees for contour-based spatial inference and support informed decisions about the number and placement of contour levels. Figure 3 presents a comprehensive uncertainty quantification workflow for US summer temperature data. The top-left panel shows the posterior mean field derived from approximately 8,000 observation locations using a Matérn spatial model with elevation as a fixed effect. The top-right panel displays the posterior standard deviation, revealing heterogeneous uncertainty that is lowest in data-dense regions and highest in mountainous areas. The bottom-left panel shows the optimal contour map using 10 levels selected to achieve P₂ ≈ 0.95, providing a 95% joint guarantee that midpoint level crossings lie within their designated regions. The bottom-right panel presents the contour map function Fᵤ(s), which spatially quantifies where the contour interpretation holds with high confidence (dark green regions) versus areas of greater uncertainty (light/white regions). This complete analysis demonstrates how excursions transforms point estimates into rigorously quantified spatial statements. Figure 3: Complete Uncertainty Quantification for US Temperature DataThe contourmap.colors() function complements this by generating color schemes that reflect spatial uncertainty between contours, improving the interpretability of the resulting visualizations. The dynamic relationship between contour density and statistical certainty is visualized in Figure 4, which shows how the number of contours affects both spatial detail and reliability. Figure 4: Effect of Contour Density on Uncertainty GuaranteesFigure 4 demonstrates the fundamental trade-off in contour map construction through an animated sequence. Each frame shows the same US summer temperature field as in Figure 3, visualized over the contiguous United States with an increasing number of equally spaced contour levels (K = 1 to 20). As contour density increases, finer spatial structures become visible, but maintaining the joint probabilistic guarantees quantified by the quality measures (P₀, P₁, and P₂) becomes progressively more difficult. This animation synthesizes the key principle underlying the excursions framework: optimal contour map design requires balancing spatial information content against statistical certainty, a balance that the quality measures make explicit and quantifiable.The main algorithm used in the package is based on sequential importance sampling to compute high-dimensional Gaussian integrals representing joint excursion probabilities. The method builds the excursion set by sequentially evaluating whether points belong to the set, given the values at previously included points. The algorithm is particularly efficient for Gaussian Markov random fields (GMRFs), where conditional distributions can be computed using sparse matrix operations. Multi-threaded execution is supported, and users can optionally provide precomputed Cholesky factorizations to speed up computations. The core computational routines are implemented in C, utilizing BLAS, LAPACK, CHOLMOD, and functions from the GNU Scientific Library (GSL), with parallelization via OpenMP for efficient performance on large domains.Documentation for the package is extensive and designed to support both new users and advanced practitioners. The "Get Started" vignette introduces the main functionality of the package with clear examples and usage patterns. The "Methodology" vignette provides an overview of the theoretical foundations behind the implemented methods, offering conceptual explanations without requiring a deep technical background). For users working within the R-INLA framework, the "INLA interface" vignette illustrates how to extract posterior quantities from fitted models and apply the excursion set methodology in practical workflows. In parallel, the "inlabru interface" vignette shows how to extend these methods to point process models and other flexible model specifications handled via inlabru. Together, these vignettes provide a comprehensive learning path from basic usage to advanced spatial inference, and are complemented by full function documentation, reproducible examples, and implementation notes available on the excursions homepage.The package is available on CRAN and its development version is maintained on GitHub. The GitHub repository includes issue tracking, test coverage, and continuous integration across platforms. The implementation is optimized for performance, with support for sparse matrix operations, parallel computing, and large domains. excursions provides a robust platform for performing spatially aware joint inference and has become a key component in the modern spatial statistics ecosystem. Related People David Bolin Professor, Statistics spatio-temporal statistics stochastic differential equations computational statistics
Share ShareXFacebookLinkedInEmailClipboard Related Links excursions Homepage excursions GitHub Repository excursions CRAN Package excursions Main Theory Paper 1 excursions Main Theory Paper 2 excursions Main Theory Paper 3
