Gamma.like {Rdistance}

Gamma.like - Gamma distance function

Description

Computes the gamma likelihood, scaled appropriately, for use as a likelihood in estimating a distance function.

Usage

Gamma.like(
  a,
  dist,
  covars = NULL,
  w.lo = units::set_units(0, "m"),
  w.hi = max(dist),
  series = "cosine",
  expansions = 0,
  scale = TRUE,
  pointSurvey = FALSE
)

Arguments

a

A vector of likelihood parameter values. Length and meaning depend on series and expansions. If no expansion terms were called for (i.e., expansions = 0), the distance likelihoods contain one or two canonical parameters (see Details). If one or more expansions are called for, coefficients for the expansion terms follow coefficients for the canonical parameters. If p is the number of canonical parameters, coefficients for the expansion terms are a[(p+1):length(a)].

dist

A numeric vector containing the observed distances.

covars

Data frame containing values of covariates at each observation in dist.

w.lo

Scalar value of the lowest observable distance. This is the left truncation of sighting distances in dist. Same units as dist. Values less than w.lo are allowed in dist, but are ignored and their contribution to the likelihood is set to NA in the output.

w.hi

Scalar value of the largest observable distance. This is the right truncation of sighting distances in dist. Same units as dist. Values greater than w.hi are allowed in dist, but are ignored and their contribution to the likelihood is set to NA in the output.

series

A string specifying the type of expansion to use. Currently, valid values are 'simple', 'hermite', and 'cosine'; but, see dfuncEstim about defining other series.

expansions

A scalar specifying the number of terms in series. Depending on the series, this could be 0 through 5. The default of 0 equates to no expansion terms of any type.

scale

Logical scalar indicating whether or not to scale the likelihood so it integrates to 1. This parameter is used to stop recursion in other functions. If scale equals TRUE, a numerical integration routine (integration.constant) is called, which in turn calls this likelihood function again with scale = FALSE. Thus, this routine knows when its values are being used to compute the likelihood and when its value is being used to compute the constant of integration. All user defined likelihoods must have and use this parameter.

pointSurvey

Boolean. TRUE if dist is point transect data, FALSE if line transect data.

Details

This function utilizes the built-in R function dgamma to evaluate the gamma density function. Using the parameterization of dgamma, the gamma shape parameter is a[1] while the gamma scale parameter is (a[2]/gamma(r)) * (((r - 1)/exp(1))^(r - 1)). Currently, this function implements a non-covariate version of the gamma detection function used by Becker and Quang (2009). In future, linear equations will relate covariate values to values of the gamma parameters. This future implementation will fully replicate the distance functions of Becker and Quang (2009).

Value

A numeric vector the same length and order as dist containing the likelihood contribution for distances in dist. Assuming L=gamma.like(c(r,lam),dist), the full log likelihood of all the data is -sum(log(L), na.rm=T). Note that the returned likelihood value for distances less than w.lo or greater than w.hi is NA, and thus it is prudent to use na.rm=TRUE in the sum. If scale = TRUE, the integral of the likelihood from w.lo to w.hi is 1.0. If scale = FALSE, the integral of the likelihood is an arbitrary constant.

References

Becker, E. F., and P. X. Quang, 2009. A Gamma-Shaped Detection Function for Line-Transect Surveys with Mark-Recapture and Covariate Data. Journal of Agricultural, Biological, and Environmental Statistics 14(2):207-223.

See Also

dfuncEstim, halfnorm.like, hazrate.like, uniform.like, negexp.like

Examples

## Not run: 
set.seed(238642)
x <- seq(0, 100, length=100)

# Plots showing effects of changes in shape
plot(x, Gamma.like(c(20,20), x), type="l", col="red")
plot(x, Gamma.like(c(40,20), x), type="l", col="blue")

# Plots showing effects of changes in scale
plot(x, Gamma.like(c(20,20), x), type="l", col="red")
plot(x, Gamma.like(c(20,40), x), type="l", col="blue")

# Estimate 'Gamma' distance function
r <- 5
lam <- 10
b <- (1/gamma(r)) * (((r - 1)/exp(1))^(r - 1))
x <- rgamma(1000, shape=r, scale=b*lam)
dfunc <- dfuncEstim(x~1, likelihood="Gamma", x.scl="max")
plot(dfunc)

## End(Not run)