Skip to contents

Compute Rarity Dimensions Based on Selected Restrictions

prepare_gdrarity_axes.Rd

This function calculates multiple dimensions of rarity based on a set of rarity restrictions It supports geographic, functional, and phylogenetic rarity axes across both regional and local scales, depending on the availability of trait data, abundance data, and a phylogenetic tree.

Usage

prepare_gdrarity_axes(
  models_to_run,
  species_df,
  species_col = "species",
  abundance_df = NULL,
  phylogeny = NULL,
  geo_rarity_method = c("taxonomic", "range"),
  fun_rarity_method = c("min_distance", "mean_distance", "none"),
  trait_columns = NULL,
  min_dbscan_points = 5,
  min_dbscan_distance = 1,
  gbif_limit = 2000,
  num_cores = 1,
  site_col = "site",
  abundance_col = "abundance",
  time = FALSE,
  time_slices = NULL,
  relative = TRUE,
  abundance = TRUE,
  use_precomputed_axes = FALSE
)

Arguments

models_to_run

Character vector of restrictions (e.g., "GR", "FRFL", "GLFRPR", etc.) specifying which axes to compute.

species_df

Data frame containing species-level information, including traits and optionally precomputed rarity values.

species_col

Name of the column in species_df containing species names. Default is "species".

abundance_df

Optional data frame with species abundance data. Must contain "species", "site", and "abundance" columns.

phylogeny

Optional phylo object for computing phylogenetic distances.

geo_rarity_method

Method for computing regional geographic rarity. Options: "range" for range size via GBIF, or "taxonomic"(default) to use relative occupancy viafunrar`.

fun_rarity_method

Method for regional functional rarity calculation. Options: "min_distance" (default) to use minimum Euclidean distance, "mean_distance" to use mean Euclidean distance, or "none".

trait_columns

Character vector of trait column names used for functional rarity metrics.

min_dbscan_points

Integer for DBSCAN range estimation (minimum points). Default is 5.

min_dbscan_distance

Numeric minimum distance (in degrees) for DBSCAN range estimation. Default is 1.

gbif_limit

Maximum number of GBIF records to download per species (if computing range size). Default is 2000.

num_cores

Number of cores for parallel operations. Default is 1.

site_col

Name of the column representing community or site identity in abundance_df. Default is "site".

abundance_col

Name of the column representing abundance values. Default is "abundance".

time

Logical; if TRUE, time-sliced evolutionary distinctiveness is computed. Default is FALSE.

time_slices

Numeric vector of time slices for calculating time-sliced ED. Used only if time = TRUE.

relative

Logical; whether to scale phylogenetic local distinctiveness (PL) values relative to maximum distance. Default is TRUE.

abundance

Logical; whether to use abundance-weighted PL (phylogenetic local distinctiveness). Default is TRUE. #' @param use_precomputed_axes Logical. If TRUE, the function will use rarity axes already present in species_df for the models specified in models_to_run instead of recomputing them. Additional, non-standard axes (e.g., "H" for habitat specificity) are always passed through automatically if they exist in species_df, regardless of this setting. Default is FALSE.

Value

A data frame containing species and their computed rarity dimensions, one column per axis (e.g., "GR", "FL", "PR").

Details

The function calculates the following axes when requested and data are available:

  • GR – Regional Geographic Rarity (range size or restrictedness)

  • GL – Local Geographic Rarity (from funrar::scarcity_stack())

  • FR – Regional Functional Rarity (minimum or mean trait distance)

  • FL – Local Functional Rarity (from funrar::distinctiveness_stack())

  • PR – Regional Phylogenetic Rarity (evolutionary distinctiveness)

  • PL – Local Phylogenetic Rarity (abundance-weighted or unweighted MPD)

User-defined custom rarity axes (e.g., "H" for habitat specificity) are also supported if present in species_df.

Uses functions from the funrar package. Please cite funrar if this function is used in published work.

See also

prepare_gdrarity_models(), calculate_phylo_mpd(), funrar::scarcity_stack(), funrar::distinctiveness_stack()

Examples

if (FALSE) { # \dontrun{
# Example with simulated species data and traits
species_df <- data.frame(
  species = c("Abies_procera", "Alnus_incana", "Carex_distans"),
  trait1 = c(1.1, 2.3, 3.4),
 trait2 = c(4.1, 3.3, 2.2)
)

abundance_df <- data.frame(
  species = c("Abies_procera", "Alnus_incana", "Abies_procera", "Carex_distans"),
  site = c("A", "A", "B", "B"),
  presence_absence = c(1,1,1,1),
  abundance = c(5, 10, 3, 4)
)

phylo <- ape::rtree(3)
phylo$tip.label <- c("Abies_procera", "Alnus_incana", "Carex_distans")

axes <- prepare_gdrarity_axes(
  models_to_run = c("FR", "FL", "PR", "PL"),
  species_df = species_df,
  abundance_df = abundance_df,
  phylogeny = phylo,
  trait_columns = c("trait1", "trait2"),
  geo_rarity_method = "taxonomic",
  fun_rarity_method = "mean_distance"
)

head(axes)
} # }