rangemap_boundaries: Species distributional ranges based on administrative...
In rangemap: Simple Tools for Defining Species Ranges

Description Usage Arguments Details Value Examples

rangemap_boundaries generates a distributional range for a given species by considering all the polygons of administrative entities in which the species has been detected. 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_boundaries(occurrences, adm_areas, country_code, boundary_level = 0,
                    polygons, extent_of_occurrence = TRUE,
                    area_of_occupancy = TRUE, keep_data = FALSE,
                    dissolve = FALSE, final_projection, save_shp = FALSE,
                    name, overwrite = FALSE, verbose = TRUE)

`occurrences`	(optional) a data.frame containing geographic coordinates of species occurrences, columns must be: Species, Longitude, and Latitude. Geographic coordinates must be in decimal degrees (WGS84). If not defined, `adm_areas` must be defined and these areas will be used as part of the species range.
`adm_areas`	(optional, character) a vector of names of administrative areas known to be occupied by the species, names depend on the `boundary_level` selected. Check `adm_area_names` for an idea of how to define names in this parameter. If not defined, `occurrences` must exist.
`country_code`	(optional, character) vector of country codes that will be considered when creating the species range. Including neighbor countries may be necessary to obtain better results. Use `rangemap_explore` for a preview of all potential countries involved in the analysis. Codes follow the ISO-3166-1 norm as in function `getData`. If not defined, `polygons` must be included. Ignored if `polygons` is provided.
`boundary_level`	(numeric) level of the administrative boundaries (from 0 to 2; 0 is the country level and higher values indicate finer divisions). Default = 0. Ignored if `polygons` is defined.
`polygons`	(optional) a SpatialPolygonsDataFrame object that will be used instead of boundaries specified in `country_code` to create species ranges based on overlapping of species records with these layer, as well as names defined in `adm_areas`. Projection must be WGS84 (EPSG:4326). If `adm_areas` is defined, `polygons` must have, as part of its data, a field (column) named "adm_names" for selecting extra areas based on names. If `polygons` is defined, arguments `country_code` and `boundary_level` will be ignored.
`extent_of_occurrence`	(logical) whether to obtain the extent of occurrence of the species based on a simple convex hull polygon; default = `TRUE`.
`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 = `TRUE`.
`keep_data`	(logical) if `TRUE` and `polygons` is not defined, data downloaded from the GADM data base will be kept in the working directory. Useful if all or part of the downloaded files will be used in posterior analyses since those files will not be downloaded again and time will be saved. Default = `FALSE`.
`dissolve`	(logical) if `TRUE`, distinct polygons selected as part of the species range will be dissolved for creating simpler shapes, default = `FALSE`. Owing to the high resolution in the GADM data the dissolving process may be time consuming, specially if the species has a broad distribution.
`final_projection`	(character) string of projection arguments for resulting Spatial objects. Arguments must be as in the PROJ.4 documentation. See `CRS-class` for details. If `NULL`, the default, projection used is WGS84 (EPSG:4326).
`save_shp`	(logical) if `TRUE`, shapefiles of the species range, occurrences, extent of occurrence, and area of occupancy will be written in the working directory. Default = `FALSE`.
`name`	(character) valid if `save_shp` = `TRUE`. The name of the shapefile to be exported. A suffix will be added to `name` depending on the object, as follows: species extent of occurrence = "_extent_occ", area of occupancy = "_area_occ", and occurrences = "_unique_records".
`overwrite`	(logical) whether or not to overwrite previous results with the same name. Default = `FALSE`.
`verbose`	(logical) whether or not to print messages about the process. Default = TRUE.

Data for countries defined in country_code are downloaded and loaded using the function getData. Information about country codes and names of administrative areas, at distinct levels, can be consulted using: country_codes and adm_area_names.

A sp_range object (S4) containing: (1) a data.frame with information about the species range, and SpatialPolygons objects of (2) unique occurrences, (3) species range, (4) extent of occurrence, and (5) area of occupancy.

If only adm_areas are defined, the result will be a sp_range object (S4) with two elements: (1) a data.frame with information about the species range, and (2) a SpatialPolygons object of the species range.

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.

If downloading data based on country_code fails, the result is NULL.

# getting the data
data("occ_d", package = "rangemap")

# checking which countries may be involved in the analysis
rangemap_explore(occurrences = occ_d)

# preparing arguments
level <- 0
adm <- "Ecuador" # Athough no record is on this country, we know it is in Ecuador
countries <- c("PER", "BRA", "COL", "VEN", "ECU", "GUF", "GUY", "SUR", "BOL")

# running using occurrence data
b_range <- rangemap_boundaries(occurrences = occ_d, adm_areas = adm,
                               country_code = countries, boundary_level = level)

summary(b_range)

# running using only names of areas
adm1 <- c("Brazil", "Ecuador", "Peru", "Bolivia", "Colombia", "Venezuela")
b_range1 <- rangemap_boundaries(adm_areas = adm1, country_code = countries,
                                boundary_level = level)

summary(b_range1)