residency: Residency Analysis

In actel: Acoustic Telemetry Data Analysis

Residency Analysis

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"),
  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

tz	The time zone of the study area. Must match one of the values present in timezones.
section.order	A vector containing the order by which sections should be aligned in the results.
datapack	A data bundle pre-compiled through the function preload. May be used to run actel analyses based on R objects, rather than input files.
max.interval	The number of minutes that must pass between detections for a new event to be created. Defaults to 60.
minimum.detections	DEPRECATED. Please use the arguments min.total.detections and min.per.event instead.
min.total.detections	Minimum number of times a tag must have been detected during the study period for the detections to be considered true and not just random noise. Defaults to 2.
min.per.event	Minimum number of detections an event must have to be deemed valid. For analyses with both array and section events, a vector of two values can be provided. If only one value is provided, the same threshold applies for both types of events. Defaults to 1.
start.time	Detection data prior to the timestamp set in start.time (in YYYY-MM-DD HH:MM:SS format) is not considered during the analysis.
stop.time	Detection data posterior to the timestamp set in stop.time (in YYYY-MM-DD HH:MM:SS format) is not considered during the analysis.
speed.method	Can take two forms: 'last to first' or 'last to last'. If 'last to first' (default), the last detection on the previous array is matched to the first detection on the target array to perform the calculations. If 'last to last', the last detection on ´the previous array is matched to the last detection on the target array to perform the calculations.
speed.warning	If a tag moves at a speed equal or greater than speed.warning (in metres per second), a warning is issued. If left NULL (default), no warnings are issued. Must be equal to or lower than speed.error
speed.error	If a tag moves at a speed equal or greater than speed.error (in metres per second), user intervention is suggested. If left NULL (default), user intervention is never suggested.
jump.warning	If a tag crosses a number of arrays equal or greater than jump.warning without being detected, a warning is issued. Defaults to 2. To disable jump warnings, set to Inf. Must be equal to or lower than jump.error.
jump.error	If a tag crosses a number of arrays equal or greater than jump.error without being detected, user intervention is suggested. Defaults to 3. To disable user intervention suggestions, set to Inf.
inactive.warning	If a tag spends a number of days equal or greater than inactive.warning in a given array at the tail of the respective detections, a warning is issued. If left NULL (default), no warnings are issued. Must be equal to or lower than innactive.error.
inactive.error	If a tag spends a number of days equal or greater than inactive.error in a given array at the tail of the respective detections, user intervention is suggested. If left NULL (default), user intervention is never suggested.
exclude.tags	A vector of tags that should be excluded from the detection data before any analyses are performed. Intended to be used if stray tags from a different code space but with the same signal as a target tag are detected in the study area.
override	A vector of signals for which the user intends to manually define which movement events are valid and invalid.
report	Logical. Should an HTML report be created at the end of the analysis? NOTE: Setting report to TRUE will generate an HTML file in the current directory. Additionally, if auto.open = TRUE (default), the web browser will automatically be launched to open the report once the function terminates.
auto.open	Logical: Should the report be automatically opened once the analysis is over? Defaults to TRUE. NOTE: If report = TRUE and auto.open = TRUE, the web browser will automatically be launched to open the report once the function terminates.
discard.orphans	Logical: Should actel automatically discard detections that do not fall within receiver deployment periods, or that were recorded before the respective animals were released?
discard.first	A threshold amount of time (in hours) that must pass after release for the respective detections to be valid. Set to 0 to discard only the release-to-first-detection calculations.
save.detections	Logical: Should the processed detections be saved for future runs?
section.warning	If a tag has section movement events with less or equal to section.warning detections, a warning is issued. Defaults to 1. To disable section warnings, set to 0. Must be equal to or greater than section.error.
section.error	If a tag has section movement events with less or equal to section.error detections, user intervention is suggested. Defaults to 1. To disable user intervention suggestions, set to 0.
section.minimum	DEPRECATED: Please use section.warning and section.error instead.
timestep	The resolution desired for the residency calculations. One of "days" (default) or "hours".
replicates	A list containing, for each array to which intra-array efficiency is to be calculated: The standard names of the stations to be used as a replicate. See the vignettes for more details.
GUI	One of "needed", "always" or "never". If "needed", a new window is opened to inspect the movements only when the movements table is too big to be displayed in R's console. If "always", a graphical interface is always created when the possibility to invalidate events emerges. If "never", a graphical interface is never invoked. In this case, if the table to be displayed does not fit in R's console, a temporary file will be saved and the user will be prompted to open that file and examine it. Defaults to "needed".
save.tables.locally	Logical: If a table must be temporarily stored into a file for user inspection, should it be saved in the current working directory, or in R's temporary folder?
print.releases	Logical: Should the release sites be printed in the study area diagrams?
detections.y.axis	The type of y axis desired for the individual detection plots. While the argument defaults to "auto", it can be hard-set to one of "stations" or "arrays".

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)

actel documentation built on Oct. 19, 2023, 9:08 a.m.