Skip to contents

Estimate Overlap Coefficients for Multiple Species

mm_overlap_matrix.Rd

This function calculates pairwise overlap coefficients for activity patterns of multiple species using their time data.

Usage

mm_overlap_matrix(
  data,
  species_column,
  time_column,
  convert_time = F,
  format = "%H:%M:%S",
  fill_na = NULL,
  ...
)

Arguments

data

A data.frame or tibble containing species and time information.

species_column

A column in data indicating species names.

time_column

A column in data containing time data (either as radians or in a time format to be converted).

convert_time

Logical. If TRUE, the time data will be converted to radians using the mm_to_radian function.

format

A character string specifying the time format (e.g., "%H:%M:%S") if mm_to_radian() is TRUE. Defaults to "%H:%M:%S".

fill_na

Optional. A numeric value used to fill NA values in the overlap coefficient matrix. Defaults to NULL (does not fill NA values).

...

Additional arguments passed to overlap::overlapEst()` for overlap estimation.

Value

A square matrix of pairwise overlap coefficients, where rows and columns represent species.

Details

The function calculates pairwise overlap coefficients for all species in the dataset. The overlap coefficients are estimated using the overlap package:

  • For species pairs with sample sizes of at least 50 observations each, the Dhat4 estimator is used.

  • For smaller sample sizes, the Dhat1 estimator is used (Schmid & Schmidt, 2006).

References

Schmid & Schmidt (2006) Nonparametric estimation of the coefficient of overlapping - theory and empirical application, Computational Statistics and Data Analysis, 50:1583-1596.

See also

overlap::overlapEst() for overlap coefficient estimation.

Examples

# Example dataset
data <- data.frame(
  species = c("SpeciesA", "SpeciesA", "SpeciesB", "SpeciesB"),
  time = c("10:30:00", "11:45:00", "22:15:00", "23:30:00")
)

# Calculate overlap coefficients with time conversion
overlap_matrix <- mm_overlap_matrix(
  data = data,
  species_column = species,
  time_column = time,
  convert_time = TRUE,
  format = "%H:%M:%S"
)

# Fill missing values in the matrix with 0
overlap_matrix_filled <- mm_overlap_matrix(
  data = data,
  species_column = species,
  time_column = time,
  convert_time = TRUE,
  fill_na = 0
)