# Plot the survey effort necessary to detect species presence, given the species expected catch rate.

Source:`R/detectionPlot.R`

`detectionPlot.Rd`

This function plots the number of survey effort units to necessary detect species presence, calculated using median estimated parameter values from jointModel(). Detecting species presence is defined as producing at least one true positive eDNA detection or catching at least one individual. See more examples in the Package Vignette.

## Arguments

- modelfit
An object of class

`stanfit`

.- mu.min
A value indicating the minimum expected species catch rate for plotting. If multiple traditional gear types are represented in the model, mu is the catch rate of gear type 1.

- mu.max
A value indicating the maximum expected species catch rate for plotting. If multiple traditional gear types are represented in the model, mu is the catch rate of gear type 1.

- cov.val
A numeric vector indicating the values of site-level covariates to use for prediction. Default is NULL.

- probability
A numeric value indicating the probability of detecting presence. The default is 0.9.

- qPCR.N
An integer indicating the number of qPCR replicates per eDNA sample. The default is 3.

## Value

A plot displaying survey efforts necessary to detect species presence, given mu, for each survey type.

## Note

Before fitting the model, this function checks to ensure that the function is possible given the inputs. These checks include:

Input model fit is an object of class 'stanfit'.

Input mu.min is a numeric value greater than 0.

Input mu.max is a numeric value.

If model fit contains alpha, cov.val must be provided.

Input cov.val is numeric.

Input cov.val is the same length as the number of estimated covariates.

Input probability is a univariate numeric value.

Input model fit has converged (i.e. no divergent transitions after warm-up).

If any of these checks fail, the function returns an error message.

## Examples

```
# \donttest{
# Ex. 1: Calculating necessary effort for detection with site-level
# covariates
# Load data
data(gobyData)
# Fit a model including 'Filter_time' and 'Salinity' site-level covariates
fit.cov <- jointModel(data = gobyData, cov = c('Filter_time','Salinity'),
family = "poisson", p10priors = c(1,20), q = FALSE,
multicore = FALSE)
#>
#> SAMPLING FOR MODEL 'joint_binary_cov_pois' NOW (CHAIN 1).
#> Chain 1:
#> Chain 1: Gradient evaluation took 4.9e-05 seconds
#> Chain 1: 1000 transitions using 10 leapfrog steps per transition would take 0.49 seconds.
#> Chain 1: Adjust your expectations accordingly!
#> Chain 1:
#> Chain 1:
#> Chain 1: Iteration: 1 / 3000 [ 0%] (Warmup)
#> Chain 1: Iteration: 500 / 3000 [ 16%] (Warmup)
#> Chain 1: Iteration: 501 / 3000 [ 16%] (Sampling)
#> Chain 1: Iteration: 1000 / 3000 [ 33%] (Sampling)
#> Chain 1: Iteration: 1500 / 3000 [ 50%] (Sampling)
#> Chain 1: Iteration: 2000 / 3000 [ 66%] (Sampling)
#> Chain 1: Iteration: 2500 / 3000 [ 83%] (Sampling)
#> Chain 1: Iteration: 3000 / 3000 [100%] (Sampling)
#> Chain 1:
#> Chain 1: Elapsed Time: 0.892 seconds (Warm-up)
#> Chain 1: 1.75 seconds (Sampling)
#> Chain 1: 2.642 seconds (Total)
#> Chain 1:
#>
#> SAMPLING FOR MODEL 'joint_binary_cov_pois' NOW (CHAIN 2).
#> Chain 2:
#> Chain 2: Gradient evaluation took 4.7e-05 seconds
#> Chain 2: 1000 transitions using 10 leapfrog steps per transition would take 0.47 seconds.
#> Chain 2: Adjust your expectations accordingly!
#> Chain 2:
#> Chain 2:
#> Chain 2: Iteration: 1 / 3000 [ 0%] (Warmup)
#> Chain 2: Iteration: 500 / 3000 [ 16%] (Warmup)
#> Chain 2: Iteration: 501 / 3000 [ 16%] (Sampling)
#> Chain 2: Iteration: 1000 / 3000 [ 33%] (Sampling)
#> Chain 2: Iteration: 1500 / 3000 [ 50%] (Sampling)
#> Chain 2: Iteration: 2000 / 3000 [ 66%] (Sampling)
#> Chain 2: Iteration: 2500 / 3000 [ 83%] (Sampling)
#> Chain 2: Iteration: 3000 / 3000 [100%] (Sampling)
#> Chain 2:
#> Chain 2: Elapsed Time: 0.908 seconds (Warm-up)
#> Chain 2: 1.701 seconds (Sampling)
#> Chain 2: 2.609 seconds (Total)
#> Chain 2:
#>
#> SAMPLING FOR MODEL 'joint_binary_cov_pois' NOW (CHAIN 3).
#> Chain 3:
#> Chain 3: Gradient evaluation took 6e-05 seconds
#> Chain 3: 1000 transitions using 10 leapfrog steps per transition would take 0.6 seconds.
#> Chain 3: Adjust your expectations accordingly!
#> Chain 3:
#> Chain 3:
#> Chain 3: Iteration: 1 / 3000 [ 0%] (Warmup)
#> Chain 3: Iteration: 500 / 3000 [ 16%] (Warmup)
#> Chain 3: Iteration: 501 / 3000 [ 16%] (Sampling)
#> Chain 3: Iteration: 1000 / 3000 [ 33%] (Sampling)
#> Chain 3: Iteration: 1500 / 3000 [ 50%] (Sampling)
#> Chain 3: Iteration: 2000 / 3000 [ 66%] (Sampling)
#> Chain 3: Iteration: 2500 / 3000 [ 83%] (Sampling)
#> Chain 3: Iteration: 3000 / 3000 [100%] (Sampling)
#> Chain 3:
#> Chain 3: Elapsed Time: 0.782 seconds (Warm-up)
#> Chain 3: 95.97 seconds (Sampling)
#> Chain 3: 96.752 seconds (Total)
#> Chain 3:
#>
#> SAMPLING FOR MODEL 'joint_binary_cov_pois' NOW (CHAIN 4).
#> Chain 4:
#> Chain 4: Gradient evaluation took 4.5e-05 seconds
#> Chain 4: 1000 transitions using 10 leapfrog steps per transition would take 0.45 seconds.
#> Chain 4: Adjust your expectations accordingly!
#> Chain 4:
#> Chain 4:
#> Chain 4: Iteration: 1 / 3000 [ 0%] (Warmup)
#> Chain 4: Iteration: 500 / 3000 [ 16%] (Warmup)
#> Chain 4: Iteration: 501 / 3000 [ 16%] (Sampling)
#> Chain 4: Iteration: 1000 / 3000 [ 33%] (Sampling)
#> Chain 4: Iteration: 1500 / 3000 [ 50%] (Sampling)
#> Chain 4: Iteration: 2000 / 3000 [ 66%] (Sampling)
#> Chain 4: Iteration: 2500 / 3000 [ 83%] (Sampling)
#> Chain 4: Iteration: 3000 / 3000 [100%] (Sampling)
#> Chain 4:
#> Chain 4: Elapsed Time: 0.852 seconds (Warm-up)
#> Chain 4: 1.743 seconds (Sampling)
#> Chain 4: 2.595 seconds (Total)
#> Chain 4:
#> Warning: There were 199 divergent transitions after warmup. See
#> https://mc-stan.org/misc/warnings.html#divergent-transitions-after-warmup
#> to find out why this is a problem and how to eliminate them.
#> Warning: There were 2301 transitions after warmup that exceeded the maximum treedepth. Increase max_treedepth above 10. See
#> https://mc-stan.org/misc/warnings.html#maximum-treedepth-exceeded
#> Warning: There were 1 chains where the estimated Bayesian Fraction of Missing Information was low. See
#> https://mc-stan.org/misc/warnings.html#bfmi-low
#> Warning: Examine the pairs() plot to diagnose sampling problems
#> Warning: The largest R-hat is 1.06, indicating chains have not mixed.
#> Running the chains for more iterations may help. See
#> https://mc-stan.org/misc/warnings.html#r-hat
#> Warning: Bulk Effective Samples Size (ESS) is too low, indicating posterior means and medians may be unreliable.
#> Running the chains for more iterations may help. See
#> https://mc-stan.org/misc/warnings.html#bulk-ess
#> Warning: Tail Effective Samples Size (ESS) is too low, indicating posterior variances and tail quantiles may be unreliable.
#> Running the chains for more iterations may help. See
#> https://mc-stan.org/misc/warnings.html#tail-ess
#> Refer to the eDNAjoint guide for visualization tips: https://bookdown.org/abigailkeller/eDNAjoint_vignette/tips.html#visualization-tips
# Plot at the mean covariate values (covariates are standardized, so mean=0)
detectionPlot(fit.cov$model, mu.min = 0.1, mu.max = 1,
cov.val = c(0,0), qPCR.N = 3)
# Calculate mu_critical at salinity 0.5 z-scores greater than the mean
detectionPlot(fit.cov$model, mu.min = 0.1, mu.max = 1, cov.val = c(0,0.5),
qPCR.N = 3)
# Ex. 2: Calculating necessary effort for detection with multiple
# traditional gear types
# Load data
data(greencrabData)
# Fit a model with no site-level covariates
fit.q <- jointModel(data = greencrabData, cov = NULL, family = "negbin",
p10priors = c(1,20), q = TRUE,
multicore = FALSE)
#>
#> SAMPLING FOR MODEL 'joint_binary_catchability_negbin' NOW (CHAIN 1).
#> Chain 1:
#> Chain 1: Gradient evaluation took 0.000322 seconds
#> Chain 1: 1000 transitions using 10 leapfrog steps per transition would take 3.22 seconds.
#> Chain 1: Adjust your expectations accordingly!
#> Chain 1:
#> Chain 1:
#> Chain 1: Iteration: 1 / 3000 [ 0%] (Warmup)
#> Chain 1: Iteration: 500 / 3000 [ 16%] (Warmup)
#> Chain 1: Iteration: 501 / 3000 [ 16%] (Sampling)
#> Chain 1: Iteration: 1000 / 3000 [ 33%] (Sampling)
#> Chain 1: Iteration: 1500 / 3000 [ 50%] (Sampling)
#> Chain 1: Iteration: 2000 / 3000 [ 66%] (Sampling)
#> Chain 1: Iteration: 2500 / 3000 [ 83%] (Sampling)
#> Chain 1: Iteration: 3000 / 3000 [100%] (Sampling)
#> Chain 1:
#> Chain 1: Elapsed Time: 3.583 seconds (Warm-up)
#> Chain 1: 10.447 seconds (Sampling)
#> Chain 1: 14.03 seconds (Total)
#> Chain 1:
#>
#> SAMPLING FOR MODEL 'joint_binary_catchability_negbin' NOW (CHAIN 2).
#> Chain 2:
#> Chain 2: Gradient evaluation took 0.000289 seconds
#> Chain 2: 1000 transitions using 10 leapfrog steps per transition would take 2.89 seconds.
#> Chain 2: Adjust your expectations accordingly!
#> Chain 2:
#> Chain 2:
#> Chain 2: Iteration: 1 / 3000 [ 0%] (Warmup)
#> Chain 2: Iteration: 500 / 3000 [ 16%] (Warmup)
#> Chain 2: Iteration: 501 / 3000 [ 16%] (Sampling)
#> Chain 2: Iteration: 1000 / 3000 [ 33%] (Sampling)
#> Chain 2: Iteration: 1500 / 3000 [ 50%] (Sampling)
#> Chain 2: Iteration: 2000 / 3000 [ 66%] (Sampling)
#> Chain 2: Iteration: 2500 / 3000 [ 83%] (Sampling)
#> Chain 2: Iteration: 3000 / 3000 [100%] (Sampling)
#> Chain 2:
#> Chain 2: Elapsed Time: 3.347 seconds (Warm-up)
#> Chain 2: 9.735 seconds (Sampling)
#> Chain 2: 13.082 seconds (Total)
#> Chain 2:
#>
#> SAMPLING FOR MODEL 'joint_binary_catchability_negbin' NOW (CHAIN 3).
#> Chain 3:
#> Chain 3: Gradient evaluation took 0.000283 seconds
#> Chain 3: 1000 transitions using 10 leapfrog steps per transition would take 2.83 seconds.
#> Chain 3: Adjust your expectations accordingly!
#> Chain 3:
#> Chain 3:
#> Chain 3: Iteration: 1 / 3000 [ 0%] (Warmup)
#> Chain 3: Iteration: 500 / 3000 [ 16%] (Warmup)
#> Chain 3: Iteration: 501 / 3000 [ 16%] (Sampling)
#> Chain 3: Iteration: 1000 / 3000 [ 33%] (Sampling)
#> Chain 3: Iteration: 1500 / 3000 [ 50%] (Sampling)
#> Chain 3: Iteration: 2000 / 3000 [ 66%] (Sampling)
#> Chain 3: Iteration: 2500 / 3000 [ 83%] (Sampling)
#> Chain 3: Iteration: 3000 / 3000 [100%] (Sampling)
#> Chain 3:
#> Chain 3: Elapsed Time: 3.348 seconds (Warm-up)
#> Chain 3: 8.794 seconds (Sampling)
#> Chain 3: 12.142 seconds (Total)
#> Chain 3:
#>
#> SAMPLING FOR MODEL 'joint_binary_catchability_negbin' NOW (CHAIN 4).
#> Chain 4:
#> Chain 4: Gradient evaluation took 0.000325 seconds
#> Chain 4: 1000 transitions using 10 leapfrog steps per transition would take 3.25 seconds.
#> Chain 4: Adjust your expectations accordingly!
#> Chain 4:
#> Chain 4:
#> Chain 4: Iteration: 1 / 3000 [ 0%] (Warmup)
#> Chain 4: Iteration: 500 / 3000 [ 16%] (Warmup)
#> Chain 4: Iteration: 501 / 3000 [ 16%] (Sampling)
#> Chain 4: Iteration: 1000 / 3000 [ 33%] (Sampling)
#> Chain 4: Iteration: 1500 / 3000 [ 50%] (Sampling)
#> Chain 4: Iteration: 2000 / 3000 [ 66%] (Sampling)
#> Chain 4: Iteration: 2500 / 3000 [ 83%] (Sampling)
#> Chain 4: Iteration: 3000 / 3000 [100%] (Sampling)
#> Chain 4:
#> Chain 4: Elapsed Time: 3.637 seconds (Warm-up)
#> Chain 4: 6.778 seconds (Sampling)
#> Chain 4: 10.415 seconds (Total)
#> Chain 4:
#> Refer to the eDNAjoint guide for visualization tips: https://bookdown.org/abigailkeller/eDNAjoint_vignette/tips.html#visualization-tips
# Calculate
detectionPlot(fit.q$model, mu.min = 0.1, mu.max = 1,
cov.val = NULL, qPCR.N = 3)
# Change probability of detecting presence to 0.95
detectionPlot(fit.q$model, mu.min = 0.1, mu.max = 1, cov.val = NULL,
probability = 0.95, qPCR.N = 3)
# }
```