% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/huber.like.R
\name{huber.like}
\alias{huber.like}
\title{Huber distance function}
\usage{
huber.like(a, dist, covars, w.hi = NULL)
}
\arguments{
\item{a}{A vector or matrix of covariate 
and expansion term 
coefficients. If matrix, dimension is 
\emph{k} X \emph{p}, where 
\emph{k} = \code{nrow(a)}) is the number of coefficient
vectors to evaluate (cases) and \emph{p} 
= \code{ncol(a)})
is the number of covariate and expansion 
coefficients in the likelihood (i.e., rows are 
cases and columns are covariates). If \code{a} is a 
dimensionless vector, it is interpreted as a 
single row with \emph{k} = 1. 
Covariate coefficients in \code{a} are the first 
\emph{q} values (\emph{q} <= \emph{p}), and must 
be on a log scale.}

\item{dist}{A numeric vector of length \emph{n} or 
a single-column matrix (dimension \emph{n}X1) containing 
detection distances at which to evaluate the likelihood.}

\item{covars}{A numeric vector of length \emph{q} or a
matrix of dimension \emph{n}X\emph{q} containing 
covariate values 
associated with distances in argument \code{dist}.}

\item{w.hi}{A numeric scalar containing maximum 
distance. The right-hand cutoff or upper limit. 
Ignored by some likelihoods (such as halfnorm, 
negexp, and hazrate), but is a fixed parameter
in other likelihoods (such as oneStep 
and uniform).}
}
\value{
A list containing the following two components:
\itemize{
  \item \bold{L.unscaled}: A matrix of size 
   \emph{n}X\emph{k} (\emph{n} = length \code{dist}; \emph{k} = number of
   cases = \code{nrow(a)})
   containing likelihood values evaluated at 
   distances in \code{dist}.
   Each row is associated with 
   a single distance, and each column is associated with 
   a single case (row of \code{a}).  Values in this matrix are  
   the distance function \eqn{g(d)} which generally have \eqn{g(0) = 1}.
   These values are "unscaled" likelihood values; they must be 
   scaled (divided by) with the area under \eqn{g(x)} between w.lo and w.hi  
   to form proper likelihood values. 
   
 \item \bold{params}: A \emph{n}X\emph{b}X\emph{k}  array 
 of the likelihood's (canonical) parameters in link space (i.e., on 
 log scale; \emph{b} = number of canonical parameters in 
 the likelihood; \emph{k} = number of cases). 
 Rows correspond to distances in \code{dist}. Columns 
 correspond to parameters (columns of \code{a}), 
 and pages correspond to cases (rows of \code{a}). 
}
}
\description{
Computes the Huber likelihood for use as a distance function. 
The Huber likelihood is a mixture of an inverted Huber loss 
and a uniform distribution.  
The distance function is quadratic from the lowest distance to 
its first parameter, linear from the first parameter
to the sum of its first and second parameter, and constant 
after that.
}
\details{
The 'huber' likelihood is an inverted version of the 
Huber loss function, mixed with a uniform at the upper end, and contains
three canonical parameters. 
The 'huber' distance function is a negative quadratic 
between \code{0} and its first parameter \eqn{\theta_1}{T1},
linear between \eqn{\theta_1}{T1} and \eqn{\theta_1 + \theta_2}{T1 + T2}, and 
constant  after \eqn{\theta_1 + \theta_2}{T1 + T2}.
Specifically, the 'huber' likelihood is, 
\deqn{
   f(d|\theta_1,\theta_2, p) = \left(1 - \frac{(1-p)h(d)}{m}\right) \,
     I(0 \leq d \leq \Theta) \  + \  p \, I(\Theta < d \leq w)
}
where
\eqn{\Theta = \theta_1 + \theta_2}{T = T1 + T2}, \eqn{w} = \code{w.hi - w.lo},
\eqn{
 m = \theta_1(\Theta - 0.5\theta_1)
}{
 m = T1(T - 0.5(T1))
}
and \emph{h(d)} is Huber loss between 0 and \eqn{\Theta}{T}, i.e.,
\deqn{
 h(d)  = 0.5d^2\, I(0 \leq d \leq \theta_1) \ + \ 
         \theta_1(d - 0.5\theta_1)\, I(\theta_1 < d \leq \Theta).
}

The first parameter, \eqn{\theta_1}{T1}, is related to covariates, 
i.e., \eqn{log(\theta_1) = \beta_0 + \beta_1x_1 + \ldots + \beta_qx_q}{
log(T_1) = B_0 + B_1(x_1) + ... + B_q(x_q)}.  \eqn{\theta_2}{T2} and \eqn{p} 
are constant across covariate values.
}
\examples{

t1 <- c(65,80,120)
t2 <- 60
p  <- 0.05
a <- matrix(c(log(t1)
       , rep(t2,3)
       , rep(p,3))
       , 3,3)
d <- seq(0, 200, length=201)
X <- matrix(1,length(d),1)
y <- huber.like(a, d, X)

# Plot showing covariate effects 
plot(range(d), range(y$L.unscaled)
  , type = "n", xlab = "d", ylab = "Huber(d)")
for(i in 1:3){
  # Distance functions
  lines(d
    , y$L.unscaled[,i]
    , col = i
    , lwd= 2)
  # Quadradic to linear transitions
  points(exp(a[i,1])
    , y$L.unscaled[(t1[i]-0.1) < d & d < (t1[i]+0.01),i]
    , pch = 16
    , col = i )
  # Linear to constant transition
  Theta <- exp(a[i,1]) + a[i,2]
  points(Theta
    , y$L.unscaled[(Theta-0.1) < d & d < (Theta+0.1),i]
    , pch = 15
    , col = i )
}

}
\seealso{
See \href{https://mcdonalddatasciences.com/Rdistance.html}{Rdistance tutorials}
for a method to generate random observations from the Huber likelihood.
}
