rSPDE is an R package used for computing rational approximations of fractional SPDEs. These rational approximations can be used for computationally efficient statistical inference.
Basic statistical operations such as likelihood evaluations and kriging predictions using the fractional approximations are also implemented. The package also contains interfaces to R-INLA and inlabru.
For illustration purposes, the package contains a simple FEM implementation for models on R. See the
Getting Started to the rSPDE package vignette for an introduction to the package. The Rational approximation with the rSPDE package and Operator-based rational approximation vignettes provide
introductions to how to create and fit rSPDE models. For an introduction to the R-INLA implementation
of the rSPDE models see the R-INLA implementation of the rational SPDE approach. The rSPDE documentation contains descriptions and examples of the functions in the rSPDE package.
The paper Covariance-based rational approximations of fractional SPDEs for computationally efficient Bayesian inference contains a study on the accuracy of the various rational approximations that are implemented in the rSPDE package. These are summarized in a shiny app that can be run directly from GitHub by using the following command (you may need to install some of the dependencies):
# install.packages(c("shiny", "shinythemes", "plotly"))
# install.packages(c("tidyr", "dplyr"))
shiny::runGitHub("davidbolin/rSPDE", subdir="shiny_app")D. Bolin, A. B. Simas, Z. Xiong (2023) Covariance-based rational approximations of fractional SPDEs for computationally efficient Bayesian inference. Journal of Computational and Graphical Statistics, in press.
D. Bolin and K. Kirchner (2020) The rational SPDE approach for Gaussian random fields with general smoothness. Journal of Computational and Graphical Statistics, 29:2, 274-285.
The latest CRAN release of the package can be installed directly from CRAN with install.packages("rSPDE").
It is also possible to install the CRAN version from github by using the command:
remotes::install_github("davidbolin/rspde", ref = "cran")The latest stable version (which on very rare occasions can be slightly more recent than the CRAN version), can be installed by using the command
remotes::install_github("davidbolin/rspde", ref = "stable")in R. The development version can be installed using the command
remotes::install_github("davidbolin/rspde", ref = "devel")The following is intended for expert use only:
The devel branch ships pure R by default but also carries the C/C++ cgeneric sources, which can be compiled on demand to build the local INLA shared object (inst/shared/rspde_cgeneric_models.so). Compilation is opt-in and controlled by either an environment variable or a --enable-compiled flag passed to remotes::install_github():
# Pure R install (default; matches CRAN):
remotes::install_github("davidbolin/rSPDE", ref = "devel")
# Opt in to the compiled cgeneric library:
remotes::install_github(
"davidbolin/rSPDE",
ref = "devel",
configure.args = "--enable-compiled"
)
# Or via an environment variable:
withr::with_envvar(
c(RSPDE_COMPILE = "1"),
remotes::install_github("davidbolin/rSPDE", ref = "devel")
)If you have already cloned the repository locally, devtools::install() works the same way. The most reliable form is to set the RSPDE_COMPILE environment variable before installing — devtools::install() does not accept a configure.args argument directly; configure flags must be forwarded through args = "--configure-args=...":
# From the cloned repo root, pure R (default, no compilation):
devtools::install()
# From the cloned repo root, with compilation (env-var form, recommended):
Sys.setenv(RSPDE_COMPILE = "1")
devtools::install()
# Or scoped to a single call:
withr::with_envvar(
c(RSPDE_COMPILE = "1"),
devtools::install()
)
# Equivalent --configure-args form (note: pass via `args`, not `configure.args`):
devtools::install(args = "--configure-args=--enable-compiled")The compiled C/C++ sources live in inst/src-optional/. The configure (POSIX) and configure.win (Windows) scripts copy them into src/ only when compilation is requested; otherwise they write a no-op Makevars so the install stays pure R. CRAN passes neither flag, so the CRAN tarball is unaffected.
At runtime the package reads getOption("rspde.compiled") to know whether the local shared object is available, falling back to the shared library shipped with INLA otherwise.
For Windows users without Rtools, leave compilation disabled — the default pure-R install does not require a toolchain.
The compilation is only required to create the shared object used by INLA's cgeneric interface; INLA itself ships such a shared object, so most users do not need to compile. The stable-src and devel-src branches are deprecated in favour of this single-branch devel workflow.
See the vignette Building the rSPDE package from source on Mac and Linux for the toolchain prerequisites (gcc-14 on macOS, etc.) used by the optional compile path.
The package version format for released versions is major.minor.bugfix. All regular development — both the R code and the C/C++ cgeneric sources in inst/src-optional/ — should be performed on the devel branch or in a feature branch managed with git flow feature. The legacy devel-src / stable-src branches are deprecated; the optional-compile machinery on devel (see Installation instructions above) replaces them. The devel version of the package should contain unit tests and examples for all important functions. Several functions may depend on INLA. Examples and tests for such functions might create problems when submitting to CRAN. To solve this problem, we created some Github Actions scripts that get the examples and tests depending on INLA on the devel branch and adapt to versions that will not fail on CRAN. Therefore, the best way to handle these situations is to avoid as much as possible to do any push to the stable branch. The idea is to update the stable branch by merges following the workflow that will be described below.
The examples that depend on INLA should have the following structure:
#' \donttest{ #devel version
#' library(INLA)
#'
#' # The contents of the example
#'
#' #devel.tag
#' }
The inla branch is used to mirror the source files that need to be available under src/ for INLA. These files should be maintained on the devel branch under inst/src-optional/; they should not be edited manually on the inla branch.
To send the source files from devel to inla, commit the changes on devel with a commit message that ends with INLA UPDATE, and push to devel:
git checkout devel
# Edit the relevant files in inst/src-optional/
git add inst/src-optional
git commit -m "Update INLA cgeneric sources INLA UPDATE"
git push origin develWhen the last commit message in the push ends with INLA UPDATE, the GitHub Actions workflow copies the following files from inst/src-optional/ on devel into src/ on inla:
- all
.cfiles; - all
.cppfiles; cgeneric_cpp.h;cgeneric_defs.h.
The workflow then commits the copied files on the inla branch and pushes that branch. Only the head commit message of the push is checked, so if several commits are pushed at once, the last commit in the push must be the one whose message ends with INLA UPDATE. If the workflow file itself is being added for the first time, first push the workflow to devel, and then make a second push whose commit message ends with INLA UPDATE.
The tests that depend on INLA should have the following structure:
test_that("Description of the test", {
testthat::skip_on_cran()
if (!requireNamespace("INLA", quietly=TRUE))
testthat::skip(message = 'INLA package is not installed. (see www.r-inla.org/download-install)')
old_threads <- INLA::inla.getOption("num.threads")
INLA::inla.setOption(num.threads = "1:1")
# The contents of the test
INLA::inla.setOption(num.threads = old_threads)
})
On the devel branch, the version number is major.minor.bugfix.9000, where the first three components reflect the latest released version with changes present in the default branch. Bugfixes should be applied via the git flow bugfix and git flow hotfix methods, as indicated below. For git flow configuration, use master as the stable master branch, devel as the develop branch, and v as the version tag prefix. Hotfixes directly stable should be avoided whenever possible to minimize conflicts on merges. See the git flow tutorial for more information.
For non devel branches that collaborators need access to (e.g. release branches, feature branches, etc, use the git flow publish mechanism).
- Prepare a new stable release with CRAN submission:
# If git flow was not initialized, initialize it with
git flow init
# When initializing git flow, choose the tag prefix as v
# Now, start the release
git flow release start major.(minor+1).0
# In R, the following updates the version number in DESCRIPTION and NEWS:
usethis::use_version("minor")
## At this point, see the CRAN submission section below.
git flow release finish 'VERSION'
# In the stable merge, accept all incoming changes.
# Do adjustments if needed and push the changes.
# Check the existing tags with
git tag
# If a tag was not created, create one with
git tag vX.X.X -m "Tag for version X.X.X"
# After pushing the merge, also push the tag:
git push origin vX.X.X
# After handling the stable branch, merge back with devel.
# In R, the following updates the dev version number in DESCRIPTION and NEWS:
usethis::use_dev_version()
- Do a hotfix (branch from stable branch; use bugfix for release branch bugfixes):
git flow hotfix start hotfix_branch_name
## Do the bugfix, update the verison number major.minor.(bugfix+1), and commit
## Optionally, do CRAN submission
git flow hotfix finish hotfix_branch_name
## Resolve merge conflicts, if any
- CRAN submission
## Perform CRAN checks on the stable branch
## If unsuccessful then do bugfixes with increasing bugfix version, until ok
## Submit to CRAN
## If not accepted then do more bugfixes and repeat