eco.buffer: Ecological Buffer Tool
In bwcompton/eco.buffer: Delineates Ecologically-Defined Buffers Around Target Conservation Areas

eco.buffer

R Documentation

Ecological Buffer Tool

Description

Delineates ecologically-defined buffers around target conservation areas using a resistant kernel

Usage

eco.buffer(
  seeds,
  bandwidth,
  seedid = "Id",
  result = NULL,
  resultgrid = NULL,
  resist = NULL,
  resist.table = NULL,
  default.resist = NULL,
  landcover = "",
  barrier = NULL,
  passage = NULL,
  resist.mult = 1,
  resist.table.mult = 1,
  barrier.mult = 1,
  passage.mult = 1,
  save.resist = NULL,
  path = "",
  density = 1,
  expand = NULL,
  screen = NULL,
  broccoli = NULL,
  flow = NULL,
  accumulation = NULL,
  streams = NULL,
  clip = NULL,
  fullextent = FALSE,
  simplify = TRUE,
  simplify.tolerance = 30,
  verbose = TRUE,
  timing = FALSE
)

Arguments

`seeds`	a shapefile of points, lines, or polygons designating conservation targets
`bandwidth`	maximum distance (m) to spread through cells of resistance = 1.
`seedid`	name of numeric ID column in seeds shapefile.
`result`	name of result polygon shapefile of ecological buffers.
`resultgrid`	name of result kernel grid (optional). If resultgrid is supplied, a graduated kernel representation. of buffers will be created, useful for exploring parameterization and visualizing kernel-creation process.
`resist`	landscape resistance grid. Optional if landcover and resist.table are used to assign resistance by landcover type. Resistance values should range from 1 to infinity. Use resist.mult to invert positive grids.
`resist.table`	optional tab-delimited text file. Defines resistance value for each landcover class (ranging from 1 to infinity). Columns must include class (numeric landcover class) and resist (resistance value); additional columns may include landcover name for reference (highly recommended) and comments. Resistance ranges from 1 to infinity. If both resist and resist.table are supplied, the values from the resist raster will be used for values that are absent in the table.
`default.resist`	value to use for classes not included in table, or NULL to throw error if any values in landcover are missing from table. Nodata cells (outside of the landscape) always get a high resistance.
`landcover`	landcover grid. May be used to designate resistance values with resist.table; also used with screen option.
`barrier`	grid with resistance values for barriers, used as a complement to resist or resist.table, the maximum resistance of resist/resist.table will be used for each cell. Use to supply values for aquatic barriers (bridges, culverts, and dams), with nodata for other cells.
`passage`	grid with resistance values for cells that provide passage, reducing resistance, used as a complement to resist or resist.table. The minimum of resist/resist.table and passage will be used for each cell. Use to supply terrestrial passage over or under roads (bridges and wildlife passage structures), with nodata for other cells.
`resist.mult`	multiplier on resistance grid, such that such that resistance values that originally range from 0 to n or 1 to n will range from 1 to approximately n * resist.mult after multiplying. Use a negative multiplier to invert the resistances when using a positive grid, where higher values denote lower resistance. The minimum and maximum resistances are needed for this procedure. They are obtained from the entire raster before any clipping. If you are running on tiled data, or data that otherwise don't represent the entire range of resistance values, you need to supply the overall minimum and maximum as the 2nd and 3rd elements. The default multiplier is 1, thus resistance values are used directly (or 1 is added if the minimum is 0).
`resist.table.mult`	multiplier on resistances from a table. See resist.mult.
`barrier.mult`	multiplier on barrier resistances. See resist.mult.
`passage.mult`	multiplier on passage resistances. See resist.mult.
`save.resist`	specify a result TIFF to write the realized resistance grid to, for assessing complex combinations of resistance sources.
`path`	base path prepended to input and result names/paths. Inputs that include a complete path (starting with / or a drive letter) don't use path. This option helps keep the inputs cleaner, and makes for easy switching to different sets of inputs and results.
`density`	build kernels for every nth cell to speed things up. By default, density = 1, and resistant kernels are built from each edge cell in seeds; a larger value will decrease runtime (by density2) at the cost of precision. You can get away with higher values for density when using larger bandwidths.
`expand`	distance to expand seeds (m). Use with screen to apply lines to wide streams, for example. If expanded seeds overlap, the overlapping area will be arbitrarily assigned the seedid of one of the seeds.
`screen`	limit seeds to these landcover classes (requires landcover). Use this if seeds are sloppy, e.g. when designating stream cores from vector data that don't correspond exactly to streams in landcover, or to exclude development classes from conservation target polygons.
`broccoli`	include entire watershed above point in stream if watershed area at point is <= x km2 (requires flow, accumulation, and streams grids). Used to include the entirety of small watersheds.
`flow`	flow direction grid, used with broccoli option. Grid is a standard D8 grid.
`accumulation`	flow accumulation grid, used with broccoli option.
`streams`	stream centerline grid, used with the broccoli option.
`clip`	a polygon shapefile to clip the analysis to. Use this when developing parameters and testing to speed runs up immensely.
`fullextent`	if TRUE, produces a result grid at the full extent of the landscape. This runs more slowly, so use the default of FALSE unless you have a good reason not to. If TRUE, all grids are clipped to the reference grid (landcover if it exists, otherwise, reference grid) to enforce alignment.
`simplify`	if TRUE, simplify result polygons; if FALSE, polygons exactly match raster.
`simplify.tolerance`	polygon smoothing parameter used if simplify = TRUE. Larger values give simpler polygons.
`verbose`	set to FALSE to suppress informational chatter.
`timing`	display overall timing message if TRUE, and also intermediate timing messages if 'all' (verbose must be TRUE too).

Details

The ecological buffer tool eco.buffer is a stand-alone R package for delineating ecologically-defined buffers around target conservation areas. Targeted areas are designated by point, line, or polygon shapefiles. Buffers are based on resistant kernels with flexible parameters to accommodate terrestrial or aquatic settings. Landscape resistance can be defined by a landcover raster and a table of classes and resistance values, directly from resistance rasters, or from a combination of a resistance table and rasters. Results are a polygon shapefile of ecological buffers and an optional geoTIFF raster of the resistant kernels.

The buffer tool is based on resistant kernels (Compton et. al 2007), which have been used in a number of conservation applications since 2003, including estimating local and regional connectivity (McGarigal et al. 2018) and building terrestrial and aquatic conservation cores in Designing Sustainable Landscapes/Nature's Network (McGarigal et al. 2017); they have also been used in TNC's Resilient Sites for Terrestrial Conservation and Massachusetts Natural Heritage's Living Waters and BioMap 2.

Notes

Resistance values must range from 1 to infinity. The spread value starts in each focal cell (all edge cells of each seed) at bandwidth / cell size. At each cell, the cell's resistance x multiplier is subtracted from the spread value. For example, a bandwidth of 5000 m when the cell size is 30 m gives a spread value of 166.67. The spread will stop once it has passed through cells with a cumulative resistance * multiplier of 166.67. Resistances greater than or equal to this value will stop the spread at a single cell, thus these cells act as complete barriers.
Raster inputs may be either Arc grids or geoTIFFs (other formats will likely work).
The seeds shapefile may be singlepart or multipart.
The seed id field (specified with the seedid option) will be preserved in the resulting buffer polygon. When result buffers overlap, the id of the seed with a shortest cost-distance to each point will be used.
When using the CAPS landcover for terrestrial cores, make sure to set the resistance of classes 60 (Bridge or culvert) and 61 (Dam) to the maximum road resistance, as these classes interrupt roads, thus with a lower resistance, they can allow a kernel to spread across roads where they occur.
When using the CAPS landcover for aquatic cores, you may want to use the Aquatic Barriers (abarriers) grid as a secondary resistance grid using the barriers option, to assign resistance to each bridge or culvert and each dam based on estimates of their aquatic passability.
If both a resistance raster (resist option) and resistance table (resist.table and landcover options) are supplied, the table is used for all classes in the table, and the raster is used for any classes not in the table (default.resist will be ignored).
When testing and developing parameters, runtime will be much faster if you limit seeds to a relatively small geographic area, or use the clip option select a small area of the landscape.
All input grids will be snapped and clipped to the reference grid–the landcover, if supplied, or else the resistance grid.
When using the broccoli option with a flow accumulation grid in terms of cells (as is the CAPS grid), convert to km^2 with 1e6 / cellsize ^ 2. For a 30 m grid, use flow accumulation / 1111 to get km^2.
Note that when using polygons as seeds, tiny or skinny polygons that cover less than half of a cell may not be properly captured when converting seeds to raster. eco.buffer ensures that at least the centroid (moved inside of the polygon) will be captured, but long polygons that are narrower than a cell may be represented by only a single cell or a disjunct series of cells. It's always good practice to use the resultgrid option to save a raster version of the result, and look at cells with a value of 1.0 to see where the seed polygons ended up in the raster representation.

References

Compton, B.W., K. McGarigal, S.A. Cushman, and L.R. Gamble. 2007. A resistant-kernel model of connectivity for amphibians that breed in vernal pools. Conservation Biology 21:788-799. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1111/j.1523-1739.2007.00674.x")}.

McGarigal, K., B.W. Compton, E.B. Plunkett, W.V. DeLuca, J. Grand, E. Ene, and S.D. Jackson. 2018. A landscape index of ecological integrity to inform landscape conservation. Landscape Ecology 33:1029-1048. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1007/s10980-018-0653-9")}.

McGarigal K., B.W. Compton, E.B. Plunkett, W.V. DeLuca, and J. Grand. 2017. Designing sustainable landscapes: landscape conservation design. Report to the North Atlantic Conservation Cooperative, US Fish and Wildlife Service, Northeast Region. http://landeco.umass.edu/web/lcc/dsl/technical/DSL_documentation_landscape_design.pdf

Author

Bradley W. Compton bcompton@umass.edu

Examples

### Set up temporary directory for examples
require(eco.buffer)
dp <- paste(shortPathName(system.file('exampledata', package='eco.buffer')), '/.', sep = '')
dir <- tempdir()
if(!file.exists(dir)) dir.create(dir)
file.copy(dp, dir, recursive=TRUE)
cat('Example data and results will be in', dir)

### 1. terrestrial kernels (creates test1.shp and testg1.tif)
eco.buffer('seed_points', bandwidth = 2000, landcover = 'capsland.tif',
resist.table = 'resistance.txt', result = 'test1', resultgrid = 'testg1.tif', path = dir)

### 2. WMA poly example (creates WMAtest2.shp)
eco.buffer('wma_seeds', 5000, landcover = 'capsland.tif', resist = 'iei.tif', resist.mult = -30,
     resist.table = 'resist_dev.txt', result = 'WMAtest2', path = dir)

### 3. stream cores (creates stream_test3.tif)
eco.buffer('stream_seeds', bandwidth = 3000, landcover = 'capsland.tif',
     resist.table = 'resist_streams.txt', default.resist = 999, barrier = 'abarriers.tif',
     barrier.mult = 100, result = 'stream_test3', simplify = FALSE, path = dir)

bwcompton/eco.buffer documentation built on Jan. 29, 2024, 1:25 p.m.