---
title: "4.3) Multi-way efficiency estimations"
author: "Hugo Flávio"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{4.3) Multi-way efficiency estimations}
  %\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. [The preload() function](a-3_preload.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)


## Multi-way efficiency

Before starting efficiency estimations, actel gathers detailed information on the array structure of your study area. Let's use the study area below as an example. 

<center>
<img src="multi_way_efficiency.svg" alt="drawing" width="330"/>
</center>

With this spatial.txt file:

```
A -- B -- C -- G
A -- D -- E -- G
D -- F -- G
D -- B
C -- E
C -- F
E -- F
```

Using array B as an example, actel finds out which arrays are directly connected to B, and which would be the shortest path (in number of arrays) between B and the remaining arrays. If there are multiple paths with the same number of array jumps, actel stores them all. Let's have a look in more detail:

1. B is connected directly to A, C and D.

2. There are two equally long paths between B and E:

    B -> C -> E

    B -> D -> E

3. The same applies between B and F:

    B -> C -> F

    B -> D -> F

4. However, there is only one shortest path between B and G:

    B -> C -> G

    (the fish could go through D and E/F, but that would require one more jump)

Now, why is this relevant? If a fish is detected at B and then, for example, at F, the fish is equally likely to have gone through C or D. This means we cannot choose a most likely path. However, if a fish is detected at B and then at G, we can assume it is more likely that array C failed, than that the fish passed through two arrays undetected (i.e. D and E or F).

## Assigning successful events

To count the number of successful events, actel assigns one point for every time the fish shifts positions. This means that, if a fish has multiple detection events in one single array, it counts as a single point, but if a fish goes somewhere else and returns to the initial array, it will count as two points in the initial array. Let's see some movement tables as examples:

|Array  | Detections|First.station |Last.station |First.time          |Last.time           |... |
|:------|----------:|:-------------|:------------|:-------------------|:-------------------|:---|
|A      |          1|St.1          |St.1         |2019-06-13 22:26:37 |2019-06-13 22:26:37 |... |
|D      |          1|St.4          |St.4         |2019-07-13 22:26:38 |2019-07-13 22:26:38 |... |
|D      |          1|St.4          |St.4         |2019-07-14 13:26:39 |2019-07-14 13:26:39 |... |
|D      |          1|St.4          |St.4         |2019-07-14 20:26:40 |2019-07-14 20:26:40 |... |
|E      |          1|St.5          |St.5         |2019-07-15 10:26:41 |2019-07-15 10:26:41 |... |
|C      |          1|St.3          |St.3         |2019-08-30 22:26:42 |2019-08-30 22:26:42 |... |


In this example, the fish was detected at A, D, E and C. Even though there are three movement events at D, since they are sequential, they will count as a single successful detection.

|Array  | Detections|First.station |Last.station |First.time          |Last.time           |... |
|:------|----------:|:-------------|:------------|:-------------------|:-------------------|:---|
|A      |          1|St.1          |St.1         |2019-06-13 22:26:37 |2019-06-13 22:26:37 |... |
|D      |          1|St.4          |St.4         |2019-07-13 22:26:38 |2019-07-13 22:26:38 |... |
|E      |          1|St.5          |St.5         |2019-07-14 13:26:39 |2019-07-14 13:26:39 |... |
|D      |          1|St.4          |St.4         |2019-07-14 20:26:40 |2019-07-14 20:26:40 |... |
|A      |          1|St.1          |St.1         |2019-07-15 10:26:41 |2019-07-15 10:26:41 |... |
|A      |          1|St.1          |St.1         |2019-08-30 22:26:42 |2019-08-30 22:26:42 |... |

In this case, the fish is detected at A, D and E. However, unlike the example above, there are multiple occasions when the fish was detected at A and D (i.e., the fish was elsewhere in between). As such, this fish would award one point to array E and two points to arrays A and D.

## Assigning failed events

When a fish is detected at more than one array, actel checks if consecutive events are at neighbouring arrays or not. If the two consecutive arrays are neighbours, everything is in order, but if not, actel proceeds to finding out which arrays have failed. If there is one single shortest path between the two arrays, actel attributes a "surely missed" point to the arrays constituting that path. If there are more than one equally short paths between the two arrays, actel attributes a "potentially missed" point to all the arrays involved in those paths. Here is an example:


|Array  | Detections|First.station |Last.station |First.time          |Last.time           |... |
|:------|----------:|:-------------|:------------|:-------------------|:-------------------|:---|
|A      |          1|St.1          |St.1         |2019-06-13 22:26:37 |2019-06-13 22:26:37 |... |
|D      |          1|St.4          |St.4         |2019-07-13 22:26:38 |2019-07-13 22:26:38 |... |
|G      |          1|St.7          |St.7         |2019-07-14 13:26:39 |2019-07-14 13:26:39 |... |
|C      |          1|St.3          |St.3         |2019-07-14 20:26:40 |2019-07-14 20:26:40 |... |
|A      |          1|St.1          |St.1         |2019-07-15 10:26:41 |2019-07-15 10:26:41 |... |

Let's go by events:

1. The fish moved from A to D.

    These two arrays are neighbours, so everything is ok.

2. The fish moved from D to G.

    These two arrays are not neighbours, and there are two equally long paths between them. As such, actel will attribute one "potentially missed" point to arrays E and F.

3. The fish moved from G to C.

    These two arrays are neighbours, so everything is ok.

4. The fish moved from C to A.

    These two arrays are not neighbours, and there is only one shortest path between them. As such, actel will attribute one "surely missed" point to array B.

The process for this fish is then finished.


## Minimum and maximum efficiency

Actel repeats the processes above for all fish, and compiles a table of successful, surely missed and potentially missed events. Then, we have what we need to calculate efficiency:

`max_efficiency = 1 - (s / (r + s))`

`min_efficiency = 1 - ((s + p) / (r + s + p))`

Where:

`r` = recorded events

`s` = surely missed events

`p` = potentially missed events

All the information used to calculate the efficiency is stored in the [`efficiency` object](d-2_residency_results.html#efficiency).


## Intra-array efficiency

Intra array efficiency calculations are performed following the equations provided by <a href="https://www.researchgate.net/publication/256443823_Using_mark-recapture_models_to_estimate_survival_from_telemetry_data" target="_blank">Perry et al. (2012)</a>. Specifically, actel splits the array's receivers in "original" and "replicates" (depending on what you specified in the [replicates argument](d-0_residency.html#replicates)), and compares the fish detected at both of these elements. The results of the intra-array calculations for each array are then stored in the [`intra.array.CJS` list](d-2_residency_results.html#intra.array.cjs).


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

[Back to top.](#)
