reconstruct_env: Reconstruct past environmental conditions using ecometric...

In commecometrics: Ecometric Models of Trait–Environment Relationships at the Community Level

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

fossildata	A data frame containing fossil trait summaries per fossil site. Must include columns corresponding to the same two summary metrics used for modern communities, using the column names specified by fossil_summ_trait_1 and fossil_summ_trait_2.
model_out	Output list from run_ecometric_model(), containing modern data, diagnostics, and model settings.
inv_transform	A function to back-transform environmental estimates to the original scale. Default is exp(x) - 1. If NULL, the inverse transform stored in model_out is used if available.
ci	The width of the interval to calculate around the maximum likelihood estimate (default = 0.05).
match_nearest	Logical; if TRUE, the function matches each fossil to its nearest modern point based on coordinates (default = TRUE).
fossil_lon	Name of the longitude column in fossildata. Required if match_nearest = TRUE.
fossil_lat	Name of the latitude column in fossildata. Required if match_nearest = TRUE.
modern_id	Name of the unique ID column in modern points (e.g., "GlobalID").
modern_lon	Name of the longitude column in modern points. Required if match_nearest = TRUE.
modern_lat	Name of the latitude column in modern points. Required if match_nearest = TRUE.
crs_proj	Coordinate reference system to use when converting fossil and modern data to sf format (default = EPSG:4326).

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"
)

commecometrics documentation built on Aug. 8, 2025, 6:10 p.m.