Internal utilities and global variables

Description

Internal utilities and variable declarations to support NSE and ggplot2 piping.

Run an ecometric model for quantitative environmental variables

Description

Builds an ecometric trait space for quantitative environmental variables, estimating environmental values of each category at each trait bin combination. Also calculates anomalies based on observed values for each point.

Usage

ecometric_model(
  points_df,
  env_var = "env_var",
  transform_fun = function(x) x,
  inv_transform_fun = function(x) x,
  grid_bins_1 = NULL,
  grid_bins_2 = NULL,
  min_species = 3
)

Arguments

Value

A list containing:

Examples

# Load internal dataset
data("geoPoints", package = "commecometrics")
data("traits", package = "commecometrics")
data("spRanges", package = "commecometrics")

# Summarize trait values at sampling points
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
)

# Fit an ecometric model using annual precipitation (BIO12)
modelResult <- ecometric_model(
  points_df = traitsByPoint$points,
  env_var = "precip",
  transform_fun = function(x) log(x + 1),
  inv_transform_fun = function(x) exp(x) - 1,
  min_species = 3
)

# View correlation between predicted and observed values
print(modelResult$correlation)

# View summary of the linear model fit
summary(modelResult$model)

Run an ecometric model for qualitative environmental variables

Description

Builds an ecometric trait space for qualitative environmental variables, estimating the most probable category and the probability of each category at each trait bin combination. Also calculates prediction accuracy and anomalies for each point.

Usage

ecometric_model_qual(
  points_df,
  category_col,
  grid_bins_1 = NULL,
  grid_bins_2 = NULL,
  min_species = 3
)

Arguments

Value

A list containing:

Examples

# Load internal data
data("geoPoints", package = "commecometrics")
data("traits", package = "commecometrics")
data("spRanges", package = "commecometrics")

# Step 1: Summarize trait values at sampling points
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
)

# Step 2: Run ecometric model using land cover class as qualitative variable
modelResult <- ecometric_model_qual(
  points_df = traitsByPoint$points,
  category_col = "vegetation",
  min_species = 3
)

# View the percentage of correctly predicted categories
print(modelResult$prediction_accuracy)

Plot ecometric space for quantitative environmental variables

Description

Visualizes the ecometric space for quantitative environmental variables based on the output from ecometric_model().

Usage

ecometric_space(
  model_out,
  env_name = "env_var",
  fossil_data = NULL,
  fossil_color = "#000000",
  modern_color = "#bc4749",
  palette = c("#bc6c25", "#fefae0", "#606c38"),
  x_label = "Summary metric 1",
  y_label = "Summary metric 2"
)

Arguments

Value

A ggplot2 object visualizing the ecometric trait-environment surface.

Examples

# Load internal data
data("geoPoints", package = "commecometrics")
data("traits", package = "commecometrics")
data("spRanges", package = "commecometrics")
data("fossils", package = "commecometrics")

# Summarize trait values at sampling points
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
)

# Run ecometric model
ecoModel <- ecometric_model(
  points_df = traitsByPoint$points,
  env_var = "precip",
  transform_fun = function(x) log(x + 1),
  inv_transform_fun = function(x) exp(x) - 1,
  min_species = 3
)

# Reconstruct environments for fossil sites
recon <- reconstruct_env(
  fossildata = fossils,
  model_out = ecoModel,
  match_nearest = TRUE,
  fossil_lon = "Long",
  fossil_lat = "Lat",
  modern_id = "ID",
  modern_lon = "Longitude",
  modern_lat = "Latitude"
)

# Plot the ecometric trait–environment space
ecometricPlot <- ecometric_space(
  model_out = ecoModel,
  env_name = "Precipitation (log mm)",
  fossil_data = recon
)

# Display plot
print(ecometricPlot)

Plot ecometric space for qualitative environmental variables

Description

Visualizes the predicted ecometric space (predicted category) and probability maps for each category based on the output from ecometric_model_qualitative().

Usage

ecometric_space_qual(
  model_out,
  category_labels = NULL,
  palette = NULL,
  fossil_data = NULL,
  fossil_color = "#000000",
  modern_color = "#bc4749",
  x_label = "Summary metric 1",
  y_label = "Summary metric 2"
)

Arguments

Value

A list containing:

Examples

# Load internal data
data("geoPoints", package = "commecometrics")
data("traits", package = "commecometrics")
data("spRanges", package = "commecometrics")
data("fossils", package = "commecometrics")

# Summarize trait values at sampling points
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
)

# Run ecometric model for qualitative variable
modelResult <- ecometric_model_qual(
  points_df = traitsByPoint$points,
  category_col = "vegetation",
  min_species = 3
)

# Reconstruct fossil environmental categories
reconQual <- reconstruct_env_qual(
  fossildata = fossils,
  model_out = modelResult,
  match_nearest = TRUE,
  fossil_lon = "Long",
  fossil_lat = "Lat",
  modern_id = "ID",
  modern_lon = "Longitude",
  modern_lat = "Latitude"
)

# Plot qualitative ecometric space
ecoPlotQual <- ecometric_space_qual(
  model_out = modelResult,
  fossil_data = reconQual
)

# Display predicted category map
print(ecoPlotQual$ecometric_space_plot)

# Display one of the probability maps
print(ecoPlotQual$probability_maps[["1"]])

Fossil trait data for projection onto ecometric space

Description

A dataset of fossil sites with estimated trait distribution and geographic coordinates, used to project extinct communities onto modern ecometric space.

Usage

fossils

Format

A data frame with the following columns:

Site

Unique identifier for the fossil sample

fossil_summ_trait_1

Estimated mean of relative blade length for the fossil site

fossil_summ_trait_2

Estimated sd of relative blade length for the fossil site

Long

Longitude coordinate (decimal degrees)

Lat

Latitude coordinate (decimal degrees)

Source

Siciliano-Martina et al. (2024). Ecology and Evolution, 14(10), e70214.

Example climate sampling points

Description

A subset of 100 global sampling points with associated bioclimatic and vegetation variables. All points overlap with species ranges in the spRanges dataset.

Usage

geoPoints

Format

A data frame with the following columns:

ID

Unique identifier for each point

Longitude

Longitude coordinate (decimal degrees)

Latitude

Latitude coordinate (decimal degrees)

temp

Mean annual temperature (°C × 10)

precip

Annual precipitation (mm)

vegetation

Vegetation units (integer code)

Source

Derived from Siciliano-Martina et al. (2024), filtered for overlap with IUCN polygons.

Inspect overlapping species at sampling points

Description

Creates an interactive map to verify species overlap at selected points.

Usage

inspect_point_species(
  traits_summary,
  point_ids = NULL,
  n_random = 10,
  lon_col = "Longitude",
  lat_col = "Latitude",
  ID_col = "ID",
  min_species_valid = 3,
  env_var = NULL
)

Arguments

Value

An interactive leaflet map showing selected points with species list popups.

Examples

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

# Summarize traits at points
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
)

# Visualize a random sample of 10 points
inspect_point_species(
  traits_summary = traitsByPoint,
  n_random = 10,
  min_species_valid = 3
)

Determine optimal number of bins using Scott's Rule

Description

Calculates the optimal number of bins for a numeric vector based on Scott's rule.

Usage

optimal_bins(x)

Arguments

Value

Integer representing the optimal number of bins.

Examples

# Simple example
# Example with normally distributed data
optimal_bins(rnorm(100))

Reconstruct past environmental conditions using ecometric models

Description

Uses fossil community trait summaries to reconstruct past environmental conditions by projecting them onto a binned ecometric trait space built from modern data. Optionally, it also assigns each fossil point to the nearest modern sampling site to retrieve observed environmental data.

Usage

reconstruct_env(
  fossildata,
  model_out,
  inv_transform = NULL,
  ci = 0.05,
  match_nearest = TRUE,
  fossil_lon = NULL,
  fossil_lat = NULL,
  modern_id = NULL,
  modern_lon = NULL,
  modern_lat = NULL,
  crs_proj = 4326
)

Arguments

Value

A data frame (fossildata) with reconstructed environmental values and optional nearest modern point data. Includes the following additional columns:

fossil_bin_1

Assigned bin number for the first trait axis (based on first summary metric of trait distribution of fossil communities).

fossil_bin_2

Assigned bin number for the second trait axis (based on second summary metric of trait distribution of fossil communities).

fossil_env_est

Maximum likelihood estimate of the environmental variable (on transformed scale if applicable).

fossil_minlimit

Lower bound of the confidence interval around the environmental estimate (transformed scale).

fossil_maxlimit

Upper bound of the confidence interval around the environmental estimate (transformed scale).

fossil_env_est_UN

(Optional) Inverse-transformed environmental estimate, on the original scale.

fossil_minlimit_UN

(Optional) Inverse-transformed lower bound of the confidence interval.

fossil_maxlimit_UN

(Optional) Inverse-transformed upper bound of the confidence interval.

nearest_modern_point

(Optional) ID of the nearest modern sampling point (if match_nearest = TRUE).

...

Additional columns from the matched modern site if match_nearest = TRUE (e.g., observed environmental values).

Examples

# Load internal data
data("geoPoints", package = "commecometrics")
data("traits", package = "commecometrics")
data("spRanges", package = "commecometrics")
data("fossils", package = "commecometrics")

# Step 1: Summarize modern trait values at sampling points
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
)

# Step 2: Run an ecometric model with BIO12 (precipitation)
ecoModel <- ecometric_model(
  points_df = traitsByPoint$points,
  env_var = "precip",
  transform_fun = function(x) log(x + 1),
  inv_transform_fun = function(x) exp(x) - 1,
  min_species = 3
)

# Step 3: Reconstruct fossil environments
recon <- reconstruct_env(
  fossildata = fossils,
  model_out = ecoModel,
  match_nearest = TRUE,
  fossil_lon = "Long",
  fossil_lat = "Lat",
  modern_id = "ID",
  modern_lon = "Longitude",
  modern_lat = "Latitude"
)

Reconstruct past qualitative environmental categories using ecometric models

Description

Uses fossil community trait summaries to reconstruct the most likely environmental category by projecting them onto a qualitative ecometric space built from modern data. Optionally, it assigns each fossil point to the nearest modern sampling point.

Usage

reconstruct_env_qual(
  fossildata,
  model_out,
  match_nearest = TRUE,
  fossil_lon = NULL,
  fossil_lat = NULL,
  modern_id = NULL,
  modern_lon = NULL,
  modern_lat = NULL,
  crs_proj = 4326
)

Arguments

Value

A data frame (fossildata) updated with:

fossil_bin_1

Assigned bin number for the first trait axis (based on first summary metric of trait distribution of fossil communities).

fossil_bin_2

Assigned bin number for the second trait axis (based on second summary metric of trait distribution of fossil communities).

fossil_env_est

Predicted environmental category based on trait bin.

fossil_prob_*

Probability of each environmental category for the assigned bin.

nearest_modern_point

(Optional) ID of the nearest modern sampling point (if match_nearest = TRUE).

...

Additional columns from the matched modern site if match_nearest = TRUE.

Examples

# Load internal data
data("geoPoints", package = "commecometrics")
data("traits", package = "commecometrics")
data("spRanges", package = "commecometrics")
data("fossils", package = "commecometrics")

# Step 1: Summarize trait values at sampling points
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
)

# Step 2: Run a qualitative ecometric model (e.g., land cover class)
ecoModelQual <- ecometric_model_qual(
  points_df = traitsByPoint$points,
  category_col = "vegetation",
  min_species = 3
)

# Step 3: Reconstruct qualitative environments for fossil data
reconQual <- reconstruct_env_qual(
  fossildata = fossils,
  model_out = ecoModelQual,
  match_nearest = TRUE,
  fossil_lon = "Long",
  fossil_lat = "Lat",
  modern_id = "ID",
  modern_lon = "Longitude",
  modern_lat = "Latitude"
)

Perform sensitivity analysis on ecometric models (quantitative environmental variables)

Description

Evaluates how varying sample sizes affect the performance of ecometric models, focusing on two aspects:

• Sensitivity (internal consistency): How accurately the model predicts environmental conditions on the same data it was trained on.

• Transferability (external applicability): How well the model performs on unseen data.

It tests different sample sizes by resampling the data multiple times (bootstrap iterations), training an ecometric model on each subset, and evaluating prediction error and correlation.

Usage

sensitivity_analysis(
  points_df,
  env_var,
  sample_sizes,
  iterations = 20,
  test_split = 0.2,
  grid_bins_1 = NULL,
  grid_bins_2 = NULL,
  transform_fun = NULL,
  parallel = TRUE,
  n_cores = parallel::detectCores() - 1
)

Arguments

Details

Four base R plots are generated to visualize model performance as a function of sample size:

1. Training correlation vs. Sample size: Shows how well the model fits training data.

2. Testing correlation vs. Sample size: Shows generalizability to new data.

3. Training mean anomaly vs. Sample size: Shows average prediction error on training data.

4. Testing mean anomaly vs. Sample size: Shows average prediction error on test data.

Parallel processing is supported to speed up the analysis.

Value

A list containing:

Examples

# Load internal data
data("geoPoints", package = "commecometrics")
data("traits", package = "commecometrics")
data("spRanges", package = "commecometrics")

# Summarize trait values at sampling points
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
)

# Run sensitivity analysis using annual precipitation
sensitivityResults <- sensitivity_analysis(
  points_df = traitsByPoint$points,
  env_var = "precip",
  sample_sizes = seq(40, 90, 10),
  iterations = 5,
  transform_fun = function(x) log(x + 1),
  parallel = FALSE  # Set to TRUE for faster performance on multicore machines
)

# View results
head(sensitivityResults$summary_results)

Perform sensitivity analysis on ecometric models (qualitative environmental variables)

Description

Evaluates how varying sample sizes affect the performance of ecometric models, focusing on two aspects:

• Sensitivity (internal consistency): How accurately the model predicts environmental conditions on the same data it was trained on.

• Transferability (external applicability): How well the model performs on unseen data.

It tests different sample sizes by resampling the data multiple times (bootstrap iterations), training an ecometric model on each subset, and evaluating prediction error and correlation.

Usage

sensitivity_analysis_qual(
  points_df,
  category_col,
  sample_sizes,
  iterations = 20,
  test_split = 0.2,
  grid_bins_1 = NULL,
  grid_bins_2 = NULL,
  parallel = TRUE,
  n_cores = parallel::detectCores() - 1
)

Arguments

Details

Two plots are generated:

1. Training Accuracy vs. Sample size: Reflects internal model consistency.

2. Testing Accuracy vs. Sample size: Reflects external model performance.

Parallel processing is supported to speed up the analysis.

Value

A list containing:

Examples

# Load internal data
data("geoPoints", package = "commecometrics")
data("traits", package = "commecometrics")
data("spRanges", package = "commecometrics")

# Summarize trait values at sampling points
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
)

# Run sensitivity analysis for dominant land cover class
sensitivityQual <- sensitivity_analysis_qual(
  points_df = traitsByPoint$points,
  category_col = "vegetation",
  sample_sizes = seq(40, 90, 10),
  iterations = 5,
  parallel = FALSE
)

# View results
head(sensitivityQual$summary_results)

Species distribution polygons for five Carnivora species

Description

A spatial dataset of species range polygons matching the species in the traits dataset.

Usage

spRanges

Format

An sf object with the following columns:

TaxonName

Species name (matching the traits table)

geometry

Polygon geometry representing species distribution

Source

Download from the IUCN Red List webpage (IUCN, 2025).

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

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)

Relative blade length trait data for Carnivora

Description

A dataset of relative blade length (RBL) values for five species in the order Carnivora. These species match those in the spRanges dataset.

Usage

traits

Format

A data frame with the following columns:

TaxonName

Species name (binomial)

RBL

Relative blade length (unitless ratio)

Source

Siciliano-Martina et al. (2024). Ecology and Evolution, 14(10), e70214.