% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sdbuildR_custom_func.R
\name{ricker}
\alias{ricker}
\title{Generalized Ricker function}
\usage{
ricker(x, location = 1, upper = 1, shape = 1, a = NULL, b = NULL)
}
\arguments{
\item{x}{Value at which to evaluate the function. Because the curve involves a fractional power of \code{x}, \code{x} is expected to be non-negative.}

\item{location}{Value of \code{x} at which the function reaches its peak. Defaults to 1.}

\item{upper}{Maximal value (height) of the function, attained at the peak. Defaults to 1.}

\item{shape}{Exponent controlling the width of the peak: values above 1 narrow
the peak, values below 1 broaden it. \code{shape = 1} gives the standard Ricker
function. Defaults to 1.}

\item{a, b}{Coefficients of the equivalent expanded form
\eqn{f(x) = a \cdot x^{shape} \cdot e^{-b \cdot x}}. Optional alternative to
\code{location} and \code{upper}: when both \code{a} and \code{b} are supplied, they take
precedence and set \code{location = shape / b} and \verb{upper = a \\cdot (location / e)^\{shape\}}.
With \code{shape = 1} this is the standard Ricker parameterization
\eqn{f(x) = a \cdot x \cdot e^{-b \cdot x}}. Supplying only one of them, or
combining them with an explicit \code{location} or \code{upper}, is an error. Default
to \code{NULL}.}
}
\value{
Numeric value given by \deqn{f(x) = upper \cdot \left(\frac{x}{location} \cdot e^{1 - x / location}\right)^{shape}}
}
\description{
Computes the generalized Ricker function, a smooth hump-shaped curve that rises
from zero, peaks, and then decays back towards zero. It is commonly used to
describe humped (non-monotonic) dependencies, such as stock-recruitment
relationships in ecology or size-dependent predation.
}
\details{
The generalized Ricker function (Persson et al., 1998) is defined as:

\deqn{f(x) = upper \cdot \left(\frac{x}{location} \cdot e^{1 - x / location}\right)^{shape}}

with a power parameter (\eqn{\alpha}, or \code{shape}) that broadens or narrows the
peak. The function peaks at \code{x = location}, where it attains the value \code{upper},
for any \code{shape}.

Expanding the expression shows that it is equivalent to:

\deqn{f(x) = a \cdot x^{shape} \cdot e^{-b \cdot x}}

with coefficients

\deqn{a = upper \cdot (e / location)^{shape}}
\deqn{b = shape / location}

or equivalently

\deqn{location = shape / b}
\deqn{upper = a \cdot (location / e)^{shape}.}

Note that \eqn{e} is the base of the natural logarithm (i.e., \code{exp(1)}). When
\code{shape = 1}, the power on \code{x} is 1 and this reduces to the standard Ricker
function \eqn{f(x) = a \cdot x \cdot e^{-b \cdot x}}, with \eqn{a = upper \cdot e / location}
and \eqn{b = 1 / location}.

See Bolker, B. M. (2008). \emph{Ecological Models and Data in R}. Princeton
University Press, Section 8.1.
}
\examples{
ricker(1)

# Adjust parameters
ricker(2, location = 2, upper = 10, shape = 1)

# Use the expanded form f(x) = a * x^shape * exp(-b * x) instead.
# With shape = 1 this is the standard Ricker f(x) = a * x * exp(-b * x).
ricker(3, a = 2.5, b = 0.4)
# equivalent to:
ricker(3, location = 1 / 0.4, upper = 2.5 * (1 / 0.4 / exp(1)))

# The mapping holds for any shape, e.g. f(x) = a * x^2 * exp(-b * x)
ricker(3, a = 2.5, b = 0.4, shape = 2)

# Visualize different peak widths
curve(ricker(x, location = 2), from = 0, to = 10, ylab = "f(x)", ylim = c(0, 1.5))
curve(ricker(x, location = 2, shape = 0.5), add = TRUE, col = "blue")
curve(ricker(x, location = 2, shape = 3), add = TRUE, col = "red")
legend("topright",
  legend = c("shape = 1", "shape = 0.5", "shape = 3"),
  col = c("black", "blue", "red"), lty = 1
)
}
\concept{convenience}
