Skip to contents

Prepare Restrictions for the Global Model of Discretized Rarity

prepare_gdrarity_models.Rd

This function assesses available data for a given set of species and determines which rarity dimensions and corresponding restrictions can be used to analyze multidimensional rarity. It also supports automated model selection based on data completeness.

Usage

prepare_gdrarity_models(
  species_df,
  abundance_df = NULL,
  phylo = NULL,
  use_internal_phylo = TRUE,
  internal_phylo_name = "ALLMB",
  trait_cols = NULL,
  species_col = "species",
  use_most_complete_model = FALSE,
  model = NULL,
  additional_dimensions = NULL
)

Arguments

species_df

A data frame with at least one column identifying species (default column name is "species").

abundance_df

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

phylo

Optional phylo object representing a phylogenetic tree. If not provided, an internal tree can be used.

use_internal_phylo

Logical; if TRUE (default) and no phylo is provided, the function will attempt to retrieve an internal seed plant phylogeny.

internal_phylo_name

Character; name of the internal tree to use (e.g., "ALLMB").

trait_cols

Optional character vector specifying the names of trait columns in species_df.

species_col

Character; the name of the column in species_df that contains species names (default "species").

use_most_complete_model

Logical; if TRUE, returns only the most complete model available.

model

Optional character vector of specific model codes to restrict the output to. If specified, only these models are returned (if valid). Restrictions are named using rarity dimensions in the following order: geographic (G), functional (F), and phylogenetic (P) at regional (R) and local (L) scales; to run the full global model the code is GRGLFRFLPRPL.

additional_dimensions

Optional character vector of additional column names in species_df to treat as rarity dimensions (e.g., "HabitatType").

Value

An (invisible) list with the following components:

species_df

The processed species data frame.

abundance_df

The original abundance data frame if provided.

trait_cols

The trait column names, if traits were available.

phylo

The pruned phylogenetic tree used, or NULL if none available.

available_axes

Character vector of available rarity axes (e.g., "GR", "FR").

models_to_run

Character vector of restrictions to use based on input data.

Details

The function checks for availability of different rarity dimensions:

  • "GR": Geographic restriction (always available if species list exists).

  • "GL": Geographic local abundance (requires abundance_df).

  • "FR": Functional restriction (requires trait data).

  • "FL": Functional local abundance (requires trait and abundance data).

  • "PR": Phylogenetic restriction (requires a phylogeny).

  • "PL": Phylogenetic local abundance (requires a phylogeny).

Additional rarity dimensions can be provided. The function constructs valid model codes (e.g., "GRFR", "GRGLFRFL", etc.) based on combinations of available axes.

See also

get_phy_angio() for retrieving internal phylogenies.

Examples

if (FALSE) { # \dontrun{
species_df <- data.frame(species = c("Abies_procera", "Alnus_incana"), trait1 = c(1.2, 3.4))
abundance_df <- data.frame(species = c("Abies_procera", "Alnus_incana"), site = c("A", "A"), abundance = c(10, 5))

setup <- prepare_gdrarity_models(
  species_df = species_df,
  abundance_df = abundance_df,
  trait_cols = "trait1",
  use_internal_phylo = TRUE,
  internal_phylo_name = "ALLMB"
)
setup$models_to_run
} # }