R/rangemap_hull.R
rangemap_hull.Rdrangemap_hull generates a distributional range for a given species by creating convex or concave hull polygons based on occurrence data. Optionally, representations of the species extent of occurrence (using convex hulls) and the area of occupancy according to the IUCN criteria can also be generated. Shapefiles can be saved in the working directory if it is needed.
rangemap_hull(occurrences, hull_type = "convex", concave_distance_lim = 5000, buffer_distance = 50000, split = FALSE, cluster_method = "hierarchical", split_distance = NULL, n_k_means = NULL, polygons = NULL, extent_of_occurrence = TRUE, area_of_occupancy = TRUE, final_projection = NULL, save_shp = FALSE, name, overwrite = FALSE, verbose = TRUE)
| occurrences | a data.frame containing geographic coordinates of species occurrences, columns must be: Species, Longitude, and Latitude. Geographic coordinates must be in decimal degrees (WGS84). |
|---|---|
| hull_type | (character) type of hull polygons to be created. Available options are: "convex" and "concave". Default = "convex". |
| concave_distance_lim | (numeric) distance, in meters, to be passed to the
length_threshold parameter of the |
| buffer_distance | (numeric) distance, in meters, to be used for creating a buffer around resulting hull polygons; default = 50000. |
| split | (logical) if |
| cluster_method | (character) name of the method to be used for clustering
the occurrences. Options are "hierarchical" and "k-means"; default =
"hierarchical". Note that this parameter is ignored when |
| split_distance | (numeric) distance in meters that will limit connectivity
among hull polygons created with chunks of points separated by long distances.
This parameter is used when |
| n_k_means | (numeric) if |
| polygons | (optional) a SpatialPolygons* object to clip polygons and
adjust the species range and other polygons to these limits. Projection must
be WGS84 (EPSG:4326). If |
| extent_of_occurrence | (logical) whether to obtain the extent of occurrence
of the species based on a simple convex hull polygon; default = |
| area_of_occupancy | (logical) whether to obtain the area of occupancy
of the species based on a simple grid of 4 km^2 resolution;
default = |
| final_projection | (character) string of projection arguments for resulting
Spatial objects. Arguments must be as in the PROJ.4 documentation. See
|
| save_shp | (logical) if |
| name | (character) valid if |
| overwrite | (logical) whether or not to overwrite previous results with
the same name. Default = |
| verbose | (logical) whether or not to print messages about the process. Default = TRUE. |
A sp_range object (S4) containing: (1) a data.frame with information about the species range, and Spatial objects of (2) unique occurrences, (3) species range, (4) extent of occurrence, and (5) area of occupancy.
If extent_of_occurrence and/or area_of_occupancy = FALSE,
the corresponding spatial objects in the resulting sp_range object will be
empty, an areas will have a value of 0.
All resulting Spatial objects in the results will be projected to the
final_projection. Areas are calculated in square kilometers using the
Lambert Azimuthal Equal Area projection, centered on the centroid of occurrence
points given as inputs.
If split = TRUE, some point clusters may end up having less than
three points, in which cases creating hull polygons is not possible. Such
point clusters will be discarded if buffer_distance = 0. To keep them
as part of the final result, use a buffer_distance > 0.
The cluster_method must be chosen based on the spatial configuration of
the species occurrences. Both methods make distinct assumptions and one of
them may perform better than the other depending on the spatial pattern of the
data.
The k-means method, for example, performs better when the following assumptions are fulfilled: Clusters are spatially grouped—or “spherical” and Clusters are of a similar size. Owing to the nature of the hierarchical clustering algorithm it may take more time than the k-means method. Both methods make assumptions and they may work well on some data sets, and fail on others.
Another important factor to consider is that the k-means method always starts with a random choice of cluster centers, thus it may end in different results on different runs. That may be problematic when trying to replicate your methods. With hierarchical clustering, most likely the same clusters can be obtained if the process is repeated.
For more information on these clustering methods see Aggarwal and Reddy (2014), here.
# \donttest{ # getting the data data("occ_d", package = "rangemap") # other info for running dist <- 100000 hull <- "convex" # try also "concave" hull_range <- rangemap_hull(occurrences = occ_d, hull_type = hull, buffer_distance = dist)#>#> #> Summary of sp_range_iucn object #> --------------------------------------------------------------------------- #> #> Species range derived from: Convex_hull #> #> Species Unique_records Range_area Extent_of_occurrence #> Dasypus kappleri 56 4860934 4095146 #> Area_of_occupancy #> 184 #> #> #> #> Other contents: #>#> Length Class Mode #> species_range 6 SpatialPolygonsDataFrame S4 #> species_unique_records 56 SpatialPointsDataFrame S4 #> extent_of_occurrence 1 SpatialPolygonsDataFrame S4 #> area_of_occupancy 46 SpatialPolygonsDataFrame S4# }