Compute Order-wise Metrics — compute

This function computes metrics for ecological data across specified order levels. It supports single-site, pairwise, and higher-order calculations, and allows for parallel processing for efficiency.

Usage

compute_orderwise(
  df,
  func,
  site_col,
  sp_cols = NULL,
  order = 2,
  sample_no = NULL,
  sample_portion = 1,
  parallel = TRUE,
  n_workers = parallel::detectCores() - 1
)

Arguments

df

A data frame containing the ecological data.

func

A function to compute metrics. It must accept inputs in the form of species vectors or site information depending on the order.

site_col

A character string specifying the column name in df representing site IDs.

sp_cols

A vector of column names in df representing species data (default: NULL).

order

An integer or vector of integers specifying the order(s) of computation.

1: Single-site computations.
2: Pairwise computations.
>= 3: Higher-order computations.

sample_no

An integer specifying the maximum number of combinations to sample for higher-order computations (default: NULL for all combinations).

sample_portion

A numeric value between 0 and 1 indicating the proportion of combinations to sample for higher-order computations (default: 1, meaning 100%).

parallel

A logical value indicating whether to enable parallel computation (default: TRUE).

n_workers

An integer specifying the number of parallel workers to use (default: one less than the number of available cores).

Value

A data.table containing the results of computations. Columns include:

site_from: The source site.
site_to: The target site(s) (NA for order = 1).
order: The computation order.
value: The computed metric value.

Examples

# Example usage with a custom metric function
metric_func = function(vec1, vec2 = NULL) {
  if (is.null(vec2)) {
    return(sum(vec1))  # Example: species richness
  } else {
    return(sum((vec1 - vec2)^2))  # Example: pairwise dissimilarity
  }
}

data = data.frame(
  site = rep(letters[1:3], each = 3),
  sp1 = c(1, 0, 2, 1, 2, 0, 0, 1, 1),
  sp2 = c(0, 1, 1, 2, 0, 0, 1, 0, 2)
)

# SPECIES RICHNESS
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
richness = function(vec_from, vec_to = NULL) {
 if (is.null(vec_to)) {
   # Handle single-site calculations (order = 1)
   return(sum(vec_from != 0, na.rm = TRUE))
 } else if (length(vec_from) > 1 && length(vec_to) > 1) {
   # Handle pairwise or higher-order comparisons
   return(abs(sum(vec_from != 0, na.rm = TRUE) - sum(vec_to != 0, na.rm = TRUE)))
 } else {
   # Invalid input case
   return(NA)
 }
}

rich_o12 = compute_orderwise(
 df = block_sp,
 func = richness,
 site_col = 'grid_id',
 sp_cols = sp_cols,
 # sample_no = 1000,
 # sample_portion = 0.5,  # Default is 1 (100%)
 order = 1:2,  # Compute for pairwise and higher-order comparisons
 parallel = TRUE,
 n_workers = 4
)
#> Error: object 'block_sp' not found
head(rich_o12)
#> Error: object 'rich_o12' not found