Species distributional ranges based on trend surface analyses

Source: R/rangemap_tsa.R

rangemap_tsa generates a distributional range for a given species using a trend surface analysis. An approach to the species extent of occurrence (using convex hulls) and the area of occupancy according to the IUCN criteria is also generated. Shapefiles can be saved in the working directory if it is needed.

rangemap_tsa(occurrences, region_of_interest, cell_size = 5,
             threshold = 0, simplify = FALSE, simplify_level = 0,
             extent_of_occurrence = TRUE, area_of_occupancy = TRUE,
             final_projection = NULL, save_shp = FALSE,
             save_ts_layer = FALSE, name, overwrite = FALSE, verbose = TRUE)

Arguments

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).
region_of_interest

a SpatialPolygonsDataFrame object on which the trend surface analysis will be performed. For instance, a country, an ecoregion, or a biogeographic region. Projection must be WGS84 (EPSG:4326).
cell_size

(numeric) vector of length 1 or 2, defining the size of cells (km) at which the resultant trend surface will be created; default = 5. cell_size will depend on the extent of region_of_interest. Values lower than 1 are only recommended when the species is locally distributed.
threshold

(numeric) percentage of occurrence records to be excluded when deciding the minimum value trend surface output to be considered as part of the species range. Default = 0.
simplify

(logical) if TRUE, polygons of suitable areas will be simplified at a tolerance defined in simplify_level. Default = FALSE.
simplify_level

(numeric) tolerance at the moment of simplifying polygons created using the trend surface model. Lower values will produce polygons more similar to the original geometry. Default = 0. If simplifying is needed, try numbers between 0 and 1 first.
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.
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.
save_ts_layer

(logical) if TRUE, the TSA layer will be included as part of the object returned. If save_shp = TRUE, the TSA layer will be written in GeoTiff format. Default = FALSE
name

(character) valid if save_shp = TRUE. The name of the geographic files 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", occurrences = "_unique_records", and, if save_ts_layer = TRUE, trend surface layer "_tsa".
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.

Value

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 save_ts_layer = TRUE, a (6) TSA layer will be included as well.

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.

Details

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.

Trend surface analysis is a method based on low-order polynomials of spatial coordinates for estimating a regular grid of points from scattered observations. This method assumes that all cells not occupied by occurrences are absences; hence its use depends on the quality of data and the certainty of having or not a complete sampling of the regiong_of_interest.

Examples

# data
data("occ_f", package = "rangemap")

CU <- simple_wmap("simple", regions = "Cuba")

# running
tsa_range <- rangemap_tsa(occurrences = occ_f, region_of_interest = CU,
                          cell_size = 5)

#> Warning: CRS object has comment, which is lost in output

summary(tsa_range)

#> 
#>                       Summary of sp_range_iucn object
#> ---------------------------------------------------------------------------
#> 
#> Species range derived from:	TSA 
#> 
#>               Species Unique_records Range_area Extent_of_occurrence
#>  Peltophryne fustiger             18       6825             1630.968
#>  Area_of_occupancy
#>                 48
#> 
#> 
#> 
#> Other contents:
#> 
#>                        Length Class                    Mode
#> species_range           1     SpatialPolygonsDataFrame S4  
#> species_unique_records 18     SpatialPointsDataFrame   S4  
#> extent_of_occurrence    1     SpatialPolygonsDataFrame S4  
#> area_of_occupancy      12     SpatialPolygonsDataFrame S4