First of all, congratulations! If you are reading this page, you must have successfully ran an actel analysis on your data. I hope you have found the results useful :)
Here you will find some additional examples of things you can do using the output of your analysis. As actel connects to other packages and expands its capacities, so will this page.
Both the migration and the residency analyses include efficiency calculations. However, these calculations can sometimes be somewhat limited. To get a better idea of your array efficiencies, you can run the function advEfficiency on the efficiency outputs of your actel analysis.
Let us assume that you have stored the results of your analysis in an object called results (i.e. you ran results <- migration(...) or results <- residency(...)).
You can run advEfficiency on three different contexts:
# Run estimation on the overall detections
advEfficiency(results$overall.CJS)
# Run estimation on the detections for a specific group
advEfficiency(results$group.overview$name)
# Replace "name" with the actual name of the group.
# Run estimation on the detections for a specific group from a specific release site
advEfficiency(results$release.overview$A.B)
# Replace "A" with the group name and "B" with the name of the release site.# advEfficiency will estimate both the maximum and minimum efficiency.
advEfficiency(results$efficiency)
# additionally, you can choose how these are plotted by manipulating
# the 'paired' and 'force.grid' arguments, e.g.:
advEfficiency(results$efficiency, paired = TRUE, force.grid = c(1, 4))advEfficiency(results$intra.array.CJS$name)
# Replace "name" with the name of the array for which the intra-array efficiency was calculated.Bonus case: If you want to know intra-array estimations for a specific group, you can adapt and run the code below:
# Fetch the detection matrix for the intra array estimate
# (replace "name" with the actual name of the array)
m <- results$intra.array.matrices$name
# Fetch the signals of the tags of the group you are interest in
# (replace "group_name" with the name of the group)
tags <- results$status.df$Signal[results$status.df$Group == "group_name"]
# Extract only the matrix rows that match the target group
m <- x[match(tags, stripCodeSpaces(rownames(m))), ]
# Remove any NA leftovers
m <- m[complete.cases(m), ]
# Re-calculate the intra-array CJS
x <- dualArrayCJS(m)
# Run advEfficiency on the new results
advEfficiency(x)advEfficiency comes with some additional parameters that will help you get the results exactly as you need them. Find more by running ?advEfficiency. The advEfficiency manual page also includes additional information on how the calculations are made, and how you could explain them in a paper, if you need to!
Circular plots are a great way to display your results in a publication. Examples include differences between groups or between arrival points at different places. Although actel provides circular plots with its analyses, these default plots may not be exactly what you are looking for. As such, I created the function plotTimes, to help you get your plot just right.
You can prepare the input for plotTimes by using two other functions (which may also be useful on their own): getTimes and timesToCircular.
For example, if you want to plot the arrival times for all your fish at two arrays:
# Extrat the times from your 'results' object
x <- getTimes(results, locations = c("A", "B"))
# Convert the times to a circular object
x <- timesToCircular(x)
# and plot it
plotTimes(x)
# You can include a night period by using the night argument, e.g.:
plotTimes(x, night = c("20:00", "06:00"))This will plot two data series (one for array “A” and one for array “B”), with all your fish pooled together.
However, if you want to plot the arrival times at a specific array per group, you could do the following:
x <- getTimes(results, locations = "A")
x <- timesToCircular(x, by.group = TRUE)
plotTimes(x)
# You can change the names on the legend by changing the
# names of object 'x' (run 'names(x)' to see them).This will plot each group that arrived at array “A” in a different colour.
You can then choose the combination that makes more sense for the point you are trying to prove. Additionally, plotTimes allows you to shade a portion of the graphic to highlight the night period, and comes with a series of other arguments that allow you to personalise your plot until it is on point (see ?plotTimes for more details).
Bonus case: You can combine time data from multiple analyses. For example, if you ran your study during two years, you can plot the arrival times at a given array for both years and see if there is any variation.
# Load the results from both years:
y1 <- dataToList("actel_migration_results_year1.RData")
y2 <- dataToList("actel_migration_results_year2.RData")
# extract the time data for a specific array:
x1 <- getTimes(y1, locations = "A")
x2 <- getTimes(y2, locations = "A")
# Convert the times to circular, and combine them in a single list
x <- list(
year.1 = timesToCircular(x1)[[1]],
year.2 = timesToCircular(x2)[[1]])
# The names you choose for each object above will be used in the plot legend,
# for example, in this plot, the legend would read "year.1" and "year.2".
# plot both years together!
plotTimes(x)
# You can also choose your own colours, and even give it a title:
plotTimes(x, col = c("blue", "orange"), title = "A plot of two datasets!")You can expand on the example above to plot different groups too. Once you have finished your plot, you can save it to an svg file by adding a name to the ‘file’ argument.
Detection plots provide a lot of information. However, the default plots printed in the reports may be to small to analyse, or perhaps you would like to edit them to use in a presentation or paper. plotMoves() is the function you are looking for.
# Assuming you saved the output of an actel analysis as 'results',
# you can then plot the detections for single individuals. Imagine
# you want to see tag 'R64K-1995'. You can run:
plotMoves(results, tag = "R64K-1995")
# plotMoves comes with some additional personalisation arguments,
# such as title, or array.alias. array.alias allows you to replace
# default name of an array with a name of your choosing, e.g.:
plotMoves(results, tag = "R64K-1995", array.alias = c("River1" = "My_first_array"))
# additionally, if you give the same name to multiple arrays, they
# will be combined automatically! e.g.:
plotMoves(results, tag = "R64K-1995", array.alias = c("River1" = "River", "River2" = "River"))
# You can find all the details about plotMoves arguments by running
?plotMoves
# plotMoves returns a ggplot object, which means you can edit it further!
# Very simple example:
library(ggplot2)
p <- plotMoves(results, tag = "R64K-1995")
p <- p + xlab("changing the label after running plotMoves is possible!")
p
# Of course, you can also save your new plots using ggsave.If you have included a valid distances matrix in your analysis, then there is a lot of valuable information scattered throughout the fish movements. While this information is summarised at the section level in the status.df object (for migration() and residency() analyses), maybe you would like to have a look at the event-to-event values. To avoid having to go through each movement table individually, you can use the function getSpeeds():
# As usual, lets assume you saved the output of an actel analysis as 'results'.
# Running getSpeeds on the results will return all the recorded speeds, for
# every fish.
getSpeeds(results)
# However, you can trim this output by using the remaining arguments in getSpeeds().
# For example, return only the speeds between neighbouring arrays by using:
getSpeeds(results, direct = TRUE)
# This will only return speeds when the respective movement did not imply
# skipping an ALS array.
# You can further trim these results by choosing only events in a specific direction:
# To display only speeds in a forward direction (as specified by the study area structure)
getSpeeds(results, direct = TRUE, type = "forward")
# Or only in the backwards direction
getSpeeds(results, direct = TRUE, type = "backward")
# The default is "all"
getSpeeds(results, direct = TRUE, type = "all")
# A little side note on directions:
# If you stated in the spatial.txt file that "A -- B", then A is considered to
# come before B, and thus a movement from A to B is a forward movement.
# Consequently a movement from B to A is considered a backwards movement.
#
# Note that movements between parallel arrays are not forward nor backward,
# and the respective speeds will only be displayed if type = "all".
# Finally, you can choose how many events per fish you want to see:
getSpeeds(results, direct = TRUE, type = "all", n.events = "first") # default
getSpeeds(results, direct = TRUE, type = "all", n.events = "all")
getSpeeds(results, direct = TRUE, type = "all", n.events = "last")
# The n.events controls how many instances of a specific movement event you would like to see.
# If a fish moved twice from A to B, "first" will return only the first speed, "last" will
# return only the last speed, and "all" will return both.
# Note that moving from A to B is not the same as moving from B to A, and both will be treated
# separately by getSpeeds.Because speeds have many underlying variables (from where, to where, which fish, etc.), there is no pre-made plot function for speeds. However, the output of getSpeeds() is structured in a way that should make it easy for you to jump to ggplot2 and start drawing your plots, your way :)
actel is a work in progress. Is there any anything you would like to do or see in your data that is missing? Do you think it could be a useful function for actel? Get in touch!
I hope you enjoy using actel!