---
title: "4.1) Processes behind residency()"
author: "Hugo Flávio"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{4.1) Processes behind residency()}
  %\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 multi-way efficiency estimations are [explained in this manual page.](d-3_residency_efficiency.html)

## Section movements

The initial processes of residency() are the same as those from [the explore() function](b-1_explore_processes.html).

Upon validating the movement events, the residency analysis proceeds to compressing these array-level events into section-level events. [You can find an example here](d-2_residency_results.html#section.movements). This shows how many times a fish entered and left each section. It is here that [the argument `section.minimum`](d-0_residency.html#section.minimum) comes in. If the number of consecutive detections at a given section are lower than the value stipulated, a warning will be issued, and user interaction is suggested:

````
M: Section movements with less than 2 detections are present for fish R64K-3.
Would you like to inspect the section movements from fish R64K-3?(y/N/comment)
````

You can then decide whether or not something should be considered invalid. Once all fish have been validated, 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-3 as the respective section movements were discarded by the user.
````

## Residency lists

Once the section movements have been validated, actel fills in the gaps between movements using the departure timestamp of a given section and the arrival timestamp of the next. These middle locations are labelled using both sections' names, separated with a dash (e.g. Down-Right). [You can find an example here](d-2_residency_results.html#residency.list).


## Compiling a timetable

Using the residency table above, actel compiles a summary timetable containing the following information for each section: number of times the fish entered the section, average entry time, average time spent per stay, average departure time and total time spent in the section. A few more summary columns are added to this table before it is bound to the information provided in the biometrics table.


## Daily locations

Based on the table above, actel will proceed to calculate the amount of time spent per day (in seconds) at each location. This leads to a very long table displaying both the number of seconds spent per day at each location, as well as the respective percentages. It also contains an additional column showing the location where the fish spent the most time each day. [You can find an example here](d-2_residency_results.html#daily.ratios).


## Global ratios

Using the table above as a reference for each fish, actel is then able to calculate how many of your fish were at each location during each passing day. Actel calculates two similar tables, one with absolute numbers, and one with percentages. [You can find an example here](d-2_residency_results.html#global.ratios).


## Wrapping up

After all this information has been compiled and stored, actel will wrap up by collecting the valid detections and storing them in the `valid.detections` object, which you can then use for other analyses. One last table is also stored containing a summary of the place of last detection for each group of fish. 

__[Learn more about the results of residency()](d-2_residency_results.html)__

[Back to top.](#)
