Skip to contents

Rarefy focal-individual counts to a common number of individuals

timefish_rarefy_focal.Rd

This function generalises row-wise rarefaction from a focal count column and a total-individuals column. It returns the expected focal count after repeatedly drawing N individuals.

Usage

timefish_rarefy_focal(
  data,
  focal_col,
  total_col,
  N = NULL,
  reps = 1000,
  replace = FALSE,
  total_includes_focal = TRUE,
  seed = NULL,
  cores = NULL,
  benchmark_cores = TRUE,
  core_candidates = NULL,
  show_parallel_info = TRUE
)

Arguments

data

A data frame.

focal_col

Column name with focal counts (e.g., cleaner abundance or focal richness counts).

total_col

Column name with total individuals.

N

Number of individuals to draw. If NULL, uses the minimum positive value from total_col.

reps

Number of random replicates per row.

replace

Logical. Should sampling be with replacement?

total_includes_focal

Logical. If TRUE (default), assumes total_col includes focal_col and uses other = total - focal.

seed

Optional integer seed for reproducible runs.

cores

Number of CPU cores to use. If NULL, the user can choose interactively (or defaults to 1 in non-interactive sessions).

benchmark_cores

Logical. If TRUE, print an estimated runtime table by core count before running.

core_candidates

Optional vector of candidate core counts to benchmark (for example 2:8).

show_parallel_info

Logical. If TRUE, print available cores, the benchmark table, and selected cores.

Value

A numeric vector with the rarefied expected focal counts per row.

Examples

dat <- data.frame(focal = c(5, 2), total = c(20, 15))
timefish_rarefy_focal(dat, focal_col = "focal", total_col = "total", N = 10, reps = 500)
#> Available cores: 2
#> Estimated runtime by cores:
#>  cores pilot_seconds estimated_total_seconds speedup_vs_1_core estimated_time
#>      1      0.000060                0.000060              1.00      0.000060s
#>      2      0.011217                0.011217              0.01      0.011217s
#>    source
#>  measured
#>  measured
#> Using cores: 1
#> [1] 2.546 1.362