Package 'grainscape'

Description

Given a landscape resistance surface, creates minimum planar graph and grains of connectivity models that can be used to calculate effective distances for landscape connectivity at multiple scales.

Details

Landscape connectivity modelling to understand the movement and dispersal of organisms has been done using raster resistance surfaces and landscape graph methods. Grains of connectivity (GOC) models combine elements of both approaches to produce a continuous and scalable tool that can be applied in a variety of study systems. The purpose of this package is to implement grains of connectivity analyses. Routines accept raster-based resistance surfaces as input and return raster, vector and graph-based data structures to represent connectivity at multiple scales. Effective distances describing connectivity between geographic locations can be determined at multiple scales. Analyses of this sort can contribute to corridor identification, landscape genetics, as well as other connectivity assessments. Minimum planar graph (MPG; Fall et al., 2007) models of resource patches on landscapes can also be generated using the software.

MPG calculations and generalization of the Voronoi tessellation used in GOC models is based on the routines in SELES software (Fall and Fall, 2001). Routines also depend on the sp (Pebesma and Bivand, 2005), raster (Hijmans and van Etten, 2011), and igraph (Csardi and Nepusz, 2006) packages.

A paper describing the use of this package for landscape connectivity modelling is available at doi:10.1111/2041-210X.13350.

A detailed tutorial is available as a vignette (see browseVignettes('grainscape')).

Author(s)

Maintainer: Alex M Chubaty [email protected] (ORCID)

Authors:

• Paul Galpern [email protected] (ORCID) [copyright holder]

• Sam Doctolero [email protected]

References

Csardi, G. and T. Nepusz. (2006). The igraph software package for complex network research. InterJournal Complex Systems 1695. https://igraph.org.

Fall, A. and J. Fall. (2001). A domain-specific language for models of landscape dynamics. Ecological Modelling 141:1-18.

Fall, A., M.-J. Fortin, M. Manseau, D. O'Brien. (2007) Spatial graphs: Principles and applications for habitat connectivity. Ecosystems 10:448:461.

Galpern, P., M. Manseau. (2013a) Finding the functional grain: comparing methods for scaling resistance surfaces. Landscape Ecology 28:1269-1291.

Galpern, P., M. Manseau. (2013b) Modelling the influence of landscape connectivity on animal distribution: a functional grain approach. Ecography 36:1004-1016.

Galpern, P., M. Manseau, A. Fall. (2011) Patch-based graphs of landscape connectivity: A guide to construction, analysis and application for conservation. Biological Conservation 144:44-55.

Galpern, P., M. Manseau, P.J. Wilson. (2012) Grains of connectivity: analysis at multiple spatial scales in landscape genetics. Molecular Ecology 21:3996-4009.

Hijmans, R.J. (2023). raster: Geographic Data Analysis and Modeling. R package version 3.6-20, https://CRAN.R-project.org/package=raster.

Pebesma, E.J. and R.S. Bivand. (2005). Classes and methods for spatial data in R. R News 5 (2), https://cran.r-project.org/doc/Rnews/.

See Also

Useful links:

• https://www.alexchubaty.com/grainscape/

• https://github.com/achubaty/grainscape

• Report bugs at https://github.com/achubaty/grainscape/issues

Description

Extract or Replace Parts of an Object

Usage

## S4 method for signature 'goc'
x$name

## S4 replacement method for signature 'goc'
x$name <- value

## S4 method for signature 'mpg'
x$name

## S4 replacement method for signature 'mpg'
x$name <- value

Arguments

Description

Given a series of GOC models built at different scales, visualize the corridor (or shortest path) between two points using one of the tessellations (i.e., scales) in these models.

Usage

corridor(x, ...)

## S4 method for signature 'goc'
corridor(x, whichThresh, coords, weight = "meanWeight", ...)

Arguments

Value

An object of class corridor.

Author(s)

Paul Galpern and Alex Chubaty

References

Fall, A., M.-J. Fortin, M. Manseau, D. O'Brien. (2007) Spatial graphs: Principles and applications for habitat connectivity. Ecosystems 10:448:461.

Galpern, P., M. Manseau. (2013a) Finding the functional grain: comparing methods for scaling resistance surfaces. Landscape Ecology 28:1269-1291.

Galpern, P., M. Manseau. (2013b) Modelling the influence of landscape connectivity on animal distribution: a functional grain approach. Ecography 36:1004-1016.

Galpern, P., M. Manseau, A. Fall. (2011) Patch-based graphs of landscape connectivity: a guide to construction, analysis, and application for conservation. Biological Conservation 144:44-55.

Galpern, P., M. Manseau, P.J. Wilson. (2012) Grains of connectivity: analysis at multiple spatial scales in landscape genetics. Molecular Ecology 21:3996-4009.

See Also

GOC(), visualize()

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features=1
tinyPatchMPG <- MPG(cost = tinyCost, patch = tinyCost == 1)
## Extract a representative subset of 5 grains of connectivity
tinyPatchGOC <- GOC(tinyPatchMPG, nThresh = 5)
## Quick visualization of a corridor
corridorStartEnd <- rbind(c(10, 10), c(90, 90))
tinyPatchCorridor <- corridor(tinyPatchGOC, whichThresh = 3, coords = corridorStartEnd)
if (interactive())
  plot(tinyPatchCorridor)

## More control over a corridor visualization
if (interactive()) {
  plot(tinyPatchCorridor@voronoi, col = "lightgrey", lwd = 2)
  plot(tinyPatchCorridor@linksSP, col = "darkred", lty = "dashed", add = TRUE)
  plot(tinyPatchCorridor@nodesSP, col = "darkred", pch = 21, bg = "white", add = TRUE)
  plot(tinyPatchCorridor@shortestLinksSP, col = "darkred", lty = "solid", lwd = 2, add = TRUE)
  plot(tinyPatchCorridor@shortestNodesSP, col = "darkred", pch = 21, bg = "darkred", add = TRUE)
  mtext(paste("Corridor shortest path length:",
              round(tinyPatchCorridor@corridorLength, 2),
              "resistance units"), side = 1)
}

Description

The corridor class

Slots

voronoi

A RasterLayer representation of the boundaries of the voronoi polygons.

linksSP

A SpatialLinesDataFrame representation of links in the grains of connectivity graph.

nodesSP

A SpatialPoints representation of the nodes in the grains of connectivity graph

shortestLinksSP

A SpatialLines representation of the links in the shortest path between coordinates

shortestNodesSP

A SpatialPoints representation of the nodes in the shortest path between coordinates

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(s)

Alex Chubaty and Paul Galpern

Description

Find the shortest network distance between pairs of points using the GOC graph. This can be used as an effective distance for landscape connectivity assessments.

Usage

distance(x, y, ...)

## S4 method for signature 'goc,SpatialPoints'
distance(x, y, weight = "meanWeight", ...)

## S4 method for signature 'goc,matrix'
distance(x, y, weight = "meanWeight", ...)

## S4 method for signature 'goc,numeric'
distance(x, y, weight = "meanWeight", ...)

Arguments

Value

A list object giving a distance matrix for each threshold in the GOC object. Distance matrices give the pairwise grains of connectivity network distances between sampling locations. Matrix indices correspond to rows in the coordinates matrix (y).

Author(s)

Paul Galpern and Alex Chubaty

References

Fall, A., M.-J. Fortin, M. Manseau, D. O'Brien. (2007) Spatial graphs: Principles and applications for habitat connectivity. Ecosystems 10:448:461.

Galpern, P., M. Manseau. (2013a) Finding the functional grain: comparing methods for scaling resistance surfaces. Landscape Ecology 28:1269-1291.

Galpern, P., M. Manseau. (2013b) Modelling the influence of landscape connectivity on animal distribution: a functional grain approach. Ecography 36:1004-1016.

Galpern, P., M. Manseau, A. Fall. (2011) Patch-based graphs of landscape connectivity: a guide to construction, analysis, and application for conservation. Biological Conservation 144:44-55.

Galpern, P., M. Manseau, P.J. Wilson. (2012) Grains of connectivity: analysis at multiple spatial scales in landscape genetics. Molecular Ecology 21:3996-4009.

See Also

GOC(), point()

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features=1
tinyPatchMPG <- MPG(cost = tinyCost, patch = tinyCost == 1)
## Extract a representative subset of 5 grains of connectivity
tinyPatchGOC <- GOC(tinyPatchMPG, nThresh = 5)
## Three sets of coordinates in the study area
loc <- cbind(c(30, 60, 90), c(30, 60, 90))

## Find the GOC network distance matrices between these points
## for each of the 5 grains of connectivity
tinyDist <- grainscape::distance(tinyPatchGOC, loc)

Description

This function automates the export of raster and vector spatial data from mpg and grain objects. By default it places them in a new directory, unless an existing one is specified with overwrite = TRUE.

It can also be used to process mpg and grain objects to produce R spatial objects that are convenient for plotting or analysis within R. Use R = TRUE in which case all parameters related to file export are ignored. (Default R = FALSE)

The raster::writeRaster() is used for rasters, and sf::st_write() is used to export ESRI compatible shape files.

Usage

export(
  x,
  dirname = NULL,
  path = ".",
  rasterFormat = "GTiff",
  overwrite = FALSE,
  R = FALSE,
  vorBound = FALSE,
  ...
)

## S4 method for signature 'mpg'
export(
  x,
  dirname = NULL,
  path = ".",
  rasterFormat = "GTiff",
  overwrite = FALSE,
  R = FALSE,
  vorBound = FALSE,
  ...
)

## S4 method for signature 'grain'
export(
  x,
  dirname = NULL,
  path = ".",
  rasterFormat = "GTiff",
  overwrite = FALSE,
  R = FALSE,
  vorBound = FALSE,
  ...
)

## S4 method for signature 'goc'
export(
  x,
  dirname = NULL,
  path = ".",
  rasterFormat = "GTiff",
  overwrite = FALSE,
  R = FALSE,
  vorBound = FALSE,
  ...
)

Arguments

Value

Invisibly returns the path to the folder created.

Side effect of exporting files representing raster and vector spatial data in the object.

Please note that for vector data export the attribute name is limited to 8 characters in shape files. See the tables below for the abbreviations used and their meaning.

Exported from mpg objects:

nodes, linksCentroid, linksPerim are shape files giving the locations of the patch centroids, links among centroids, and links among perimeters of patches respectively. ⁠patchId, voronoi⁠ are rasters giving the patch identifier of the patch, or of the patch that the Voronoi polygon refers to. ⁠lcpPerimWeight, lcpLinkId⁠ give the weight in cost surface units of the shortest paths between perimeters, and the identifiers of those links respectively. vorBound gives the boundaries of the Voronoi polygons (if specified).

Description of node (vertex) and link (edge) weights in mpg objects and their corresponding attribute names in the shape files created.

Exported from grain objects:

⁠nodes, linksCentroid⁠ are shape files giving the locations of the Voronoi polygon centroids and links among them respectively. voronoi are rasters gives the polygon identifier of each cluster of patches. vorBound gives the boundaries of the Voronoi polygons (if specified).

Description of node (vertex) and link (edge) weights in grain objects and their corresponding attribute names in the shape files created.

Author(s)

Paul Galpern and Alex Chubaty

See Also

MPG(), GOC(), grain()

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features=1
tinyPatchMPG <- MPG(cost = tinyCost, patch = tinyCost == 1)
## Extract a representative subset of 5 grains of connectivity
tinyPatchGOC <- GOC(tinyPatchMPG, nThresh = 5)
## Export rasters and vectors and place in an R object
sp_tinyPatchGOC <- export(grain(tinyPatchGOC, 2), R = TRUE)  # nolint
sp_tinyPatchMPG <- export(tinyPatchMPG, R = TRUE) # nolint

## Export raster and vectors to a specified directory
exportPath <- tempdir()
export(grain(tinyPatchGOC, 2), dirname = "tiny_goc_thresh2", path = exportPath)
export(tinyPatchMPG, dirname = "tiny_mpg", path = exportPath, vorBound = TRUE)

## clean up
unlink(file.path(exportPath, "tiny_goc_thresh2"), recursive = TRUE)
unlink(file.path(exportPath, "tiny_mpg"), recursive = TRUE)

Description

This is an informal fortify-type method that prepares either RasterLayer or igraph objects contained as slots within MPG or grain objects for easy plotting with ggplot().

Usage

ggGS(x, type = NULL, ...)

## S4 method for signature 'RasterLayer'
ggGS(x, type = NULL, ...)

## S4 method for signature 'list'
ggGS(x, type = NULL, ...)

## S4 method for signature 'mpg'
ggGS(x, type = NULL, ...)

## S4 method for signature 'grain'
ggGS(x, type = NULL, ...)

## S4 method for signature 'goc'
ggGS(x, type = NULL, ...)

Arguments

Value

A data.frame suitable for plotting with ggplot().

Where type is a raster the data.frame will have the following columns:

value

the value of the raster cell

x

the x coordinate of the centre of the raster cell

y

the y coordinate of the centre of the raster cell

Where type = 'nodes' the data.frame will have the following columns:

x

the x coordinate of the node

y

the y coordinate of the node

...

other attributes associated with the network nodes

Where type = 'links' the data.frame will have the following columns:

x1

the x coordinate of the first node

y1

the y coordinate of the first node

x2

the x coordinate of the second node

y2

the y coordinate of the second node

x1p

the x coordinate at the perimeter of the first node

y1p

the y coordinate at the perimeter of the first node

x2p

the x coordinate at the perimeter of the second node

y2p

the y coordinate at the perimeter of the second node

...

other attributes associated with the network links

Note

Options for type parameter

If a RasterLayer is supplied type is optional.

For mpg type options are "node" or "links". This prepares the nodes and links of the minimum planar graph network for plotting, Also "patchId", "voronoi", "lcpPerimWeight", "lcpLinkId", "mpgPlot" will prepare rasters for plotting.

For grain objects type options are "nodes" or"links" to prepare the nodes and links of the grains of connectivity network for plotting. Also "voronoi" will prepare the grains of connectivity Voronoi polygons raster for plotting.

For either mpg or grain objects type = "vorBound" will identify the boundaries of the Voronoi polygons for plotting. This is potentially time consuming for large rasters.

Author(s)

Paul Galpern and Alex Chubaty

See Also

MPG(), GOC()

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features=1
tinyPatchMPG <- MPG(cost = tinyCost, patch = tinyCost == 1)
## Extract a representative subset of 5 grains of connectivity
tinyPatchGOC <- GOC(tinyPatchMPG, nThresh = 5)
if (interactive()) {
  library(ggplot2)

  ## Plot the patches in a minimum planar graph
  theme_set(theme_grainscape())
  ggplot() +
    geom_tile(data = ggGS(tinyPatchMPG, "patchId"),
              aes(x = x, y = y, fill = value))

  ## Plot the grain polygons in a grain of connectivity
  ggplot() +
    geom_tile(data = ggGS(grain(tinyPatchGOC, 3), "voronoi"),
              aes(x = x, y = y, fill = value))

  ## Plot the grain polygon boundaries
  ggplot() +
    geom_tile(data = ggGS(grain(tinyPatchGOC, 3), "vorBound"),
              aes(x = x, y = y, fill = value))

  ## Plot the patches and perimeter links of a minimum planar graph
  ggplot() +
    geom_tile(data = ggGS(tinyPatchMPG, "patchId"),
              aes(x = x, y = y, fill = value)) +
    geom_segment(data = ggGS(tinyPatchMPG, "links"),
                 aes(x = x1p, y = y1p, xend = x2p, yend = y2p))

  ## Plot the patches and linear representations of the perimeter links
  ## of a minimum planar graph
  ggplot() +
    geom_tile(data = ggGS(tinyPatchMPG, "patchId"),
              aes(x = x, y = y, fill = value)) +
    geom_segment(data = ggGS(tinyPatchMPG, "links"),
                 aes(x = x1p, y = y1p, xend = x2p, yend = y2p))

  ## Plot the nodes and links of a grains of connectivity network
  ## superimposed over the grain polygons
  focalGrain <- grain(tinyPatchGOC, 3)
  ggplot() +
    geom_tile(data = ggGS(focalGrain, "vorBound"),
              aes(x = x, y = y, fill = value)) +
    geom_point(data = ggGS(focalGrain, "nodes"),
               aes(x = x, y = y)) +
    geom_segment(data = ggGS(focalGrain, "links"),
                 aes(x = x1, y = y1, xend = x2, yend = y2))
}

Description

Produce a grains of connectivity (GOC) model at multiple scales (resistance thresholds) by scalar analysis. Patch-based or lattice GOC modelling can be done with this function.

Usage

GOC(x, ...)

## S4 method for signature 'mpg'
GOC(
  x,
  nThresh = NULL,
  doThresh = NULL,
  weight = "lcpPerimWeight",
  verbose = 0,
  ...
)

Arguments

Details

Grain or scalar analysis of connectivity may be appropriate for a variety of purposes, not limited to visualization and improving connectivity estimates for highly-mobile organisms. See Galpern et al. (2012), Galpern & Manseau (2013a, 2013b) for applications and review of these capabilities.

Value

A goc() object.

Note

Researchers should consider whether the use of a patch-based GOC or a lattice GOC model is appropriate based on the patch-dependency of the organism under study. Patch-based models make most sense when animals are restricted to, or dependent on, a resource patch. Lattice models can be used as a generalized and functional approach to scaling resistance surfaces.

See MPG() for warning related to areal measurements.

Author(s)

Paul Galpern

References

Fall, A., M.-J. Fortin, M. Manseau, D. O'Brien. (2007) Spatial graphs: Principles and applications for habitat connectivity. Ecosystems 10:448:461.

Galpern, P., M. Manseau. (2013a) Finding the functional grain: comparing methods for scaling resistance surfaces. Landscape Ecology 28:1269-1291.

Galpern, P., M. Manseau. (2013b) Modelling the influence of landscape connectivity on animal distribution: a functional grain approach. Ecography 36:1004-1016.

Galpern, P., M. Manseau, A. Fall. (2011) Patch-based graphs of landscape connectivity: a guide to construction, analysis, and application for conservation. Biological Conservation 144:44-55.

Galpern, P., M. Manseau, P.J. Wilson. (2012) Grains of connectivity: analysis at multiple spatial scales in landscape genetics. Molecular Ecology 21:3996-4009.

See Also

MPG(), grain(), distance(), point()

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features=1
tinyPatchMPG <- MPG(cost = tinyCost, patch = tinyCost == 1)
## Extract a representative subset of 5 grains of connectivity
tinyPatchGOC <- GOC(tinyPatchMPG, nThresh = 5)
## Examine the properties of the GOC graph of grain 3 of 5
graphdf(grain(tinyPatchGOC, whichThresh = 3))

## Extract grains of connectivity
## representation of the finest grain and three others
## by giving thresholds in link weights (doThresh)
tinyPatchGOC <- GOC(tinyPatchMPG, doThresh = c(0, 20, 40))

Description

The goc class

Slots

voronoi

A RasterLayer describing the regions of proximity in resistance units around the focal patches or points.

summary

A summary of the the grains of connectivity generated and their properties.

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(). 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(s)

Alex Chubaty and Paul Galpern

Description

Extract a grain (i.e. a scaled version of a Voronoi tessellation) from a GOC model.

Usage

grain(x, ...)

## S4 method for signature 'goc'
grain(x, whichThresh, ...)

Arguments

Value

A list object containing the following elements:

summary

gives the properties of the specified scale/grain whichThresh of the GOC model;

voronoi

a RasterLayer giving the Voronoi tessellation the specified scale/grain whichThresh of the GOC model;

centroids

a SpatialPoints objects giving the centroids of the polygons in the Voronoi tessellation at the specified scale/grain whichThresh;

th

a igraph object giving the graph describing the relationship among the polygons at the specified scale/grain whichThresh

Author(s)

Paul Galpern and Alex Chubaty

References

Fall, A., M.-J. Fortin, M. Manseau, D. O'Brien. (2007) Spatial graphs: Principles and applications for habitat connectivity. Ecosystems 10:448:461.

Galpern, P., M. Manseau. (2013a) Finding the functional grain: comparing methods for scaling resistance surfaces. Landscape Ecology 28:1269-1291.

Galpern, P., M. Manseau. (2013b) Modelling the influence of landscape connectivity on animal distribution: a functional grain approach. Ecography 36:1004-1016.

Galpern, P., M. Manseau, A. Fall. (2011) Patch-based graphs of landscape connectivity: a guide to construction, analysis, and application for conservation. Biological Conservation 144:44-55.

Galpern, P., M. Manseau, P.J. Wilson. (2012) Grains of connectivity: analysis at multiple spatial scales in landscape genetics. Molecular Ecology 21:3996-4009.

See Also

GOC()

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features=1
tinyPatchMPG <- MPG(cost = tinyCost, patch = tinyCost == 1)
## Extract a representative subset of 5 grains of connectivity
tinyPatchGOC <- GOC(tinyPatchMPG, nThresh = 5)
## Very quick visualization at the finest scale/grain/threshold
tinyPatchGOCgrain <- grain(tinyPatchGOC, whichThresh = 1)
if (interactive())
  plot(tinyPatchGOCgrain, col = topo.colors(10))

## Visualize the model at the finest scale/grain/threshold
## Manual control of plotting
if (interactive()) {
  plot(grain(tinyPatchGOC, whichThresh = 1)@voronoi,
       col = sample(rainbow(100)), legend = FALSE, main = "Threshold 1")
}

Description

The grain class

Slots

voronoi

A RasterLayer describing the regions of proximity in resistance units around the focal patches or points.

summary

A summary of the the grains of connectivity generated and their properties.

centroids

A SpatialPoints object indicating the grain's polygon centroids.

th

A list of igraph objects giving the graphs describing the relationship among the polygons in that grain

See grain() for more information.

Author(s)

Alex Chubaty and Paul Galpern

Description

Intended for users to explore the functionality of the package using simple and artificial land cover maps. These maps have four or five discrete land cover classes (integers from 1 to 5) intended to represent distinct land cover types. Typical analyses begin by reclassifying these to reflect resistance to movement.

Format

raster

Details

patchy.asc

A caricatured map of four land cover classes, where patches are large and easy to identify polygonal regions for heuristic purposes. This unrealistic map can be used to illustrate the method and understand how it works. The map also serves a similar heuristic purpose in a review of graph-based connectivity methods (Galpern et al., 2011). (400 x 400 raster cells.)

fragmented.asc

A simulated land cover map with five land cover classes using an algorithm that produces fragmentation. (400 x 400 raster cells.)

tiny.asc

Similar to fragmented.asc but smaller in extent for lightning-fast computation and experimental use. (100 x 100 raster cells.)

Description

Produce a data.frame containing the node (vertex) and link (edge) structure as well as the associated attributes for these. This provides an easy way to create data tables describing graphs, particularly helpful for users unfamiliar with the structure of igraph objects.

Usage

graphdf(x, ...)

## S4 method for signature 'list'
graphdf(x, ...)

## S4 method for signature 'goc'
graphdf(x, ...)

## S4 method for signature 'grain'
graphdf(x, ...)

## S4 method for signature 'mpg'
graphdf(x, ...)

## S4 method for signature 'igraph'
graphdf(x, ...)

Arguments

Value

A list object containing:

v

node (vertex) names and associated attributes;

e

link (edge) lists and associated attributes.

Please see MPG() and GOC() for details about the attributes.

For GOC() objects which typically contain multiple thresholds, an enumerated list of the same length as the number of thresholds is returned each containing v and e elements.

Author(s)

Paul Galpern and Alex Chubaty

See Also

MPG(), GOC()

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features=1
tinyPatchMPG <- MPG(cost = tinyCost, patch = tinyCost == 1)
## Extract a representative subset of 5 grains of connectivity
tinyPatchGOC <- GOC(tinyPatchMPG, nThresh = 5)
## Create a data.frame with the structure and attributes of a MPG object
tinyPatchMPG_df <- graphdf(tinyPatchMPG) # nolint

## Create a data.frame with the structure and attributes of a GOC object
tinyPatchGOC_df <- graphdf(tinyPatchGOC) # nolint

## Create a data.frame with the structure and attributes of any igraph object
graphdf(tinyPatchGOC@th[[1]]$goc)

Description

These have been deprecated and will be removed in a future release.

Usage

gsGOC(
  mpg,
  nThresh = NULL,
  doThresh = NULL,
  weight = "lcpPerimWeight",
  sp = FALSE,
  verbose = 3
)

gsGOCCorridor(GOC, whichThresh, coords, doPlot = FALSE, weight = "meanWeight")

gsGOCDistance(GOC, coords, weight = "meanWeight")

gsGOCPoint(GOC, coords)

gsGOCVisualize(GOC, whichThresh, sp = FALSE, doPlot = FALSE)

visualize(GOC, whichThresh, sp = FALSE, doPlot = FALSE)

gsGraphDataFrame(x)

gsMPG(cost, patch, sa = NULL, filterPatch = NULL, spreadFactor = 0)

Arguments

Note

the sp argument has also been deprecated from all functions.

Description

These functions have removed from grainscape.

Usage

gsMPGstitch(...)

Arguments

Description

Extracts a minimum planar graph (MPG) and is also the first step in grains of connectivity (GOC) modelling. Both patch-based and lattice MPGs can be extracted.

Usage

MPG(cost, patch, ...)

## S4 method for signature 'RasterLayer,RasterLayer'
MPG(cost, patch, ...)

## S4 method for signature 'RasterLayer,numeric'
MPG(cost, patch, ...)

Arguments

Details

Use this function to create a minimum planar graph (MPG) that can be further analyzed using igraph() routines. It is also the first step in grains of connectivity (GOC) modelling.

Value

A mpg() object.

Note

Researchers should consider whether the use of a patch-based MPG or a lattice MPG model is appropriate based on the patch-dependency of the organism under study. Patch-based models make most sense when animals are restricted to, or dependent on, a resource patch. Lattice models can be used as a generalized and functional approach to scaling resistance surfaces.

Rasters should be projected and not in geographic coordinates (i.e. projection(cost) should not contain "+proj=longlat") or the function will issue a warning. In unprojected cases consider using projectRaster() to change to an appropriate coordinate system for the location and extent of interest that balances both distance and areal accuracy. See https://www.spatialreference.org/ for location-specific suggestions. Use of geographic coordinates will result in inaccurate areal and distance measurements, rendering the models themselves inaccurate.

Author(s)

Paul Galpern, Sam Doctolero, Alex Chubaty

References

Fall, A., M.-J. Fortin, M. Manseau, D. O'Brien. (2007) Spatial graphs: Principles and applications for habitat connectivity. Ecosystems 10:448:461.

Galpern, P., M. Manseau. (2013a) Finding the functional grain: comparing methods for scaling resistance surfaces. Landscape Ecology 28:1269-1291.

Galpern, P., M. Manseau. (2013b) Modelling the influence of landscape connectivity on animal distribution: a functional grain approach. Ecography 36:1004-1016.

Galpern, P., M. Manseau, A. Fall. (2011) Patch-based graphs of landscape connectivity: a guide to construction, analysis, and application for conservation. Biological Conservation 144:44-55.

Galpern, P., M. Manseau, P.J. Wilson. (2012) Grains of connectivity: analysis at multiple spatial scales in landscape genetics. Molecular Ecology 21:3996-4009.

See Also

⁠[GOC], [threshold]⁠

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features=1
tinyPatchMPG <- MPG(cost = tinyCost, patch = tinyCost == 1)
## Explore the graph structure and node/link attributes
graphdf(tinyPatchMPG)

## Find the mean patch area (see igraph manual for use of V() and E())
mean(igraph::V(tinyPatchMPG@mpg)$patchArea)

## Quick visualization of the MPG
if (interactive())
  plot(tinyPatchMPG, col = c("grey", "black"), legend = FALSE)

## Additional graph extraction scenarios
## Produce a lattice MPG where focal points are spaced 10 cells apart
tinyLatticeMPG <- MPG(cost = tinyCost, patch = 10)
if (interactive())
  plot(tinyLatticeMPG)

Description

The mpg class

Slots

mpg

The minimum planar graph as class igraph.

patchId

The input patch raster with patch cells assigned to their id (RasterLayer).

voronoi

The Voronoi tessellation of the patches and resistance surface (RasterLayer).

lcpPerimWeight

The paths of the links between patches and their accumulated costs (RasterLayer).

lcpLinkId

The paths of the links between patches and their id (RasterLayer).

mpgPlot

A RasterLayer 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(s)

Alex Chubaty and Paul Galpern

Description

Pre-process patch rasters prior to their use with MPG().

Usage

patchFilter(x, cells = NULL, area = NULL, ...)

## S4 method for signature 'RasterLayer'
patchFilter(x, cells = NULL, area = NULL, ...)

Arguments

Details

It examines a binary raster to identify all patches or clumps of cells with values ⁠=1⁠, determines their area, and returns a binary raster where only patches of area greater than or equal to the specified amount are represented.

This is helpful when analyzing habitat connectivity models where patches represent a land cover or habitat type. For example, a raster may have patches of a certain habitat type of insufficient area to support the ecological process of interest. Another use case is remote sensing classification errors that have introduced artifacts. Filtering can help in both cases.

Value

A binary raster where all patches (i.e. clumped areas ⁠=1⁠) are greater than the specified area.

Author(s)

Paul Galpern and Alex Chubaty

See Also

MPG()

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features = 10
## and all patches are greater than or equal to 2 cells in size
filteredPatch <- patchFilter(tinyCost == 10, cells = 2)
tinyPatchMPG <- MPG(cost = tinyCost, patch = filteredPatch)
if (interactive()) plot(tinyPatchMPG)

## Compare to removal of patches greater than or equal to 40 cells in size!
filteredPatch <- patchFilter(tinyCost == 10, cells = 40)
tinyPatchMPG <- MPG(cost = tinyCost, patch = filteredPatch)
if (interactive()) plot(tinyPatchMPG)

## Use a rook/castle 4-direction case rather than the queen 8-direction case
## to identify neighbouring cells in a patch
filteredPatch <- patchFilter(tinyCost == 10, cells = 40, directions = 4)
tinyPatchMPG <- MPG(cost = tinyCost, patch = filteredPatch)
if (interactive()) plot(tinyPatchMPG)

Description

Plot quick visualizations of mpg, grain, and corridor objects.

This function is intended to get a quick look at the state of a grainscape object by rendering what are likely to be the most universally useful visualizations of the spatial data within these objects.

Much more control is available using ggGS() with ggplot() enabling the layering of different different analytical products, and the visualization of node and link attributes.

For high-resolution visualization and the greatest level of control use export() to export spatial objects for cartographic representation in a geographic information system (GIS).

Usage

## S4 method for signature 'corridor,ANY'
plot(x, y, quick = NULL, print = TRUE, theme = TRUE, ...)

## S4 method for signature 'grain,ANY'
plot(x, y, quick = NULL, print = TRUE, theme = TRUE, ...)

## S4 method for signature 'mpg,ANY'
plot(x, y, quick = NULL, print = TRUE, theme = TRUE, ...)

Arguments

Value

   Invisibly, a `ggplot2` object to which additional `ggplot`
           geoms and adjustments can be applied. Has the side effect of
           rendering the plot, unless `print = FALSE`.

Types of visualization available with the quick parameter

"mpgPerimPlot" gives a a vector rendering of the minimum planar graph with vector links connecting the perimeters of the patches. This doesn't accurately represent the sinuosity of paths of the links between patches but offers a good approximation that renders better at large extents. Default for mpg objects. Not available for other objects.

"mpgPlot" gives a raster-only rendering of the minimum planar graph where patchId are positive integers, and linkId are negative integers showing the shortest paths between patches Only available for mpg objects.

"network" gives a vector rendering of the minimum planar graph or the grains of connectivity network with nodes and links plotted at the patch or polygon centroid locations. Available for mpg and grain objects. Default for grain objects.

"grainPlot" gives a raster and vector rendering of the grains of connectivity network with nodes and links plotted at polygon centroid locations, superimposed over the boundaries of the Voronoi polygons. Can be time consuming on large rasters due to the Voronoi boundary extraction. Only available for grain objects.

"corridorPlot" renders the output of a corridor() analysis. It is the only option available with corridor objects and the default.

Author(s)

Alex Chubaty and Paul Galpern

See Also

ggGS(), export(), corridor, grain, mpg

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features=1
tinyPatchMPG <- MPG(cost = tinyCost, patch = tinyCost == 1)
## Extract a representative subset of 5 grains of connectivity
tinyPatchGOC <- GOC(tinyPatchMPG, nThresh = 5)
if (interactive()) {
  library(ggplot2)

  ## MPG and showing simplified links among the perimeters of patches
  plot(tinyPatchMPG)

  ## MPG showing links among the nodes of connected patches
  plot(tinyPatchMPG, quick = "network")

  ## MPG showing the shortest paths between patches actually used to
  ## to calculate link weight values
  plot(tinyPatchMPG, quick = "mpgPlot")

  ## A grain of connectivity network plot with Voronoi boundaries
  plot(grain(tinyPatchGOC, 3), quick = "grainPlot")

  ## Capture plot output for further processing with ggplot
  g <- plot(tinyPatchMPG, print = FALSE, theme = FALSE)
  g <- g + theme_minimal() + ggtitle("Minimum planar graph") +
    theme(plot.title = element_text(size = 20, hjust = 0.5)) +
    theme(legend.position = "none") +
    xlab("Easting") + ylab("Northing")
  g

  ## To change aesthetics it is best to build the plot from scratch
  ## using grainscape::ggGS(). See examples therein.
}

Description

Identify the polygon containing a location at multiple scales.

Usage

point(x, ...)

## S4 method for signature 'goc'
point(x, coords, ...)

Arguments

Value

A list with elements:

pointPolygon

a matrix with elements giving the id of the polygon from the goc, where rows give points of interest and columns give thresholds;

pointTotalPatchArea

is a matrix with elements giving the area of patches in a polygon (in cell counts), where rows give points of and columns give thresholds;

pointTotalCoreArea

the same for core area of patches;

pointECS

gives the patch area (in cell counts) averaged for all points of interest (defined by O'Brien et al., 2006);

pointECSCore

is the same for the core area of patches.

Note

See MPG() for warning related to areal measurements.

Author(s)

Paul Galpern and Alex Chubaty

References

Fall, A., M.-J. Fortin, M. Manseau, D. O'Brien. (2007) Spatial graphs: Principles and applications for habitat connectivity. Ecosystems 10:448:461.

Galpern, P., M. Manseau. (2013a) Finding the functional grain: comparing methods for scaling resistance surfaces. Landscape Ecology 28:1269-1291.

Galpern, P., M. Manseau. (2013b) Modelling the influence of landscape connectivity on animal distribution: a functional grain approach. Ecography 36:1004-1016.

Galpern, P., M. Manseau, A. Fall. (2011) Patch-based graphs of landscape connectivity: a guide to construction, analysis, and application for conservation. Biological Conservation 144:44-55.

Galpern, P., M. Manseau, P.J. Wilson. (2012) Grains of connectivity: analysis at multiple spatial scales in landscape genetics. Molecular Ecology 21:3996-4009.

O'Brien, D., M. Manseau, A. Fall, and M.-J. Fortin. (2006) Testing the importance of spatial configuration of winter habitat for woodland caribou: An application of graph theory. Biological Conservation 130:70-83.

See Also

GOC(), distance()

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features=1
tinyPatchMPG <- MPG(cost = tinyCost, patch = tinyCost == 1)
## Extract a representative subset of 5 grains of connectivity
tinyPatchGOC <- GOC(tinyPatchMPG, nThresh = 5)
## Three sets of coordinates in the study area
loc <- cbind(c(30, 60, 90), c(30, 60, 90))

## Find the GOC polygon containing these three locations
## for each of the 5 grains of connectivity
tinyPts <- point(tinyPatchGOC, loc)

Description

Custom show method to safely print the contents of a goc or grain object.

Usage

## S4 method for signature 'goc'
show(object)

## S4 method for signature 'grain'
show(object)

## S4 method for signature 'corridor'
show(object)

Arguments

Description

A ggplot2() theme designed for grainscape based on the ggthemes::theme_map() theme, with several modifications.

Usage

theme_grainscape(base_size = 9, base_family = "")

Arguments

Value

A theme suitable for use with ggplot()

Author(s)

Paul Galpern and Alex Chubaty

See Also

ggGS(), plot(), ggthemes::theme_map()

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features=1
tinyPatchMPG <- MPG(cost = tinyCost, patch = tinyCost == 1)
if (interactive()) {
  library(ggplot2)

  ## Plot the patches in a minimum planar graph
  theme_set(theme_grainscape())
  plot(tinyPatchMPG, quick = "mpgPlot")
}

Description

Perform a scalar analysis of a minimum planar graph (MPG) by building the graph at a series of link thresholds. As the threshold value increases more nodes in the graph become connected, forming increasingly fewer components, until the graph becomes connected (e.g., Brooks, 2003). N.B. Grains of connectivity (GOC) done by GOC() is also a scalar analysis using Voronoi tessellations rather than patches (see Galpern et al., 2012).

Usage

threshold(x, ...)

## S4 method for signature 'mpg'
threshold(x, weight = "lcpPerimWeight", nThresh = NULL, doThresh = NULL, ...)

Arguments

Value

A list object with the following elements:

summary

summarizes the thresholded graphs generated and their properties;

th

a list of length nThresh or length(doThresh) giving the thresholded graph (class igraph) at each threshold.

Note

See MPG() for warning related to areal measurements.

Author(s)

Paul Galpern and Alex Chubaty

References

Brooks, C.P. (2003) A scalar analysis of landscape connectivity. Oikos 102:433-439.

Fall, A., M.-J. Fortin, M. Manseau, D. O'Brien. (2007) Spatial graphs: Principles and applications for habitat connectivity. Ecosystems 10:448:461.

Galpern, P., M. Manseau. (2013a) Finding the functional grain: comparing methods for scaling resistance surfaces. Landscape Ecology 28:1269-1291.

Galpern, P., M. Manseau. (2013b) Modelling the influence of landscape connectivity on animal distribution: a functional grain approach. Ecography 36:1004-1016.

Galpern, P., M. Manseau, A. Fall. (2011) Patch-based graphs of landscape connectivity: a guide to construction, analysis, and application for conservation. Biological Conservation 144:44-55.

Galpern, P., M. Manseau, P.J. Wilson. (2012) Grains of connectivity: analysis at multiple spatial scales in landscape genetics. Molecular Ecology 21:3996-4009.

See Also

MPG()

Examples

## Load raster landscape
tiny <- raster::raster(system.file("extdata/tiny.asc", package = "grainscape"))

## Create a resistance surface from a raster using an is-becomes reclassification
tinyCost <- raster::reclassify(tiny, rcl = cbind(c(1, 2, 3, 4), c(1, 5, 10, 12)))
## Produce a patch-based MPG where patches are resistance features=1
tinyPatchMPG <- MPG(cost = tinyCost, patch = tinyCost == 1)
## Threshold this graph at a representative subset of 10 thresholds
tinyThresh <- threshold(tinyPatchMPG, nThresh = 10)

## Examine the properties of one of these threshold graphs
print(tinyThresh$th[[7]], vertex = TRUE, edge = TRUE)