---
title: "3.2) Inspecting the migration() results"
author: "Hugo Flávio"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{3.2) Inspecting the migration() results}
  %\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. [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)
1. [Errors and messages](g-0_messages.html)


## Results within R

The results compiled by the migration() function include [those of the explore() function](b-2_explore_results.html). To keep the vignettes shorter, I will only detail **new** outputs here:

### section.movements

The `section.movements` list contains the section-level movement events created during [the movement compressing process](c-1_migration_processes.html#section-movements). Here is an example:

|Section  | Events| Detections|First.array  |Last.array  |First.time |Last.time |Time.travelling |Time.in.section |
|:--------|------:|----------:|:------------|:-----------|:----------|:---------|:---------------|:---------------|
|River    |      3|         10|River1       |River3      |...        |...       |11:45           |0:00            |
|Fjord    |      2|          5|Fjord1       |Fjord2      |...        |...       |14:00           |03:32           |
|Sea      |      2|          7|Sea1         |Sea1        |...        |...       |26:27           |15:59           |
(Timestamps were trimmed so the table fits better in the page)


### status.df

The `status.df` is a data frame that combines both the timetable data and your biometrics into a single, organised table. 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 the recorded fate for each fish (i.e. disappeared somewhere or succeeded at crossing the study area), and summary information on the number and length of the recorded backwards movements. 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.


### section.overview

This small table is automatically generated with data extracted from the `status.df`. For each fish group, it details the number of fish that disappeared on any section and those that passed to the next. It is very helpful to get a quick overview of the results, and is incorporated in the [actel report](#actel_migration_report.html-if-report-true). Here is an example:

|         | Total| Disap..in.River| Migrated.to.Sea| Disap..in.Sea| Succeeded|
|:--------|-----:|---------------:|---------------:|-------------:|---------:|
|Hatchery |    40|              30|              10|             3|         7|
|Wild     |    40|              24|              16|             2|        14|


### array.overview

The `array.overview` shows you the number of known and estimated fish, per group, to have passed each of your arrays.

Note:
  : These only take into account forward movements. I.e., if the fish moved backwards, the results displayed in array.overview will no longer match the known survival. When looking for survival estimates, you should always refer back to the `section.overview` object for confirmation of the number of fish that entered/left each section.

If you activated the [report option](b-0_explore.html#report), this table is then converted into a graphic, which can be found in the actel migration report, under the section "Progression".


### matrices

In this object you will find the matrix/matrices that were used for efficiency estimations during CJS modelling. Note that these matrices only represent the forward movements. You can read more about it below, in the description of the `overall.CJS`.


### overall.CJS

This object contains the results of the efficiency estimations performed by actel. During the migration analysis, actel calculates forward efficiency only to improve the accuracy of the efficiency measurement. You can learn more about how these one-way efficiency estimations are made in [this manual page.](c-3_migration_efficiency.html)


### intra.array.CJS

If you provided intra-array estimates in the [replicates argument](c-0_migration.html#replicates), 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 CJS.


## Results in your working directory

The migration function saves [outputs similar to those saved by explore](b-2_explore_results.html#results-in-your-working-directory). The main differences are in the two elements listed below.

### actel_migration_results.RData

``
Would you like to save a copy of the results to actel_migration_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_migration_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 migration report contains the same sections as the explore report, plus the following:

1. **Array forward efficiency**

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

2. **Section survival**

  The survival is displayed both as a table and a figure, both of which use the content of the `section.overview` object, which is in your results in R.

2. **Last seen arrays**

  This graphic compiles the information on where each fish was last seen. The information used for this graphic can be found in the `status.df` object, which is in your results in R (more specifically in the 'Very.last.array' column).

3. **Progression**

  The progression plot is a visual representation of the `overall.CJS` object, which is in your results in R. 
  You can also examine the detailed values per group in the tables supplied (i.e. the `array.overview` object).


4. **Fish comparisons (Dotplots)**

  As the name suggests, this plot compares variables across all your fish: The total number of detections, and the time to/time in each of your study area sections. To simplify the visualisation, for each variable, the **top 10%** of the data is painted in **red**, and the **bottom 10%** of the data is painted in **blue**.

  This plot is meant to help you find fish with uncommon behaviour. Fish with a lot of detections are likely staying for a very long time within receiver range; a fish that moves too fast in comparison to the remaining may have been carried by a predator. It is up to you to look at these graphics and decide if anything looks odd. If it does, then note down the tag number, so you can have a closer look at the respective plot of detections.


5. **Graphics of detected tags**

  These graphics contain more information than those created by the explore function: the vertical grey dashed lines show the assigned moments of entry and exit for each study area section, and the assigned fate of the fish is shown in the header.

  It is a good idea to have a good look at all of these graphics and verify that everything is looking correct (i.e. actel has assigned fates and entry/exit points correctly). This is also a good chance to have a closer look at the tags you flagged as suspicious during the analysis.


## What if actel has miss-assigned something?

Fish with strange behaviour can be complicated to analyse. While actel's functions have been designed to deal with this as best as possible, you can always [enter manual mode](e-0_manual_mode.html) if you find out that actel has miss-assigned something. I.e. has a movement event been invalidated that seems valid, or vice-versa? Are part of the movements detected characteristic of predator behaviour?

[Back to top.](#)