calba (version 0.1.2)

ba_decay: Calculate Basal Area with Decay Function

Description

This function calculates the basal area across a given set of trees, applying a decay effect based on distance and species identity for each tree within a given radius.

Usage

ba_decay(
  mu_values,
  sp,
  gx,
  gy,
  ba,
  r,
  exponential_normal = FALSE,
  edge_correction = c("none", "safe"),
  bounds = NULL
)

Value

A list with two matrices:

`con_ba_matrix`

A numeric matrix of basal areas with decay applied for conspecific (same species) trees.

`total_ba_matrix`

A numeric matrix of basal areas with decay applied for all trees (conspecific + heterospecific).

Arguments

mu_values

A numeric vector of decay parameters. Each value in `mu_values` represents a decay factor that modifies how the basal area contribution diminishes with distance.

sp

A character vector containing species names for each tree.

gx

A numeric vector of x-coordinates for the trees.

gy

A numeric vector of y-coordinates for the trees.

ba

A numeric vector of basal area values for the trees.

r

A numeric scalar representing the radius to consider for neighboring trees.

exponential_normal

A logical value. If `FALSE` (default), use exponential decay. If `TRUE`, use exponential-normal decay.

edge_correction

Character. See `ba_simple()` for the `"safe"` behavior that skips edge trees.

bounds

Optional numeric vector `c(xmin, xmax, ymin, ymax)` giving the plot extent. When `NULL`, the range of `gx`/`gy` is used; supply bounds if your data do not span the full plot.

Details

The function applies an exponential decay model where the basal area contribution diminishes with distance from the focal tree: $$\text{decayed basal area} = \text{ba} \cdot \exp\left(-\frac{\text{dist}}{\mu}\right)$$ where `mu` is the decay parameter, `ba` is the basal area, and `dist` is the Euclidean distance between trees.

Examples

# Generate a sample dataset
set.seed(42)
sample_data <- data.frame(
  latin = sample(letters[1:4], 100, replace = TRUE),
  gx = runif(100, 0, 10),
  gy = runif(100, 0, 10),
  ba = runif(100, 10, 30)
)
mu_values <- c(1, 3, 5, 7)
ba_decay(
  mu_values = mu_values,
  sp = sample_data$latin,
  gx = sample_data$gx,
  gy = sample_data$gy,
  ba = sample_data$ba,
  r = 3,
  exponential_normal = FALSE
)