gsGOC: Produce a grains of connectivity model at multiple scales...
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

Given a gsMPG object 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.

1 2	gsGOC(gsMPG, nThresh = NULL, doThresh = NULL, weight = "lcpPerimWeight", sp = FALSE, verbose = 3)

`gsMPG`	A `gsMPG` object produced by `gsMPG`. For lattice GOC `gsMPG` must be run with patch set as an integer value.
`nThresh`	Optional. An integer giving the number of thresholds (or scales) at which to create GOC models. Thresholds are selected to produce a maximum number of unique grains (i.e. models). `nThresh` thresholds are also approximately evenly spread between 0 and the threshold at which all patches or focal points on the landscape are connected. This is a simple way to get a representative subset of all possible GOC models. Provide either `nThresh` or `doThresh` not both.
`doThresh`	Optional. A vector giving the link thresholds at which to create GOC models. Use `link{gsThreshold}` to identify thresholds of interest. Provide either `nThresh` or `doThresh` not both.
`weight`	A string giving the link weight or attribute to use for threshold. `"lcpPerimWeight"` uses the accumulated resistance or least-cost path distance from the perimeters of patches as the link weight. `"eucPerimWeight"` use the Euclidean distance from the perimeters of patches as the link weight.
`sp`	Logical. If `TRUE` the `rgeos` package is used to create a vector of class `SpatialPolygonsDataFrame` describing the finest grain of connectivity. This is very useful for visualizing grains of connectivity models, especially for print purposes. Equally, using the `maptools` or `rgdal` packages these polygons can be exported as shapefiles for use in other GIS applications. But, please see details.
`verbose`	Set `verbose=1` for no progress information to console.

This function can take a long time to run when sp=TRUE. Time taken is dependent on the dimensions of the gsMPG$voronoi raster. Also, as of this release (May, 2012) there was still a memory leak in rgeos caused by its parent GEOS library. In extreme circumstances sp=TRUE may fail or cause a crash of the R process.

A gsGOC object, consisting of a list of objects.

The main elements:
$voronoi is a raster describing the regions of proximity in resistance units around the focal patches or points (RasterLayer)
$voronoiSP is a vector representation of these regions of proximity (SpatialPolygons; if sp=TRUE)
$summary summarizes the grains of connectivity generated and their properties
$th is a list of length nThresh or length(doThresh) 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 gsGOCDistance for more information.

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 gsMPG for warning related to areal measurements.

Paul Galpern (pgalpern@gmail.com)

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.

gsMPG, gsGOCVisualize, gsGOCDistance, gsGOCPoint

## 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 reclassifyifyification
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)


## Extract a representative subset of 5 grains of connectivity
tinyPatchGOC <- gsGOC(tinyPatchMPG, nThresh=5)

## Examine the properties of the GOC graph of grain 3 of 5
print(tinyPatchGOC$th[[3]]$goc, vertex=TRUE, edge=TRUE)

## Extract specified grains of connectivity and produce a vector SpatialPolygons
## representation of the finest grain of connectivity (Threshold=0)
tinyPatchGOC <- gsGOC(tinyPatchMPG, doThresh=c(0, 20, 40), sp=TRUE)


## End(Not run)