# Introduction

Detection functions are often fit using a small set of likelihood functions that lend themselves to the distance-sampling data (e.g., half-normal, hazard rate, etc.). `Rdistance` has many of these traditional likelihood functions built in (see help documentation for `F.dfunc.estim`), but the package also allows the user to specify a custom function. Here, we give an example of how to specify a user-defined likelihood function when fitting a detection function in `Rdistance`. This tutorial is current as of version `r packageVersion("Rdistance")` of Rdistance.

# Details

Assuming that the user-defined likelihood is named form, estimation of a user-defined likelihood requires that the following two functions be defined:

1. `form.like` - The likelihood: This function defines the user-defined likelihood and should take the following inputs, in this order:

2. `a` = the parameter vector for the likelihood.

3. `dist` = the vector of observed distances.
4. `covars` = a matrix of covariates, one line per detection. If no covariates are included, set `covars` = NULL.
5. `pointSurvey` = a logical scalar equal to TRUE if distances are radial from a point, FALSE if distances are perpendicular off-transect.
6. `w.lo` = the left truncation (minimum distance).
7. `w.hi` = the right truncation (maximum distance).
8. `series` = the name of the expansion series. If the likelihood does not use a series, this function still requires a parameter named `series`.
9. `expansions` = the number of expansions. If the likelihood does not use expansions, this function still needs a parameter named `expansions`.
10. `scale` = a logical scalar. If TRUE, the likelihood should be scaled to integrate to 1.0. If FALSE, the user defined likelihood does not need to integrate to 1.0. See the help documentation for `uniform.like` for an example of how this parameter should be used.

The likelihood function should return a vector the same length as `dist` (the vector of distances) containing the likelihood values. That is, the i-th element of the output vector should be the likelihood of observing `dist[i]`.

1. `form.start.limits` - This function provides the starting values, limits, and names of parameters in the likelihood and should take the following inputs (described above): `dist`, `expansions`, `w.lo`, and `w.hi`.

This function should return a list containing the following components:

• `start` = a vector of length p of starting values for the parameters of the likelihood, assuming there are p parameters in the likelihood.
• `lowlimit` = a vector of length p of lower limits for parameters of the likelihood.
• `highlimit` = a vector of length p of upper limits for parameters of the likelihood.
• `names` = a vector of length p of names for the parameters of the likelihood.

# Example

A user-defined likelihood function: the triangular distribution on [0, b].

```# Part 1:  The likelihood function
triangular.like <- function(a, dist, covars=NULL,
pointSurvey=FALSE, w.lo=0, w.hi,
series="", expansions=0, scale=TRUE){
L <- (2/a)*(1 - dist/a)
L[ L < 0 ] <- 0
L
}
```
```# Part 2:  The starting values, limits, and names of parameters in the likelihood
triangular.start.limits <- function(dist, expansions, w.lo, w.hi){
list(start=max(dist)*.75,
lowlimit=w.lo,
highlimit=w.hi,
names="Max")
}
```

To demonstrate, generate some data and fit the triangular distance function.

```# A function to generate triangular random deviates
rtriang <- function(n, b){
x <- seq(0, b, length=500)
CDF <- 2*x/b - (x/b)^2
u <- runif(n)
r <- approx( CDF, x, xout=u )\$y
}

# Simulated vector of distances
set.seed(123)
d <- rtriang(500, 100)  # true b = 100
hist(d)
```
```# Fit detection function with user-defined "triangular" likelihood
# Requires the F.dfunc.estim function from Rdistance
require(Rdistance)
tri.dfunc <- dfuncEstim( d~1, likelihood="triangular", w.hi=150 )
tri.dfunc
```

All `dfunc` methods (e.g., `plot`, `predict`, etc.) should work with custom distance functions.

```plot(tri.dfunc)
AIC(tri.dfunc)
```

The effective strip width of a distance function is simply the area under the distance function after scaling. In `Rdistance`, scaling is accomplished by setting `x.scl` and `g.x.scl` in the call to `dfuncEstim`. `dfuncEstim` scales the distance function such that g(`x.scl`) = `g.x.scl`. The default is `x.scl` = 0 and `g.x.scl` = 1.

For the triangular case, g(0) = 1 and the true effective strip width is simply the area of a right triangle located at the origin. The true effective strip width of the triangular distance function is:

```tri.dfunc\$g.x.scl*tri.dfunc\$param / 2
```

The effective strip width calculated using `ESW` differs only slightly due to numerical integration error.

```ESW(tri.dfunc)
```

## Try the Rdistance package in your browser

Any scripts or data that you put into this service are public.

Rdistance documentation built on May 2, 2019, 3:49 a.m.