range_sample: Resample the observed range of species occurrences

In rBatt/trawlDiversity: Long-term changes in species richness along the North American coastline

Description

Resample tows among sites to determine range size while accounting for variability in tow frequency

Usage

range_sample(X, sppName, tow_target = 1, calc = TRUE, nPerm = 100,
  rarefy = FALSE, tow_max = NULL)

Arguments

X	A matrix with rows being sites (indicating range size) and columns as tows within a site. Elements of matrix are taken to be binary: 0 for absent, 1 for present
sppName	character of length 1, corresponding to "spp" in trawlDiversity::data_all
tow_target	an integer of length 1 indicating the number of tows that should be represented in the estimated range size. I.e., the range size
calc	logical, if TRUE (default), the range size is calculated directly, rather than using the resampling technique that achieves the equivalent result (when nPerm is large)
nPerm	integer of length 1, number of permutations when resampling tows. I.e., simulated sample size behind returned value (and each point in rarefaction curve)
rarefy	logical, default TRUE. Compute the rarefaction curve?
tow_max	integer of length 1 indicating the maximum extent of the rarefaction curve when rarefy is TRUE; when NULL (default), tow_max is set to the maximum number of tows for any site in X

Details

Resampling is done with replacement. Therefore, the rarefaction curve will not asymptote to the observed range size at the maximum number of tows (default value when tow_max is NULL). The asymptote will always be at the observed range size.

Value

If rarefy is FALSE, returns a numeric of length 1 indicating the estimated range size as a fraction of the total number of rows (sites) in X. Otherwise, returns same as above but with the attribute "rc", the Rarefaction Curve, that is a vector of length(tow_max) indicating the estimated range size for a number of tows equal to the index seq_len(tow_max).

See Also

local_rich_sample

Examples

# ---- range size at 1 tow ----
Xdat <- data_all[reg=="shelf" & year==1985, list(stratum,spp,K,Kmax,abund)]
range_sample(X=Xdat, sppName="Leucoraja erinacea")

# ---- calculate and plot rarefaction curve ----
rc <- range_sample(X=Xdat, sppName="Leucoraja erinacea", rarefy=TRUE)
plot(attributes(rc)$rc, type='o')

# ---- calculate for all species in a region for 2 years ----
# calculate resampled range
test <- data_all[reg=='shelf' & year%in%(1989:1990),j={
	uspp <- unique(spp)
	tf <- function(x){
		range_sample(X=.SD, sppName=x, nPerm=3)
		# Note: low nPerm for fast example
	}
	rs <- sapply(uspp, tf)
	data.table(spp=names(rs), range_size_samp=unname(rs))
},by=c("reg","year")]

# calculate observed range
obs <- data_all[reg=='shelf' & year%in%(1989:1990), j={
	nS <- length(unique(stratum))
	.SD[,j={
		list(obs_rs=length(unique(stratum))/nS)
	},by="spp"]
},by=c("reg","year")]

# merge and plot
obs_test <- merge(obs, test, by=c("reg","year","spp"))
obs_test[,plot(obs_rs, range_size_samp)]
abline(a=0, b=1)

rBatt/trawlDiversity documentation built on Aug. 14, 2021, 1:01 p.m.