---
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 animal could go through D and E/F, but that would require one more array jump)

Now, why is this relevant? If a tag is detected at B and then, for example, at F, the animal is equally likely to have gone through C or D. This means we cannot choose a most likely path. However, if a tag is detected at B and then at G, we can assume it is more likely that array C failed, than that the tag 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 tags shift positions. This means that, if a tag has multiple detection events in one single array, it counts as a single point, but if a tag 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 tag 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 tag is detected at A, D and E. However, unlike the example above, there are multiple occasions when the tag was detected at A and D (i.e., the tag was elsewhere in between). As such, this tag would award one point to array E and two points to arrays A and D.

## Assigning failed events

When a tag 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 tag moved from A to D.

    These two arrays are neighbours, so everything is ok.

2. The tag 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 tag moved from G to C.

    These two arrays are neighbours, so everything is ok.

4. The tag 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 tag is then finished.


## Minimum and maximum efficiency

Actel repeats the processes above for all tags, 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 tags 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.](#)
