/
add_loglinear_targets.html
375 lines (304 loc) · 18.3 KB
/
add_loglinear_targets.html
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
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
<!-- Generated by pkgdown: do not edit by hand -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Add targets using log-linear scaling — add_loglinear_targets • prioritizr</title>
<!-- favicons -->
<link rel="icon" type="image/png" sizes="16x16" href="../favicon-16x16.png">
<link rel="icon" type="image/png" sizes="32x32" href="../favicon-32x32.png">
<link rel="apple-touch-icon" type="image/png" sizes="180x180" href="../apple-touch-icon.png" />
<link rel="apple-touch-icon" type="image/png" sizes="120x120" href="../apple-touch-icon-120x120.png" />
<link rel="apple-touch-icon" type="image/png" sizes="76x76" href="../apple-touch-icon-76x76.png" />
<link rel="apple-touch-icon" type="image/png" sizes="60x60" href="../apple-touch-icon-60x60.png" />
<!-- jquery -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
<!-- Bootstrap -->
<link href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.4.0/flatly/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha256-nuL8/2cJ5NDSSwnKD8VqreErSWHtnEP9E7AySL+1ev4=" crossorigin="anonymous"></script>
<!-- bootstrap-toc -->
<link rel="stylesheet" href="../bootstrap-toc.css">
<script src="../bootstrap-toc.js"></script>
<!-- Font Awesome icons -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous" />
<!-- clipboard.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.6/clipboard.min.js" integrity="sha256-inc5kl9MA1hkeYUt+EC3BhlIgyp/2jDIyBLS6k3UxPI=" crossorigin="anonymous"></script>
<!-- headroom.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script>
<!-- pkgdown -->
<link href="../pkgdown.css" rel="stylesheet">
<script src="../pkgdown.js"></script>
<!-- docsearch -->
<script src="../docsearch.js"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/docsearch.js/2.6.3/docsearch.min.css" integrity="sha256-QOSRU/ra9ActyXkIBbiIB144aDBdtvXBcNc3OTNuX/Q=" crossorigin="anonymous" />
<link href="../docsearch.css" rel="stylesheet">
<script src="https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/jquery.mark.min.js" integrity="sha256-4HLtjeVgH0eIB3aZ9mLYF6E8oU5chNdjU6p6rrXpl9U=" crossorigin="anonymous"></script>
<link href="../extra.css" rel="stylesheet">
<meta property="og:title" content="Add targets using log-linear scaling — add_loglinear_targets" />
<meta property="og:description" content="Add targets to a conservation planning problem() by log-linearly
interpolating the targets between thresholds based on the total amount of
each feature in the study area (Rodrigues et al. 2004). Additionally,
caps can be applied to targets to prevent features with massive
distributions from being over-represented
in solutions (Butchart et al. 2015)." />
<meta property="og:image" content="https://prioritizr.net/logo.png" />
<!-- mathjax -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script>
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-70466840-4"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-70466840-4');
</script>
</head>
<body data-spy="scroll" data-target="#toc">
<div class="container template-reference-topic">
<header>
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<span class="navbar-brand">
<a class="navbar-link" href="../index.html">prioritizr</a>
<span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="Released version">7.1.1.3</span>
</span>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li>
<a href="../articles/prioritizr.html">Get started</a>
</li>
<li>
<a href="../reference/index.html">Reference</a>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">
Articles
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="../articles/gurobi_installation.html">Gurobi Installation Guide</a>
</li>
<li>
<a href="../articles/publication_record.html">Publication Record</a>
</li>
<li>
<a href="../articles/saltspring.html">Salt Spring Island Tutorial</a>
</li>
<li>
<a href="../articles/solver_benchmark.html">Solver Benchmarks</a>
</li>
<li>
<a href="../articles/tasmania.html">Tasmania Tutorial</a>
</li>
<li>
<a href="../articles/zones.html">Management Zones</a>
</li>
</ul>
</li>
<li>
<a href="../news/index.html">Changelog</a>
</li>
</ul>
<ul class="nav navbar-nav navbar-right">
<li>
<a href="https://github.com/prioritizr/prioritizr/">
<span class="fab fa-github fa-lg"></span>
</a>
</li>
</ul>
<form class="navbar-form navbar-right hidden-xs hidden-sm" role="search">
<div class="form-group">
<input type="search" class="form-control" name="search-input" id="search-input" placeholder="Search..." aria-label="Search for..." autocomplete="off">
</div>
</form>
</div><!--/.nav-collapse -->
</div><!--/.container -->
</div><!--/.navbar -->
</header>
<div class="row">
<div class="col-md-9 contents">
<div class="page-header">
<h1>Add targets using log-linear scaling</h1>
<small class="dont-index">Source: <a href='https://github.com/prioritizr/prioritizr/blob/master/R/add_loglinear_targets.R'><code>R/add_loglinear_targets.R</code></a></small>
<div class="hidden name"><code>add_loglinear_targets.Rd</code></div>
</div>
<div class="ref-description">
<p>Add targets to a conservation planning <code><a href='problem.html'>problem()</a></code> by log-linearly
interpolating the targets between thresholds based on the total amount of
each feature in the study area (Rodrigues <em>et al.</em> 2004). Additionally,
caps can be applied to targets to prevent features with massive
distributions from being over-represented
in solutions (Butchart <em>et al.</em> 2015).</p>
</div>
<div class="ref-usage sourceCode"><pre class='sourceCode r'><code><span class='fu'>add_loglinear_targets</span><span class='op'>(</span>
<span class='va'>x</span>,
<span class='va'>lower_bound_amount</span>,
<span class='va'>lower_bound_target</span>,
<span class='va'>upper_bound_amount</span>,
<span class='va'>upper_bound_target</span>,
cap_amount <span class='op'>=</span> <span class='cn'>NULL</span>,
cap_target <span class='op'>=</span> <span class='cn'>NULL</span>,
abundances <span class='op'>=</span> <span class='fu'><a href='feature_abundances.html'>feature_abundances</a></span><span class='op'>(</span><span class='va'>x</span>, na.rm <span class='op'>=</span> <span class='cn'>FALSE</span><span class='op'>)</span><span class='op'>$</span><span class='va'>absolute_abundance</span>
<span class='op'>)</span></code></pre></div>
<h2 class="hasAnchor" id="arguments"><a class="anchor" href="#arguments"></a>Arguments</h2>
<table class="ref-arguments">
<colgroup><col class="name" /><col class="desc" /></colgroup>
<tr>
<th>x</th>
<td><p><code><a href='problem.html'>problem()</a></code> (i.e. <code><a href='ConservationProblem-class.html'>ConservationProblem</a></code>) object.</p></td>
</tr>
<tr>
<th>lower_bound_amount</th>
<td><p><code>numeric</code> threshold.</p></td>
</tr>
<tr>
<th>lower_bound_target</th>
<td><p><code>numeric</code> relative target that should be
applied to features with a total amount that is less
than or equal to <code>lower_bound_amount</code>.</p></td>
</tr>
<tr>
<th>upper_bound_amount</th>
<td><p><code>numeric</code> threshold.</p></td>
</tr>
<tr>
<th>upper_bound_target</th>
<td><p><code>numeric</code> relative target that should be
applied to features with a total amount that is greater
than or equal to <code>upper_bound_amount</code>.</p></td>
</tr>
<tr>
<th>cap_amount</th>
<td><p><code>numeric</code> total amount at which targets should be
capped. Defaults to <code>NULL</code> so that targets are not capped.</p></td>
</tr>
<tr>
<th>cap_target</th>
<td><p><code>numeric</code> amount-based target to apply to features
which have a total amount greater than argument to <code>cap_amount</code>.
Defaults to <code>NULL</code> so that targets are not capped.</p></td>
</tr>
<tr>
<th>abundances</th>
<td><p><code>numeric</code> total amount of each feature to
use when calculating the targets. Defaults to the feature abundances in the
study area (calculated using the <code><a href='feature_abundances.html'>feature_abundances()</a></code> function.</p></td>
</tr>
</table>
<h2 class="hasAnchor" id="value"><a class="anchor" href="#value"></a>Value</h2>
<p>Object (i.e. <code><a href='ConservationProblem-class.html'>ConservationProblem</a></code>) with the targets added
to it.</p>
<h2 class="hasAnchor" id="details"><a class="anchor" href="#details"></a>Details</h2>
<p>Targets are used to specify the minimum amount or proportion of a
feature's distribution that needs to be protected. All conservation
planning problems require adding targets with the exception of the maximum
cover problem (see <code><a href='add_max_cover_objective.html'>add_max_cover_objective()</a></code>), which maximizes
all features in the solution and therefore does not require targets.</p>
<p>Seven parameters are used to calculate the targets:
<code>lower_bound_amount</code> specifies the first range size threshold,
<code>lower_bound_target</code> specifies the relative target required for
species with a range size equal to or less than the first threshold,
<code>upper_bound_amount</code> specifies the second range size threshold,
<code>upper_bound_target</code> specifies the relative target required for
species with a range size equal to or greater than the second threshold,
<code>cap_amount</code> specifies the third range size threshold,
<code>cap_target</code> specifies the absolute target that is uniformly applied
to species with a range size larger than that third threshold, and finally
<code>abundances</code> specifies the range size for each feature
that should be used when calculating the targets.</p>
<p>The target calculations do not account for the
size of each planning unit. Therefore, the feature data should account for
the size of each planning unit if this is important (e.g. pixel values in
the argument to <code>features</code> in the function <code><a href='problem.html'>problem()</a></code> could
correspond to amount of land occupied by the feature in \(km^2\) units).
Additionally, the function can only be applied to
<code><a href='ConservationProblem-class.html'>ConservationProblem</a></code> objects that are associated with a
single zone.</p>
<h2 class="hasAnchor" id="notes"><a class="anchor" href="#notes"></a>Notes</h2>
<p>Early versions (< 5.0.2.4) used different equations for calculating
targets.</p>
<h2 class="hasAnchor" id="references"><a class="anchor" href="#references"></a>References</h2>
<p>Rodrigues ASL, Akcakaya HR, Andelman SJ, Bakarr MI, Boitani L, Brooks TM,
Chanson JS, Fishpool LDC, da Fonseca GAB, Gaston KJ, and others (2004)
Global gap analysis: priority regions for expanding the global
protected-area network. <em>BioScience</em>, 54: 1092--1100.</p>
<p>Butchart SHM, Clarke M, Smith RJ, Sykes RE, Scharlemann JPW, Harfoot M,
Buchanan, GM, Angulo A, Balmford A, Bertzky B, and others (2015) Shortfalls
and solutions for meeting national and global conservation area targets.
<em>Conservation Letters</em>, 8: 329--337.</p>
<h2 class="hasAnchor" id="see-also"><a class="anchor" href="#see-also"></a>See also</h2>
<div class='dont-index'><p>See <a href='targets.html'>targets</a> for an overview of all functions for adding targets.</p>
<p>Other targets:
<code><a href='add_absolute_targets.html'>add_absolute_targets</a>()</code>,
<code><a href='add_manual_targets.html'>add_manual_targets</a>()</code>,
<code><a href='add_relative_targets.html'>add_relative_targets</a>()</code></p></div>
<h2 class="hasAnchor" id="examples"><a class="anchor" href="#examples"></a>Examples</h2>
<div class="ref-examples sourceCode"><pre class='sourceCode r'><code><span class='r-in'><span class='co'># load data</span></span>
<span class='r-in'><span class='fu'><a href='https://rdrr.io/r/utils/data.html'>data</a></span><span class='op'>(</span><span class='va'>sim_pu_raster</span>, <span class='va'>sim_features</span><span class='op'>)</span></span>
<span class='r-in'></span>
<span class='r-in'><span class='co'># create problem using loglinear targets</span></span>
<span class='r-in'><span class='va'>p</span> <span class='op'><-</span> <span class='fu'><a href='problem.html'>problem</a></span><span class='op'>(</span><span class='va'>sim_pu_raster</span>, <span class='va'>sim_features</span><span class='op'>)</span> <span class='op'><a href='pipe.html'>%>%</a></span></span>
<span class='r-in'> <span class='fu'><a href='add_min_set_objective.html'>add_min_set_objective</a></span><span class='op'>(</span><span class='op'>)</span> <span class='op'><a href='pipe.html'>%>%</a></span></span>
<span class='r-in'> <span class='fu'>add_loglinear_targets</span><span class='op'>(</span><span class='fl'>10</span>, <span class='fl'>0.9</span>, <span class='fl'>100</span>, <span class='fl'>0.2</span><span class='op'>)</span> <span class='op'><a href='pipe.html'>%>%</a></span></span>
<span class='r-in'> <span class='fu'><a href='add_binary_decisions.html'>add_binary_decisions</a></span><span class='op'>(</span><span class='op'>)</span> <span class='op'><a href='pipe.html'>%>%</a></span></span>
<span class='r-in'> <span class='fu'><a href='add_default_solver.html'>add_default_solver</a></span><span class='op'>(</span>verbose <span class='op'>=</span> <span class='cn'>FALSE</span><span class='op'>)</span></span>
<span class='r-in'><span class='co'># \dontrun{</span></span>
<span class='r-in'><span class='co'># solve problem</span></span>
<span class='r-in'><span class='va'>s</span> <span class='op'><-</span> <span class='fu'><a href='solve.html'>solve</a></span><span class='op'>(</span><span class='va'>p</span><span class='op'>)</span></span>
<span class='r-in'></span>
<span class='r-in'><span class='co'># plot solution</span></span>
<span class='r-in'><span class='fu'><a href='https://rdrr.io/pkg/raster/man/plot.html'>plot</a></span><span class='op'>(</span><span class='va'>s</span>, main <span class='op'>=</span> <span class='st'>"solution"</span>, axes <span class='op'>=</span> <span class='cn'>FALSE</span>, box <span class='op'>=</span> <span class='cn'>FALSE</span><span class='op'>)</span></span>
<span class='r-plt'><img src='add_loglinear_targets-1.png' alt='' width='700' height='433' /></span>
<span class='r-in'><span class='co'># }</span></span>
<span class='r-in'></span>
</code></pre></div>
</div>
<div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">
<nav id="toc" data-toggle="toc" class="sticky-top">
<h2 data-toc-skip>Contents</h2>
</nav>
</div>
</div>
<footer>
<div class="copyright">
<p><p>Developed by <a href="https://jeffrey-hanson.com" class="external-link">Jeffrey O Hanson</a>, <a href="http://www.richard-schuster.com" class="external-link">Richard Schuster</a>, Nina Morrell, <a href="http://strimas.com" class="external-link">Matthew Strimas-Mackey</a>, Brandon P M Edwards, Matthew E Watts, <a href="https://arcese.forestry.ubc.ca" class="external-link">Peter Arcese</a>, <a href="https://josephrbennett.wordpress.com" class="external-link">Joseph Bennett</a>, <a href="http://www.possinghamlab.org" class="external-link">Hugh P Possingham</a>.</p></p>
</div>
<div class="pkgdown">
<p><p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 1.6.1.9001.</p></p>
</div>
</footer>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/docsearch.js/2.6.1/docsearch.min.js" integrity="sha256-GKvGqXDznoRYHCwKXGnuchvKSwmx9SRMrZOTh2g4Sb0=" crossorigin="anonymous"></script>
<script>
docsearch({
apiKey: '486efa122ea6783724263412c5f28ab3',
indexName: 'prioritizr',
inputSelector: 'input#search-input.form-control',
transformData: function(hits) {
return hits.map(function (hit) {
hit.url = updateHitURL(hit);
return hit;
});
}
});
</script>
</body>
</html>