MetricGraph is an R package used for working with data and random fields on metric graphs, such as street or river networks. The main functionality is contained in the metric_graph class, which is used for specifying metric graphs, adding data to them, visualization, and other basic functions that are needed for working with data and random fields on metric graphs. The package also implements various Gaussian fields on metric graphs, and in particular the Whittle--Matérn fields introduced in the references below.
Basic statistical tasks such as likelihood evaluation and prediction is implemented for these Gaussian fields in MetricGraph. Further, the package also contains interfaces to R-INLA and inlabru that facilitates using those packages for full Bayesian inference of general Latent Gaussian Models (LGMs) that includes Whittle-Matérn fields on metric graphs.
We refer to the package homepage for detailed tutorials on all different aspects of the package.
The latest CRAN release of the package can be installed directly from CRAN with install.packages("MetricGraph").
It is also possible to install the CRAN version from github by using the command:
remotes::install_github("davidbolin/metricgraph", ref = "cran")The latest stable version can be installed by using the command
remotes::install_github("davidbolin/metricgraph", ref = "stable")in R. The development version can be installed using the command
remotes::install_github("davidbolin/metricgraph", ref = "devel")D. Bolin, A. Simas, J. Wallin (2024) Gaussian Whittle-Matérn fields on metric graphs. Bernoulli, 30, 1611-1639.
D. Bolin, M. Kovács, V. Kumar, A. Simas (2023) Regularity and numerical approximation of fractional elliptic differential equations on compact metric graphs. Mathematics of Computation. In press.
D. Bolin, A. Simas, J. Wallin (2023) Markov properties of Gaussian random fields on compact metric graphs. ArXiv:2304.03190
D. Bolin, A. Simas, J. Wallin (2023) Statistical inference for Gaussian Whittle-Matérn fields on metric graphs. ArXiv:2304.10372
The package version format for released versions is major.minor.bugfix. All regular development should be performed on the devel branch or in a feature branch, managed with git flow feature. Ideally, all the changes should be made on the devel branch. 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 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 vestion 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 master and 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