Assign rarity types based on rarity restriction

This function classifies species into discrete rarity types based on combinations rarity axes characterizing restrictions of the global model of discretized rarity. It uses k-means clustering or percentile-based thresholding to determine the rarity of each dimension of rarity (+ for rare and - for common).

Usage

assign_rarity_types(
  df,
  models_to_run,
  slope_factor = 1,
  thresholds = list(GR = 0.15, GL = 0.15, FR = 0.9, FL = 0.9, PR = 0.9, PL = 0.9),
  directions = list(GR = "low", GL = "low", FR = "high", FL = "high", PR = "high", PL =
    "high"),
  k_means = FALSE
)

Arguments

df

A data frame containing species-level rarity dimensions. Must include one row per species and columns matching the axes listed in thresholds and/or models_to_run.

models_to_run

A character vector of restrictions. Custom model names are parsed dynamically.

slope_factor

A numeric value passed to find_optimal_k() for determining the optimal number of k clusters based on the steepness of the slope. Default is 1.

thresholds

A named list of numeric values representing the percentile cutoff for each axis. Default thresholds mark the bottom 15% for geographic rarity and the top 10% for functional and phylogenetic rarity. Custom dimensions of rarity must be thresholded by user.

directions

A named list specifying whether rarity is associated with "low" or "high" values for each dimension If unspecified, the function defaults to "low" for "GR" and "GL", and "high" for all other axes. Users can specify only a subset of axes to override the defaults.

k_means

Logical; if TRUE, thresholds are computed using k-means clustering instead of percentile cutoffs.

Value

A data frame with species-level rarity classifications. This includes raw values and rarity flags for each axis and rarity classifications for each restriction.

Details

Thresholds can be derived either by percentile cutoffs or k-means clustering, controlled by k_means. K-means clustering is only applied if the axis has at least 5 non-NA values; otherwise, percentile cutoffs are used as fallback. Missing values (NAs) in axis data are ignored during threshold calculations. Composite rarity labels are generated by passing each species' axis flags through map_est_types().

See also

map_est_types, find_optimal_k, rename_model_columns, check_eco_status for related classification utilities.

Author

Alivia G. Nytko, anytko@vols.utk.edu

Examples

if (FALSE) { # \dontrun{
data <- data.frame(
  species = c("Species1", "Species2", "Species3"),
  GR = c(0.02, 0.6, 0.1),
  FR = c(0.95, 0.2, 0.91),
  PR = c(0.92, 0.3, 0.85)
)

classified <- assign_rarity_types(
  df = data,
  models_to_run = c("GRFR", "EER"),
  slope_factor = 1,
  k_means = FALSE,
  thresholds = list(GR = 0.15, GL = 0.15,
                                 FR = 0.75, FL = 0.9,
                                 PR = 0.90, PL = 0.90),
  directions = list(PR = "low")
)
print(classified)
} # }