gsMPG: Extract a minimum planar graph (MPG) model from a landscape...
In grainscape: Grains of connectivity and minimum planar graph modelling of landscape connectivity (Windows only)

Description Usage Arguments Details Value Note Author(s) References See Also Examples

This function is used to extract a minimum planar graph (MPG) and it is also the first step in grains of connectivity (GOC) modelling. Both patch-based and lattice MPGs can be extracted. The function calls SELES, a Windows-based executable distributed with the package, to extract the graph.

1 2	gsMPG(cost, patch, sa = NULL, outputFolder = NULL, filterPatch = NULL, spreadFactor = 0, selesPath = system.file("SELES", package = "grainscape"))

`cost`	A raster of class `RasterLayer` giving a landscape resistance surface, where the values of each raster cell are proportional to the resistance to movement, dispersal, or gene flow for an organism in the landscape feature they represent. Missing values `NA` are acceptable (but see below). Negative values are not. To extract an MPG with Euclidean links (i.e. and not least-cost path links) set `cost[] <- 1`.
`patch`	A raster of class `RasterLayer` for a patch-based analysis OR an integer for a lattice analysis. If a raster is given it must be of the same extent, origin and projection as `cost` and be binary, without missing values, where patches=1 and non-patches=0. For lattice analyses, an integer gives the spacing in raster cells between focal points in the lattice.
`sa`	Optional. A raster of class `RasterLayer` of the same extent, origin and projection as `cost` indicating the study area (i.e. cells on the landscape to include in the analysis). If not supplied `sa` is the full extent of `cost`. To mask out areas of the landscape to exclude from analysis (e.g. at the edges of a map), supply a binary raster where included cells=1 and excluded cells=0.
`outputFolder`	Optional. If not supplied this function creates files for use by `SELES` in a temporary folder placed in the R working directory that is deleted following successful execution. Another location may be specified instead. If supplied the location is not deleted after the analysis completes. This can be useful for debugging purposes.
`filterPatch`	Optional. Remove patches from the analysis that are smaller than a given number of cells.
`spreadFactor`	Optional. Fine-grained control over the accuracy of Voronoi polygons. To reduce accuracy and increase speed, set this as `spreadFactor=10` or `spreadFactor=100`.
`selesPath`	Optional. The location of the `SELES` installation. By default this is the folder in the package installation.

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.

A gsMPG object, consisting of a list of objects.

The main elements:
$mpg is the minimum planar graph as class igraph
$patchId is the input patch raster with patch cells assigned to their id (RasterLayer)
$voronoi is the Voronoi tessellation of the patches and resistance surface (RasterLayer)
$lcpPerimWeight gives the paths of the links between patches and their accumulated costs (RasterLayer)
$lcpLinkId gives the paths of the links between patches and their id (RasterLayer)
$lcpPerimType gives the paths of the links between patches and their type (RasterLayer; see notes)
$mpgPlot provides a quick way of visualizing the mpg (RasterLayer)

The $mpg has 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.

SELES has been compiled for Windows. Therefore use of gsMPG is limited to Windows-based platforms.

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.

Four types of links are identified in the MPG (1=Nearest neighbour; 2=Minimum spanning tree; 3=Gabriel; 4=Delaunay;)

Areal measurements are given as raster cell counts. If the raster projection is one where cell sizes are approximately constant in area (e.g. UTM), or the raster covers a relatively small geographic extent (e.g. < 1000 km in dimension) areal measurements will often be adequate. Reprojection of rasters should be considered to minimize these effects in other cases (see projectRaster).

Paul Galpern (pgalpern@gmail.com), Andrew Fall

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, P.J. Wilson. (2012) Grains of connectivity: analysis at multiple spatial scales in landscape genetics. Molecular Ecology 21:3996-4009.

gsGOC, gsThreshold

## Not run: 

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

## Create a resistance surface from a raster using an is-becomes reclassifyification
tinyCost <- 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 <- gsMPG(cost=tinyCost, patch=tinyCost==1)

## Explore the graph structure and node/link attributes
gsGraphDataFrame(tinyPatchMPG)

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

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

## Visualize the minimum spanning tree of the MPG
plot(tinyPatchMPG$patchId, col="black", legend=FALSE)
plot(tinyPatchMPG$lcpPerimType %in% c(1,2), add=TRUE, legend=FALSE, col=c(NA, "grey"))

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

## Produce a patch-based MPG with a study area consisting of half of the map
tinySa <- tinyCost
tinySa[] <- 1
tinySa[1:5000] <- 0
tinyPatchMPG <- gsMPG(cost=tinyCost, patch=tinyCost==1, sa=tinySa)


## End(Not run)