Package 'MRFtools'

Title: Tools for Constructing and Plotting Markov Random Fields in R for Graphical Data
Description: Utility functions for using Markov Random Field smooths in Generalized Additive Models fitted with the 'mgcv' package.
Authors: Eric J. Pedersen [aut, cre] (ORCID: <https://orcid.org/0000-0003-1016-540X>), Gavin L. Simpson [aut] (ORCID: <https://orcid.org/0000-0002-4842-3657>), Valentin Lucet [ctb] (ORCID: <https://orcid.org/0000-0003-0268-818X>)
Maintainer: Eric J. Pedersen <[email protected]>
License: GPL-3
Version: 0.0-3
Built: 2026-06-03 08:32:36 UTC
Source: https://github.com/gavinsimpson/MRFtools

Help Index

Create a "mrf_penalty" object from a matrix and a config

Description

Create a "mrf_penalty" object from a matrix and a config

Usage

as_mrf_penalty(penalty, config)

Arguments

penalty

matrix
config

list

Convert a MRF penalty object to a matrix

Description

Convert a MRF penalty object to a matrix

Usage

## S3 method for class 'mrf_penalty'
as.matrix(x, ...)

Arguments

x

an object inheriting from class "mrf_penalty"
...

arguments passed to other methods

Examples

p <- mrf_penalty(1:10)
as.matrix(p)

Extract configuration details of an MRF penalty

Description

Extract configuration details of an MRF penalty

Usage

get_config(penalty)

Arguments

penalty

an object of class "mrf_penalty"

Value

An object of class "mrf_config", a list.

Extract MRF node labels from an MRF penalty

Description

Extract MRF node labels from an MRF penalty

Usage

get_labels(penalty)

Arguments

penalty

an object of class "mrf_penalty"

Extract the model type and parameters from an MRF penalty

Description

Extract the model type and parameters from an MRF penalty

Usage

get_model(penalty)

Arguments

penalty

an object of class "mrf_penalty"

Extract a fitted MRF

Description

Extract a fitted MRF

Usage

get_mrf(object, ...)

## S3 method for class 'bam'
get_mrf(object, ...)

## S3 method for class 'gamm'
get_mrf(object, ...)

## S3 method for class 'list'
get_mrf(object, ...)

## S3 method for class 'gam'
get_mrf(object, term, ...)

Arguments

object

An object from which to extract the fitted MRF. Currently only for objects of classes gam, bam, and gamm, and GAMMs fitted by gamm4::gamm4().
...

Arguments passed to other methods.
term

character; the MRF term to extract. Can be a partial match to a term, which is matched against the smooth label.

Value

A object representing the fitted MRF

Extract a MRF penalty matrix

Description

Extract a MRF penalty matrix

Usage

get_penalty(penalty, ...)

## S3 method for class 'mrf_penalty'
get_penalty(penalty, ...)

Arguments

penalty

an R object from which to extract the MRF penalty matrix.
...

arguments passed to other methods.

Value

A penalty matrix of class "matrix".

Extract the type of MRF from the penalty

Description

Extract the type of MRF from the penalty

Usage

get_type(object)

## S3 method for class 'mrf_penalty'
get_type(object)

## S3 method for class 'mrf_config'
get_type(object)

Arguments

object

an object of class "mrf_penalty" or "mrf_config".

Value

A length 1 character vector containing the type of MRF penalty.

MRF penalty configuration data

Description

MRF penalty configuration data

Usage

mrf_config(
  type = NULL,
  model = NULL,
  params = NULL,
  node_labels = NULL,
  delta = NULL,
  obj = NULL
)

Arguments

type

character
model

character
params

list?
node_labels

character
delta

numeric
obj

character

Markov Random Field Penalty

Description

Markov Random Field Penalty

Usage

mrf_penalty(object, ...)

Arguments

object

an R object to create the MRF penalty from.
...

arguments passed to other methods.

MRF penalty from a dendrogram

Description

MRF penalty from a dendrogram

Usage

## S3 method for class 'dendrogram'
mrf_penalty(object, model = NULL, node_labels = NULL, delta = FALSE, ...)

Arguments

object

an R object to create the MRF penalty from.
model

character; one of "full" or "individual" indicating if a fully connected graph ("full") or a random effect (random intercepts; "individual") penalty is created.
node_labels

character; a vector of alternative labels for the levels of the factor.
delta

numeric or logical; either the numeric value to add to the diagonal of the MRF penalty matrix, or a logical value indicating if such an adjustment should be made. The default is to not alter the diagonal of the penalty matrix.
...

arguments passed to other methods.

Fully connected graph and random effect MRF penalties from a factor

Description

Fully connected graph and random effect MRF penalties from a factor

Usage

## S3 method for class 'factor'
mrf_penalty(
  object,
  model = c("full", "individual"),
  node_labels = NULL,
  delta = FALSE,
  ...,
  type
)

Arguments

object

an R object to create the MRF penalty from.
model

character; one of "full" or "individual" indicating if a fully connected graph ("full") or a random effect (random intercepts; "individual") penalty is created.
node_labels

character; a vector of alternative labels for the levels of the factor.
delta

numeric or logical; either the numeric value to add to the diagonal of the MRF penalty matrix, or a logical value indicating if such an adjustment should be made. The default is to not alter the diagonal of the penalty matrix.
...

arguments passed to other methods.
type

character; deprecated. Use, model instead.

Examples

# a factor
fv <- factor(letters[1:10])

# create the MRF penalty for a fully connected graph
p <- mrf_penalty(fv, model = "full")
p
as.matrix(p)

# create the MRF penalty equivalent of random effects
p <- mrf_penalty(fv, model = "individual")
p
as.matrix(p)

MRF penalty from a hclust object

Description

MRF penalty from a hclust object

Usage

## S3 method for class 'hclust'
mrf_penalty(object, ...)

Arguments

object

an R object to create the MRF penalty from.
...

arguments passed to other methods.

Continuous-time random walk MRF penalty from a numeric vector

Description

Models one-dimensional numeric vectors as random-walk models.

Usage

## S3 method for class 'numeric'
mrf_penalty(
  object,
  model = c("rw1", "rw2", "ar1", "ou"),
  cyclic = FALSE,
  rho = NULL,
  at_nodes = NULL,
  node_labels = NULL,
  add_missing = NULL,
  end_points = NULL,
  end_dist = NULL,
  delta = FALSE,
  ...,
  type
)

Arguments

object

an R object to create the MRF penalty from.
model

character; one of "rw1", "rw2", "ar1", or "ou". See Description for details on the models
cyclic

logical; If TRUE, the end points are treated as neighbouring each other. See Description for details
rho

numeric;
at_nodes

numeric;
node_labels

character; a vector of alternative labels for the levels of the factor.
add_missing

logical;
end_points

numeric; an optional vector of length 2 providing the end points of the period of cycle.
end_dist

numeric;
delta

numeric or logical; either the numeric value to add to the diagonal of the MRF penalty matrix, or a logical value indicating if such an adjustment should be made. The default is to not alter the diagonal of the penalty matrix.
...

arguments passed to other methods.
type

character; deprecated. Use, model instead.

Examples

# linear rw1: 1st order continuous-time random walk
p <- mrf_penalty(1:10)
as.matrix(p)

# cyclic rw1:
p <- mrf_penalty(1:10, model = "rw1", cyclic = TRUE)
as.matrix(p)

# cyclic with user-specified end points
p <- mrf_penalty(1:10, model = "rw1", cyclic = TRUE, end_points = c(0,11))
as.matrix(p)

MRF penalty from a phylogeny

Description

MRF penalty from a phylogeny

Usage

## S3 method for class 'phylo'
mrf_penalty(
  object,
  model = c("rw1", "Brownian"),
  node_labels = NULL,
  delta = FALSE,
  eps = 0,
  ...
)

Arguments

object

an R object to create the MRF penalty from.
model

character; one of "full" or "individual" indicating if a fully connected graph ("full") or a random effect (random intercepts; "individual") penalty is created.
node_labels

character; a vector of alternative labels for the levels of the factor.
delta

numeric or logical; either the numeric value to add to the diagonal of the MRF penalty matrix, or a logical value indicating if such an adjustment should be made. The default is to not alter the diagonal of the penalty matrix.
eps

A value to add to the variance-covariance matrix diagonal to make it positive definite
...

arguments passed to other methods.

MRF penalty from polygon or multi-polygon simple features

Description

MRF penalty from polygon or multi-polygon simple features

Usage

## S3 method for class 'sf'
mrf_penalty(
  object,
  model = "icar",
  node_labels = NULL,
  buffer = NULL,
  delta = FALSE,
  ...
)

Arguments

object

an R object to create the MRF penalty from.
model

character; one of "full" or "individual" indicating if a fully connected graph ("full") or a random effect (random intercepts; "individual") penalty is created.
node_labels

character; a vector of alternative labels for the levels of the factor.
buffer

numeric; buffer distance for all or for individual elements of the geometry. See argument dist in sf::st_buffer for details.
delta

numeric or logical; either the numeric value to add to the diagonal of the MRF penalty matrix, or a logical value indicating if such an adjustment should be made. The default is to not alter the diagonal of the penalty matrix.
...

arguments passed to other methods.

MRF penalty from a SpatialPolygons

Description

MRF penalty from a SpatialPolygons

Usage

## S3 method for class 'SpatialPolygons'
mrf_penalty(
  object,
  model = "icar",
  node_labels = NULL,
  buffer = NULL,
  delta = FALSE,
  ...
)

Arguments

object

an R object to create the MRF penalty from.
model

character; one of "full" or "individual" indicating if a fully connected graph ("full") or a random effect (random intercepts; "individual") penalty is created.
node_labels

character; a vector of alternative labels for the levels of the factor.
buffer

numeric; buffer distance for all or for individual elements of the geometry. See argument dist in sf::st_buffer for details.
delta

numeric or logical; either the numeric value to add to the diagonal of the MRF penalty matrix, or a logical value indicating if such an adjustment should be made. The default is to not alter the diagonal of the penalty matrix.
...

arguments passed to other methods.

MRF penalty from a SpatialPoylgonsDataFrame

Description

MRF penalty from a SpatialPoylgonsDataFrame

Usage

## S3 method for class 'SpatialPolygonsDataFrame'
mrf_penalty(
  object,
  model = "icar",
  node_labels = NULL,
  buffer = NULL,
  delta = FALSE,
  ...
)

Arguments

object

an R object to create the MRF penalty from.
model

character; one of "full" or "individual" indicating if a fully connected graph ("full") or a random effect (random intercepts; "individual") penalty is created.
node_labels

character; a vector of alternative labels for the levels of the factor.
buffer

numeric; buffer distance for all or for individual elements of the geometry. See argument dist in sf::st_buffer for details.
delta

numeric or logical; either the numeric value to add to the diagonal of the MRF penalty matrix, or a logical value indicating if such an adjustment should be made. The default is to not alter the diagonal of the penalty matrix.
...

arguments passed to other methods.

Visualize a data set or object

Description

Synonyms of the generics::visualize() method. Alternatives are vis() and visualise().

Usage

vis(x, ...)

visualise(x, ...)

Arguments

x

A data frame or other object.
...

Other arguments passed to methods

Visualizing penalty matrix or graph object for a cyclic 1D MRF

Description

Visualizing penalty matrix or graph object for a cyclic 1D MRF

Usage

## S3 method for class 'cyclic_mrf_penalty'
visualize(x, graph = TRUE, layout = "linear", circular = TRUE, ...)

Arguments

x

an object of class "cyclic_mrf_penalty"
graph

logical;
layout

character;
circular

logical;
...

arguments passed to other methods and ultimately on to ggraph::create_layout() if graph = TRUE.

Examples

# example code
mrf_penalty(1:10, type = "linear") |>
  visualize()

Plot a thing

Description

Plot a thing

Usage

## S3 method for class 'dendrogram_mrf_penalty'
visualize(
  x,
  graph = TRUE,
  layout = "stress",
  circular = FALSE,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  fill_scale = NULL,
  ...
)

Arguments

x

an object of class "dendrogram_mrf_penalty"
graph

logical;
layout

character;
circular

logical;
xlab, ylab, title, subtitle, caption

character; labels for plots. If xlab or ylab are not supplied, a suitable default is used.
fill_scale

a suitable fill scale to use if plotting the penalty matrix
...

arguments passed to other methods and ultimately on to ggraph::create_layout() if graph = TRUE.

Examples

# example code
hc <- hclust(dist(USArrests), "complete")
mrf_penalty(hc) |>
  visualize()

Plot a thing

Description

Plot a thing

Usage

## S3 method for class 'fully_connected_graph_mrf_penalty'
visualize(
  x,
  graph = TRUE,
  layout = "stress",
  circular = FALSE,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  fill_scale = NULL,
  ...
)

Arguments

x

an object of class "fully_connected_graph_mrf_penalty"
graph

logical;
layout

character;
circular

logical;
xlab, ylab, title, subtitle, caption

character; labels for plots. If xlab or ylab are not supplied, a suitable default is used.
fill_scale

a suitable fill scale to use if plotting the penalty matrix
...

arguments passed to other methods and ultimately on to ggraph::create_layout() if graph = TRUE.

Examples

# example code
mrf_penalty(1:10, type = "linear") |>
  visualize()

Plot a thing

Description

Plot a thing

Usage

## S3 method for class 'sequential_mrf_penalty'
visualize(
  x,
  graph = TRUE,
  layout = "linear",
  circular = FALSE,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  fill_scale = NULL,
  ...
)

Arguments

x

an object of class "sequential_mrf_penalty"
graph

logical;
layout

character;
circular

logical;
xlab, ylab, title, subtitle, caption

character; labels for plots. If xlab or ylab are not supplied, a suitable default is used.
fill_scale

a suitable fill scale to use if plotting the penalty matrix
...

arguments passed to other methods and ultimately on to ggraph::create_layout() if graph = TRUE.

Examples

# example code
mrf_penalty(1:10, type = "linear") |>
  visualize()