Rdistance (version 1.1)

F.dfunc.estim: F.dfunc.estim - Estimate a distance function.

Description

Fit a specific distance function to a set of observed off-transect distances.

Usage

F.dfunc.estim(dist, likelihood = "halfnorm", w.lo = 0, w.hi = max(dist), expansions = 0, 
    series = "cosine", x.scl=0, g.x.scl=1, observer="both", warn=TRUE )

Arguments

dist

The vector of observed off-transect distances. All values in dist must be between w.lo and w.hi.

likelihood

String specifying the likelihood to assume. Valid values at present are "uniform", "halfnorm", "hazrate", "negexp", and "Gamma". See Details and Example for user defined likelihoods.

w.lo

Lower or left-truncation limit of the distances in dist. This is the minimum possible off-transect distance. Default is 0.

w.hi

Upper or right-truncation limit of the distances in dist. This is the maximum off-transect distance that could be observed. Default is the maximum of dist.

expansions

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

series

If expansions > 0, this string specifies the type of expansion to use. Valid values at present are 'simple', 'hermite', and 'cosine'.

x.scl

This parameter is passed to F.g.estim. See F.gx.estim documentation for definition.

g.x.scl

This parameter is passed to F.g.estim. See F.gx.estim documentation for definition.

observer

This parameter is passed to F.g.estim. See F.gx.estim documentation for definition.

warn

A logical scaler specifying whether to issue an R warning if the estimation did not converge or if one or more parameter estimates are at their boundaries. For estimation, warn should generally be left at its default value of TRU

Value

• An object of class 'dfunc'. Objects of class 'dfunc' are lists containing the following components:
• parameters
  The vector of estimated parameter values. Length of this vector for built-in likelihood is the number of expansion terms plus 1 plus 1 if the likelihood is either 'hazrate' or 'uniform'.
• loglik
  The maximized value of the log likelihood.
• convergence
  The convergence code. This code is returned by nlminb. Values other than 0 indicate suspect convergence.
• like.form
  The form of the likelihood assumed. This is the value of the argument likelihood.
• w.lo
  Left-truncation value used during the fit.
• w.hi
  Right-truncation value used during the fit.
• dist
  The input vector of observed off-transect distances.
• expansions
  The number of expansion terms used during estimation.
• series
  The number of expansion terms used during estimation.
• call
  The original call of this function.
• fit
  The fitted object returned by nlminb. See documentation for nlminb.

Details

Rdistance allows user-defined likelihood functions (see Examples). Assuming 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:
   • a= the parameter vector for the likelihood.
   • dist= the vector of observed distances.
   • w.lo= the left truncation (minimum distance).
   • w.hi= the right truncation (maximum distance).
   • series= the name of the expansion series. If the likelihood does not use a series, this function still requires a parameter namedseries.
   • expansions= the number of expansions. If the likelihood does not use expansions, this function still needs a parameter namedexpansions.
   • 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. Seeuniform.likefor an example of how this parameter should be used.
   The likelihood function should return a vector the same length asdistcontaining the likelihood values. That is, the i-th element of the output vector should be the likelihood of observingdist[i].
2. <form>.start.limits - The starting values, limits, and names of parameters in the likelihood. This function takes the argumentsdist,w.lo, andw.hi, and returns a list containing the following components:
   • start= a vector of lengthpof starting values for the parameters of the likelihood, assuming there arepparameters in the likelihood.
   • lowlimit= a vector of lengthpof lower limits for parameters of the likelihood.
   • highlimit= a vector of lengthpof upper limits for parameters of the likelihood.
   • names= a vector of lengthpof names for the parameters of the likelihood.

See Also

Likelihoods listed in uniform.like; F.abund.estim; F.automated.CDA

Examples

#   ------ Fit distance functions to half-normal data
set.seed(90382)
x <- rnorm(1000) * 20
x <- x[ 0 < x & x < 100 ]

un.dfunc <- F.dfunc.estim( x, likelihood="uniform", w.hi = 100)
hn.dfunc <- F.dfunc.estim( x, likelihood="halfnorm", w.hi = 100)
ne.dfunc <- F.dfunc.estim( x, likelihood="negexp", w.hi = 100)
hz.dfunc <- F.dfunc.estim( x, likelihood="hazrate", w.hi = 100)
ga.dfunc <- F.dfunc.estim( x, likelihood="Gamma", w.hi = 100, x.scl="max") 

par(mfrow=c(2,2))
plot(un.dfunc)
plot(hn.dfunc)
plot(ne.dfunc)
plot(hz.dfunc)


#   ------ A user defined likelihood function: the triangular distribution on [0,b]
triangular.like <- function(b, dist, w.lo, w.hi, series = "", expansions = 0, scale = TRUE){
    L <- (2/b)*(1 - dist/b)
    L[ L < 0 ] <- 0
    L 
}

triangular.start.limits <- function(dist, w.lo, w.hi){
    list(start=max(dist)*.75,
         lowlimit=w.lo,
         highlimit=w.hi,
         names="Max")
}

#   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
}

d <- rtriang(500,100)  # true b = 100
tri.dfunc <- F.dfunc.estim( d, likelihood="triangular", w.hi=150 )
plot(tri.dfunc)

#   For triangular case, true effective strip width = tri.dfunc$g.x.scl*tri.dfunc$param / 2.  
#   ESW(tri.dfunc) may differ slightly due to numerical integration error.