Optional: spatial.txt file
If your study area has multiple branches, then you need to tell actel how your arrays connect with each other. This file is optional because, if omitted, actel will assume that your study area is composed by a single branch and that the array order is the one listed in the spatial.csv file.
The spatial.txt file is very simple; all you need to do is connect your arrays with either dashes or arrows (find out the difference below). You can connect your arrays in pairs or make longer strings. To decide whether or not two arrays should be connected, ask yourself the following: “Can the animals move from A to B without having to pass through any other array?” If the answer is yes, then the arrays should be connected. Let’s have a look at some examples:
One branch study area, fully covering arrays
This is the simplest case, e.g. your animals are migrating through a channel, and your arrays split this channel in sections. Like in the figure below:
For this specific case you do not need to include a spatial.txt file, as long as you order the arrays in the spatial.csv file. However, if you wanted to include a spatial.txt file, it would look like this:
A -- B -- C -- D -- ENote that you could also specify only one connection per line. E.g.:
A -- B
B -- C
C -- D
D -- EOne branch study area, partly-covering arrays
This case is similar to above, but some arrays do not cover the totality. For example, they may cover a specific area of a lake (e.g. a spawning ground), Like in the figure below:
In this case, the animals can move from B to D without passing through C. As such, a spatial.txt file is now required, and it would look like this:
A -- B -- D -- E
B -- C
C -- DNote that now, B, C and D are all directly connected with each other.
Multi branch study areas
In this case, the water channel branches into multiple paths, which may then merge again or not, like in the figure below:
Things are getting a bit more complex now. To make sure you do not miss any connection, it can be useful to draw in a map the links between the arrays as you write them down, so you can check at the end if everything is done. Below, I have marked in purple the connections between all the arrays:
And here is the respective spatial.txt:
A -- B
A -- E
A -- F
B -- E
B -- F
E -- F
B -- C
C -- D
C -- E
E -- D
F -- GOr, in the shortened version:
A -- B -- C -- D
A -- E -- D
A -- F -- G
B -- E -- F
B -- F
C -- EIf are feeling wary of including multiple links in a single line, you can use the function readDot to read your spatial.txt file before starting the analysis and see if everything checks out. E.g.: readDot(input = "spatial.txt")
- Note:
- This file can be called either “spatial.dot” or “spatial.txt”, and you can create it using a simple text editor such as notepad, kate, VIM, etc.
Array direction
In the migration analysis, array direction is relevant. That means that writing A -- B is not the same as writing B -- A. In the first case, array B comes after array A (i.e. the animals are expected to reach A before reaching B), while in the second case the situation is reversed. This has implications for array efficiency calculations, so be sure to encode your study area carefully.
If you intend to run an explore or residency analysis, array direction is irrelevant.
explore()/residency() vs migration()
An optimal spatial.txt may differ depending on whether you want to run a migration or an explore/residency analysis. This is because actel interprets the spatial.txt file differently depending on the analysis:
In an explore/residency analyses, A -- B should be read as:
It is possible to move from array A to array B and vice-versaIn a migration analysis, A -- B should be read as:
It is possible to move from array A to array B and vice-versa, AND the animals are expected to pass through array A before reaching array BLet’s have a look at this example.
In this case, the spatial.txt for a residency analysis would look like this:
A -- B -- C -- G
A -- D -- E -- G
D -- F -- G
D -- B
C -- E
C -- F
E -- FBut a spatial.txt for a migration analysis would look like this:
A -- B -- C -- G
A -- D -- E -- G
D -- F -- G
D -- B -- D
C -- E -- C
C -- F -- C
E -- F -- EThe difference here is that, in the spatial.txt for migration, actel expects arrays to connected in a directional way. That means that connecting D -- B and B -- D does not mean the same thing, and it is important that you explicitly state that the animals are as likely to reach B coming from D as they are to reach D coming from B. In other words, you are saying that neither of the movements would be an explicit backwards movement. This will inform actel that D and B are parallel arrays, and that special rules should apply to them. The same goes for C, E and F.
Barriers
Sometimes it is possible for your animals to go from A to B, but not from B to A. In actel, you can include this information to further refine the analysis. In total, there are three symbols you can use to connect your arrays: --, -> or <-.
If the animals can move from A to B and vice-versa, use A -- B.
If the animals can only move from A to B, use either A -> B or B <- A.
If an animal then actually moves from B to A, actel will try to find an alternative route that the animal could have taken. If there are no alternative routes from B to A, actel will call this situation to your attention.
This has implications for array efficiency calculations, so be sure to encode your study area carefully.
You can find more information about impassable barriers here.