-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathmanual-distances.html
429 lines (337 loc) · 23.2 KB
/
manual-distances.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
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
<!DOCTYPE html>
<html lang="en">
<!-- Start Head -->
<head>
<!-- Required meta tags -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<meta name="Description" content="R package actel.">
<title>Distances</title>
<!-- Favicon -->
<link rel="shortcut icon" type="image/icon" href="assets/images/actel_favicon.ico"/>
<!-- Font Awesome -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.2.1/css/all.min.css">
<!-- Bootstrap CSS -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-beta/css/bootstrap.min.css" integrity="sha384-/Y6pD6FV/Vv2HJnA6t+vslU6fwYXjCFtcEpHbNJ0lyAFsXTsjBbfaDjzALeQsN6M" crossorigin="anonymous">
<!-- Slick slider -->
<link href="assets/css/slick.css" rel="stylesheet">
<!-- Theme color -->
<link id="switcher" href="assets/css/theme-color/default-theme.css" rel="stylesheet">
<!-- Modal popup -->
<link href="assets/css/modal.css" rel="stylesheet">
<!-- Main Style -->
<link href="assets/css/style.css" rel="stylesheet">
<link href="assets/css/section_image_bg.css" rel="stylesheet">
<link href="assets/css/basic_typography.css" rel="stylesheet">
<link href="assets/css/dropdown_menu.css" rel="stylesheet">
<link href="assets/css/tables.css" rel="stylesheet">
<link href="assets/css/buttons.css" rel="stylesheet">
<link href="assets/css/size_responsiveness.css" rel="stylesheet">
<link href="assets/css/prism.css" rel="stylesheet">
<!-- Fonts -->
<!-- Poppins For Title -->
<link href="https://fonts.googleapis.com/css?family=Poppins" rel="stylesheet">
<!-- navBar -->
<link href="assets/css/navBar_for_white_bg.css" rel="stylesheet">
<link href="assets/css/navBar-second_for_white_bg.css" rel="stylesheet">
<!-- Code colouring -->
<link rel="stylesheet"
href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/default.min.css">
</head>
<!-- End Head -->
<!-- Start Body -->
<body>
<div class="page-container">
<!--START SCROLL TOP BUTTON -->
<a class="scrollToTop" href="#">
<i class="fa fa-angle-up"></i>
</a>
<!-- END SCROLL TOP BUTTON -->
<!-- Start NavBar -->
<div class="navBar" id="navBar">
<a href="index.html">Home</a>
<a href="news.html">News</a>
<button onclick="toogleManualNavBarResponsive()"><strong>Manual</strong> <i class="fa-solid fa-caret-down"></i></button>
<a href="mailto:[email protected]" onclick="closeNavBarDropdown()">Need help?<i class="fa fa-envelope" style="padding-left: 10px"></i></a>
<a href="javascript:void(0);" style="font-size:15px;" class="icon" onclick="toogleNavBarResponsive()"><i class="fa fa-bars"></i></a>
</div>
<!-- End NavBar -->
<!-- Start manual NavBar -->
<div class="navBar-second" id="navBar-manual">
<a href="manual-index.html">Section index</a>
<a href="manual-data.html"><strong>Input data</strong></a>
<a href="manual-explore.html"><code>explore()</code></a>
<a href="manual-migration.html"><code>migration()</code></a>
<a href="manual-residency.html"><code>residency()</code></a>
<a href="manual-manual.html">Manual mode</a>
<a href="manual-beyond.html">Beyond the three analyses</a>
<a href="javascript:void(0);" style="font-size:15px;" class="icon" onclick="toogleManualNavBarResponsive()"><i class="fa-solid fa-arrow-left"></i></a>
</div>
<!-- End manual NavBar -->
<!-- Start Main Content -->
<main>
<section class="section-white-bg">
<div class="container">
<div class="col-md-12 section-white-bg-area">
<div class="callout">
<div class="callout-header"> Before you start, note:</div>
<div class="callout-container">
<p>This is the new manual page for calculating distances (actel 1.2.1.9016 and higher).</p>
<p>If you are interested in the old manual page, see <a href="manual-distances-old.html"> <u>this page instead.</u></a></p>
</div>
</div>
<h2>What is the distances matrix?</h2>
<div class="manual">
<p>
A distances matrix is a table that contains information on the distance (in metres) between every pair of spatial elements in your study area (i.e. your receiver stations and your release sites). It looks like the table below:
</p>
<div style="overflow-x: auto;">
<table>
<tr><th></th><th>St.1</th><th>St.2</th><th>St.3</th><th>St.4</th><th>St.5</th><th>St.6</th><th>Release</th></tr>
<tr><th>St.1</th><td>0</td><td>1366</td><td>3417</td><td>6912</td><td>8863</td><td>9272</td><td>2229</td></tr>
<tr><th>St.2</th><td>1366</td><td>0</td><td>2051</td><td>5545</td><td>7497</td><td>7906</td><td>3569</td></tr>
<tr><th>St.3</th><td>3417</td><td>2051</td><td>0</td><td>3528</td><td>5479</td><td>5888</td><td>5621</td></tr>
<tr><th>St.4</th><td>6912</td><td>5545</td><td>3528</td><td>0</td><td>1963</td><td>2372</td><td>9115</td></tr>
<tr><th>St.5</th><td>8863</td><td>7497</td><td>5479</td><td>1963</td><td>0</td><td>408</td><td>11067</td></tr>
<tr><th>St.6</th><td>9272</td><td>7906</td><td>5888</td><td>2372</td><td>408</td><td>0</td><td>11476</td></tr>
<tr><th>Release</th><td>2229</td><td>3569</td><td>5621</td><td>9115</td><td>11067</td><td>11476</td><td>0</td></tr>
</table>
</div>
<div class="callout">
<div class="callout-header"> Note:</div>
<div class="callout-container">
<p>The matrix is symmetric (i.e. the entries of the matrix are symmetric with respect to the main diagonal).</p>
<p>The diagonal line is composed of 0's as it represents the distance between an element and itself.</p>
<p>You <strong>must</strong> have at least one release site, and the names of the release sites must be identical to those in your 'spatial.csv' and your 'biometrics.csv'.</p>
</div>
</div>
</div>
</div>
</div>
</section>
<section class="section-white-bg">
<div class="container">
<div class="col-md-12 section-white-bg-area">
<h2>Creating your distances matrix</h2>
<div class="manual">
<p>
There are two ways to create a distance matrix for actel: manually, or automatically. While the manual way is more prone to errors and can be tedious, the automatic way can take some time and requires some GIS knowledge. It is up to you to decide which way to use:
</p>
</div>
<div class="manual">
<h3>The automatic way</h3>
<p>As your studies start having more and more receivers, it might get complicated to find and write down the distances between every single combination of receivers and release sites. To avoid doing this manually, you can get R to do it for you. Here's what you need:</p>
<ul class="fa-ul">
<li><i class="fa-li fa fa-angle-right manual-list-icon"></i> A shapefile with a land polygon of your study area.</li>
<li><i class="fa-li fa fa-angle-right manual-list-icon"></i> The coordinates of your receivers and release sites in <strong>the same coordinate system as the shapefile</strong>.</li>
</ul>
<p>If you are not familiar with shapefiles and GIS, it might be a good idea to ask for a colleague's help.</p>
</div>
<div class="manual">
<h4>Preparing the shapefile</h4>
<p>To begin, you need to create a shapefile that extends over all your receivers and release sites. This shapefile is expected to contain polygons of the land masses, which means that your rivers, lakes, fjords and any water bodies must be "empty space". The width of your water channels is important, as the shapefile will be converted into a raster later on (i.e. a image made of pixels). If your pixels represent squares of 30 by 30 metres, and your channel width originally was of five metres, then the river path will be lost during the conversion process. Try to ensure, as best as possible, that the corners of your shapefile are aligned (i.e. the shape as a rectangular/quadrangular form).</p>
<div class="callout">
<div class="callout-header"> Note:</div>
<div class="callout-container">
<p>Make sure that the shapefile is in the same coordinate system as the points in your spatial file!</p>
</div>
</div>
<p>Below is an example of the study area in the left, and the respective shapefile in the right:</p>
<div class="row">
<div class="image-margins col-md-6"><img src="assets/images/manual/distances_shape_1.png" alt="drawing"/></div>
<div class="image-margins col-md-6"><img src="assets/images/manual/distances_shape_2.png" alt="drawing"/></div>
</div>
<p>Once you have your shapefile ready, copy the shapefile and respective auxiliary files to the folder where you have your 'spatial.csv'. Do make sure to copy the auxiliary files, as they contain information regarding the coordinate system of the shapefile!</p>
</div>
<div class="manual">
<h4>Preparing the spatial.csv file</h4>
<p>In your spatial file, you must include two columns with the coordinates for your receiver stations and release sites. These coordinates **must** be in the same coordinate system as the shapefile you just created before. Later on, you will need to know the *column names* of the columns that contain the X and Y coordinates.</p>
</div>
<div class="manual">
<h4>Importing the shapefile and preparing it</h4>
<p>Now that both your shapefile and your spatial.csv file are ready, lets get back to R. The first thing you need to do is import your shapefile and convert to a raster. I have created a function that can perform these steps for you, called <code>shapeToRaster()</code>.</p>
<pre><code class="language-r">base.raster <- shapeToRaster(shape, size, spatial, coord.x, coord.y, buffer)</code></pre>
<ol>
<li>The <code>shape</code> is the path to your shapefile, including the ".shp" extension. </li>
<li>The <code>size</code> determines the size of the raster's pixels.</strong>.
<ul>
<li>For example, if <code>size = 20</code>, then each pixel will have 20 by 20 meters. </li>
<li>Keep in mind that your pixel size must allow R to still capture the presence of your river channels. If the river channels are too slim, you can go back to your shapefile and artificially enlarge them.</li>
</ul>
</li>
<li>The <code>coord.x</code> and <code>coord.y</code> allow actel to search your spatial.csv file and match the station positions with the extent of the shapefile. Write the names of the columns containing the x and y coordinates in these two arguments to activate these checks.</li>
<li>The <code>buffer</code> allows you to request an expansion of the shapefile limits (can come in handy to ensure your stations are not cut-off from each other).</li>
</ol>
<p>Once the shapefile is successfully loaded, you can have a quick look at the resulting raster by running <code>raster::plot()</code>; i.e.:</p>
<pre><code class="language-r">raster::plot(base.raster)</code></pre>
<p>This should show you a plot where only the water areas are painted. Some water may show up around the edges of the original shapefile due to the range adjustments made by shapeToRaster. Converting a shapefile into a raster can take a while, specially if the original shapefile is very big and the pixel size is low.</p>
<p>If you have the spatial table loaded (e.g. through <code>loadSpatial()</code>), you can also add the stations to the plot generated by the line above:</p>
<pre><code class="language-r"># if you need to load a spatial.csv file:
spatial <- loadSpatial()
# Then, with the raster plot window open:
points(x = spatial$X, y = spatial$Y, pch = 20, col = "red")
# replace X and Y with the column names containing the coordinates
</code></pre>
</div>
<div class="manual">
<h4>Creating a transition layer</h4>
<p>A transition layer is an object that allows R to estimate least cost paths between two locations. Using the raster generated above, creating a transition layer is straight forward:</p>
<pre><code class="language-r">t.layer <- transitionLayer(base.raster, directions = 16)</code></pre>
The <code>directions</code> determine the complexity of R's distance tracking techniques. It can take one of four values: four, eight or sixteen, defaulting to the latter.
<ul>
<li>If <code>directions = 4</code>, the animal can only in the direction of the cardinal winds (North, South, East and West). </li>
<li>If <code>directions = 8</code>, the animal can also move in a intercardinal wind direction (Northeast, Northwest, Southeast and Southwest). </li>
<li>If <code>directions = 16</code>, then the animal can also move in the eight half-winds' directions.</li>
</ul>
<p>Increasing the <code>directions</code> improves the distance estimation fidelity, but also increases computation time.</p>
<p>Transition layers can take a long time to compute, especially for larger rasters, so you may have to bear with your computer for a bit here. To avoid having to go through this process multiple times, it may be a good idea to save the output of shapeToRaster and transitionLayer in a separate RData file, for later use.</p>
</div>
<div class="manual">
<h4>Creating the distances matrix</h4>
<p>Once you have your transition layer, you can use it to calculate multiple distances matrices, as long as the target objects fall within the extent of the original shapefile, and all targets are within water. To create your distances matrix, you must run <code>distancesMatrix()</code> in the same working directory as your 'spatial.csv' file. This will allow it you automatically load the spatial file into the function environment.</p>
<pre><code class="language-r">dist.mat <- distancesMatrix(t.layer, coord.x, coord.y)</code></pre>
<p>The <code>t.layer</code> is the transition layer you just calculated. Fill in the column names of the X and Y coordinates of your 'spatial.csv' file in <code>coord.x</code> and <code>coord.y</code>. When you run this command, actel will ask you if you want to save the output to a 'distances.csv' file. Alternatively, you can check the output within R and then save the matrix yourself!</p>
<p>Actel will automatically recognise the 'distances.csv' file and activate speed calculations in your next analysis!</p>
<div class="callout">
<div class="callout-header"> Note:</div>
<div class="callout-container">
<p> It is important that you check the results of this process by inspecting your distances matrix. If the distances do not look correct, you may have accidentally done something wrong in the steps above.</p>
</div>
</div>
<p>Here is a minimal example:</p>
<pre><code class="language-r"># move to a temporary directory to avoid
# overwriting local files
old.wd <- getwd()
setwd(tempdir())
# Fetch the location of actel's example files
aux <- system.file(package = "actel")[1]
# deploy the example spatial.csv file
file.copy(paste0(aux, "/example_spatial.csv"), "spatial.csv")
# import the example shapefile and use the spatial.csv file to check
# the extents.
base.raster <- shapeToRaster(shape = paste0(aux, "/example_shapefile.shp"),
coord.x = "x", coord.y = "y", size = 20)
# You can have a look at the resulting raster by running
raster::plot(base.raster)
# There should be two small islands in the bottom left area
# Build the transition layer
t.layer <- transitionLayer(base.raster)
# compile the distances matrix. Columns x and y in the spatial dataframe
# contain the coordinates of the stations and release sites.
dist.mat <- distancesMatrix(t.layer, coord.x = 'x', coord.y = 'y')
# check out the output:
dist.mat
# And return to your old working directory once done :)
setwd(old.wd)
rm(old.wd)
</code></pre>
<p>Remember that you can find more information about each of these functions by visiting their help pages. You can access the help pages by running <code>?shapeToRaster</code>, <code>?transitionLayer</code> or <code>?distancesMatrix</code>.</p>
</div>
<div class="manual">
<h3>The manual way</h3>
<p>The manual way is simple. In your R session, move to the folder where you have your spatial file, and run the command <code>emptyMatrix</code>. This will read your spatial data and create a matrix that is in accordance with it. It is important that you create your template this way, as the column and row names of the distance matrix are essential for actel to recognise the data. Below is an example of a distances matrix created by <code>emptyMatrix</code>.</p>
<div style="overflow-x: auto;">
<table>
<tr><th></th><th>St.1</th><th>St.2</th><th>St.3</th><th>St.4</th><th>St.5</th><th>St.6</th><th>Release</th></tr>
<tr><th>St.1</th><td>0</td><td></td><td></td><td></td><td></td><td></td><td></td></tr>
<tr><th>St.2</th><td></td><td>0</td><td></td><td></td><td></td><td></td><td></td></tr>
<tr><th>St.3</th><td></td><td></td><td>0</td><td></td><td></td><td></td><td></td></tr>
<tr><th>St.4</th><td></td><td></td><td></td><td>0</td><td></td><td></td><td></td></tr>
<tr><th>St.5</th><td></td><td></td><td></td><td></td><td>0</td><td></td><td></td></tr>
<tr><th>St.6</th><td></td><td></td><td></td><td></td><td></td><td>0</td><td></td></tr>
<tr><th>Release</th><td></td><td></td><td></td><td></td><td></td><td></td><td>0</td></tr>
</table>
</div>
<p>You can find the correspondence between the standard names (e.g. "St.1", "St.2") and your receivers by running <code>loadSpatial()</code> (see the 'Standard.name' column).</p>
<p>Now, you can either fill in the matrix directly in R or save it and edit it a spreadsheet editor (make sure to save the row names too!). To simplify the task, you can fill in the upper diagonal-half of the matrix, reload into R if you used an external editor, and then run <code>completeMatrix</code> on the edited object.</p>
<p>Here is how it works:</p>
<ol>
<li>Fill in the top part of the matrix:
<div style="overflow-x: auto;">
<table>
<tr><th></th><th>St.1</th><th>St.2</th><th>St.3</th><th>St.4</th><th>St.5</th><th>St.6</th><th>Release</th></tr>
<tr><th>St.1</th><td>0</td><td>1366</td><td>3417</td><td>6912</td><td>8864</td><td>9273</td><td>2230</td></tr>
<tr><th>St.2</th><td></td><td>0</td><td>2051</td><td>5546</td><td>7498</td><td>7906</td><td>3570</td></tr>
<tr><th>St.3</th><td></td><td></td><td>0</td><td>3528</td><td>5480</td><td>5889</td><td>5621</td></tr>
<tr><th>St.4</th><td></td><td></td><td></td><td>0</td><td>1963</td><td>2372</td><td>9116</td></tr>
<tr><th>St.5</th><td></td><td></td><td></td><td></td><td>0</td><td>409</td><td>11068</td></tr>
<tr><th>St.6</th><td></td><td></td><td></td><td></td><td></td><td>0</td><td>11476</td></tr>
<tr><th>Release</th><td></td><td></td><td></td><td></td><td></td><td></td><td>0</td></tr>
</table>
</div>
</li>
<li>Run <code>completeMatrix()</code> on the half-filled matrix:
<div style="overflow-x: auto;">
<table>
<tr><th></th><th>St.1</th><th>St.2</th><th>St.3</th><th>St.4</th><th>St.5</th><th>St.6</th><th>Release</th></tr>
<tr><th>St.1</th><td>0</td><td>1366</td><td>3417</td><td>6912</td><td>8864</td><td>9273</td><td>2230</td></tr>
<tr><th>St.2</th><td>1366</td><td>0</td><td>2051</td><td>5546</td><td>7498</td><td>7906</td><td>3570</td></tr>
<tr><th>St.3</th><td>3417</td><td>2051</td><td>0</td><td>3528</td><td>5480</td><td>5889</td><td>5621</td></tr>
<tr><th>St.4</th><td>6912</td><td>5546</td><td>3528</td><td>0</td><td>1963</td><td>2372</td><td>9116</td></tr>
<tr><th>St.5</th><td>8864</td><td>7498</td><td>5480</td><td>1963</td><td>0</td><td>409</td><td>11068</td></tr>
<tr><th>St.6</th><td>9273</td><td>7906</td><td>5889</td><td>2372</td><td>409</td><td>0</td><td>11476</td></tr>
<tr><th>Release</th><td>2230</td><td>3570</td><td>5621</td><td>9116</td><td>11068</td><td>11476</td><td>0</td></tr>
</table>
</div>
</li>
<li>Save the complete matrix as 'distances.csv' in the folder that has the remaining actel data.
</li>
</ol>
<div class="callout">
<div class="callout-header"> Note:</div>
<div class="callout-container">
<p>The distance values <strong>must</strong> be in metres!</p>
</div>
</div>
</div>
</div>
</div>
</section>
</main>
<!-- End main content -->
<!-- Start footer -->
<footer id="st-footer">
<div class="container">
<div class="st-footer-area">
<div class="row">
<div class="col-md-6">
<div class="st-footer-left">
<p class="st-copy-right">actel: Simplifying acoustic telemetry data analysis</p>
</div>
</div>
<div class="col-md-6">
<div class="st-footer-right">
<div class="st-social-media">
<a href="mailto:[email protected]" target="_blank" rel="noopener noreferrer"><i class="fa fa-envelope"></i></a>
<a href="https://ecoevo.social/@HugoMFlavio" target="_blank" rel="noopener noreferrer"><i class="fa-brands fa-mastodon"></i></a>
</div>
</div>
</div>
</div>
</div>
</div>
</footer>
<!-- End footer -->
<!-- Start JavaScript -->
<!-- jQuery first, then Popper.js, then Bootstrap JS -->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.2.1/jquery.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.11.0/umd/popper.min.js" integrity="sha384-b/U6ypiBEHpOf/4+1nzFpr53nxSS+GLCkfwBdFNTxtclqqenISfwAzpKaMNFNmj4" crossorigin="anonymous"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-beta/js/bootstrap.min.js" integrity="sha384-h0AbiXch4ZDo7tp9hKZ4TsHbi047NrKGLO3SEJAg45jXxnGIfYzk4Si90RDIqNm1" crossorigin="anonymous"></script>
<!-- Slick slider -->
<script type="text/javascript" src="assets/js/slick.min.js"></script>
<!-- Ajax contact form -->
<script type="text/javascript" src="assets/js/app.js"></script>
<!-- Modal popup -->
<script type="text/javascript" src="assets/js/modal.js"></script>
<!-- Custom js -->
<script type="text/javascript" src="assets/js/custom.js"></script>
<script type="text/javascript" src="assets/js/navBar.js"></script>
<!-- Code colouring -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>
<script>document.write('<script src="http://' + (location.host || 'localhost').split(':')[0] + ':35729/livereload.js?snipver=1"></' + 'script>')</script>
<!-- End JavaScript -->
</div>
</body>
<!-- End Body -->
</html>