-
Notifications
You must be signed in to change notification settings - Fork 43
/
Copy pathsetResource.Rd
180 lines (147 loc) · 7.4 KB
/
setResource.Rd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/setResource.R
\name{setResource}
\alias{setResource}
\alias{resource_rate}
\alias{resource_rate<-}
\alias{resource_capacity}
\alias{resource_capacity<-}
\alias{resource_level}
\alias{resource_level<-}
\alias{resource_dynamics}
\alias{resource_dynamics<-}
\title{Set resource dynamics}
\usage{
setResource(
params,
resource_rate = NULL,
resource_capacity = NULL,
resource_level = NULL,
resource_dynamics = NULL,
balance = NULL,
lambda = resource_params(params)[["lambda"]],
n = resource_params(params)[["n"]],
w_pp_cutoff = resource_params(params)[["w_pp_cutoff"]],
r_pp = deprecated(),
kappa = deprecated(),
...
)
resource_rate(params)
resource_rate(params) <- value
resource_capacity(params)
resource_capacity(params) <- value
resource_level(params)
resource_level(params) <- value
resource_dynamics(params)
resource_dynamics(params) <- value
}
\arguments{
\item{params}{A MizerParams object}
\item{resource_rate}{Optional. A vector of per-capita resource birth
rate for each size class or a single number giving the coefficient in the
power-law for this rate, see "Setting resource dynamics" below.
Must be strictly positive.}
\item{resource_capacity}{Optional. Vector of resource intrinsic carrying
capacities or coefficient in the power-law for the capacity, see
"Setting resource dynamics" below.
The resource capacity must be larger than the resource abundance.}
\item{resource_level}{Optional. The ratio between the current resource number
density and the resource capacity. Either a number used at all sizes or a
vector specifying a value for each size. Must be strictly between 0 and 1,
except at sizes where the resource is zero, where it can be \code{NaN}. This
determines the resource capacity, so do not specify both this and
\code{resource_capacity}.}
\item{resource_dynamics}{Optional. Name of the function that determines the
resource dynamics by calculating the resource spectrum at the next time
step from the current state.}
\item{balance}{By default, if possible, the resource parameters are
set so that the resource replenishes at the same rate at which it is
consumed. In this case you should only specify either the resource rate
or the resource capacity (or resource level) because the other is then
determined automatically. Set to FALSE if you do not want the balancing.}
\item{lambda}{Used to set power-law exponent for resource capacity if the
\code{resource_capacity} argument is given as a single number.}
\item{n}{Used to set power-law exponent for resource rate if the
\code{resource_rate} argument is given as a single number.}
\item{w_pp_cutoff}{The upper cut off size of the resource spectrum power law
used only if \code{resource_capacity} is given as a single number.}
\item{r_pp}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}. Use \code{resource_rate} argument
instead.}
\item{kappa}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}. Use \code{resource_capacity}
argument instead.}
\item{...}{Unused}
\item{value}{The desired new value for the respective parameter.}
}
\value{
\code{setResource}: A MizerParams object with updated resource parameters
A vector with the intrinsic resource birth rate for each size class.
A vector with the intrinsic resource capacity for each size class.
A vector with the ratio between the current resource number density
and the resource capacity for each size class.
The name of the function that determines the resource dynamics.
}
\description{
Sets the intrinsic resource birth rate and the intrinsic resource carrying
capacity as well as the name of the function used to simulate the resource
dynamics. By default, the birth rate and the carrying capacity are changed
together in such a way that the resource replenishes at the same rate at
which it is consumed. So you should only provide either the
\code{resource_rate} or the \code{resource_capacity} (or \code{resource_level}) because
the other is determined by the requirement that the resource replenishes
at the same rate at which it is consumed.
}
\details{
You would usually set the resource dynamics only after having finished the
calibration of the steady state. Then setting the resource dynamics with
this function will preserve that steady state, unless you explicitly
choose to set \code{balance = FALSE}. Your choice of the resource dynamics only
affects the dynamics around the steady state. The higher the resource rate
or the lower the resource capacity the less sensitive the model will be to
changes in the competition for resource.
If you provide the \code{resource_level} then that sets the \code{resource_capacity}
to the current resource number density divided by the resource level. So
in that case you should not specify \code{resource_capacity} as well.
If you provide none of the arguments \code{resource_level}, \code{resource_rate} or
\code{resource_capacity} then the resource rate is set to the resource rate is
kept at its previous value.
}
\section{Setting resource dynamics}{
The \code{resource_dynamics} argument allows you to choose the resource dynamics
function. By default, mizer uses a semichemostat model to describe the
resource dynamics in each size class independently. This semichemostat
dynamics is implemented by the function \code{\link[=resource_semichemostat]{resource_semichemostat()}}. You can
change that to use a logistic model implemented by \code{\link[=resource_logistic]{resource_logistic()}} or
you can use \code{\link[=resource_constant]{resource_constant()}} which keeps the resource constant or you
can write your own function.
Both the \code{\link[=resource_semichemostat]{resource_semichemostat()}} and the \code{\link[=resource_logistic]{resource_logistic()}} dynamics
are parametrised in terms of a size-dependent birth rate \eqn{r_R(w)} and a
size-dependent capacity \eqn{c_R}. The help pages of these functions give
the details.
The \code{resource_rate} argument can be a vector (with the same length as
\code{w_full(params)}) specifying the intrinsic resource birth rate for each size
class. Alternatively it can be a single number that is used as the
coefficient in a power law: then the intrinsic birth rate \eqn{r_R(w)} at
size \eqn{w} is set to
\deqn{r_R(w) = r_R w^{n-1}.}
The power-law exponent \eqn{n} is taken from the \code{n} argument.
The \code{resource_capacity} argument can be a vector specifying the intrinsic
resource carrying capacity for each size class. Alternatively it can be a
single number that is used as the coefficient in a truncated power
law: then the intrinsic carrying capacity \eqn{c_R(w)} at size \eqn{w}
is set to
\deqn{c_R(w) = c_R\, w^{-\lambda}}{c_R(w) = c_R w^{-\lambda}}
for all \eqn{w} less than \code{w_pp_cutoff} and zero for larger sizes.
The power-law exponent \eqn{\lambda} is taken from the \code{lambda} argument.
The values for \code{lambda}, \code{n} and \code{w_pp_cutoff} are stored in a list
in the \code{resource_params} slot of the MizerParams object so that they can be
re-used automatically in the future. That list can be accessed with
\code{\link[=resource_params]{resource_params()}}.
}
\examples{
params <- NS_params
resource_dynamics(params)
resource_dynamics(params) <- "resource_constant"
}
\seealso{
\code{\link[=setParams]{setParams()}}
}