Skip to contents
library(ngvb)
library(ggplot2)
library(INLA)     # ngvb uses INLA as a backend; attach it to call inla() directly

Overview

A latent Gaussian model (LGM), the workhorse of R-INLA, places a Gaussian prior on a latent field: a random walk, an autoregression, a spatial effect, or a set of random effects. That prior is convenient but rigid, because it assumes Gaussianity everywhere. Real data often break this assumption in just a few places, such as a sudden jump in a time series, one outlying subject, a sharp boundary between regions, or a local hotspot in space. A Gaussian model then has to compromise. It either over-smooths the interesting feature or inflates the variance everywhere to accommodate it.

ngvb relaxes that single assumption. It keeps everything you already have, the same INLA model and the same code, and replaces the Gaussian driving noise with a heavier-tailed one. The result adds flexibility only where the data ask for it and falls back to the Gaussian model everywhere else. Two functions do the work, and both take an ordinary inla fit that was run with control.compute = list(config = TRUE):

  • ng.check(fit) asks whether you should relax the Gaussian assumption, and where.
  • ngvb(fit) fits the non-Gaussian extension.

The model in one paragraph

Every LGM writes its latent field 𝐱\mathbf x through a model-specific dependency matrix 𝐃(𝛉)\mathbf D(\boldsymbol\theta) that turns 𝐱\mathbf x into independent Gaussian increments, 𝐃(𝛉)𝐱=d𝚲,Λi∼N(0,hi).\mathbf D(\boldsymbol\theta)\,\mathbf x \;\overset{d}{=}\; \boldsymbol\Lambda, \qquad \Lambda_i \sim N(0,\,h_i). For a random walk Λi=xi−xi−1\Lambda_i=x_{i}-x_{i-1}, for an autoregression Λi=xi−ρxi−1\Lambda_i=x_i-\rho x_{i-1}, and so on. Equivalently, the Gaussian field has precision 𝐐(𝛉)=𝐃(𝛉)⊤diag(1/𝐡)𝐃(𝛉)\mathbf Q(\boldsymbol\theta)=\mathbf D(\boldsymbol\theta)^\top\mathrm{diag}(1/\mathbf h)\, \mathbf D(\boldsymbol\theta). The non-Gaussian model keeps the same 𝐃\mathbf D but lets each increment have its own variance ViV_i, Λi∣Vi∼N(0,Vi),Vi∼IG(hi,η−1hi2),E[Vi]=hi.\Lambda_i \mid V_i \sim N(0,\,V_i),\qquad V_i \sim \mathrm{IG}(h_i,\,\eta^{-1}h_i^2),\qquad E[V_i]=h_i . The mixing variables 𝐕\mathbf V carry the local flexibility. Where Vi=hiV_i=h_i the model is Gaussian, and where ViV_i is inflated the increment is allowed to be unusually large. A single non-Gaussianity parameter η≥0\eta\ge 0 controls how far 𝐕\mathbf V may stray from 𝐡\mathbf h, and η=0\eta=0 is exactly the Gaussian model. Conditional on 𝐕\mathbf V the field is still Gaussian, with precision 𝐐(𝛉,𝐕)=𝐃(𝛉)⊤diag(1/𝐕)𝐃(𝛉).\mathbf Q(\boldsymbol\theta,\mathbf V)=\mathbf D(\boldsymbol\theta)^\top\, \mathrm{diag}(1/\mathbf V)\,\mathbf D(\boldsymbol\theta).ngvb fits the model with a short variational-Bayes loop that repeatedly calls INLA with 𝐕\mathbf V fixed and then updates 𝐕\mathbf V and η\eta. The prior on η\eta is an exponential (a penalised-complexity prior with rate alpha.eta, default 22) that shrinks toward the Gaussian model, so non-Gaussianity has to earn its place. Increase alpha.eta for stronger shrinkage.

Two variational algorithms are available. The default, method = "SVI", is a structured mean-field scheme that updates q(𝐕)q(\mathbf V) and q(η)q(\eta) in turn, and it is the more reliable choice. The alternative, method = "SCVI", integrates 𝐕\mathbf V out of the η\eta update analytically and so converges in fewer iterations, but its collapsed marginal can over-shrink a weak yet genuine effect all the way to the Gaussian model.

Which models and likelihoods are supported

The non-Gaussianity in ngvb lives entirely in the latent field, on its driving noise, and never touches the observation model. So every INLA likelihood is available: Gaussian, Poisson, binomial, negative binomial, survival families, and the rest all work unchanged. You just fit your LGM as usual and hand it to ng.check() or ngvb().

The latent components split into three groups.

Detected automatically. If your fit uses one of these, ngvb() and ng.check() find it with no extra arguments: iid, rw1, rw2, ar1, besag (the intrinsic CAR), spde / spde2 (Matern fields), and seasonal. Each of these is a single operator applied to independent noise, so it has the dependency matrix 𝐃\mathbf D the method needs.

Added by hand. Some models are not auto-detected but are still described by 𝐃(𝛉)𝐱=d𝚲\mathbf D(\boldsymbol\theta)\,\mathbf x \;\overset{d}{=}\; \boldsymbol\Lambda, so you can build them with ngvb_operator() which expects the matrix 𝐃\mathbf D, the vector 𝐡\mathbf h. This covers the simultaneous autoregression (sar) or the Ornstein-Uhlenbeck process (ou). It is also possible to use the matrices and operators of the ngme2 package to define the LnGM; both are covered in Custom models.

Not compatible. Some components are not a single operator applied to one field, and the method does not apply to them. The main cases are the additive spatial models bym, bym2, besag2 (a latent field that is a sum of parts), the conditionally specified besagproper, the copy and mixture constructions generic1, generic2, generic3, copy, scopy, z, the measurement-error models mec, meb, and the nonlinear-covariate effects sigm, revsigm, log1exp, logdist. For an additive model such as bym, the practical fix is to split it into its besag and iid parts as two separate f() terms, which ngvb() then extends jointly.

Priors carry over the same way: pc.prec, loggamma, and normal precision priors on the original f() term are read from the fit and reused automatically; anything else falls back to a default prior with a warning.

A time series with jumps

jumpts is a series that is smooth apart from two abrupt jumps.

ggplot(jumpts, aes(x, y)) +
  geom_line(colour = "grey70") +
  geom_point(colour = "grey30", size = 1.3) +
  labs(title = "jumpts", x = "time", y = "y") +
  theme_minimal(base_size = 12)

The jumpts series: a smooth trend broken by two abrupt vertical jumps.

A first-order random walk models the series through its increments, xi−xi−1∼N(0,1/τ),x_i - x_{i-1} \sim N(0,\,1/\tau), which is the operator 𝐃=τ𝐃0\mathbf D = \sqrt{\tau}\,\mathbf D_0 with 𝐃0\mathbf D_0 the first-difference matrix. A Gaussian RW1 forces every increment to share the same variance, so it cannot tell a jump from ordinary noise. Fit it with INLA:

LGM <- inla(y ~ -1 + f(x, model = "rw1"), data = jumpts,
            control.compute = list(config = TRUE))

Now check whether the latent Gaussian assumption holds:

check <- ng.check(LGM, compute.fixed = FALSE)

Diagnostic for the RW1 fit: per-index sensitivity spiking at the two jumps, and the observed overall sensitivity far in the tail of its Gaussian reference distribution.

The left panel is the per-index sensitivity di(y)d_i(y), which measures how much the evidence would improve if increment ii were allowed to be non-Gaussian. It spikes at the two jumps. The right panel compares the observed overall sensitivity s0=∑idis_0=\sum_i d_i (the vertical line) against the distribution it would have under a truly Gaussian field (the grey curve). The observed value sits far out in the tail, with p≈0p\approx0, so the Gaussian RW1 is inadequate and we know exactly where.

Now we extend it to non-Gaussianity. The model is auto-detected, so this is a single call:

LnGM <- ngvb(LGM)
#> Components: x [rw1]
#> ngvb: converged after 24 iteration(s);  E[eta] = 3.742
plot(LnGM)

ngvb fit summary: mixing weights inflated at the two jumps and near one elsewhere, the posterior of the non-Gaussianity parameter, and its convergence across iterations.

For each component the plot shows the mixing weights Vi/hiV_i/h_i (the posterior mean with a 90 percent credible interval, and a cross at the plug-in value 1/E[1/Vi]1/E[1/V_i] that INLA is actually refit with, which sits a little below the mean because q(Vi)q(V_i) is right-skewed). The final panel tracks E[η]E[\eta] across the iterations. The mixing variables are inflated precisely at the two jumps and sit near one elsewhere, so the model bought local flexibility exactly where it was needed and stayed Gaussian in between. The non-Gaussianity parameter is clearly positive.

Beyond the point estimate, you can integrate the mixing variables V out entirely by sampling from their variational posterior and refitting the LGM at each draw. This gives the Bayes factor against the Gaussian model, and, pooled with importance weights, posterior summaries of anything the underlying inla() fit reports:

samples <- ngvb_sample(LnGM, n.samples = 30)
bayes.factor(samples)               # LnGM vs. LGM marginal-likelihood ratio
#> Bayes factor (non-Gaussian vs Gaussian): 9.96e+23
#>   log10 BF = 24.00  (decisive)
#>   weight ESS = 2.2 of 30 draws
summary(samples)                    # importance-weighted summaries, V integrated out
#> Latent non-Gaussian model, V integrated out over 30 draws
#> Bayes factor vs Gaussian model: 9.96e+23 (log10 = 24.00), weight ESS 2.2
#> 
#> Fixed effects:
#>   (none)
#> 
#> Hyperparameters:
#>                                              mean         sd
#> Precision for the Gaussian observations 3588.3315 13688.8103
#> Theta1 for x                               2.1162     0.4493
#> 
#> Random effects:
#>   $x (100 nodes)
#>   ID    mean     sd
#> 1  1 -0.8755 0.1419
#> 2  2 -0.6634 0.1094
#> 3  3 -0.7070 0.0956
#> 4  4 -0.6998 0.0999
#> 5  5 -0.8781 0.1213
#> 6  6 -0.7240 0.1306
#>   ... 94 more row(s); use what = "random" to print in full

On the usual scale a log⁡10\log_{10} Bayes factor above 0.50.5, 11, or 22 is substantial, strong, or decisive evidence for the non-Gaussian model. Here it is far into the decisive range. The ess field is the effective number of draws behind the estimate; if it is small, raise n.samples.

Where to next

The same two calls carry over to every other kind of data:

  • Geostatistical data fits a Matern (SPDE) field to pressure readings and maps, before ngvb() is ever run, where the spatial predictions will move.
  • Areal data applies the intrinsic CAR (besag) model to burglary rates across Columbus, Ohio.
  • Random intercepts and slopes treats subject-level random effects in a longitudinal growth study.
  • Custom models builds a simultaneous autoregression by hand with ngvb_custom(), and borrows ready-made operators from the ngme2 package.