---
title: "3.1) Processes behind migration()"
author: "Hugo Flávio"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{3.1) Processes behind migration()}
  %\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)


Note: 
  : The processes behind one-way efficiency estimations are explained in a [dedicated manual page.](c-3_migration_efficiency.html)

## Additional movement processes

The initial processes of migration() are the same as those from [the explore() function](b-1_explore_processes.html). However, when it comes to movement validity, actel will now also check if the fish was detected at an array that is not directly or indirectly below its release site. Should this happen, the following warning will be issued:

````
Warning: Fish R64K-1234 was detected in an array that is not after its release site! Opening relevant data for inspection.
   Release site: Trap
   Expected first array: River3

[...]

You may either:
  a) Stop the analysis if the expected first array is wrong;
  b) Continue as is (does not impact the results);
  c) Render a movement event invalid, if you are confident it is a false detection.

Decision:(a/b/c/comment)
````

Note:
  : An array is considered "behind the release site" if it is not part of the arrays to which the release array connects directly or indirectly. You can find the arrays considered directly or indirectly after/below of each array by checking the [arrays object](b-2_explore_results.html#arrays).

## Section movements

Upon validating the movement events, the migration analysis proceeds to compressing these array-level events into section-level events. These section-level events are then used to access the unidirectionality of movement, from release to the success arrays.

### Backwards movements

Tagged fish can move backwards either because they are reluctant of the new environments or because something ate them and you are now tracking the predator. The very first evidence of this is that the arrays to which each movement event belongs will no longer be arranged as expected. 

If this happens, but then the fish continues its journey, then the last movement events on each section will still be ordered as expected. Otherwise, if the fish moves backwards and then never returns, then the last movement events of each section will also be in an unexpected order. 

Let's have a look at two examples:

<img src="event_order_a1.svg" alt="drawing" width="330"/> <img src="event_order_b1.svg" alt="drawing" width="330"/>

#### A) Movement events unordered, but last events ordered

In this example, the fish starts by moving towards the Fjord, as expected, but then the moves back upstream into the river again. However, the fish then moves back in the expected direction and eventually leaves the study area. In this case, the last event in the Fjord will be after the last event in the River.

These backwards movements imply going to an anterior section. As such, a warning will be issued:

````
Warning: Inter-section backwards movements were detected for Fish R64K-4456.
````

#### B) Both Movement events and last events are unordered

In this example, contrary to the above, the fish moves back into the river and then disappears. This means that the last event in the Fjord is actually **before** the last event in the River. 

This has both an impact the assignment of the fish's fate. As such, a longer warning will be issued:

````
Warning: Inter-section backwards movements were detected for Fish R64K-4526 and the last events are not ordered!
````

#### Making movements linear

While early versions of actel required you to linearise the movements, the migration update introduced on 2020-05-31 gives migration() the power to handle these events. As such, you can choose to leave them as valid, if you think they represent the movements of your target fish, or invalidate them, if these seem like the movements of a predator, for example.

Once you have gone through this process for all relevant fish, if any section movement has been deemed invalid, the respective array movements will also be invalidated. Actel will let you know this happened by issuing a message:

````
M: Rendering 1 array movement(s) invalid for fish R64K-4508 as the respective section movements were discarded by the user.
````

## Compiling a timetable

Once the movement events have been verified, they will be used to fill in the timetable, which is the most important step of migration(). For each fish, actel will compile a series of metrics  for each of the [study area's sections](a-1_study_area.html#sections) (e.g. average speed, total time spent, number of entries, etc). Once actel determines when the fish entered and left the study area's sections, it becomes possible to determine the fish's fate. This is  where the [`success.arrays` variable](c-0_migration.html#success.arrays) comes in. If your fish was last detected on an one of those arrays, it's fate will be assigned as "Succeeded".

## Combining the time data with the biometrics

Finally, actel will automatically combine the time information with the information you included in the biometrics file. This new data frame is called *status.df*, and will be available to you in the function output.

## Inspecting the results

Finally, actel will compile some summary tables, prepare the report, and finish up. 

__[Learn more about the results of migration()](c-2_migration_results.html)__


[Back to top.](#)