aHull: aHull: generate alpha hull polygons for multiple-species
In thaisdoria/habitaR: Tools for mapping the species’ area of habitat (AOH) from geospatial data

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

From a set of occurrences records, provides the alpha hull representing the extent of occurrence (EOO) of multiple species which have a minimun of 3 not duplicate records. It is build based on the original function getDynamicAlphaHull from the rangeBuilder package, that determines the α parameter by the spatial distribution of the coordinates.

1
2
3

aHull (occ, crs, distOcc = NULL, fraction = NULL, partCount = NULL,
alphaIncrement = NULL, buff = 0.0, poly = NULL, cropToPoly = FALSE, rasOut = FALSE,
ras = NULL)

`occ`	Occurrences records of the species (coordinates in decimal degrees). 'It might correspond to path for a folder with the species occurrences files (.csv format) a 'list' of 'data.frames' with the occurrences from multiple species (see data examples) a 'list' of of 'SpatialPoints' from multiple species (see data examples) 'spOcc' object corresponding to a list of 'SpatialPoints' from multiple species (see `readOcc` to obtain such object). NOTE: If path is provided, each .csv file should correspond to only one species and the file must be named with the corresponding species names. The files must have 3 columns identified as "species" (species names or other identification of taxa), "long" (longitude), "lat" (latitude). Longitude must be in a column before the latitude column.
`crs`	The Coordinate Reference System (CRS) specifing the projection and datum of dataset. Could be a CRS object or a character string. Only used if 'occ' not correspond to a object from 'SpatialPoints' class.
`distOcc`	A value corresponding to the minimum distance to consider two coordinates as not duplicate. Values up to this distance will correspond to duplicates and removed. Units of this value must be in km. Default is zero (i.e. only exactly coincindent coordinates will be removed). Optional and only used if 'occ' is a path for .csv files or a list of data.frames. If 'occ' correspond to 'SpatialPoints', this argument should be ignored (i.e., distOcc = NULL). For more details, see `remove.duplicates` in the sp package.
`fraction`	The minimum fraction of occurrences that must be included in polygon.
`partCount`	The maximum number of disjunct polygons that are allowed.
`alphaIncrement`	The amount to increase alpha with each iteration.
`buff`	A buffer distance in meters to increase boundaries of alpha hull. Default is zero (0).
`poly`	Optional. A polygon (ESRI shapefile in a 'SpatialPolygonsDataFrame' class) of a given area to be checked for occurrences of species and to restrict the building of alpha hull only to the species occurring inside of the provided polygon. NOTE: this argument does not reduce the set of occurrences based on the poly, but only reduce the species dataset based on its presence inside of poly. See details.
`cropToPoly`	(logical) Whether the output should also include the alpha hull cropped by the provided poly. Only used if 'poly' is provided. Default is `FALSE`.
`rasOut`	(logical) Whether the output should be also include a raster objects. Default is `FALSE`.
`ras`	A raster object (file in .asc or .tif format) to be used as baseline to rasterize the ahull polygons. Only used if rasOut' is `TRUE`.

Based on a set of occurrences records of multiple-species, the function generate alpha hull polygons ('SpatialPolygons' class) by sequentially increasing the value of α parameter (starting from 0 in steps of defined alphaIncrement) until find the smallest value that met the partCount condition and encompass the fraction of occurrences assigned by the user. If poly is provided, the function filter the original species dataset by keeping only those species occurring inside of the specified region. In this case, the construction of alpha hulls will be restricted only to the filtered species, but the extension of these resulting maps can extrapolate the area of 'poly' if the occurrences extend far away beyond the boundaries of 'poly' object. NOTE: if the user want have the alpha hull cropped by the area of poly, 'cropToPoly' should be assign as TRUE, but even in this case, the alpha hull is firstly constructed based on all dataset of occurrences and then cropped by some desired region in a second step. Thus, cropped alpha hulls correspond to the original alpha hull clipped/trinned by some region and not drawn based in a restrict set of occurrences recorded inside of some specific region.

By default, aHull returns a list with two elements:

A data.frame of species and the respective alpha values and number of occurrences (after the removal of duplicate coordinates) used to construct the alpha hull. If the conditions assigned by the user to build the alpha hulls cannot be satisfied, is returned the minimum convex hull (MCH) and the alpha value is identified as 'MCH'.
A 'aHull' object corresponding to a list of species-specific alpha hulls ('SpatialPolygons class).

NOTE: if a poly is provided and cropToPoly is TRUE, aHull also returns a third element from the resulting list:

A 'aHull' object corresponding to a list of species-specific cropped alpha hulls.

Thaís Dória & Daniel Gonçalves-Souza

1. Brugman M.A., and Fox J.C. (2003). Bias in species range estimates from minimum convex polygons: implications for conservation and options for improved planning. Animal Conservation 6:19-28.

2. Capinha C., and Pateiro-López B. (2014). Predicting species distributions in new areas or time periods with alpha-shapes. Ecological Informatics, 24:231–237.

3. Rabosky A.R.D., Cox C.L., Rabosky D.L., Title P.O., Holmes I.A., Feldman A., and McGuire J.A. (2016). Coral snakes predict the evolution of mimicry across New World snakes. Nature Communications 7:11484.

4. Meyer L., Diniz-Filho J.A.F., and Lohmann L.G. (2018). A comparison of hull methods for estimating species ranges and richness maps. Plant Ecology & Diversity, 10(5-6):389-401.

The dynamic alpha hulls drawn from the sequentially increasing of alpha values are created with getDynamicAlphaHull from rangeBuilder package.

### Fictitious plants data

# Example for signature 'DataFrame' (occ).

ahull_plants<-aHull(occ = occ_plants, crs= "+proj=longlat +datum=WGS84 +ellps=WGS84
 +towgs84=0,0,0", distOcc = 0.25, fraction = 1, partCount = 1, alphaIncrement = 1,
 buff = 0, poly = poly, cropToPoly = TRUE, rasOut = TRUE, ras = ras)