4.2) Inspecting the residency() results

Hugo Flávio



  1. Preparing your data
    1. Structuring the study area
    2. Creating a distances matrix
    3. The preload() function
  2. explore()
    1. Processes behind explore()
    2. Inspecting the explore() results
  3. migration()
    1. Processes behind migration()
    2. Inspecting the migration() results
    3. One-way efficiency estimations
  4. residency()
    1. Processes behind residency()
    2. Inspecting the residency() results
    3. Multi-way efficiency estimations
  5. Manual mode
  6. Beyond the three main analyses

Results within R

The results compiled by the residency() function include those of the explore() function. To keep the vignettes shorter, I will only detail new outputs here:


The status.df is a data frame that combines both the timetable data and your biometrics into a single, organised table (see “Compiling a timetable”). If you have stored any comments during the analysis process, they will show up in a reserved column in this table. The status.df also contains some more summary information for each animal. This table can be quite big, so it may be a good idea to use head(status.df) the first time you look at it.


The section.movements list contains the section-level movement events created during the movement compressing process. Here is an example:

Section Events Detections First.array Last.array First.time Last.time Time.travelling Time.in.section
Down 1 1 Down1 Down1 11:45 0:00
Right 2 2 Right1 Right2 44:00 563:32
Left 2 2 Left4 Left4 56:27 295:59
Right 2 2 Right2 Right1 101:00 626:12
Down 1 1 Down2 Down2 462:47 0:00
Left 1 1 Left3 Left3 54:59 0:00

(Timestamps were trimmed so the table fits better in the page)


The residency.list contains a table for each of the target tags, detailing where it was since its first valid detection to its last. Here is an example of the residency list produced based on the section movements above:

Section First.time Last.time
Down 2019-06-06 00:00:15 2019-06-06 00:00:15
Down-Right 2019-06-06 00:00:15 2019-06-07 20:00:20
Right 2019-06-07 20:00:20 2019-07-01 07:33:00
Left-Right 2019-07-01 07:33:00 2019-07-03 16:00:53
Left 2019-07-03 16:00:53 2019-07-16 00:00:16
Left-Right 2019-07-16 00:00:16 2019-07-20 05:00:35
Right 2019-07-20 05:00:35 2019-08-15 07:13:00
Down-Right 2019-08-15 07:13:00 2019-09-03 14:00:10
Down 2019-09-03 14:00:10 2019-09-03 14:00:10
Down-Left 2019-09-03 14:00:10 2019-09-05 21:00:05
Left 2019-09-05 21:00:05 2019-09-05 21:00:05


This table contains information on the all arrival times for each tag, at each array. It is used to produce circular graphics in the report.


section.times is a list that contains two tables. The first one has all the arrival times for each tag, at each section, and the second has all the departure times, sorted in the same fashion. These are used to produce circular graphics in the report.


The time.ratios contains detailed information on the time spent at each location, per day (or hour, if timestep = "hours") , for each of the target tags. These tables can be quite long. Here is an example:

Date Down pDown Down-Right pDown-Right Right pRight Changes Most.time
2019-06-06 0 0 86385 1.000 0 0.000 0 Down-Right
2019-06-07 0 0 72020 0.834 14380 0.166 1 Down-Right
2019-06-08 0 0 0 0.000 86400 1.000 0 Right
2019-06-09 0 0 0 0.000 86400 1.000 0 Right
2019-06-10 0 0 0 0.000 86400 1.000 0 Right
2019-06-11 0 0 0 0.000 86400 1.000 0 Right

(Columns and rows were hidden so the table fits better in the page)


The time.locations is a data frame showing the place where each tag spent the most time during each day. It is a crucial middle step between the time.ratios and the global.ratios.


The global ratios is a list containing two elements:

  1. The absolute number of tags at each location in each day/hour:
Date Down Down-Left Down-Right Left Left-Right Right Total
2019-06-05 0 0 0 2 0 0 2
2019-06-06 0 0 1 2 0 0 3
2019-06-07 1 0 2 1 0 0 4
2019-06-08 3 0 1 1 0 1 6
2019-06-09 3 0 1 1 0 1 6
2019-06-10 2 1 1 1 0 1 6
  1. The percentage of tags at each location in each day/hour:
Date Down Down-Left Down-Right Left Left-Right Right Total
2019-06-05 0.000 0.000 0.000 1.000 0 0.000 1
2019-06-06 0.000 0.000 0.333 0.667 0 0.000 1
2019-06-07 0.250 0.000 0.500 0.250 0 0.000 1
2019-06-08 0.500 0.000 0.167 0.167 0 0.167 1
2019-06-09 0.500 0.000 0.167 0.167 0 0.167 1
2019-06-10 0.333 0.167 0.167 0.167 0 0.167 1


The group ratios are lists similar to the global.ratios, but where the data has been split by the groups you defined in the biometrics. This allows you to compare the residency patterns of your different groups!


The last.seen is a simple summary table, showing how many tags from each group were last seen at each section, with an extra column for tags that were never detected:

Disap. in Down Disap. in Left Disap. in Right Disap. at Release
Hatchery 2 1 0 0
Wild 2 2 3 0


The efficiency is a list containing three elements.

  1. A table of absolute events used to calculate the efficiency
  2. The maximum efficiency estimates for each array, using the data in the absolutes table.
  3. The minimum efficiency estimates, using the same table.

You can find more about how efficiency estimations are made in the residency analysis in this manual page.


If you provided intra-array estimates in the replicates argument, actel will estimate intra-array efficiencies for the target arrays. These results are stored in the object intra.array.CJS, and the combined efficiency estimate is used to complement the overall efficiency results.

Results in your working directory

The residency function saves outputs similar to those saved by explore. The main differences are in the two elements listed below.


Would you like to save a copy of the results to actel_residency_results.RData?(y/N)

To make sure that you don’t accidentally lose your results, you can save them right away in the current directory. The results present in this file are the same as the ones you obtain directly in your R console (see above). It differs from the explore() output both in name and content.

actel_residency_report.html (if report = TRUE)

This is the main non-R output. If you activated the report option, actel will compile an html report for you. The residency report contains the same sections as the explore report, plus the following:

  1. Array efficiency

Here you can see how efficient your receiver arrays were at detecting the tags that moved past them. These results can also be found in the efficiency object, which is in your results in R. If you supplied replicates, the results of the intra-array estimations will also show up here.

  1. Last seen

The sections where the tags were last detected is displayed both as a table and a figure, both of which use the content of the last.seen object, which is in your results in R.

  1. Average array arrival times

For each of your study area’s arrays, a circular plot will be drawn with all the arrival times of each tag. The tags are grouped by the groups listed in the biometrics.csv file. These plots are saved in .svg format in the Report folder, so you can easily use them elsewhere, if needed.

  1. Time details per section

This section is divided in two main subsections: arrivals and departures. A plot with the days when tags arrived/departed each of the sections is made, as well as circular plots with all the times-of-day recorded for each tag arriving/departing each section. These graphics are all based in the section.times object.

  1. Section progression

This section has a graphic representation of the data present in the global.ratios object. It shows how the tags have distributed across your study area as the days pass by.

  1. Individual residency plots

Here you can find a graphic representation of the data present in the daily.ratios object. It shows how much time each tag has spent at each location for each day/hour. All plots start and end in the same day, so it is easy to compare the behaviour of different animals.

Back to top.