R/classes.R

In grainscape: Landscape Connectivity, Habitat, and Protected Area Networks

## register the S3 `igraph` class for use with S4 methods.
setOldClass("igraph")
selectMethod("show", "igraph")

## register the S3 `sf` class for use with S4 slots.
setOldClass("sf")

#' The `hce` class
#'
#' Used internally.
#'
#' @slot voronoi     The Voronoi tessellation of the patches and resistance
#'                   surface (`SpatRaster`).
#'
#' @slot patchLinks  A `SpatRaster` whose values indicate patch ids
#'                   (positive integers) and link ids (negative integers).
#'
#' @slot linkData    A `data.frame` of link attributes.
#'
#' @author Alex Chubaty and Sam Doctolero
#' @importClassesFrom terra SpatRaster
#' @include grainscape-package.R
#' @keywords internal
setClass(
  "hce",
  slots = list(
    voronoi = "SpatRaster",
    patchLinks = "SpatRaster",
    linkData = "data.frame"
  )
)

#' The `mpg` class
#'
#' @slot mpg         The minimum planar graph as class `igraph`.
#'
#' @slot patchId     The input `patch` raster with patch cells assigned to
#'                   their id (`SpatRaster`).
#'
#' @slot voronoi     The Voronoi tessellation of the patches and resistance
#'                   surface (`SpatRaster`).
#'
#' @slot lcpPerimWeight  The paths of the links between patches and their
#'                       accumulated costs (`SpatRaster`).
#'
#' @slot lcpLinkId   The paths of the links between patches and their id (`SpatRaster`).
#'
#' @slot mpgPlot     A `SpatRaster` version of the `mpg`, which can be
#'                   easily plotted to visualize the MPG.
#'
#' The `mpg` slot contains useful vertex and edge attributes.
#' Vertex attributes give attributes of patches including patch area,
#' the area of patch edges, the core area of each patch, and the coordinates
#' of the patch centroid.
#' All areal measurements are given as raster cell counts.
#' Edge attributes give attributes of the graph links including link
#' weights giving accumulated resistance/least-cost path distance,
#' Euclidean distance, and the start and end coordinates of each link.
#'
#' @author Alex Chubaty and Paul Galpern
#' @importClassesFrom terra SpatRaster
#' @include grainscape-package.R
#'
setClass(
  "mpg",
  slots = list(
    mpg = "igraph",
    patchId = "SpatRaster",
    voronoi = "SpatRaster",
    lcpPerimWeight = "SpatRaster",
    lcpLinkId = "SpatRaster",
    mpgPlot = "SpatRaster"
  )
)

#' The `goc` class
#'
#' @slot voronoi    A `SpatRaster` describing the regions of proximity in
#'                  resistance units around the focal patches or points.
#'
#' @slot summary    A summary of the the grains of connectivity generated and
#'                  their properties.
#'
#' @slot th         A list giving the GOC graph at each threshold.
#'
#' Each element of `th` contains a `goc` object giving the GOC graph as
#' class [igraph::igraph()].
#' Vertex attributes describes qualities of each polygon including the coordinates
#' of each polygon centroid, the area of these polygons, and the original patch
#' IDs in the MPG that are included in each polygon.
#' All areal measurements are given as raster cell counts.
#' A variety of edge attributes are also given in the GOC graph.
#' See [distance()] for more information.
#'
#' @author Alex Chubaty and Paul Galpern
#' @importClassesFrom terra SpatRaster
setClass(
  "goc",
  slots = list(
    voronoi = "SpatRaster",
    summary = "data.frame",
    th = "list"
  )
)

#' Show a `grainscape` object
#'
#' Custom `show` method to safely print the contents of a `goc` or `grain` object.
#'
#'
#' @param object  A [`goc()`][goc-class] or
#'                [`grain()`][grain-class] object.
#'
#' @export
#' @rdname show
setMethod("show", signature = "goc", definition = function(object) {
  cat("Slot voronoi:\n")
  cat(show(object@voronoi))

  cat("\nSlot summary:\n")
  cat(show(object@summary))

  cat("\nSlot th:\n")
  cat("List of ", length(object@th), " goc elements", "\n")
})

#' The `grain` class
#'
#' @slot voronoi    A `SpatRaster` describing the regions of proximity in
#'                  resistance units around the focal patches or points.
#'
#' @slot summary    A summary of the the grains of connectivity generated and
#'                  their properties.
#'
#' @slot centroids  An `sf` object indicating the grain's polygon
#'                  centroids.
#'
#' @slot th         A list of `igraph` objects giving the graphs describing the relationship
#'                  among the polygons in that grain
#'
#' See [grain()] for more information.
#'
#' @author Alex Chubaty and Paul Galpern
#' @importClassesFrom terra SpatRaster
setClass(
  "grain",
  slots = list(
    voronoi = "SpatRaster",
    summary = "data.frame",
    centroids = "sf",
    th = "igraph"
  )
)

#' @export
#' @rdname show
setMethod("show", signature = "grain", definition = function(object) {
  cat("Slot voronoi:\n")
  cat(show(object@voronoi))

  cat("\nSlot summary:\n")
  cat(show(object@summary))

  cat("\nSlot centroids:\n")
  cat("sf object with ", nrow(object@centroids), " features", "\n")

  cat("\nSlot th:\n")
  cat(show(object@th))
})

#' The `corridor` class
#'
#' @slot voronoi          A `SpatRaster` representation of the boundaries
#'                        of the voronoi polygons.
#'
#' @slot linksSP          An `sf` representation of links
#'                        in the grains of connectivity graph.
#'
#' @slot nodesSP          An `sf` representation of the nodes in
#'                        the grains of connectivity graph
#'
#' @slot shortestLinksSP  An `sf` representation of the links in
#'                        the shortest path between coordinates
#'
#' @slot shortestNodesSP  An `sf` representation of the nodes in
#'                        the shortest path between coordinates
#'
#' @slot corridorLength   A `numeric` of length 1 giving the length of the
#'                        shortest path between coordinates in accumulated
#'                        resistance units.
#'
#' See [corridor()] for more information.
#'
#' @author Alex Chubaty and Paul Galpern
#' @importClassesFrom terra SpatRaster
#'
setClass(
  "corridor",
  slots = list(
    voronoi = "SpatRaster",
    linksSP = "sf",
    nodesSP = "sf",
    shortestLinksSP = "sf",
    shortestNodesSP = "sf",
    corridorLength = "numeric"
  )
)

#' @export
#' @rdname show
setMethod("show", signature = "corridor", definition = function(object) {
  cat("Slot voronoi:\n")
  cat(show(object@voronoi))

  cat("\nSlot linksSP:\n")
  cat(show(object@linksSP))

  cat("\nSlot nodesSP:\n")
  cat(show(object@nodesSP))

  cat("\nSlot shortestLinksSP:\n")
  cat(show(object@shortestLinksSP))

  cat("\nSlot shortestNodesSP:\n")
  cat(show(object@shortestNodesSP))

  cat("\nSlot corridorLength:\n")
  cat(show(object@corridorLength))
})