summarize_traits_by_point {commecometrics}R Documentation

Summarize trait distributions at sampling points with optional continent assignment

Description

For each spatial sampling point, this function calculates two metrics specified by the user of a trait across all overlapping species polygons, and calculates richness. Optionally, it assigns each point to a continent using Natural Earth data.

Usage

summarize_traits_by_point(
  points_df,
  trait_df,
  species_polygons,
  comm_metric_1 = function(x) mean(x, na.rm = TRUE),
  comm_metric_2 = function(x) sd(x, na.rm = TRUE),
  trait_column = "trait_name",
  species_name_col = "sci_name",
  continent = FALSE,
  lon_col = "Longitude",
  lat_col = "Latitude",
  parallel = TRUE,
  n_cores = parallel::detectCores() - 1
)

Arguments

points_df

A data frame containing sampling points with columns for longitude and latitude.

trait_df

A data frame of trait data. Must include a column for species names ('TaxonName') and the trait of interest (default = "trait_name").

species_polygons

An sf object containing species distribution polygons. Must include a species name column.

comm_metric_1

A function used to summarize the trait values across overlapping species. Defaults to mean(x, na.rm = TRUE). The function must take a numeric vector as input and return a single numeric value. Can be replaced by any user-defined function, such as max, median, or a custom function.

comm_metric_2

A second function used to summarize trait values. Defaults to sd(x, na.rm = TRUE). Works the same way as summary_trait_1.

trait_column

The name of the trait column in trait_df to summarize.

species_name_col

The name of the column in species_polygons that contains species names (default = "sci_name").

continent

Logical. If TRUE, assigns each sampling point to a continent using the Natural Earth shapefile via rnaturalearth::ne_countries(). If FALSE (default), no continent assignment is performed.

lon_col

Name of the longitude column in points_df. Default is 'Longitude'.

lat_col

Name of the latitude column in points_df. Default is 'Latitude'.

parallel

Logical; whether to parallelize the summarization step (default TRUE).

n_cores

Number of cores to use if parallelizing (default: detectCores() - 1).

Value

A list with two elements:

points

A data frame identical to points_df but with additional columns:

summ_trait_1

Result of applying metric_1 to the trait values of overlapping species (e.g., mean, max, median).

summ_trait_2

Result of applying metric_2 to the trait values of overlapping species (e.g., standard deviation, range).

richness

Number of species overlapping the point (regardless of trait availability).

count_trait

Number of species with non-missing trait values at the point.

continent

(Optional) Continent name assigned from Natural Earth data, if continent = TRUE.

overlap

A list of character vectors, each containing the names of species whose distribution polygons overlap a given sampling point.

Examples


# Load sample data from the package
data("geoPoints", package = "commecometrics")
data("traits", package = "commecometrics")
data("spRanges", package = "commecometrics")

traitsByPoint <- summarize_traits_by_point(
  points_df = geoPoints,
  trait_df = traits,
  species_polygons = spRanges,
  trait_column = "RBL",
  species_name_col = "sci_name",
  continent = FALSE,
  parallel = FALSE
)

head(traitsByPoint$points)



[Package commecometrics version 1.0.0 Index]