setExtEncounter.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/setExtEncounter.R
\name{setExtEncounter}
\alias{setExtEncounter}
\alias{getExtEncounter}
\alias{ext_encounter}
\alias{ext_encounter<-}
\title{Set external encounter rate}
\usage{
setExtEncounter(params, ext_encounter = NULL, reset = FALSE, ...)

getExtEncounter(params)

ext_encounter(params)

ext_encounter(params) <- value
}
\arguments{
\item{params}{MizerParams}

\item{ext_encounter}{Optional. An array (species x size) holding the external
encounter rate.  If not supplied, a default is calculated from the \code{E_ext}
and \code{n} species parameters as described in the section "Setting external
encounter rate".}

\item{reset}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
If set to TRUE, then the external encounter rate will be reset to the value
calculated from the species parameters, even if it was previously
overwritten with a custom value. If set to FALSE (default) then a
recalculation from the species parameters will take place only if no
custom value has been set.}

\item{...}{Unused}

\item{value}{ext_encounter}
}
\value{
\code{setExtEncounter()}: A MizerParams object with updated external encounter
rate.

\code{getExtEncounter()} or equivalently \code{ext_encounter()}: A
\code{ArraySpeciesBySize} object (species x size) with the external encounter rate.
}
\description{
Set external encounter rate
}
\section{Setting external encounter rate}{

The external encounter rate is the rate at which a predator encounters
food that is not explicitly modelled. It is a rate with units mass/year.

The \code{ext_encounter} argument allows you to specify an external encounter rate
that depends on species and body size. You can see an example of this in
the Examples section of the help page for \code{\link[=setExtEncounter]{setExtEncounter()}}.

If the \code{ext_encounter} argument is not supplied, then the external encounter
rate is calculated as a power law:
\deqn{E_{ext.i}(w) = E_{ext.i}\, w^{n_i}.}{E_{ext.i}(w) = E_{ext.i} * w^n_i.}
The coefficient \eqn{E_{ext.i}} is taken from the \code{E_ext} column of the
species parameter data frame, which defaults to 0. The exponent \eqn{n_i} is
taken from the \code{n} column of the species parameter data frame.

If the \code{ext_encounter} slot has a comment and \code{reset = FALSE}, then a
recalculation from the species parameters is suppressed and a message is
issued if the recalculated values would differ from the stored ones.
}

\examples{
params <- newMultispeciesParams(NS_species_params)

#### Setting allometric encounter rate #######################

# Set coefficient for each species. Here we choose 0.1 for each species
encounter_pre <- rep(0.1, nrow(species_params(params)))

# Multiply by power of size with exponent, here chosen to be 3/4
# The outer() function makes it an array species x size
allo_encounter <- outer(encounter_pre, w(params)^(3/4))

# Change the external encounter rate in the params object
ext_encounter(params) <- allo_encounter
}
\seealso{
Other functions for setting parameters: 
\code{\link{gear_params}()},
\code{\link{setDiffusion}()},
\code{\link{setExtMort}()},
\code{\link{setFishing}()},
\code{\link{setInitialValues}()},
\code{\link{setInteraction}()},
\code{\link{setMaxIntakeRate}()},
\code{\link{setMetabolicRate}()},
\code{\link{setParams}()},
\code{\link{setPredKernel}()},
\code{\link{setReproduction}()},
\code{\link{setSearchVolume}()},
\code{\link{species_params}()}
}
\concept{functions for setting parameters}