Skip to contents

Calculate range sizes for multiple species

calc_range_size.Rd

This function calculates the range sizes (sq km) of multiple species by retrieving occurrence data from GBIF, generating convex hulls, and clipping them to continent boundaries. It uses parallel processing to handle multiple species efficiently.

Usage

calc_range_size(
  data_frame,
  species_col = "species_name",
  num_cores = 1,
  min_points = 5,
  min_distance = 1,
  gbif_limit = 2000,
  continent_file = NULL
)

Arguments

data_frame

A data.frame containing scienfic names of species with a column named species_name.

species_col

A character string indicating the column in data_frame that contains species names. Default is "species_name".

num_cores

The number of cores to use for parallel processing. Default is 1 (no parallel processing).

min_points

The minimum number of points required to form a range cluster. Default is 5.

min_distance

The minimum distance between points in a range cluster. Default is 1 epsilon (eps).

gbif_limit

The maximum number of GBIF records to retrieve per species. Default is 2000.

continent_file

Optional path or URL to a GeoJSON or shapefile (.shp and .shx) containing continent or country boundaries. If NULL (default), Natural Earth continent data is retrieved via get_continent_sf().

Value

A data.frame with two columns:

  • species_col — species name.

  • range_size — total range size in square kilometers.

Details

This function wraps the following internal steps:

  1. Retrieves GBIF occurrence data via get_range_convex_hulls().

  2. Reads continent boundaries via get_continent_sf() or from a user-supplied file.

  3. Clips convex hull polygons to land boundaries using clip_polygons_to_land().

  4. Calculates total polygon area (km²) per species using range_sizes().

Parallelization is handled via future and future.apply. Each species is processed independently and requires internet accesss.

Examples

# Generate a test dataframe with species Abies cephalonica
if (FALSE) { # \dontrun{
test_data <- data.frame(species = c("Abies cephalonica"))

# Generate range sizes for each speices
range_size <- calc_range_size(data_frame = test_data, min_points = 4, species_col = "species")
print(range_size)
} # }