---
title: "1.1) Structuring the study area"
author: "Hugo Flávio"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{1.1) Structuring the study area}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Index

1. [Preparing your data](a-0_workspace_requirements.html)
    1. [__Structuring the study area__](a-1_study_area.html)
    1. [Creating a distances matrix](a-2_distances_matrix.html)
1. [explore()](b-0_explore.html)
    1. [Processes behind explore()](b-1_explore_processes.html)
    1. [Inspecting the explore() results](b-2_explore_results.html)
1. [migration()](c-0_migration.html)
    1. [Processes behind migration()](c-1_migration_processes.html)
    1. [Inspecting the migration() results](c-2_migration_results.html)
    1. [One-way efficiency estimations](c-3_migration_efficiency.html)
1. [residency()](d-0_residency.html)
    1. [Processes behind residency()](d-1_residency_processes.html)
    1. [Inspecting the residency() results](d-2_residency_results.html)
    1. [Multi-way efficiency estimations](d-3_residency_efficiency.html)
1. [Manual mode](e-0_manual_mode.html)
1. [Beyond the three main analyses](f-0_post_functions.html)
1. [Errors and messages](g-0_messages.html)

## From the field to the computer

To be able to process your data, actel must understand how your study area works. To do this, actel relies on two things: the study area sections and the receiver arrays. There are three levels of organization in an actel study area: sections, arrays and stations. Sections are composed by one or more arrays, and arrays are composed by one ore more stations.

Here is a visual example of a study area with an overlay of the respective arrays and sections:

<img src="study_area.svg" alt="drawing" width="680"/>


### Sections

The sections divide your study area in big blocks, for which you would like specific metrics to be calculated. In the example above, there are three sections: River, Fjord and Sea.

When you type the sections argument into the `migration()` function, you should order them in the order that you expect your fish will cross the sections. For example, if you expect your fish to move from the river to a fjord and ultimately to the sea (and you have receiver  arrays in all these sections), then `sections = c("River", "Fjord", "Sea")`. In the other hand, if you expect your fish to migrate upstream, then `sections = c("Sea", "Fjord", "River")`.

If you are running a `residency()` analysis, the order of the sections is not relevant (except for plotting purposes).

The `explore()` analysis does not take sections into consideration.


### Arrays

Arrays are the functional unit of actel. They determine groups of stations that, together, represent a point of change in the fish position. In the study area above, there are seven arrays, which are grouped into three sections.

Unless you are just running explore(), the array names are what links them to their respective sections. An array called "River1" is expected to belong to a section "River", an array called "Fjord3" is expected to belong to a section "Fjord", and so forth. To run migration() or residency(), array names **must** be an exact copy of the section they belong to, plus the number of the array. The connectivity between the arrays is determined either by their order of appearance in the _spatial.csv_ file, __or__ by a _spatial.txt_ file (you can see some examples below). It is **very important** that you structure your arrays correctly.


#### Avoid overlapping arrays

When a fish moves from one array to another, a new movement event is created (you will learn more about movement events later on). This means that, if you have two stations close to each other, but listed in two different arrays, you can end up with many 'false' movement events (i.e. the fish is just standing still within range of both arrays). Here is an example:

```{r, echo=FALSE, results='asis'}
load("badmovements.Rdata")
knitr::kable(badmovements[20:25,1:7])
```

Stations 15 and 17 are very close to each other, but were placed in different arrays. That in turn led to the creation of numerous movement events with only one detection, with nearly no time travelling between them. This fish ended up having 58 movement events, during most of which it was most likely just standing still.

As a rule of thumb, if two stations' ranges are likely to overlap, you should consider assigning them to the same array:

<img src="arrays_good.svg" alt="drawing" width="330"/> <img src="arrays_bad.svg" alt="drawing" width="330"/>

### Stations

Stations are geographical locations where one or more receivers have been deployed over the course of your study. They pinpoint the deployments on the map, and allow actel to make the link between detections and respective arrays. The stations must have unique names, so that the receiver deployments can be allocated to a specific stations, and are assigned to their respective arrays using the _spatial.csv_ file. You can find some examples below.

### Release sites

Release sites are a special form of station. Used to pinpoint the release locations of the tagged fish, release sites do not have receivers associated to them. Additionally, instead of being allocated to an array, they indicate which array is expected to be the first to detect the released fish. If you are not sure which array is expected to detect your fish first (e.g. fish released in a lake with multiple exits), you can tell actel to expect a first detection at multiple arrays. This has important consequences for array efficiency estimation, so it is important to get this right.


### Rivers with multiple parallel channels

If your study area includes multiple pathways that the fish may take, you must tell actel how to connect the arrays. By default, arrays are sorted in a linear order according to the spatial.csv file. To instruct actel to act otherwise, you must create a '**spatial.txt**' file. The spatial.txt file is very simple; all you need to do is connect your arrays in pairs. [You can learn more about spatial.txt files here](a-0_workspace_requirements.html#optional-spatial.txt-file)

Now you know how to organise your study area in a way that actel will understand!

**<a href="javascript:history.back()">Return to previous page</a>**

## Examples

### Single channel:

Let's imagine the following study area, where the red dots represent receiver stations:

<center>
<img src="spatialcsv_a1.svg" alt="drawing" width="400"/>
</center>

The first thing you will want to do is give individual names to your stations:

<center>
<img src="spatialcsv_a2.svg" alt="drawing" width="400"/>
</center>

Then, you need to decide how these stations should be organized into arrays. In this case, lets say each station is its own array:

<center>
<img src="spatialcsv_a3.svg" alt="drawing" width="400"/>
</center>

Then, you need to decide how many sections there are in your study area. In this case, one section (e.g. "River"), would probably be the best fit, but let's say we have two sections, for the sake of the exercise:

<center>
<img src="spatialcsv_a4.svg" alt="drawing" width="400"/>
</center>

Now that you know your stations, arrays, and sections, you can start filling up the spatial.csv file. Station A will belong to the first array of section Up (i.e. Up1), Station D will belong to the first array of section Down (i.e. Down1), and so forth:

```{r, echo=FALSE, results='asis'}
  spatial <- data.frame(Station.name=c("A","B","C","D","E")
    ,Array=c("Up1","Up2","Up3","Down1","Down2")
    ,Type=c("Hydrophone","Hydrophone","Hydrophone","Hydrophone","Hydrophone")
    )
knitr::kable(spatial)
```

Now onwards to the release sites. If you only have one release site at the top of the study area, i.e.:

<center>
<img src="spatialcsv_a5.svg" alt="drawing" width="400"/>
</center>

Then you are sure that the fish are expected to be first detected at array Up1:


```{r, echo=FALSE, results='asis'}
  spatial <- data.frame(Station.name=c("RS1")
    ,Array=c("Up1")
    ,Type=c("Release")
    )
knitr::kable(spatial)
```

However, you can also have fish released somewhere in the middle of the study area, i.e.:

<center>
<img src="spatialcsv_a6.svg" alt="drawing" width="400"/>
</center>

In this case, if you know that your fish are expected to move in a specific direction (i.e. a migration scenario), then we could say that there is only one expected first array (Down1, if the fish is migrating left to right):

```{r, echo=FALSE, results='asis'}
  spatial <- data.frame(Station.name=c("RS2")
    ,Array=c("Down1")
    ,Type=c("Release")
    )
knitr::kable(spatial)
```

However, if you do not know which direction the fish will take (i.e. a residency scenario), then the fish is just as likely to be first detected at Down1 as it is to be detected at Up3. To account for this, you must include both arrays in the spatial.csv file, separating them with a "\|".

```{r, echo=FALSE, results='asis'}
  spatial <- data.frame(Station.name=c("RS2")
    ,Array=c("Up3|Down1")
    ,Type=c("Release")
    )
knitr::kable(spatial)
```

You can now combine the stations and the release sites to obtain your spatial.csv file:

```{r, echo=FALSE, results='asis'}
  spatial <- data.frame(Station.name=c("A","B","C","D","E","RS1","RS2")
    ,Array=c("Up1","Up2","Up3","Down1","Down2","Up1","Up3|Down1")
    ,Type=c("Hydrophone","Hydrophone","Hydrophone","Hydrophone","Hydrophone","Release","Release")
    )
knitr::kable(spatial)
```

### Complex study area:

Let's now imagine a more complex study area, like the one below:

<center>
<img src="spatialcsv_b1.svg" alt="drawing" width="400"/>
</center>

Like before, you need to name your stations, group them into arrays, and define your study area sections:


<center>
<img src="spatialcsv_b2.svg" alt="drawing" width="400"/>
</center>

We can then start filling in the spatial.csv file:

```{r, echo=FALSE, results='asis'}
  spatial <- data.frame(Station.name=c("A","B","C","D","E","F","G")
    ,Array=c("Lake1","Lake2","Lake3","Lake4","River1","River2","River2")
    ,Type=c("Hydrophone","Hydrophone","Hydrophone","Hydrophone","Hydrophone","Hydrophone","Hydrophone")
    )
knitr::kable(spatial)
```

Now let's assume the fish are released inside the lake:

<center>
<img src="spatialcsv_b3.svg" alt="drawing" width="400"/>
</center>

In this case, regardless of the analysis you are running (migration or residency), there is uncertainty in the first expected array. If you expect that the fish will be migrating from the Lake to the River, you should state that the expected first arrays are either Lake3 or Lake4. If you are running a residency analysis, then it may make more sense to consider all Lake arrays as potential first arrays.

So, if you know your fish are moving to the river:

```{r, echo=FALSE, results='asis'}
  spatial <- data.frame(Station.name=c("RS1")
    ,Array=c("Lake3|Lake4")
    ,Type=c("Release")
    )
knitr::kable(spatial)
```

If you don't know where the fish will go to:

```{r, echo=FALSE, results='asis'}
  spatial <- data.frame(Station.name=c("RS1")
    ,Array=c("Lake1|Lake2|Lake3|Lake4")
    ,Type=c("Release")
    )
knitr::kable(spatial)
```


Like before, you can now compile the full spatial.csv file:


```{r, echo=FALSE, results='asis'}
  spatial <- data.frame(Station.name=c("A","B","C","D","E","F","G","RS1")
    ,Array=c("Lake1","Lake2","Lake3","Lake4","River1","River2","River2","Lake1|Lake2|Lake3|Lake4")
    ,Type=c("Hydrophone","Hydrophone","Hydrophone","Hydrophone","Hydrophone","Hydrophone","Hydrophone","Release")
    )
knitr::kable(spatial)
```

Since this study area is not linear, you would be required to write a spatial.txt file to tell actel how to link the arrays. [You can learn more about spatial.txt files here](a-0_workspace_requirements.html#optional-spatial.txt-file).

[Back to top.](#)