| 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-6 |
| Built: | 2026-05-14 18:15:06 UTC |
| Source: | https://github.com/gam-mafia/MRFtools |
"mrf_penalty" object from a matrix and a configCreate a "mrf_penalty" object from a matrix and a config
as_mrf_penalty(penalty, config)as_mrf_penalty(penalty, config)
penalty |
matrix |
config |
list |
Convert a MRF penalty object to a matrix
## S3 method for class 'mrf_penalty' as.matrix(x, ...)## S3 method for class 'mrf_penalty' as.matrix(x, ...)
x |
an object inheriting from class |
... |
arguments passed to other methods |
p <- mrf_penalty(1:10) as.matrix(p)p <- mrf_penalty(1:10) as.matrix(p)
Extract configuration details of an MRF penalty
get_config(penalty)get_config(penalty)
penalty |
an object of class |
An object of class "mrf_config", a list.
Extract MRF node labels from an MRF penalty
get_labels(penalty)get_labels(penalty)
penalty |
an object of class |
Extract the model type and parameters from an MRF penalty
get_model(penalty)get_model(penalty)
penalty |
an object of class |
Extract a fitted MRF
get_mrf(object, ...) ## S3 method for class 'bam' get_mrf(object, ...) ## S3 method for class 'gamm' get_mrf(object, ...) ## S3 method for class 'gamm4' get_mrf(object, ...) ## S3 method for class 'gam' get_mrf(object, term, ...)get_mrf(object, ...) ## S3 method for class 'bam' get_mrf(object, ...) ## S3 method for class 'gamm' get_mrf(object, ...) ## S3 method for class 'gamm4' get_mrf(object, ...) ## S3 method for class 'gam' get_mrf(object, term, ...)
object |
An object from which to extract the fitted MRF. Currently only
for objects of classes |
... |
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. |
A object representing the fitted MRF
Extract the original object used to construct an MRF penalty
get_obj(object) ## S3 method for class 'mrf_config' get_obj(object) ## S3 method for class 'mrf_penalty' get_obj(object)get_obj(object) ## S3 method for class 'mrf_config' get_obj(object) ## S3 method for class 'mrf_penalty' get_obj(object)
object |
an object of class |
A length 1 character vector containing the type of MRF penalty.
Extract a MRF penalty matrix
get_penalty(penalty, ...) ## S3 method for class 'mrf_penalty' get_penalty(penalty, ...)get_penalty(penalty, ...) ## S3 method for class 'mrf_penalty' get_penalty(penalty, ...)
penalty |
an R object from which to extract the MRF penalty matrix. |
... |
arguments passed to other methods. |
A penalty matrix of class "matrix".
Extract the type of MRF from the penalty
get_type(object) ## S3 method for class 'mrf_penalty' get_type(object) ## S3 method for class 'mrf_config' get_type(object) ## S3 method for class 'mrf_penalty' get_type(object)get_type(object) ## S3 method for class 'mrf_penalty' get_type(object) ## S3 method for class 'mrf_config' get_type(object) ## S3 method for class 'mrf_penalty' get_type(object)
object |
an object of class |
A length 1 character vector containing the type of MRF penalty.
MRF penalty configuration data
mrf_config( type = NULL, model = NULL, params = NULL, node_labels = NULL, delta = NULL, obj = NULL )mrf_config( type = NULL, model = NULL, params = NULL, node_labels = NULL, delta = NULL, obj = NULL )
type |
character |
model |
character |
params |
list? |
node_labels |
character |
delta |
numeric |
obj |
character |
Markov Random Field Penalty
mrf_penalty(object, ...)mrf_penalty(object, ...)
object |
an R object to create the MRF penalty from. |
... |
arguments passed to other methods. |
MRF penalty from a dendrogram
## S3 method for class 'dendrogram' mrf_penalty( object, model = c("rw1", "ou", "brownian"), alpha = NULL, at_tips = NULL, internal_nodes = TRUE, delta = FALSE, ... )## S3 method for class 'dendrogram' mrf_penalty( object, model = c("rw1", "ou", "brownian"), alpha = NULL, at_tips = NULL, internal_nodes = TRUE, delta = FALSE, ... )
object |
an R object to create the MRF penalty from. |
model |
character; one of |
alpha |
numeric; the autoregressive parameter for an OU stochastic process. Should be >1e-5 (alpha = 0 would correspond to a "rw1" model). |
at_tips |
character; vector of tip labels to calculate the penalty at. All values in the vector must correpond to tip name labels in the tree. |
internal_nodes |
logical; should the internal nodes of the tree be
included in the penalty ( |
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
## S3 method for class 'factor' mrf_penalty( object, model = c("full", "individual"), node_labels = NULL, delta = FALSE, ..., type )## S3 method for class 'factor' mrf_penalty( object, model = c("full", "individual"), node_labels = NULL, delta = FALSE, ..., type )
object |
an R object to create the MRF penalty from. |
model |
character; one of |
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, |
# 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)# 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
## S3 method for class 'hclust' mrf_penalty( object, model = c("rw1", "ou", "brownian"), alpha = NULL, at_tips = NULL, internal_nodes = TRUE, delta = FALSE, ... )## S3 method for class 'hclust' mrf_penalty( object, model = c("rw1", "ou", "brownian"), alpha = NULL, at_tips = NULL, internal_nodes = TRUE, delta = FALSE, ... )
object |
an R object to create the MRF penalty from. |
model |
character; one of |
alpha |
numeric; the autoregressive parameter for an OU stochastic process. Should be >1e-5 (alpha = 0 would correspond to a "rw1" model). |
at_tips |
character; vector of tip labels to calculate the penalty at. All values in the vector must correpond to tip name labels in the tree. |
internal_nodes |
logical; should the internal nodes of the tree be
included in the penalty ( |
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. |
Models one-dimensional numeric vectors as random-walk models.
## S3 method for class 'numeric' mrf_penalty( object, model = c("rw1", "rw2", "rw2_d", "ar1", "ou"), cyclic = FALSE, alpha = NULL, rho = NULL, at_nodes = NULL, node_labels = NULL, end_points = NULL, end_dist = NULL, delta = FALSE, ..., type )## S3 method for class 'numeric' mrf_penalty( object, model = c("rw1", "rw2", "rw2_d", "ar1", "ou"), cyclic = FALSE, alpha = NULL, rho = NULL, at_nodes = NULL, node_labels = NULL, end_points = NULL, end_dist = NULL, delta = FALSE, ..., type )
object |
an R object to create the MRF penalty from. |
model |
character; one of "rw1","ou", "ar1", "rw2", or "rw2_d". "rw1" is a first-order continuous-time random walk model (I.e. Brownian motion). "ou" is the Ornstein-Uhlenbeck (I.e. continuous-time first-order autoregressive model); model = "ou" also requires specifying a value of alpha. "ar1" is a first-order discrete-time autoregressive model, and requires specifying the |
cyclic |
logical; If TRUE, the end points are treated as neighbouring each other. See Description for details |
alpha |
numeric; autoregression parameter for a continuous-time random walk ("ou"). rho must be >0. |
rho |
numeric; autoregression parameter for a discrete-time random walk ("ar1"). abs(rho) must be < 1 if specified. |
at_nodes |
numeric; what nodes (I.e. object values) that you want to evaluate the penalty at. Must include all values levels specified in |
node_labels |
character; a vector of alternative labels for the levels of the factor. |
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, |
# create some test data x_cont <- seq(0,5, length = 10) x_disc <- 1:10 # linear rw1: 1st order continuous-time random walk p1 <- mrf_penalty(x_cont) p1 # cyclic rw1: p2 <- mrf_penalty(x_cont, model = "rw1", cyclic = TRUE) p2 # cyclic with user-specified end points p3 <- mrf_penalty(x_cont, model = "rw1", cyclic = TRUE, end_points = c(0,6)) p3 # Continuous-time auto-regressive (I.e. "ou") model: p4 <- mrf_penalty(x_cont, model = "ou",alpha = 2) p4 # Discrete-time autoregressive model with negative 1st order autocorrelation p5 <- mrf_penalty(x_disc, model = "ar1", rho = -0.5)# create some test data x_cont <- seq(0,5, length = 10) x_disc <- 1:10 # linear rw1: 1st order continuous-time random walk p1 <- mrf_penalty(x_cont) p1 # cyclic rw1: p2 <- mrf_penalty(x_cont, model = "rw1", cyclic = TRUE) p2 # cyclic with user-specified end points p3 <- mrf_penalty(x_cont, model = "rw1", cyclic = TRUE, end_points = c(0,6)) p3 # Continuous-time auto-regressive (I.e. "ou") model: p4 <- mrf_penalty(x_cont, model = "ou",alpha = 2) p4 # Discrete-time autoregressive model with negative 1st order autocorrelation p5 <- mrf_penalty(x_disc, model = "ar1", rho = -0.5)
MRF penalty from a phylogeny
## S3 method for class 'phylo' mrf_penalty( object, model = c("rw1", "ou", "brownian"), alpha = NULL, at_tips = NULL, internal_nodes = TRUE, delta = FALSE, ... )## S3 method for class 'phylo' mrf_penalty( object, model = c("rw1", "ou", "brownian"), alpha = NULL, at_tips = NULL, internal_nodes = TRUE, delta = FALSE, ... )
object |
an R object to create the MRF penalty from. |
model |
character; one of |
alpha |
numeric; the autoregressive parameter for an OU stochastic process. Should be >1e-5 (alpha = 0 would correspond to a "rw1" model). |
at_tips |
character; vector of tip labels to calculate the penalty at. All values in the vector must correpond to tip name labels in the tree. |
internal_nodes |
logical; should the internal nodes of the tree be
included in the penalty ( |
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. |
#Example code#Example code
MRF penalty from a phylogeny from a phylo4 object
## S3 method for class 'phylo4' mrf_penalty( object, model = c("rw1", "ou", "brownian"), alpha = NULL, at_tips = NULL, internal_nodes = TRUE, delta = FALSE, ... )## S3 method for class 'phylo4' mrf_penalty( object, model = c("rw1", "ou", "brownian"), alpha = NULL, at_tips = NULL, internal_nodes = TRUE, delta = FALSE, ... )
object |
an R object to create the MRF penalty from. |
model |
character; one of |
alpha |
numeric; the autoregressive parameter for an OU stochastic process. Should be >1e-5 (alpha = 0 would correspond to a "rw1" model). |
at_tips |
character; vector of tip labels to calculate the penalty at. All values in the vector must correpond to tip name labels in the tree. |
internal_nodes |
logical; should the internal nodes of the tree be
included in the penalty ( |
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. |
#loading the geospiza dataset from phylobase library(phylobase) data(geospiza) #Random-walk (rw1) penalty for both tips and nodes: pen_rw <- mrf_penalty(geospiza, model = "rw1") #Same model, but for a reduced number of species species <- c("fortis", "pauper", "fusca", "olivacea") pen_rw_subset <- mrf_penalty(geospiza, model = "rw1", at_tips = species) plot(get_obj(pen_rw_subset)) #Random-walk penalty matrix for just the tips for all geospiza data: pen_rw_tips <- mrf_penalty(geospiza, model = "rw1", internal_nodes = FALSE) pen_rw_tips #Ornstein-Uhlenbeck ("ou") process penalty matrix, specifying alpha parameter (autocorrelation) pen_ou <- mrf_penalty(geospiza, model = "ou", alpha = 1)#loading the geospiza dataset from phylobase library(phylobase) data(geospiza) #Random-walk (rw1) penalty for both tips and nodes: pen_rw <- mrf_penalty(geospiza, model = "rw1") #Same model, but for a reduced number of species species <- c("fortis", "pauper", "fusca", "olivacea") pen_rw_subset <- mrf_penalty(geospiza, model = "rw1", at_tips = species) plot(get_obj(pen_rw_subset)) #Random-walk penalty matrix for just the tips for all geospiza data: pen_rw_tips <- mrf_penalty(geospiza, model = "rw1", internal_nodes = FALSE) pen_rw_tips #Ornstein-Uhlenbeck ("ou") process penalty matrix, specifying alpha parameter (autocorrelation) pen_ou <- mrf_penalty(geospiza, model = "ou", alpha = 1)
MRF penalty from polygon or multi-polygon simple features
## S3 method for class 'sf' mrf_penalty( object, model = "icar", node_labels = NULL, buffer = NULL, delta = FALSE, ... )## S3 method for class 'sf' mrf_penalty( object, model = "icar", node_labels = NULL, buffer = NULL, delta = FALSE, ... )
object |
an R object to create the MRF penalty from. |
model |
character; one of |
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 |
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
## S3 method for class 'SpatialPolygons' mrf_penalty( object, model = "icar", node_labels = NULL, buffer = NULL, delta = FALSE, ... )## S3 method for class 'SpatialPolygons' mrf_penalty( object, model = "icar", node_labels = NULL, buffer = NULL, delta = FALSE, ... )
object |
an R object to create the MRF penalty from. |
model |
character; one of |
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 |
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
## S3 method for class 'SpatialPolygonsDataFrame' mrf_penalty( object, model = "icar", node_labels = NULL, buffer = NULL, delta = FALSE, ... )## S3 method for class 'SpatialPolygonsDataFrame' mrf_penalty( object, model = "icar", node_labels = NULL, buffer = NULL, delta = FALSE, ... )
object |
an R object to create the MRF penalty from. |
model |
character; one of |
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 |
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. |
Synonyms of the generics::visualize() method. Alternatives are vis() and
visualise().
vis(x, ...) visualise(x, ...)vis(x, ...) visualise(x, ...)
x |
A data frame or other object. |
... |
Other arguments passed to methods |
Visualizing penalty matrix or graph object for a cyclic 1D MRF
## S3 method for class 'cyclic_mrf_penalty' visualize(x, graph = TRUE, layout = "linear", circular = TRUE, ...)## S3 method for class 'cyclic_mrf_penalty' visualize(x, graph = TRUE, layout = "linear", circular = TRUE, ...)
x |
an object of class |
graph |
logical; |
layout |
character; |
circular |
logical; |
... |
arguments passed to other methods and ultimately on to
|
# example code mrf_penalty(1:10, type = "linear") |> visualize()# example code mrf_penalty(1:10, type = "linear") |> visualize()
Plot a thing
## 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, ... )## 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, ... )
x |
an object of class |
graph |
logical; |
layout |
character; |
circular |
logical; |
xlab, ylab, title, subtitle, caption
|
character; labels for plots. If
|
fill_scale |
a suitable fill scale to use if plotting the penalty matrix |
... |
arguments passed to other methods and ultimately on to
|
# example code mrf_penalty(1:10, type = "linear") |> visualize()# example code mrf_penalty(1:10, type = "linear") |> visualize()
Plot a thing
## 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, ... )## 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, ... )
x |
an object of class |
graph |
logical; |
layout |
character; |
circular |
logical; |
xlab, ylab, title, subtitle, caption
|
character; labels for plots. If
|
fill_scale |
a suitable fill scale to use if plotting the penalty matrix |
... |
arguments passed to other methods and ultimately on to
|
# example code mrf_penalty(1:10, type = "linear") |> visualize()# example code mrf_penalty(1:10, type = "linear") |> visualize()
Plot a thing
## S3 method for class 'tree_mrf_penalty' visualize( x, graph = TRUE, layout = "stress", circular = FALSE, xlab = NULL, ylab = NULL, title = NULL, subtitle = NULL, caption = NULL, fill_scale = NULL, ... )## S3 method for class 'tree_mrf_penalty' visualize( x, graph = TRUE, layout = "stress", circular = FALSE, xlab = NULL, ylab = NULL, title = NULL, subtitle = NULL, caption = NULL, fill_scale = NULL, ... )
x |
an object of class |
graph |
logical; |
layout |
character; |
circular |
logical; |
xlab, ylab, title, subtitle, caption
|
character; labels for plots. If
|
fill_scale |
a suitable fill scale to use if plotting the penalty matrix |
... |
arguments passed to other methods and ultimately on to
|
# example code hc <- hclust(dist(USArrests), "complete") mrf_penalty(hc, internal_nodes = FALSE) |> visualize()# example code hc <- hclust(dist(USArrests), "complete") mrf_penalty(hc, internal_nodes = FALSE) |> visualize()