get_detection_pr: A detection probability function based on distance

In edwardlavender/flapper: Routines for the Analysis of Passive Acoustic Telemetry Data

A detection probability function based on distance

Description

This function calculates detection probability (e.g., of an acoustic detection) at specified distances from the sampling device (e.g., a passive acoustic telemetry receiver) using user-defined parameters (i.e., a model intercept, a coefficient for the effect of distance and an inverse link function). The function returns a plot of detection probability with distance and/or a vector of detection probabilities.

Usage

get_detection_pr(
  distance = 1:1000,
  beta_0 = 2.5,
  beta_1 = -0.01,
  inv_link = stats::plogis,
  output = 3L,
  ...
)

Arguments

distance	A numeric vector of distances at which to calculate detection probability.
beta_0, beta_1	Single numbers that define the model coefficients (i.e., the intercept and gradient on the scale of the link function).
inv_link	A function that defines the inverse link function. The default function is the logistic (inverse logit) function.
output	An integer (1L, 2L or 3L) that defines the output type. 1L returns a plot of detection probability against distance; 2L returns a numeric vector of detection probabilities; and 3L returns both of the above.
...	Additional arguments, passed to pretty_plot, to customise the plot. These are only implemented if output = 1L or output = 3L.

Value

The function calculates detection probability at each specified distance and returns a plot, a vector of detection probabilities, or both, depending on the value of the output argument. If a vector of detection probabilities is returned, this contains the following attributes: ‘X’, the model matrix; ‘beta’, the regression coefficients; and ‘inv_link’, the inverse link function.

Author(s)

Edward Lavender

Examples

#### Example (1): Implement the function using the default parameters
# The function returns a graph and a vector of detection probabilities
det_pr <- get_detection_pr()
utils::head(det_pr)
# The vector has attributes:
# ... 'X' (the model matrix)
# ... 'beta' (the regression coefficient)
# ... 'inv_link' (the inverse link function)
utils::str(det_pr)

#### Example (2): Adjust model parameters
# Change regression coefficients
det_pr <- get_detection_pr(beta_0 = 2.5, beta_1 = -0.006)
# Use inverse probit link function
det_pr <- get_detection_pr(beta_0 = 2.5, beta_1 = -0.006, inv_link = stats::pnorm)

#### Example (3): Modify graphical properties
det_pr <- get_detection_pr(
  beta_0 = 2.5,
  beta_1 = -0.006,
  type = "l",
  xlab = "Distance (m)",
  ylab = "Detection Probability"
)

#### Example (4): Modify return options
# Only graph
get_detection_pr(output = 1L)
# Only values
get_detection_pr(output = 2L)
# Both graph and values (the default)
get_detection_pr(output = 3L)

edwardlavender/flapper documentation built on Jan. 22, 2025, 2:44 p.m.