% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/newMultispeciesParams.R
\name{setParams}
\alias{setParams}
\title{Set or change any model parameters}
\usage{
setParams(params, interaction = NULL, ...)
}
\arguments{
\item{params}{A \linkS4class{MizerParams} object}

\item{interaction}{Optional interaction matrix of the species (predator
species x prey species). By default all entries are 1. See "Setting
interaction matrix" section below.}

\item{...}{
  Arguments passed on to \code{\link[=setPredKernel]{setPredKernel}}, \code{\link[=setSearchVolume]{setSearchVolume}}, \code{\link[=setMaxIntakeRate]{setMaxIntakeRate}}, \code{\link[=setMetabolicRate]{setMetabolicRate}}, \code{\link[=setExtMort]{setExtMort}}, \code{\link[=setReproduction]{setReproduction}}, \code{\link[=setFishing]{setFishing}}
  \describe{
    \item{\code{pred_kernel}}{Optional. An array (species x predator size x prey size)
that holds the predation coefficient of each predator at size on each prey
size. If not supplied, a default is set as described in section "Setting
predation kernel".}
    \item{\code{search_vol}}{Optional. An array (species x size) holding the search volume
for each species at size. If not supplied, a default is set as described in
the section "Setting search volume".}
    \item{\code{intake_max}}{Optional. An array (species x size) holding the maximum
intake rate for each species at size. If not supplied, a default is set as
described in the section "Setting maximum intake rate".}
    \item{\code{metab}}{Optional. An array (species x size) holding the metabolic rate
for each species at size. If not supplied, a default is set as described in
the section "Setting metabolic rate".}
    \item{\code{p}}{The allometric metabolic exponent. This is only used if \code{metab}
is not given explicitly and if the exponent is not specified in a \code{p}
column in the \code{species_params}.}
    \item{\code{ext_mort}}{Optional. An array (species x size) holding the external
mortality rate.  If not supplied, a default is set as described in the
section "Setting external mortality rate".}
    \item{\code{z0pre}}{If \code{z0}, the mortality from other sources, is not a column
in the species data frame, it is calculated as z0pre * w_max ^ z0exp.
Default value is 0.6.}
    \item{\code{z0exp}}{If \code{z0}, the mortality from other sources, is not a column in
the species data frame, it is calculated as \code{z0pre * w_max ^ z0exp}.
Default value is \code{n-1}.}
    \item{\code{z0}}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use \code{ext_mort} instead. Not to
be confused with the species_parameter \code{z0}.}
    \item{\code{maturity}}{Optional. An array (species x size) that holds the proportion
of individuals of each species at size that are mature. If not supplied, a
default is set as described in the section "Setting reproduction".}
    \item{\code{repro_prop}}{Optional. An array (species x size) that holds the
proportion of consumed energy that a mature individual allocates to
reproduction for each species at size. If not supplied, a default is set as
described in the section "Setting reproduction".}
    \item{\code{RDD}}{The name of the function calculating the density-dependent
reproduction rate from the density-independent rate. Defaults to
"\code{\link[=BevertonHoltRDD]{BevertonHoltRDD()}}".}
    \item{\code{selectivity}}{Optional. An array (gear x species x size) that holds the
selectivity of each gear for species and size, \eqn{S_{g,i,w}}.}
    \item{\code{catchability}}{Optional. An array (gear x species) that holds the catchability of
each species by each gear, \eqn{Q_{g,i}}.}
    \item{\code{initial_effort}}{Optional. A number or a named numeric vector specifying
the fishing effort. If a number, the same effort is used for all gears. If
a vector, must be named by gear.}
  }}
}
\value{
A \linkS4class{MizerParams} object
}
\description{
This is a convenient wrapper function calling each of the following
functions
\itemize{
\item \code{\link[=setPredKernel]{setPredKernel()}}
\item \code{\link[=setSearchVolume]{setSearchVolume()}}
\item \code{\link[=setInteraction]{setInteraction()}}
\item \code{\link[=setMaxIntakeRate]{setMaxIntakeRate()}}
\item \code{\link[=setMetabolicRate]{setMetabolicRate()}}
\item \code{\link[=setExtMort]{setExtMort()}}
\item \code{\link[=setReproduction]{setReproduction()}}
\item \code{\link[=setFishing]{setFishing()}}
\item \code{\link[=setResource]{setResource()}}
}
See the Details section below for a discussion of how to use this function.
}
\details{
If you are not happy with the assumptions that mizer makes by default about
the shape of the model functions, for example if you want to change one of
the allometric scaling assumptions, you can do this by providing your
choice as an array in the appropriate argument to \code{setParams()}. The
sections below discuss all the model functions that you can change this way.

Because of the way the R language works, \code{setParams} does not make the
changes to the \code{params} object that you pass to it but instead returns a new
params object. So to affect the change you call the function in the form
\code{params <- setParams(params, ...)}.

Usually, if you are happy with the way mizer calculates its model functions
from the species parameters and only want to change the values of some
species parameters, you would make those changes in the \code{species_params} data
frame contained in the \code{params} object using \code{\link[=species_params<-]{species_params<-()}}.
Here is an example which assumes that
you have have a MizerParams object \code{params} in which you just want to change
the \code{gamma} parameter of the third species:

\if{html}{\out{<div class="sourceCode">}}\preformatted{species_params(params)$gamma[[3]] <- 1000
}\if{html}{\out{</div>}}

Internally that will actually call \code{setParams()} to recalculate any of the
other parameters that are affected by the change in the species parameter.

\code{setParams()} will use the species parameters in the \code{params} object to
recalculate the values of all the model functions except those for which you
have set custom values.
}
\section{Units in mizer}{

Mizer uses grams to measure weight, centimetres to measure lengths, and
years to measure time.

Mizer is agnostic about whether abundances are given as
\enumerate{
\item numbers per area,
\item numbers per volume or
\item total numbers for the entire study area.
}

You should make the choice most convenient for your application and then
stick with it. If you make choice 1 or 2 you will also have to choose a unit
for area or volume. Your choice will then determine the units for some of
the parameters. This will be mentioned when the parameters are discussed in
the sections below.

Your choice will also affect the units of the quantities you may want to
calculate with the model. For example, the yield will be in grams/year/m^2 in
case 1 if you choose m^2 as your measure of area, in grams/year/m^3 in case 2
if you choose m^3 as your unit of volume, or simply grams/year in case 3. The
same comment applies for other measures, like total biomass, which will be
grams/area in case 1, grams/volume in case 2 or simply grams in case 3. When
mizer puts units on axes in plots, it will choose the units appropriate for
case 3. So for example in \code{\link[=plotBiomass]{plotBiomass()}} it gives the unit as grams.

You can convert between these choices. For example, if you use case 1, you
need to multiply with the area of the ecosystem to get the total quantity.
If you work with case 2, you need to multiply by both area and the thickness
of the productive layer. In that respect, case 2 is a bit cumbersome. The
function \code{\link[=scaleModel]{scaleModel()}} is useful to change the units you are using.
}

\section{Setting interaction matrix}{


You do not need to specify an interaction matrix. If you do not, then the
predator-prey interactions are purely determined by the size of predator
and prey and totally independent of the species of predator and prey.

The interaction matrix \eqn{\theta_{ij}} modifies the interaction of each
pair of species in the model. This can be used for example to allow for
different spatial overlap among the species.
The values in the interaction matrix are used to scale the encountered food
and predation mortality (see on the website \href{https://sizespectrum.org/mizer/articles/model_description.html#sec:pref}{the section on predator-prey encounter rate}
and on \href{https://sizespectrum.org/mizer/articles/model_description.html#mortality}{predation mortality}).
The first index refers to the predator species and the second to the prey
species.

The interaction matrix is used when calculating the food encounter rate in
\code{\link[=getEncounter]{getEncounter()}} and the predation mortality rate in \code{\link[=getPredMort]{getPredMort()}}. Its
entries are dimensionless numbers. If all the values in the interaction
matrix are equal then predator-prey interactions are determined entirely by
size-preference.

This function checks that the supplied interaction matrix is valid and then
stores it in the \code{interaction} slot of the \code{params} object.

The order of the columns and rows of the \code{interaction} argument should be
the same as the order in the species params data frame in the \code{params}
object. If you supply a named array then the function will check the order
and warn if it is different. One way of creating your own interaction
matrix is to enter the data using a spreadsheet program and saving it as a
.csv file. The data can then be read into R using the command \code{read.csv()}.

The interaction of the species with the resource are set via a column
\code{interaction_resource} in the \code{species_params} data frame. By default this
column is set to all 1s.
}

\section{Setting predation kernel}{

\strong{Kernel dependent on predator to prey size ratio}

If the \code{pred_kernel} argument is not supplied, then this function sets a
predation kernel that depends only on the ratio of predator mass to prey
mass, not on the two masses independently. The shape of that kernel is then
determined by the \code{pred_kernel_type} column in species_params.

The default for \code{pred_kernel_type} is "lognormal". This will call the function
\code{\link[=lognormal_pred_kernel]{lognormal_pred_kernel()}} to calculate the predation kernel.
An alternative pred_kernel type is "box", implemented by the function
\code{\link[=box_pred_kernel]{box_pred_kernel()}}, and "power_law", implemented by the function
\code{\link[=power_law_pred_kernel]{power_law_pred_kernel()}}. These functions require certain species
parameters in the species_params data frame. For the lognormal kernel these
are \code{beta} and \code{sigma}, for the box kernel they are \code{ppmr_min}
and \code{ppmr_max}. They are explained in the help pages for the kernel
functions. Except for \code{beta} and \code{sigma}, no defaults are set for
these parameters. If they are missing from the species_params data frame then
mizer will issue an error message.

You can use any other string for \code{pred_kernel_type}. If for example you
choose "my" then you need to define a function \code{my_pred_kernel} that you can
model on the existing functions like \code{\link[=lognormal_pred_kernel]{lognormal_pred_kernel()}}.

When using a kernel that depends on the predator/prey size ratio only, mizer
does not need to store the entire three dimensional array in the MizerParams
object. Such an array can be very big when there is a large number of size
bins. Instead, mizer only needs to store two two-dimensional arrays that hold
Fourier transforms of the feeding kernel function that allow the encounter
rate and the predation rate to be calculated very efficiently. However, if
you need the full three-dimensional array you can calculate it with the
\code{\link[=getPredKernel]{getPredKernel()}} function.

\strong{Kernel dependent on both predator and prey size}

If you want to work with a feeding kernel that depends on predator mass and
prey mass independently, you can specify the full feeding kernel as a
three-dimensional array (predator species x predator size x prey size).

You should use this option only if a kernel dependent only on the
predator/prey mass ratio is not appropriate. Using a kernel dependent on
predator/prey mass ratio only allows mizer to use fast Fourier transform
methods to significantly reduce the running time of simulations.

The order of the predator species in \code{pred_kernel} should be the same
as the order in the species params dataframe in the \code{params} object. If you
supply a named array then the function will check the order and warn if it is
different.
}

\section{Setting search volume}{

The search volume \eqn{\gamma_i(w)} of an individual of species \eqn{i}
and weight \eqn{w} multiplies the predation kernel when
calculating the encounter rate in \code{\link[=getEncounter]{getEncounter()}} and the
predation rate in \code{\link[=getPredRate]{getPredRate()}}.

The name "search volume" is a bit misleading, because \eqn{\gamma_i(w)} does
not have units of volume. It is simply a parameter that determines the rate
of predation. Its units depend on your choice, see section "Units in mizer".
If you have chosen to work with total abundances, then it is a rate with units
1/year. If you have chosen to work with abundances per m^2 then it has units
of m^2/year. If you have chosen to work with abundances per m^3 then it has
units of m^3/year.

If the \code{search_vol} argument is not supplied, then the search volume is
set to
\deqn{\gamma_i(w) = \gamma_i w^q_i.}
The values of \eqn{\gamma_i} (the search volume at 1g) and \eqn{q_i} (the
allometric exponent of the search volume) are taken from the \code{gamma} and
\code{q} columns in the species parameter dataframe. If the \code{gamma}
column is not supplied in the species parameter dataframe, a default is
calculated by the \code{\link[=get_gamma_default]{get_gamma_default()}} function. Note that only
for predators of size \eqn{w = 1} gram is the value of the species parameter
\eqn{\gamma_i} the same as the value of the search volume \eqn{\gamma_i(w)}.
}

\section{Setting maximum intake rate}{

The maximum intake rate \eqn{h_i(w)} of an individual of species \eqn{i} and
weight \eqn{w} determines the feeding level, calculated with
\code{\link[=getFeedingLevel]{getFeedingLevel()}}. It is measured in grams/year.

If the \code{intake_max} argument is not supplied, then the maximum intake
rate is set to \deqn{h_i(w) = h_i w^{n_i}.}
The values of \eqn{h_i} (the maximum intake rate of an individual of size 1
gram) and \eqn{n_i} (the allometric exponent for the intake rate) are taken
from the \code{h} and \code{n} columns in the species parameter dataframe. If
the \code{h} column is not supplied in the species parameter dataframe, it is
calculated by the \code{\link[=get_h_default]{get_h_default()}} function.

If \eqn{h_i} is set to \code{Inf}, fish of species i will consume all encountered
food.
}

\section{Setting metabolic rate}{

The metabolic rate is subtracted from the energy income rate to calculate
the rate at which energy is available for growth and reproduction, see
\code{\link[=getEReproAndGrowth]{getEReproAndGrowth()}}. It is measured in grams/year.

If the \code{metab} argument is not supplied, then for each species the
metabolic rate \eqn{k(w)} for an individual of size \eqn{w} is set to
\deqn{k(w) = k_s w^p + k w,}
where \eqn{k_s w^p} represents the rate of standard metabolism and \eqn{k w}
is the rate at which energy is expended on activity and movement. The values
of \eqn{k_s}, \eqn{p} and \eqn{k} are taken from the \code{ks}, \code{p} and
\code{k} columns in the species parameter dataframe. If any of these
parameters are not supplied, the defaults are \eqn{k = 0}, \eqn{p = n} and
\deqn{k_s = f_c h \alpha w_{mat}^{n-p},}{k_s = f_c * h * alpha * w_mat^(n - p),}
where \eqn{f_c} is the critical feeding level taken from the \code{fc} column
in the species parameter data frame. If the critical feeding level is not
specified, a default of \eqn{f_c = 0.2} is used.
}

\section{Setting external mortality rate}{

The external mortality is all the mortality that is not due to fishing or
predation by predators included in the model. The external mortality could be
due to predation by predators that are not explicitly included in the model
(e.g. mammals or seabirds) or due to other causes like illness. It is a rate
with units 1/year.

The \code{ext_mort} argument allows you to specify an external mortality 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[=setExtMort]{setExtMort()}}.

If the \code{ext_mort} argument is not supplied, then the external mortality is
assumed to depend only on the species, not on the size of the individual:
\eqn{\mu_{ext.i}(w) = z_{0.i}}. The value of the constant \eqn{z_0} for each
species is taken from the \code{z0} column of the species parameter data frame, if
that column exists. Otherwise it is calculated as
\deqn{z_{0.i} = {\tt z0pre}_i\, w_{inf}^{\tt z0exp}.}{z_{0.i} = z0pre_i w_{inf}^{z0exp}.}
}

\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()}}.
}

\section{Setting reproduction}{


For each species and at each size, the proportion \eqn{\psi}{psi} of the
available energy
that is invested into reproduction is the product of two factors: the
proportion \code{maturity} of individuals that are mature and the proportion
\code{repro_prop} of the energy available to a mature individual that is
invested into reproduction.

\subsection{Maturity ogive}{
If the the proportion of individuals that are mature is not supplied via
the \code{maturity} argument , then it is set to a sigmoidal
maturity ogive that changes from 0 to 1 at around the maturity size:
\deqn{{\tt maturity}(w) = \left[1+\left(\frac{w}{w_{mat}}\right)^{-U}\right]^{-1}.}{
  maturity(w) = [1+(w/w_mat)^(-U)]^(-1)}
(To avoid clutter, we are not showing the species index in the equations,
although each species has its own maturity ogive.)
The maturity weights are taken from the \code{w_mat} column of the
species_params data frame. Any missing maturity weights are set to 1/4 of the
maximum weight in the \code{w_max} column.

The exponent \eqn{U} determines the steepness of the maturity ogive. By
default it is chosen as \eqn{U = 10}, however this can be overridden by
including a column \code{w_mat25} in the species parameter dataframe that
specifies the weight at which 25\% of individuals are mature, which sets
\eqn{U = \log(3) / \log(w_{mat} / w_{25}).}{U = log(3) / log(w_mat / w_25).}

The sigmoidal function given above would strictly reach 1 only asymptotically.
Mizer instead sets the function equal to 1 already at the species'
maximum size, taken from the compulsory \code{w_max} column in the
species parameter data frame. Also, for computational simplicity, any
proportion smaller than \code{1e-8} is set to \code{0}.
}

\subsection{Investment into reproduction}{
If the the energy available to a mature individual that is
invested into reproduction is not supplied via the \code{repro_prop} argument,
it is set to the allometric form
\deqn{{\tt repro\_prop}(w) = \left(\frac{w}{w_{max}}\right)^{m-n}.}{
  repro_prop(w) = (w/w_max)^(m - n).}
Here \eqn{n} is the scaling exponent of the energy income rate. Hence
the exponent \eqn{m} determines the scaling of the investment into
reproduction for mature individuals. By default it is chosen to be
\eqn{m = 1} so that the rate at which energy is invested into reproduction
scales linearly with the size. This default can be overridden by including a
column \code{m} in the species parameter dataframe. The maximum sizes
are taken from the compulsory \code{w_max} column in the species parameter
data frame.

The total proportion of energy invested into reproduction of an individual
of size \eqn{w} is then
\deqn{\psi(w) = {\tt maturity}(w){\tt repro\_prop}(w)}{psi(w) = maturity(w) * repro_prop(w)}
}

\subsection{Reproductive efficiency}{
The reproductive efficiency \eqn{\epsilon}, i.e., the proportion of energy allocated to
reproduction that results in egg biomass, is set through the \code{erepro}
column in the species_params data frame. If that is not provided, the default
is set to 1 (which you will want to override). The offspring biomass divided
by the egg biomass gives the rate of egg production, returned by
\code{\link[=getRDI]{getRDI()}}:
\deqn{R_{di} = \frac{\epsilon}{2 w_{min}} \int N(w)  E_r(w) \psi(w) \, dw}{R_di = (\epsilon/(2 w_min)) \int N(w)  E_r(w) \psi(w) dw}
}

\subsection{Density dependence}{
The stock-recruitment relationship is an emergent phenomenon in mizer, with
several sources of density dependence. Firstly, the amount of energy invested
into reproduction depends on the energy income of the spawners, which is
density-dependent due to competition for prey. Secondly, the proportion of
larvae that grow up to recruitment size depends on the larval mortality,
which depends on the density of predators, and on larval growth rate, which
depends on density of prey.

Finally, to encode all the density dependence in the stock-recruitment
relationship that is not already included in the other two sources of density
dependence, mizer puts the the density-independent rate of egg production
through a density-dependence function. The result is returned by
\code{\link[=getRDD]{getRDD()}}. The name of the density-dependence function is
specified by the \code{RDD} argument. The default is the Beverton-Holt
function \code{\link[=BevertonHoltRDD]{BevertonHoltRDD()}}, which requires an \code{R_max} column
in the species_params data frame giving the maximum egg production rate. If
this column does not exist, it is initialised to \code{Inf}, leading to no
density-dependence. Other functions provided by mizer are
\code{\link[=RickerRDD]{RickerRDD()}} and \code{\link[=SheperdRDD]{SheperdRDD()}} and you can easily use
these as models for writing your own functions.
}
}

\section{Setting fishing}{


\strong{Gears}

In \code{mizer}, fishing mortality is imposed on species by fishing gears. The
total per-capita fishing mortality (1/year) is obtained by summing over the
mortality from all gears,
\deqn{\mu_{f.i}(w) = \sum_g F_{g,i}(w),}
where the fishing mortality \eqn{F_{g,i}(w)} imposed by gear \eqn{g} on
species \eqn{i} at size \eqn{w} is calculated as:
\deqn{F_{g,i}(w) = S_{g,i}(w) Q_{g,i} E_{g},}
where \eqn{S} is the selectivity by species, gear and size, \eqn{Q} is the
catchability by species and gear and \eqn{E} is the fishing effort by gear.

\strong{Selectivity}

The selectivity at size of each gear for each species is saved as a three
dimensional array (gear x species x size). Each entry has a range between 0
(that gear is not selecting that species at that size) to 1 (that gear is
selecting all individuals of that species of that size). This three
dimensional array can be specified explicitly via the \code{selectivity}
argument, but usually mizer calculates it from the \code{gear_params} slot of
the MizerParams object.

To allow the calculation of the \code{selectivity} array, the \code{gear_params} slot
must be a data frame with one row for each gear-species combination. So if
for example a gear can select three species, then that gear contributes three
rows to the \code{gear_params} data frame, one for each species it can select. The
data frame must have columns \code{gear}, holding the name of the gear, \code{species},
holding the name of the species, and \code{sel_func}, holding the name of the
function that calculates the selectivity curve. Some selectivity functions
are included in the package: \code{knife_edge()}, \code{sigmoid_length()},
\code{double_sigmoid_length()}, and \code{sigmoid_weight()}.
Users are able to write their own size-based selectivity function. The first
argument to the function must be \code{w} and the function must return a vector of
the selectivity (between 0 and 1) at size.

Each selectivity function may have parameters. Values for these
parameters must be included as columns in the gear parameters data.frame.
The names of the columns must exactly match the names of the corresponding
arguments of the selectivity function. For example, the default selectivity
function is \code{knife_edge()} that a has sudden change of selectivity from 0 to 1
at a certain size. In its help page you can see that the \code{knife_edge()}
function has arguments \code{w} and \code{knife_edge_size}. The first argument, \code{w}, is
size (the function calculates selectivity at size). All selectivity functions
must have \code{w} as the first argument. The values for the other arguments must
be found in the gear parameters data.frame. So for the \code{knife_edge()}
function there should be a \code{knife_edge_size} column. Because \code{knife_edge()}
is the default selectivity function, the \code{knife_edge_size} argument has a
default value = \code{w_mat}.

In case each species is only selected by one gear, the columns of the
\code{gear_params} data frame can alternatively be provided as columns of the
\code{species_params} data frame, if this is more convenient for the user to set
up. Mizer will then copy these columns over to create the \code{gear_params} data
frame when it creates the MizerParams object. However changing these columns
in the species parameter data frame later will not update the \code{gear_params}
data frame.

\strong{Catchability}

Catchability is used as an additional factor to make the link between gear
selectivity, fishing effort and fishing mortality. For example, it can be set
so that an effort of 1 gives a desired fishing mortality. In this way effort
can then be specified relative to a 'base effort', e.g. the effort in a
particular year.

Catchability is stored as a two dimensional array (gear x species). This can
either be provided explicitly via the \code{catchability} argument, or the
information can be provided via a \code{catchability} column in the \code{gear_params}
data frame.

In the case where each species is selected by only a single gear, the
\code{catchability} column can also be provided in the \code{species_params} data
frame. Mizer will then copy this over to the \code{gear_params} data frame when
the MizerParams object is created.

\strong{Effort}

The initial fishing effort is stored in the \code{MizerParams} object. If it is
not supplied, it is set to zero. The initial effort can be overruled when
the simulation is run with \code{project()}, where it is also possible to specify
an effort that varies through time.
}

\seealso{
Other functions for setting parameters: 
\code{\link{gear_params}()},
\code{\link{setExtEncounter}()},
\code{\link{setExtMort}()},
\code{\link{setFishing}()},
\code{\link{setInitialValues}()},
\code{\link{setInteraction}()},
\code{\link{setMaxIntakeRate}()},
\code{\link{setMetabolicRate}()},
\code{\link{setPredKernel}()},
\code{\link{setReproduction}()},
\code{\link{setSearchVolume}()},
\code{\link{species_params}()}
}
\concept{functions for setting parameters}
