get_detection_pr.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_detections.R
\name{get_detection_pr}
\alias{get_detection_pr}
\title{A detection probability function based on distance}
\usage{
get_detection_pr(
  distance = 1:1000,
  beta_0 = 2.5,
  beta_1 = -0.01,
  inv_link = stats::plogis,
  output = 3L,
  ...
)
}
\arguments{
\item{distance}{A numeric vector of distances at which to calculate detection probability.}

\item{beta_0, beta_1}{Single numbers that define the model coefficients (i.e., the intercept and gradient on the scale of the link function).}

\item{inv_link}{A function that defines the inverse link function. The default function is the logistic (inverse logit) function.}

\item{output}{An integer (\code{1L}, \code{2L} or \code{3L}) that defines the output type. \code{1L} returns a plot of detection probability against distance; \code{2L} returns a numeric vector of detection probabilities; and \code{3L} returns both of the above.}

\item{...}{Additional arguments, passed to \code{\link[prettyGraphics]{pretty_plot}}, to customise the plot. These are only implemented if \code{output = 1L} or \code{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 \code{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.
}
\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.
}
\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)

}
\author{
Edward Lavender
}