The arguments in the explore()
function are transversal to the migration() and residency() functions.
Although there are many arguments available, you do not need to start working with all of them right away. This is because many of these arguments have default values. If you want to make a quick check of your study, just run explore()
with a tz
argument in the same directory as your data and you will be ready to get some results!
E.g.:
Curious about how explore() processes your data? Have a look under the hood!
Need help going through the output of explore()? Find more details here.
All the arguments of explore(), which also exist in migration() and residency(), are explained below.
explore(tz, max.interval = 60, minimum.detections = 2, start.time = NULL, stop.time = NULL,
speed.method = c("last to first", "first to first"), speed.warning = NULL,
speed.error = NULL, jump.warning = 2, jump.error = 3, inactive.warning = NULL,
inactive.error = NULL, exclude.tags = NULL, override = NULL, report = FALSE,
auto.open = TRUE, discard.orphans = FALSE, discard.first = NULL, discard.orphans = FALSE,
save.detections = FALSE, GUI = c("needed", "always", "never"),
plot.detections.by = c("stations", "arrays"))
Receivers usually work in Coordinated Universal Time (UTC). Although this is nice to integrate data from multiple receivers, depending on where you are working, it may mean that the receivers’ time is actually displaced from the daytime in your study area. To correct for this, you must include your time zone in this field. For example, to analyse a study performed in Denmark, we must use tz = "Europe/Copenhagen"
.
Time zones can be complicated business, so to help you out, you can search this wiki page or the output of OlsonNames()
for the time zone code which you should use.
If a fish is detected multiple times in one array without being detected in other arrays, these detections are grouped into a single event, assuming that the time difference between two consecutive detections does not exceed max.interval
(which is set in minutes). Should the time between detections exceed max.interval
, a new movement event will be created, in the same receiver array.
In the example below, you can see how the same detections can be interpreted as a different number of movement events depending on whether we set max.interval
to a) 120 minutes, b) 60 minutes or c) 30 minutes.
Array | Detections | First station | Last station | First time | Last time | Time travelling | Time on array |
---|---|---|---|---|---|---|---|
Array1 | 14 | St.1 | St.1 | 2019-05-15 12:00:00 | 2019-05-15 19:45:00 | NA | 7:45 |
Array | Detections | First station | Last station | First time | Last time | Time travelling | Time on array |
---|---|---|---|---|---|---|---|
Array1 | 7 | St.1 | St.1 | 2019-05-15 12:00:00 | 2019-05-15 14:40:00 | NA | 2:40 |
Array1 | 6 | St.1 | St.1 | 2019-05-15 16:00:00 | 2019-05-15 18:00:00 | 1:20 | 2:00 |
Array1 | 1 | St.1 | St.1 | 2019-05-15 19:45:00 | 2019-05-15 19:45:00 | 1:45 | 0:00 |
Array | Detections | First station | Last station | First time | Last time | Time travelling | Time on array |
---|---|---|---|---|---|---|---|
Array1 | 4 | St.1 | St.1 | 2019-05-15 12:00:00 | 2019-05-15 13:00:00 | NA | 1:00 |
Array1 | 3 | St.1 | St.1 | 2019-05-15 13:50:00 | 2019-05-15 14:40:00 | 0:50 | 0:50 |
Array1 | 2 | St.1 | St.1 | 2019-05-15 16:00:00 | 2019-05-15 16:20:00 | 1:20 | 0:20 |
Array1 | 4 | St.1 | St.1 | 2019-05-15 17:10:00 | 2019-05-15 18:00:00 | 0:50 | 0:50 |
Array1 | 1 | St.1 | St.1 | 2019-05-15 19:45:00 | 2019-05-15 19:45:00 | 1:45 | 0:00 |
This argument controls how many times a fish must be registered to be considered valid, if there is only one movement event. Lets have a look at an example:
Fish A only has one movement event at River1, with one detection.
If minimum.detections = 1
, this movement is considered valid, and the fish is considered to have passed through River1 and then disappeared.
If minimum.detections = 2
, this movement is considered invalid (i.e. could be the result of error detections), and the fish is considered to have been lost after release.
If a Fish has more than one movement event, then the minimum.detections
argument no longer plays a role.
For example, if Fish B has two movement events at River1, both with one detection (i.e. two detections in total), these movements are considered valid even if minimum.detections = 3
. This is because it is unlikely that an erroneous signal which matches a target tag would be recorded on two or more occasions separated in time and/or space.
Sometimes your receivers contain much more detection data than what you are interested in, which can increase the time it takes to process all the detections. By including a start.time
and/or an stop.time
, you can trim the detection data to those target times.
This is particularly relevant if, for example, you used some of your tags as testers before the study started, or if you used one of the receivers to activate and test the tags. A fish being detected before being released is a major issue, and actel will complain about that:
Error: Fish R64K-1111 was detected before being released!
Release time: 2018-04-10 12:00:00
First detection time: 2018-04-10 09:33:02
Number of detections before release: 1
You may either:
a) Stop the analysis and check the data;
b) Discard the before-release detections and continue.
Decision:(a/b/comment)
When you get an error like this, it is highly recommended that you check potential errors in the input files before discarding data.
When calculating movement speeds from one array to the next, it is important to know if actel should count the time from the last detection in the previous array to the first detection in the target array, or if you want actel to count the time from the last detection in the previous array to the last detection in the target array. This is what speed.method
is doing. You can choose one of "last to first"
or "last to last"
. The example below illustrates the difference between both methods:
There are two main consequences of choosing different options for speed.method. The first is that the “average.speed.m.s” column in the movement events will reflect the respective “Speed to X” in the graphic above. The second is only relevant during the migration analysis: if speed.method = “first to last”, speed will be displayed in two columns in the status.df
object: “Average.speed.to.[Section]” and “Average.speed.in.[Section]”; while if speed.method = “last to last”, only the “Average.speed.to.[Section]” will be generated.
These two variables control the speed checks. By default, they are NULL, and no speed checks are performed. actel will let you know this happened with the following message:
M: 'speed.warning'/'speed.error' were not set, skipping speed checks.
However, if you include a distances matrix in the analysis, you can specify the maximum expected speed for your fish, in metres per second. If a fish goes over these values, warnings and user interaction will be activated, as necessary.
Speed checks cannot be performed without a distance matrix. If you attempt to do this, actel will complain:
Warning: 'speed.warning'/'speed.error' were set, but a valid distance matrix is not present. Aborting speed checks.
During the course of a study, fish can (hopefully not too often) pass through a receiver array undetected. However, if this happens consecutively for more than one array, then perhaps something fishy is going on. Was your fish eaten by a bird? Was there something wrong with the arrays? Whatever the cause, there is a point after which you get suspicious. The jump.warning
and jump.error
arguments control how suspicious you want to be.
You can have a look at these arguments in action here.
These two variables control the inactiveness checks. inactive.warning
and inactive.error
must be set in days. That is, if inactive.warning = 2
, any fish that is deemed inactive for two days or more will trigger a warning. By default, they are NULL, and no inactiveness checks are performed. Actel will let you know this happened with the following message:
M: 'inactive.warning'/'inactive.error' were not set, skipping inactivity checks.
Although it is not a requirement, inactiveness checks work best if a distances matrix is present. If you choose to run inactiveness checks without a distances matrix, actel will remind you of this with the following message:
M: Running inactiveness checks without a distance matrix. Performance may be limited.
You can learn more about how the inactiveness checks operate here.
Once you finish your analysis, you should go through the generated outputs and check for any strange behaviour. We will discuss this in more detail later on, but for now the important message is that, if you would like to manually change the results for any set of tags, you can list their respective signals in override
to trigger full manual mode (e.g. override = c(1234, 1405)
).
When you list tags in override
, actel will recognise them and enter full manual mode when it is their turn to be analysed. You will know this is happening when you see the following message:
M: Override has been triggered for fish R64K-1234. Entering full manual mode.
You can find more information on how to operate full manual mode here.
The report
option activates a series of print functions that draw tables and figures for later integration in an html report. When you activate this option, actel assembles the html report and stores it in your working directory. If you already have a report in your working directory, actel will create a new file with a different name.
Here are some graphic examples:
When the report
option is activated, auto.open
comes into play. If auto.open
is TRUE (the default), then actel will automatically open your web browser and open the report as soon as it is completed!
This is a flow optimization argument. When actel finds detections outside of the receiver deployment periods, or that were recorded before their respective fish were released, by default, actel will ask the user what to do (discard those detections or stop the analysis so the user can check the data). However, you can tell actel to automatically discard any orphan detections by setting discard.orphans
to TRUE.
This argument allows you to discard any detections that happen too soon after the fish was released. You may want to do this to ensure your results are not biased by post-handling disturbance effects. discard.first
is set in hours, but if for example you want to set a time in days, you can always state that discard.first = 24 * 7
(for seven days in this case).
Detections can take a long time to compile. To save some time when importing the detections, you can set save.detections
to TRUE and actel will save an ‘actel.detections.RData’ file in your current working directory (or in the detections sub-directory) for later use. This option is particularly useful when handling very large detection datasets.
actel comes with a graphical interface intended to allow users to deal with very long movement tables that would otherwise overflow R’s output limits. However, this graphical interface requires additional packages installed, so it may not always be an option to rely on it. This is where GUI
comes in. Defaulting to ‘needed’, the graphical user interface will only kick in for very long tables. The other two options are ‘always’ and ‘never’, both of which are self explanatory.
If you cannot run the GUI on your computer and are faced with a very long table, do not worry! actel has a fall-back system, where the table is saved to a temporary file, which you can open in an external program such as Microsoft Excel of LibreOffice Calc. Have a look at the movements table there, let R know what you want to do, close the file and the analysis will continue automatically. This option requires a bit more work, but at least you can still complete your analysis :)
By default, the detections are plotted using the standard station names. However, when you are working with many stations, this can make the detection plots particularly hard to disentangle. As such, you can set plot.detections.by = 'arrays'
to use the study area’s arrays as the y axis.
Now that you know how to run the explore analysis, you may want to:
Learn more about what explore() is doing