Package 'calba'

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
)

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.

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

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
)

---

Long-format decay table

Description

Transform the matrices returned by 'ba_decay' into a tidy table that can be joined with other data or mapped with 'ggplot2'.

Usage

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

Arguments

mu_values	Numeric vector of decay parameters.
sp	Character/factor species vector.
gx	Numeric x-coordinates.
gy	Numeric y-coordinates.
ba	Numeric basal area.
r	Positive radius threshold.
exponential_normal	Logical passed to 'ba_decay'.
edge_correction	Character; see 'ba_simple()' for the '"safe"' option.
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.

Value

A data frame with 'tree_id', 'species', 'mu', 'con_ba', and 'total_ba'.

---

Calculate Simple Basal Area

Description

This function calculates the total basal area (conspecific + heterospecific) for a given set of tree data, focusing on the number of focal trees and a radius parameter. The basal area represents the cumulative cross-sectional area of tree trunks, either unadjusted or adjusted for a simple distance-weighted decay model.

Usage

ba_simple(
  sp,
  gx,
  gy,
  ba,
  r,
  dist_weighted = FALSE,
  edge_correction = c("none", "safe"),
  bounds = NULL
)

Arguments

sp	A character vector containing species names for each tree.
gx	A numeric vector of x-coordinates for the trees (e.g., 0 to 10 for realistic spatial data).
gy	A numeric vector of y-coordinates for the trees (e.g., 0 to 10 for realistic spatial data).
ba	A numeric vector of basal area values for the trees (e.g., cross-sectional area at breast height).
r	A numeric scalar for the radius parameter. This parameter represents the maximum distance to consider when summing basal areas of neighboring trees (e.g., 1–5 units for spatially distributed data).
dist_weighted	Logical. If 'TRUE', use the distance-weighted approach ('ba / dist'); if 'FALSE', use the unadjusted 'ba'.
edge_correction	Character. Use '"none"' (default) to return all focal trees or '"safe"' to skip neighborhood calculations for trees within 'r' of the plot edges and mark their output as 'NA'.
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 either: - Calculates the unadjusted basal area if 'dist_weighted = FALSE'. - Applies a simple distance-weighted approach ('ba / dist') if 'dist_weighted = TRUE'.

Value

A list with two numeric vectors:

'con_ba'

A numeric vector representing the cumulative basal area of conspecific trees within the radius.

'total_ba'

A numeric vector representing the cumulative basal area of all trees (conspecific + heterospecific) within the radius.

Examples

# Generate a sample dataset
set.seed(42)  # For reproducibility
sample_data <- data.frame(
  latin = sample(letters[1:4], 100, replace = TRUE),
  gx = runif(100, 0, 10),  # Spatial coordinates between 0 and 10
  gy = runif(100, 0, 10),
  ba = runif(100, 10, 30)  # Basal area between 10 and 30
)

# Calculate with distance weighting
ba_simple(
  sp = sample_data$latin,
  gx = sample_data$gx,
  gy = sample_data$gy,
  ba = sample_data$ba,
  r = 3,  # Radius within the spatial scale
  dist_weighted = TRUE
)

# Calculate without distance weighting
ba_simple(
  sp = sample_data$latin,
  gx = sample_data$gx,
  gy = sample_data$gy,
  ba = sample_data$ba,
  r = 3,
  dist_weighted = FALSE
)

---

Count Conspecific Trees

Description

This function counts the number of conspecific trees within a given radius for each focal tree.

Usage

count_con(sp, gx, gy, r, edge_correction = c("none", "safe"), bounds = NULL)

Arguments

sp	A character vector of species names.
gx	A numeric vector of x-coordinates for the trees.
gy	A numeric vector of y-coordinates for the trees.
r	A numeric scalar for the radius parameter.
edge_correction	Character; see 'ba_simple()' for the '"safe"' option that skips focal trees near the boundary.
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.

Value

A numeric vector containing the count of conspecific trees within the radius for each focal tree.

Examples

sample_data <- data.frame(
  latin = sample(letters[1:4], 100, replace = TRUE),
  gx = runif(100, 0, 10),
  gy = runif(100, 0, 10)
)
count_con(
  sp = sample_data$latin,
  gx = sample_data$gx,
  gy = sample_data$gy,
  r = 3
)

---

Count Total Trees

Description

This function counts the total number of trees within a given radius for each focal tree.

Usage

count_total(gx, gy, r, edge_correction = c("none", "safe"), bounds = NULL)

Arguments

gx	A numeric vector of x-coordinates for the trees.
gy	A numeric vector of y-coordinates for the trees.
r	A numeric scalar for the radius parameter.
edge_correction	Character; see 'ba_simple()' for the '"safe"' option that skips focal trees close to the edges.
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.

Value

A numeric vector containing the count of all trees within the radius for each focal tree.

Examples

sample_data <- data.frame(
  gx = runif(100, 0, 10),
  gy = runif(100, 0, 10)
)
count_total(
  gx = sample_data$gx,
  gy = sample_data$gy,
  r = 3
)

---

Neighborhood summaries for basal area and counts

Description

Provide a tidy summary of pairwise neighborhood basal area and counts, optionally including decay results for a vector of decay parameters.

Usage

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

Arguments

sp	A character or factor vector of species names.
gx	Numeric x-coordinates of each tree.
gy	Numeric y-coordinates of each tree.
ba	Numeric basal area of each tree.
r	Positive numeric radius within which neighbors are considered.
mu_values	Optional numeric vector of decay parameters. When 'NULL', the decay table is omitted.
dist_weighted	Logical flag passed to 'ba_simple' to use a simple 'ba / dist' weighting when 'TRUE'.
exponential_normal	Logical passed to 'ba_decay' to select the exponential-normal kernel.
edge_correction	Character; see 'ba_simple()' for the '"safe"' option that skips edge focal 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.

Value

A list with * 'summary': data frame with 'tree_id', 'species', 'con_ba', 'total_ba', 'con_count', 'total_count'. * 'decay': ('NULL' or) long data frame with 'tree_id', 'species', 'mu', 'con_ba', 'total_ba'.

The 'summary' component also includes derived columns: 'prop_con_ba', 'het_ba', 'het_count', and 'competition_index'.

Examples

sample_data <- data.frame(
  latin = sample(letters[1:4], 10, replace = TRUE),
  gx = runif(10, 0, 10),
  gy = runif(10, 0, 10),
  ba = runif(10, 10, 30)
)
neigh_ba(
  sp = sample_data$latin,
  gx = sample_data$gx,
  gy = sample_data$gy,
  ba = sample_data$ba,
  r = 3,
  mu_values = c(1, 3)
)

---

Neighborhood metrics across multiple radii

Description

Compute basal area sums and counts for each tree across multiple radii in one pass.

Usage

neigh_multi_r(
  sp,
  gx,
  gy,
  ba,
  r_values,
  dist_weighted = FALSE,
  edge_correction = c("none", "safe"),
  bounds = NULL
)

Arguments

sp	A character or factor vector of species names.
gx	Numeric x-coordinates of the trees.
gy	Numeric y-coordinates of the trees.
ba	Numeric basal area for each tree.
r_values	Numeric vector of radii to evaluate.
dist_weighted	Logical flag to use 'ba / dist' weighting within each radius.
edge_correction	Character; see 'ba_simple()' for the '"safe"' option.
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.

Value

A tidy tibble with 'tree_id', 'species', 'radius', 'con_ba', 'total_ba', 'con_count', 'total_count', 'prop_con_ba', 'het_ba', 'het_count', and 'competition_index'.

Examples

sample_data <- data.frame(
  latin = sample(letters[1:4], 10, replace = TRUE),
  gx = runif(10, 0, 10),
  gy = runif(10, 0, 10),
  ba = runif(10, 10, 30)
)
neigh_multi_r(
  sp = sample_data$latin,
  gx = sample_data$gx,
  gy = sample_data$gy,
  ba = sample_data$ba,
  r_values = c(3, 5)
)

---