Package 'actel'

Description

advEfficiency estimates efficiency ranges by fitting a beta distribution with parameters $\alpha$ = number of detected tags and $\beta$ = number of missed tags. The desired quantiles (argument q) are then calculated from distribution. Plots are also drawn showing the distribution, the median point (dashed red line) and the range between the lowest and largest quantile requested (red shaded section).

Usage

advEfficiency(
  x,
  labels = NULL,
  q = c(0.025, 0.5, 0.975),
  force.grid = NULL,
  paired = TRUE,
  title = ""
)

Arguments

Details

Examples for inclusion in a paper:

1. If advEfficiency was run on an overall.CJS object (i.e. migration analysis):

   "Array efficiency was estimated by fitting a beta distribution ($\alpha$ = number of tags detected subsequently and at the array, $\beta$ = number of tags detected subsequently but not at the array) and calculating the median estimated efficiency value using the R package actel [citation]."

2. If advEfficiency was run on an efficiency object (i.e. residency analysis):

   • If you are using maximum efficiency estimates:

     "Array efficiency was estimated by fitting a beta distribution ($\alpha$ = number of events recorded by the array, $\beta$ = number of events known to have been missed by the array). and calculating the median estimated efficiency value using the R package actel [citation]."

   • If you are using minimum efficiency estimates:

     "Array efficiency was estimated by fitting a beta distribution ($\alpha$ = number of events recorded by the array, $\beta$ = number of events both known to have been missed and potentially missed by the array). and calculating the median estimated efficiency value using the R package actel [citation]."

3. If advEfficiency was run on an intra.array.CJS object:

   "Intra-array efficiency was estimated by comparing the tags detected at each of the two replicates. For each replicate, a beta distribution was fitted ($\alpha$ = number of tags detected at both replicates, $\beta$ = number of tags detected at the opposite replicate but not at the one for which efficiency is being calculated) and the median estimated efficiency value was calculated. The overall efficiency of the array was then estimated as 1-((1-R1)*(1-R2)), where R1 and R2 are the median efficiency estimates for each replicate. These calculations were performed using the R package actel [citation]."

Replace [citation] with the output of citation('actel')

Value

A data frame with the required quantile values and a plot of the efficiency distributions.

Examples

# Example using the output of simpleCJS.
x <- matrix(
c(TRUE,  TRUE,  TRUE,  TRUE,  TRUE,
  TRUE, FALSE,  TRUE,  TRUE, FALSE,
  TRUE,  TRUE, FALSE, FALSE, FALSE,
  TRUE,  TRUE, FALSE,  TRUE,  TRUE,
  TRUE,  TRUE,  TRUE, FALSE, FALSE),
ncol = 5, byrow = TRUE)
colnames(x) <- c("Release", "A1", "A2", "A3", "A4")
cjs.results <- simpleCJS(x)

# These cjs results can be used in advEfficiency
advEfficiency(cjs.results)

# Example using the output of dualArrayCJS.
x <- matrix(
c( TRUE,  TRUE,
   TRUE, FALSE,
   TRUE,  TRUE,
  FALSE,  TRUE,
  FALSE,  TRUE),
ncol = 2, byrow = TRUE)
colnames(x) <- c("A1.1", "A1.2")
cjs.results <- dualArrayCJS(x)

# These cjs results can be used in advEfficiency
advEfficiency(cjs.results)

# advEfficiency can also be run with the output from the main analyses.
# the example.results dataset is the output of a migration analysis
advEfficiency(example.results$overall.CJS)

Description

Produces template files and folders required to run the explore, migration and residency functions.

Usage

blankWorkspace(dir, force = FALSE)

Arguments

Value

No return value, called for side effects

Examples

# running blankWorkspace deploys template
# files to a directory specified by the user
blankWorkspace(paste0(tempdir(), "/blankWorkspace_example"))

Description

Completes the bottom diagonal of a matrix with the same number of rows and columns.

Usage

completeMatrix(x)

Arguments

Details

It is highly recommended to read the manual page regarding distances matrices before running this function. You can find it here: https://hugomflavio.github.io/actel-website/manual-distances.html

Value

A matrix of distances between pairs of points.

Examples

# Create dummy matrix with upper diagonal filled.
x <- matrix(
 c( 0,  1,  2,  3,  4, 5,
   NA,  0,  1,  2,  3, 4,
   NA, NA,  0,  1,  2, 3,
   NA, NA, NA,  0,  1, 2,
   NA, NA, NA, NA,  0, 1,
   NA, NA, NA, NA, NA, 0),
 ncol = 6, byrow = TRUE)

# inspect x
x

# run completeMatrix
completeMatrix(x)

Description

Lotek CDMA logs are exported in TXT, and contain several chunks of of information. Importantly, the detections may be saved with a GMT offset, as opposed to the more common UTC standard. Additionally, the date format isn't the standard yyyy-mm-dd.

Usage

convertLotekCDMAFile(file, date_format = "%m/%d/%y")

Arguments

Details

This function extracts the detections from the CDMA file, converts the dates to yyyy-mm-dd, binds the time to the date and resets it to UTC, and ultimately converts the dataframe into the standard format accepted by actel.

Value

A data frame of standardized detections from the input file.

Examples

# create a dummy detections file to read
dummy_file <- tempfile()
sink(dummy_file)
cat(
"WHS FSK Receiver Data File

Receiver Configuration:
Working Frequency:  76 KHz
Bit Rate:           2400 bps
Code Type:          FSK
Serial Number:      WHS3K-1234567
Node ID:            10000

Receiver Settings:
GMT Correction:     00:00

Decoded Tag Data:
Date      Time             TOA       Tag ID    Type     Value     Power
=======================================================================
04/09/24  22:50:03     0.43875        37910       P       9.1        12
08/21/24  12:45:18     0.99646        55606       M         0         1
08/23/24  15:01:04     0.76042        55778       P       0.0         2

Receiver Sensor Messages:
Date      Time      Sensor   Temp     Press   Battery  Tilt-X  Tilt-Y  Tilt-Z
=============================================================================
04/11/24  21:44:00  T / P    1534         0

Receiver Setup Messages:
Date      Time      Type                    Details
=============================================================================
08/22/24  18:50:11  Change Logging Mode     New Mode: SETUP
")
sink()

# now read it
x <- convertLotekCDMAFile(dummy_file)

# the dummy file will be deleted automatically once you close this R session.

Description

Use blankWorkspace instead.

Usage

createWorkspace(dir, force = FALSE)

Arguments

Value

No return value, called for side effects

Examples

# createWorkspace is deprecated. Use blankWorkspace instead.

Description

Import RData in a list format

Usage

dataToList(source)

Arguments

Value

A list containing the objects present in the source RData file.

Examples

# Dummy example:
# Create two objects:
object_1 <- "This"
object_2 <- "Worked!"

# Save them as an RData file in R's temporary directory
save(object_1, object_2, file = paste0(tempdir(), "/dataToList_example.RData"))

# Remove the dummy objects as we don't need them any more
rm(object_1, object_2)

# Load the RData file as a single object
x <- dataToList(paste0(tempdir(), "/dataToList_example.RData"))

# inspect x
x

Description

Using a previously created transition layer (see transitionLayer), calculates the distances between spatial points. Adapted from Grant Adams' script "distance to closest mpa". if the argument 'actel' is set to TRUE (default), an actel-compatible matrix is generated, and the user will be asked if they would like to save the matrix as 'distances.csv' in the current directory.

Usage

distancesMatrix(
  t.layer,
  starters = NULL,
  targets = starters,
  coord.x = "x",
  coord.y = "y",
  id.col = NULL,
  actel = TRUE
)

Arguments

Details

It is highly recommended to read the manual page regarding distances matrices before running this function. You can find it here: https://hugomflavio.github.io/actel-website/manual-distances.html

Value

A matrix with the distances between each pair of points.

Examples

# check if R can run the distance functions
aux <- c(
  length(suppressWarnings(packageDescription("raster"))),
  length(suppressWarnings(packageDescription("gdistance"))),
  length(suppressWarnings(packageDescription("sp"))),
  length(suppressWarnings(packageDescription("terra"))))

missing.packages <- sapply(aux, function(x) x == 1)

if (any(missing.packages)) {
  message("Sorry, this function requires packages '",
    paste(c("raster", "gdistance", "sp", "terra")[missing.packages], collapse = "', '"),
    "' to operate. Please install ", ifelse(sum(missing.packages) > 1, "them", "it"),
    " before proceeding.")
} else {
  # move to a temporary directory
  old.wd <- getwd()
  setwd(tempdir())

  # Fetch location of actel's example files
  aux <- system.file(package = "actel")[1]

  # create a temporary spatial.csv file
  file.copy(paste0(aux, "/example_spatial.csv"), "spatial.csv")

  # import the shape file and use the spatial.csv
  # to check the extents.
  x <- shapeToRaster(shape = paste0(aux, "/example_shapefile.shp"),
    coord.x = "x", coord.y = "y", size = 20)

  raster::plot(x)

  # Build the transition layer
  t.layer <- transitionLayer(x)

  # compile the distances matrix. Columns x and y in the spatial dataframe
  # contain the coordinates of the stations and release sites.
  distancesMatrix(t.layer, coord.x = 'x', coord.y = 'y')

  # return to original directory
  setwd(old.wd)
  rm(old.wd)
}
rm(aux, missing.packages)

Description

Calculate estimated last-array efficiency

Usage

dualArrayCJS(input)

Arguments

Value

A list containing:

• absolutes A matrix with the absolute number of tags detected at each replicate and at both,

• single.efficiency A vector of calculated array detection efficiencies for each of the replicates,

• combined.efficiency The value of the combined detection efficiency for the array.

References

Perry et al (2012), 'Using mark-recapture models to estimate survival from telemetry data'. url: https://www.researchgate.net/publication/256443823_Using_mark-recapture_models_to_estimate_survival_from_telemetry_data

Examples

# prepare a dummy presence/absence matrix
x <- matrix(c(TRUE, TRUE, TRUE, TRUE, FALSE, TRUE), ncol = 2)
colnames(x) <- c("R1", "R2")

# run CJS
dualArrayCJS(x)

Description

Creates an empty matrix based on the local 'spatial.csv' file and saves it to 'distances.csv' so the user can manually fill it.

Usage

emptyMatrix(input = "spatial.csv")

Arguments

Details

It is highly recommended to read the manual page regarding distances matrices before running this function. You can find it here: https://hugomflavio.github.io/actel-website/manual-distances.html

Value

An empty matrix with the rows and columns required to operate with the target spatial file.

Examples

# This function requires a file with spatial information

# Fetch location of actel's example files
aux <- system.file(package = "actel")[1]

# run emptyMatrix on the temporary spatial.csv file
emptyMatrix(paste0(aux, "/example_spatial.csv"))

Description

Creates a ready-to-run workspace with example data.

Usage

exampleWorkspace(dir, force = FALSE)

Arguments

Value

No return value, called for side effects.

Examples

# deploy a minimal dataset to try actel!
exampleWorkspace(paste0(tempdir(), "/exampleWorkspace_example"))

Description

explore allows you to quickly get a summary of your data. You can use explore to get a general feel for the study results, and check if the input files are behaving as expected. It is also a good candidate if you just want to validate your detections for later use in other analyses.

Usage

explore(
  tz = NULL,
  datapack = NULL,
  max.interval = 60,
  minimum.detections,
  min.total.detections = 2,
  min.per.event = 1,
  start.time = NULL,
  stop.time = NULL,
  speed.method = c("last to first", "last to last", "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,
  save.detections = FALSE,
  GUI = c("needed", "always", "never"),
  save.tables.locally = FALSE,
  print.releases = TRUE,
  detections.y.axis = c("auto", "stations", "arrays")
)

Arguments

Value

A list containing:

• bio: A copy of the biometrics input;

• detections: A list containing all detections for each target tag;

• valid.detections: A list containing the valid detections for each target tag;

• spatial: A list containing the spatial information used during the analysis;

• deployments: A data frame containing the deployments of each receiver;

• arrays: A list containing the array details used during the analysis;

• movements: A list containing all movement events for each target tag;

• valid.movements: A list containing the valid movement events for each target tag;

• times: A data frame containing all arrival times (per tag) at each array;

• rsp.info: A list containing containing appendix information for the RSP package;

• dist.mat: A matrix containing the distance matrix used in the analysis (if a valid distance matrix was supplied)

See Also

migration, residency

Examples

# Start by moving to a temporary directory
old.wd <- getwd()
setwd(tempdir())

# Deploy the example workspace
exampleWorkspace("explore_example")

# Move your R session into the example workspace
setwd("explore_example")

# run the explore analysis. Ensure the tz argument
# matches the time zone of the study area. For the
# example dataset, tz = "Europe/Copenhagen"
results <- explore(tz = "Europe/Copenhagen")

# to obtain an HTML report, run the analysis with report = TRUE

# return to original working directory
setwd(old.wd)
rm(old.wd)

Description

Extract Code Spaces from transmitter names

Usage

extractCodeSpaces(input)

Arguments

Value

A vector of transmitter signals

Examples

# create dummy string
x <- c("R64K-1234", "A69-1303-12")

# run extractCodeSpaces
extractCodeSpaces(x)

Description

Extract signals from transmitter names

Usage

extractSignals(input)

Arguments

Value

A vector of transmitter signals

Examples

# create dummy string
x <- c("R64K-1234", "A69-1303-12")

# run extractSignals
extractSignals(x)

Description

Extract speeds from the analysis results.

Usage

getSpeeds(
  input,
  type = c("all", "forward", "backward"),
  direct = FALSE,
  n.events = c("first", "all", "last")
)

Arguments

Value

A data frame with the following columns:

• Tag: The tag of the animal who performed the recorded speed

• Event: The valid event where the speed was recorded

• From.array: The array from which the tags left

• From.station: The station from which the tags left

• To.array: The array to which the tags arrived

• To.station: The station to which the tags arrived

• Speed: The speed recorded in the described movement

Examples

# using the example results loaded with actel
getSpeeds(example.results)

# You can specify which direction of movement to extract with 'type'
getSpeeds(example.results, type = "forward")
# or
getSpeeds(example.results, type = "backward")

# and also how many events per tag (this won't change the output
# with the example.results, only because these results are minimal).
getSpeeds(example.results, n.events = "first")
# or
getSpeeds(example.results, n.events = "all")
# or
getSpeeds(example.results, n.events = "last")

Description

Extract timestamps from the analysis results.

Usage

getTimes(
  input,
  locations = NULL,
  move.type = c("array", "section"),
  event.type = c("arrival", "departure"),
  n.events = c("first", "all", "last")
)

Arguments

Value

A data frame with the timestamps for each tag (rows) and array (columns)

Examples

# using the example results loaded with actel
getTimes(example.results)

# You can specify which events to extract with 'event.type'
getTimes(example.results, event.type = "arrival")
# or
getTimes(example.results, event.type = "departure")

# and also how many events per tag.
getTimes(example.results, n.events = "first")
# or
getTimes(example.results, n.events = "all")
# or
getTimes(example.results, n.events = "last")

Description

Please use shapeToRaster instead.

Usage

loadShape(
  shape,
  size,
  spatial = "spatial.csv",
  coord.x = NULL,
  coord.y = NULL,
  buffer = NULL,
  type = c("land", "water")
)

Arguments

Value

A raster object.

Examples

message("This function is deprecated, please use shapeToRaster instead.")

Description

Loads a spatial file prepared for actel and appends the Standard.name column. Additionally, performs a series of quality checks on the contents of the target file.

Usage

loadSpatial(input = "spatial.csv", section.order = NULL)

Arguments

Value

A data frame with the spatial information present in 'spatial.csv' and the Standard.name column.

Examples

# This function requires the presence of a file with spatial information

# Fetch location of actel's example files
aux <- system.file(package = "actel")[1]

# run loadSpatial on the temporary spatial.csv file
loadSpatial(input = paste0(aux, '/example_spatial.csv'))

Description

The migration analysis runs the same initial checks as explore, but on top of it, it analyses the animal behaviour. By selecting the arrays that lead to success, you can define whether or not your animals survived the migration. Additional plots help you find out if some animal/tag has been acting odd. Multiple options allow you to tweak the analysis to fit your study perfectly.

Usage

migration(
  tz = NULL,
  section.order = NULL,
  datapack = NULL,
  success.arrays = NULL,
  max.interval = 60,
  minimum.detections,
  min.total.detections = 2,
  min.per.event = 1,
  start.time = NULL,
  stop.time = NULL,
  speed.method = c("last to first", "last to last", "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,
  save.detections = FALSE,
  if.last.skip.section = TRUE,
  replicates = NULL,
  disregard.parallels = TRUE,
  GUI = c("needed", "always", "never"),
  save.tables.locally = FALSE,
  print.releases = TRUE,
  detections.y.axis = c("auto", "stations", "arrays")
)

Arguments

Value

A list containing:

• detections: A list containing all detections for each target tag;

• valid.detections: A list containing the valid detections for each target tag;

• spatial: A list containing the spatial information used during the analysis;

• deployments: A data frame containing the deployments of each receiver;

• arrays: A list containing the array details used during the analysis;

• movements: A list containing all movement events for each target tag;

• valid.movements: A list containing the valid movement events for each target tag;

• section.movements: A list containing the valid section shifts for each target tag;

• status.df: A data.frame containing summary information for each tag, including the following columns:

  • Times.entered.[section]: Number of times the tag was recorded entering a given section.

  • Average.time.until.[section]: Time spent between release or leaving another section and reaching at the given section.

  • Average.speed.to.[section]: Average speed from release or leaving one section and reaching the given section (if speed.method = "last to first"), or from release/leaving one section and leaving the given section (if speed.method = "last to last").

  • First.array.[section]: Array in which the tag was first detected in a given section

  • First.station.[section]: Standard name of the first station where the tag was detected in a given section

  • First.arrived.[section]: Very first arrival time at a given section

  • Average.time.in.[section]: Average time spent within a given section at each stay.

  • Average.speed.in.[section]: Average speed within a given section at each stay (only displayed if speed.method = "last to first").

  • Last.array.[section]: Array in which the tag was last detected in a given section

  • Last.station.[section]: Standard name of the last station where the tag was detected in a given section

  • Last.left.[section]: Very last departure time from a given section

  • Total.time.in[section]: Total time spent in a given section

  • Very.last.array: Last array where the tag was detected

  • Status: Fate assigned to the tag

  • Valid.detections: Number of valid detections

  • Invalid.detections: Number of invalid detections

  • Backwards.movements: Number of backward movement events

  • Max.cons.back.moves: Longest successive backwards movements

  • P.type: Type of processing:

    • 'Skipped' if no data was found for the tag,

    • 'Auto' if no user interaction was required,

    • 'Manual' if user interaction was suggested and the user made changes to the validity of the events,

    • 'Overridden' if the user listed the tag in the override argument.

  • Comments: Comments left by the user during the analysis

• section.overview: A data frame containing the number of tags that disappeared in each section;

• group.overview: A list containing the number of known and estimated tags to have passed through each array, divided by group;

• release.overview: A list containing the number of known and estimated tags to have passed through each array, divided by group and release sites;

• matrices: A list of CJS matrices used for the efficiency calculations;

• overall.CJS: A list of CJS results of the inter-array CJS calculations;

• intra.array.CJS: A list of CJS results of the intra-array CJS calculations;

• times: A data frame containing all arrival times (per tag) at each array;

• rsp.info: A list containing appendix information for the RSP package;

• dist.mat: The distance matrix used in the analysis (if a valid distance matrix was supplied)

See Also

explore, residency

Examples

# Start by moving to a temporary directory
old.wd <- getwd()
setwd(tempdir())

# Deploy the example workspace
exampleWorkspace("migration_example")

# Move your R session into the example workspace
setwd("migration_example")

# run the migration analysis. Ensure the tz argument
# matches the time zone of the study area and that the
# sections match your array names. The line below works
# for the example data.
results <- migration(tz = "Europe/Copenhagen")

# to obtain an HTML report, run the analysis with report = TRUE

# return to original working directory
setwd(old.wd)
rm(old.wd)

Description

Plot simultaneous/cumulative presences at a give array or set of arrays

Usage

plotArray(
  input,
  arrays,
  title,
  xlab,
  ylab,
  lwd = 1,
  col,
  by.group = TRUE,
  y.style = c("absolute", "relative"),
  type = c("default", "bars", "lines"),
  timestep = c("days", "hours", "mins"),
  cumulative = FALSE,
  ladder.type = c("arrival", "departure")
)

Arguments

Value

A ggplot object.

Examples

# Using the example results that come with actel
plotArray(example.results, arrays = "A9")

# Because plotArray returns a ggplot object, you can store
# it and edit it manually, e.g.:
library(ggplot2)
p <- plotArray(example.results, arrays = "A9")
p <- p + xlab("changed the x axis label a posteriori")
p

# You can also save the plot using ggsave!

Description

The output of plotDetections is a ggplot object, which means you can then use it in combination with other ggplot functions, or even together with other packages such as patchwork.

Usage

plotDetections(
  input,
  tag,
  type,
  y.axis = c("auto", "stations", "arrays"),
  title,
  xlab,
  ylab,
  col,
  array.alias,
  section.alias,
  frame.warning = TRUE,
  x.label.format,
  only.valid = FALSE,
  like.migration = TRUE
)

Arguments

Value

A ggplot object.

Examples

# Using the example results that come with actel
plotDetections(example.results, 'R64K-4451')

# Because plotDetections returns a ggplot object, you can store
# it and edit it manually, e.g.:
library(ggplot2)
p <- plotDetections(example.results, 'R64K-4451')
p <- p + xlab("changed the x axis label a posteriori")
p

# You can also save the plot using ggsave!

Description

This function is useful for quickly checking if your spatial.txt file is properly set up. The spatial.txt file can be imported using readDot()

Usage

plotDot(
  dot,
  spatial,
  coord.x,
  coord.y,
  placement = c("literal", "spaced"),
  expand = 1,
  file,
  fill = c("#E69F00", "#56B4E9", "#009E73", "#F0E442", "#0072B2", "#D55E00", "#CC79A7"),
  text_colour = "white"
)

Arguments

Value

No return value, called to either plot or save graphic.

Examples

# create dummy dot string
x <- c(
"A--B--C--D--E--F
A--G--H--I--E
H--C")

my_dot <- readDot(string = x)

# now we can plot it using plotDot:
plotDot(my_dot)

# plotDot can also be called directly using the string of text:
plotDot(x)

Description

Plot array live times

Usage

plotLive(
  input,
  arrays,
  show.stations = FALSE,
  array.size = 2,
  station.size = 1,
  show.caps = TRUE,
  cap.prop = 2,
  title = "",
  xlab = "",
  ylab = "",
  col
)

Arguments

Value

A ggplot object.

Examples

# Using the example results that come with actel
plotLive(example.results)

# Because plotLive returns a ggplot object, you can store
# it and edit it manually, e.g.:
library(ggplot2)
p <- plotLive(example.results)
p <- p + xlab("changed the x axis label a posteriori")
p

# You can also save the plot using ggsave!

Description

The output of plotMoves is a ggplot object, which means you can then use it in combination with other ggplot functions, or even together with other packages such as patchwork.

Usage

plotMoves(
  input,
  tags,
  title,
  xlab,
  ylab,
  col,
  array.alias,
  show.release = TRUE
)

Arguments

Value

A ggplot object.

Examples

# Using the example results that come with actel
plotMoves(example.results, 'R64K-4451')

# Because plotMoves returns a ggplot object, you can store
# it and edit it manually, e.g.:
library(ggplot2)
p <- plotMoves(example.results, 'R64K-4451')
p <- p + xlab("changed the x axis label a posteriori")
p

# You can also save the plot using ggsave!

Description

By default, this function plots the global residency. However, you can use the argument 'group' to plot the results only from a specific animal group. Lastly, you can also use 'sections', rather than 'group', to compare the residency at a specific section (or group of sections) between the different groups.

Usage

plotRatios(
  input,
  groups,
  sections,
  type = c("absolutes", "percentages"),
  title,
  xlab,
  ylab,
  col,
  col.by = c("default", "section", "group")
)

Arguments

Details

The output of plotRatios is a ggplot object, which means you can then use it in combination with other ggplot functions, or even together with other packages such as patchwork.

Value

A ggplot object.

Examples

# For this example, I have modified the example.results that come with actel,
# so they resemble a residency output

plotRatios(example.residency.results)

# Because plotRatios returns a ggplot object, you can store
# it and edit it manually, e.g.:
library(ggplot2)
p <- plotRatios(example.residency.results, groups = "A")
p <- p + xlab("changed the x axis label a posteriori")
p

# You can also save the plot using ggsave!

Description

The output of plotResidency is a ggplot object, which means you can then use it in combination with other ggplot functions, or even together with other packages such as patchwork.

Usage

plotResidency(input, tag, title, xlab, ylab, col)

Arguments

Value

A ggplot object.

Examples

# For this example, I have modified the example.results that come with actel,
# so they resemble a residency output

plotResidency(example.residency.results, 'R64K-4451')

# Because plotResidency returns a ggplot object, you can store
# it and edit it manually, e.g.:
library(ggplot2)
p <- plotResidency(example.residency.results, 'R64K-4451')
p <- p + xlab("changed the x axis label a posteriori")
p

# You can also save the plot using ggsave!

Description

The output of plotSensors is a ggplot object, which means you can then use it in combination with other ggplot functions, or even together with other packages such as patchwork.

Usage

plotSensors(
  input,
  tag,
  sensor,
  title = tag,
  xlab,
  ylab,
  pcol,
  psize = 1,
  lsize = 0.5,
  colour.by = c("array", "section"),
  array.alias,
  lcol = "grey40",
  verbose = TRUE
)

Arguments

Value

A ggplot object.

Examples

# Using the example results that come with actel
plotSensors(example.results, 'R64K-4451')

# Because plotSensors returns a ggplot object, you can store
# it and edit it manually, e.g.:
library(ggplot2)
p <- plotSensors(example.results, 'R64K-4451')
p <- p + xlab("changed the x axis label a posteriori")
p

# You can also save the plot using ggsave!

Description

Wraps functions adapted from the circular R package.

Usage

plotTimes(
  times,
  night = NULL,
  circular.scale = c("area", "linear"),
  col,
  alpha = 0.8,
  title = "",
  mean.dash = TRUE,
  mean.range = TRUE,
  mean.range.darken.factor = 1.4,
  rings = TRUE,
  file,
  width,
  height,
  bg = "transparent",
  ncol,
  legend.pos = c("auto", "corner", "bottom"),
  ylegend,
  xlegend,
  xjust = c("auto", "centre", "left", "right"),
  expand = 0.95,
  cex = 1
)

Arguments

Details

For more details about the original functions, visit the circular package homepage at https://github.com/cran/circular

Value

A circular plot

Examples

# The output of timesToCircular can be used as an input to plotTimes.
x <- getTimes(example.results, location = "A1", n.events = "first", event.type = "arrival")
times <- timesToCircular(x)

# plot times
plotTimes(times)

# A night period can be added with 'night'
plotTimes(times, night = c("20:00", "06:00"))

Description

This function allows the user to prepare a set of R objects to be run through an explore, migration or residency analysis.

Usage

preload(
  biometrics,
  spatial,
  deployments,
  detections,
  dot = NULL,
  distances = NULL,
  tz,
  start.time = NULL,
  stop.time = NULL,
  section.order = NULL,
  exclude.tags = NULL,
  disregard.parallels = FALSE,
  discard.orphans = FALSE
)

Arguments

Value

A dataset that can be used as an input for actel's main analyses. This dataset contains:

• bio: The biometric data

• sections: The sections of the study area, if set using the argument sections (required to run residency and migration analyses)

• deployments: The deployment data

• spatial: The spatial data, split in stations and release sites.

• dot: A table of array connections.

• arrays: A list with the details of each array

• dotmat: A matrix of distances between arrays (in number of arrays).

• dist.mat: The distances matrix.

• detections.list: A processed list of detections for each tag.

• paths: A list of the possible paths between each pair of arrays.

• disregard.parallels: Logical: Should parallel arrays invalidate efficiency peers? (required to run residency and migration analyses)

• tz: The time zone of the study area

Examples

# This function requires a series of pre-created R objects.
# We can create them by loading the example files from actel:
aux <- system.file(package = "actel")[1]

bio <- read.csv(paste0(aux, "/example_biometrics.csv"))
deployments <- read.csv(paste0(aux, "/example_deployments.csv"))
spatial <- read.csv(paste0(aux, "/example_spatial.csv"))
detections <- read.csv(paste0(aux, "/example_detections.csv"))

dot <- "A0--A1--A2--A3--A4--A5--A6--A7--A8--A9"

# Now that we have the R objects created, we can run preload:

x <- preload(biometrics = bio, deployments = deployments, spatial = spatial,
 detections = detections, dot = dot, tz = "Europe/Copenhagen")

Description

Read dot file or string

Usage

readDot(input = NULL, string = NULL, silent = FALSE)

Arguments

Value

A data frame with the connections present in the input.

Examples

# create dummy dot string
x1 <- c("A--B--C--D--E--F")

# run readDot
readDot(string = x1)

# more complex strings are acceptable:
x2 <- c(
"A--B--C--D--E--F
A--G--H--I--E
H--C")

readDot(string = x2)

# Alternatively, connections can be read from a file

# let's create a dummy file in R's temporary directory:
write("A--B--C--D--E--F\nA--G--H--I--E\nH--C\n",
 file = paste0(tempdir(), "/dummy_dot.txt"))

# now we can read it using readDot
readDot(input = paste0(tempdir(), "/dummy_dot.txt"))

Description

Recover latest actel crash log

Usage

recoverLog(file, overwrite = FALSE)

Arguments

Value

No return value, called for side effects.

Examples

recoverLog(file = paste0(tempdir(), "/new_log.txt"))

Description

The residency analysis runs the same initial checks as explore, but, similarly to migration, explores particular points of the animal behaviour. If you want to know where your animals were in each day of the study, how many animals were in each section each day, and other residency-focused variables, this is the analysis you are looking for!

Usage

residency(
  tz = NULL,
  section.order = NULL,
  datapack = NULL,
  max.interval = 60,
  minimum.detections,
  min.total.detections = 2,
  min.per.event = 1,
  start.time = NULL,
  stop.time = NULL,
  speed.method = c("last to first", "last to last", "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,
  save.detections = FALSE,
  section.warning = 1,
  section.error = 1,
  section.minimum,
  timestep = c("days", "hours"),
  replicates = NULL,
  GUI = c("needed", "always", "never"),
  save.tables.locally = FALSE,
  print.releases = TRUE,
  detections.y.axis = c("auto", "stations", "arrays")
)

Arguments

Value

A list containing:

• detections: A list containing all detections for each target tag;

• valid.detections: A list containing the valid detections for each target tag;

• spatial: A list containing the spatial information used during the analysis;

• deployments: A data frame containing the deployments of each receiver;

• arrays: A list containing the array details used during the analysis;

• movements: A list containing all movement events for each target tag;

• valid.movements: A list containing the valid movement events for each target tag;

• section.movements: A list containing the valid section shifts for each target tag;

• status.df: A data frame containing summary information for each tag, including the following columns:

  • Times.entered.[section]: Total number of times the tag entered a given section

  • Average.entry.[section]: Average entry time at a given section

  • Average.time.[section]: Average time the tag spent in a given section during each visit

  • Average.departure.[section]: Average departure time from a given section

  • Total.time.[section]: Total time spent in a given section

  • Very.last.array: Last array where the tag was detected

  • Very.last.time: Time of the last valid detection

  • Status: Fate assigned to the animal

  • Valid.detections: Number of valid detections

  • Invalid.detections: Number of invalid detections

  • Valid.events: Number of valid events

  • Invalid.events: Number of invalid events

  • P.type: Type of processing:

    • 'Skipped' if no data was found for the tag,

    • 'Auto' if no user interaction was required,

    • 'Manual' if user interaction was suggested and the user made changes to the validity of the events,

    • 'Overridden' if the user listed the tag in the override argument.

  • Comments: Comments left by the user during the analysis

• last.seen: A data frame containing the number of tags last seen in each study area section;

• array.times: A data frame containing ALL the entry times of each tag in each array;

• section.times: A data frame containing all the entry times of each tag in each section;

• residency.list: A list containing the places of residency between first and last valid detection for each tag;

• time.ratios: A list containing the daily location per section (both in seconds spent and in percentage of day) for each tag;

• time.positions: A data frame showing the location where each tag spent the most time per day;

• global.ratios: A list containing summary tables showing the number of active tag (and respective percentages) present at each location per day;

• efficiency: A list containing the results of the inter-array Multi-way efficiency calculations (see vignettes for more details);

• intra.array.CJS: A list containing the results of the intra-array CJS calculations;

• rsp.info: A list containing appendix information for the RSP package;

• dist.mat: The distance matrix used in the analysis (if a valid distance matrix was supplied)

See Also

explore, migration

Examples

# Start by moving to a temporary directory
old.wd <- getwd()
setwd(tempdir())

# Deploy the example workspace
exampleWorkspace("residency_example")

# Move your R session into the example workspace
setwd("residency_example")

# run the residency analysis. Ensure the tz argument
# matches the time zone of the study area and that the
# sections match your array names. The line below works
# for the example data.
results <- residency(tz = "Europe/Copenhagen")

# to obtain an HTML report, run the analysis with report = TRUE

# return to original working directory
setwd(old.wd)
rm(old.wd)

Description

shapeToRaster can also perform early quality checks on the shape file, to ensure it is compatible with the remaining study data. To activate these, set the names of the columns in the spatial.csv file that contain the x and y coordinates of the stations using coord.x and coord.y. By default, shapeToRaster looks for a spatial.csv file in the current working directory, but this can be personalized using the spatial argument.

Usage

shapeToRaster(
  shape,
  size,
  spatial = "spatial.csv",
  coord.x = NULL,
  coord.y = NULL,
  buffer = NULL,
  type = c("land", "water")
)

Arguments

Details

It is highly recommended to read the manual page regarding distances matrices before running this function. You can find it here: https://hugomflavio.github.io/actel-website/manual-distances.html

Value

A raster object.

Examples

# check if R can run the distance functions
aux <- c(
  length(suppressWarnings(packageDescription("raster"))),
  length(suppressWarnings(packageDescription("gdistance"))),
  length(suppressWarnings(packageDescription("sp"))),
  length(suppressWarnings(packageDescription("terra"))))

missing.packages <- sapply(aux, function(x) x == 1)

if (any(missing.packages)) {
  message("Sorry, this function requires packages '",
    paste(c("raster", "gdistance", "sp", "terra")[missing.packages], collapse = "', '"),
    "' to operate. Please install ", ifelse(sum(missing.packages) > 1, "them", "it"),
    " before proceeding.")
} else {
  # Fetch actel's example shapefile
  example.shape <- paste0(system.file(package = "actel")[1], "/example_shapefile.shp")

  # import the shape file
  x <- shapeToRaster(shape = example.shape, size = 20)

  # have a look at the resulting raster,
  # where the blank spaces are the land areas
  terra::plot(x)
}
rm(aux, missing.packages)

Description

Computes an analytical CJS model for a presence/absence matrix.

Usage

simpleCJS(input, estimate = NULL, fixed.efficiency = NULL, silent = TRUE)

Arguments

Value

A list containing:

• absolutes A data frame with the absolute number of tags detected and missed,

• efficiency A vector of calculated array detection efficiencies,

• survival A matrix of calculated survivals,

• lambda A combined detection efficiency * survival estimate for the last array.

References

Perry et al (2012), 'Using mark-recapture models to estimate survival from telemetry data'. url: https://www.researchgate.net/publication/256443823_Using_mark-recapture_models_to_estimate_survival_from_telemetry_data

Examples

# prepare a dummy presence/absence matrix
x <- matrix(c(TRUE, TRUE, TRUE, TRUE, FALSE, TRUE, TRUE, TRUE, FALSE), ncol = 3)
colnames(x) <- c("Release", "Array1", "Array2")

# run CJS
simpleCJS(x)

Description

Find original station name

Usage

stationName(input, station)

Arguments

Value

The original station name

Examples

stationName(example.results, 1)

# or

stationName(example.results, "St.2")

Description

Convert a data frame with timestamps into a list of circular objects

Usage

timesToCircular(x, by.group = FALSE)

Arguments

Value

A list of circular objects for each data column and, optionally, for each group.

Examples

# create dummy input data frame.
# Note: the names of the columns are irrelevant.
x <- data.frame(ID = c(1:5),
 Group = c("A", "A", "B", "B", "B"),
 A1 = as.POSIXct(
   c("2019-01-03 11:21:12",
     "2019-01-04 12:22:21",
     "2019-01-05 13:31:34",
     "2019-01-06 14:32:43",
     "2019-01-07 15:23:52")),
 A2 = as.POSIXct(
   c("2019-01-08 16:51:55",
     "2019-01-09 17:42:42",
     "2019-01-10 18:33:33",
     "2019-01-11 19:24:32",
     "2019-01-12 20:15:22")),
 stringsAsFactors = TRUE)

# run timesToCircular
timesToCircular(x)

# optionally, split results by group:
timesToCircular(x, by.group = TRUE)

Description

Using a previously imported shape file that has been converted to a raster (see shapeToRaster), Prepares a TransitionLayer object to be used in distance estimations (see distancesMatrix). Adapted from Grant Adams' script "distance to closest mpa".

Usage

transitionLayer(x, directions = c(16, 8, 4))

Arguments

Details

It is highly recommended to read the manual page regarding distances matrices before running this function. You can find it here: https://hugomflavio.github.io/actel-website/manual-distances.html

Value

A TransitionLayer object.

Examples

# check if R can run the distance functions
aux <- c(
  length(suppressWarnings(packageDescription("raster"))),
  length(suppressWarnings(packageDescription("gdistance"))),
  length(suppressWarnings(packageDescription("sp"))),
  length(suppressWarnings(packageDescription("terra"))))

missing.packages <- sapply(aux, function(x) x == 1)

if (any(missing.packages)) {
  message("Sorry, this function requires packages '",
    paste(c("raster", "gdistance", "sp", "terra")[missing.packages], collapse = "', '"),
    "' to operate. Please install ", ifelse(sum(missing.packages) > 1, "them", "it"),
    " before proceeding.")
} else {
  # Fetch actel's example shapefile
  example.shape <- paste0(system.file(package = "actel")[1], "/example_shapefile.shp")

  # import the shape file
  x <- shapeToRaster(shape = example.shape, size = 20)

  # Build the transition layer
  t.layer <- transitionLayer(x)

  # inspect the output
  t.layer
}
rm(aux, missing.packages)