Title:	Acoustic Telemetry Data Analysis
Version:	1.3.0
Description:	Designed for studies where animals tagged with acoustic tags are expected to move through receiver arrays. This package combines the advantages of automatic sorting and checking of animal movements with the possibility for user intervention on tags that deviate from expected behaviour. The three analysis functions (explore(), migration() and residency()) allow the users to analyse their data in a systematic way, making it easy to compare results from different studies. CJS calculations are based on Perry et al. (2012) https://www.researchgate.net/publication/256443823_Using_mark-recapture_models_to_estimate_survival_from_telemetry_data.
License:	GPL-3
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.2.3
Language:	en-GB
Depends:	R (≥ 3.6)
Imports:	circular, data.table, DiagrammeR, DiagrammeRsvg, fasttime, ggplot2, graphics, grDevices, knitr, readr, reshape2, rmarkdown, rsvg, scales, stats, stringi, stringr, svglite, utils
Suggests:	gdistance, gWidgets2, gWidgets2tcltk, raster, sp, sf, terra, testthat
VignetteBuilder:	knitr
URL:	https://github.com/hugomflavio/actel, https://hugomflavio.github.io/actel-website/
BugReports:	https://github.com/hugomflavio/actel/issues
NeedsCompilation:	no
Packaged:	2023-10-19 03:10:14 UTC; hflavio
Author:	Hugo Flávio [aut, cre]
Maintainer:	Hugo Flávio <hflavio@wlu.ca>
Repository:	CRAN
Date/Publication:	2023-10-19 03:30:02 UTC

actel: Acoustic Telemetry Data Analysis

Description

actel is designed for studies where animals tagged with acoustic tags are expected to move through receiver arrays. actel combines the advantages of automatic sorting and checking of animal movements with the possibility for user intervention on tags that deviate from expected behaviour. The three analysis functions: explore, migration and residency, allow the users to analyse their data in a systematic way, making it easy to compare results from different studies.

Input structure

To be able to work with actel, you must prepare your data in a specific format. To learn more about this, you need to have a look at the package vignettes, which can be found by running browseVignettes('actel'). If this function returns "No vignettes found", you can alternatively find the vignettes online: https://CRAN.R-project.org/package=actel

Example dataset

If this is the first time you are using actel, you can try running it on an example dataset using the exampleWorkspace function. This function deploys a set of example files following the structure described in the package vignettes. Namely:

• biometrics.csv

• deployments.csv

• spatial.csv

• detections/ (a folder with .csv files)

Once the example dataset is created, exampleWorkspace also provides you with example code to run an explore analysis.

Note that you can also run the migration and residency analyses on the example dataset, e.g.:

results <- migration(tz = 'Europe/Copenhagen', report = TRUE)

or

results <- residency(tz = 'Europe/Copenhagen', report = TRUE)

Note: Running these lines with report = TRUE will open an analysis report on your web browser.

Main functions

The actel package provides three main analyses: explore, migration and residency

explore

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.

migration

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 animals/tags has been acting odd. Multiple options allow you to tweak the analysis to fit your study perfectly.

residency

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!

Author(s)

Maintainer: Hugo Flávio hflavio@wlu.ca (ORCID)

See Also

explore, migration, residency, exampleWorkspace, blankWorkspace

Deprecated functions in package actel.

Description

The functions listed below are deprecated and will be defunct in the near future. When possible, alternative functions with similar functionality are also mentioned. Help pages for deprecated functions are available at help("-deprecated").

Example residency results

Description

A list with residency results to append to example.results, so some examples can run.

Usage

additional.residency.results

Format

A list of outputs from residency()

Source

Data collected by the authors.

Calculate beta estimations for efficiency

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)

Append to ...

Description

Appends a note/comment to the specified recipient, which in turn corresponds to a temporary helper file.

Usage

appendTo(recipient, line, tag)

Arguments

Value

No return value, called for side effects.

Combine the individual CJS's of each array into a single table

Description

Combine the individual CJS's of each array into a single table

Usage

assembleArrayCJS(mat, CJS, arrays, releases, silent = TRUE)

Arguments

Value

A list containing the CJS absolute numbers and efficiency estimates

Assembles CJS tables for all groups

Description

Assembles CJS tables for all groups

Usage

assembleGroupCJS(mat, CJS, arrays, releases, intra.CJS = NULL)

Arguments

Value

A data frame containing the CJS results for each group

Assemble detection matrices

Description

Assemble detection matrices

Usage

assembleMatrices(spatial, movements, status.df, arrays, paths, dotmat)

Arguments

Value

A list containing the detection matrices split by groups and release sites

Create status.df

Description

Combines the timetable and the original biometrics.

Usage

assembleOutput(timetable, bio, spatial, dist.mat, tz)

Arguments

Value

A data frame containing all the final data for each tag.

Collect summary information for the residency analysis

Description

Collect summary information for the residency analysis

Usage

assembleResidency(secmoves, movements, spatial)

Arguments

Value

A data frame with the compiled residency values

Create section.overview

Description

Produces a table with the survival per group of animals present in the biometrics.

Usage

assembleSectionOverview(status.df, spatial)

Arguments

Value

A data frame containing the survival per group of animals present in the biometrics.

Assembles CJS tables for all group x release site combinations

Description

Assembles CJS tables for all group x release site combinations

Usage

assembleSplitCJS(mat, CJS, arrays, releases, intra.CJS = NULL)

Arguments

Value

A list containing the CJS results for each group x release site combination.

Create the timetable

Description

Crawls trough the movement events of each tag to find when it entered and left each section of the study area.

Usage

assembleTimetable(
  secmoves,
  valid.moves,
  all.moves,
  spatial,
  arrays,
  bio,
  tz,
  dist.mat,
  speed.method,
  if.last.skip.section,
  success.arrays
)

Arguments

Value

A data frame containing the entering and leaving timestamps for each section per target tag

Wrapper for simplifyMovements

Description

Wrapper for simplifyMovements

Usage

assembleValidMoves(movements, bio, discard.first, speed.method, dist.mat)

Arguments

Value

A list of valid movements

Wrapper for sectionMovements

Description

Wrapper for sectionMovements

Usage

assembleValidSecMoves(valid.moves, spatial, valid.dist)

Arguments

Value

A list of valid movements

Find which arrays to blame for a jump in movement events

Description

Find which arrays to blame for a jump in movement events

Usage

blameArrays(from, to, paths)

Arguments

Value

A list containing information on the arrays that failed

Create a Blank Workspace

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

Break the detection matrices per array

Description

Break the detection matrices per array

Usage

breakMatricesByArray(m, arrays, type = c("peers", "all"), verbose = TRUE)

Arguments

Value

A list containing the split matrices for each array

Check argument quality

Description

Check argument quality

Usage

checkArguments(
  dp,
  tz,
  min.total.detections,
  min.per.event,
  max.interval,
  speed.method = c("last to first", "last to last"),
  speed.warning,
  speed.error,
  start.time,
  stop.time,
  report,
  auto.open,
  save.detections,
  jump.warning,
  jump.error,
  inactive.warning,
  inactive.error,
  exclude.tags,
  override,
  print.releases,
  detections.y.axis = c("auto", "stations", "arrays"),
  if.last.skip.section = NULL,
  replicates = NULL,
  section.warning,
  section.error,
  section.order = NULL,
  timestep = c("days", "hours")
)

Arguments

Value

updated parameters

Confirm that the station names in the deployments table match those listed in the spatial file

Description

Confirm that the station names in the deployments table match those listed in the spatial file

Usage

checkDeploymentStations(input, spatial)

Arguments

Value

A data frame with the deployment locations

Confirm that receivers were not re-deployed before being retrieved

Description

Confirm that receivers were not re-deployed before being retrieved

Usage

checkDeploymentTimes(input)

Arguments

Value

No return value, called for side effects.

Check if there are detections for the target tags before release.

Description

Check if there are detections for the target tags before release.

Usage

checkDetectionsBeforeRelease(input, bio, discard.orphans = FALSE)

Arguments

Value

A list containing the detections without invalid data.

Check if there are duplicated detection in the input data

Description

Check if there are duplicated detection in the input data

Usage

checkDupDetections(input)

Arguments

Value

The detections data frame, without duplicated detections.

Check if there are duplicated signals in the detected tags.

Description

Check if there are duplicated signals in the detected tags.

Usage

checkDupSignals(input, bio)

Arguments

Value

No return value, called for side effects.

Check for movements upstream of the release site.

Description

Check for movements upstream of the release site.

Usage

checkFirstDetBackFromRelease(
  movements,
  tag,
  bio,
  detections,
  arrays,
  spatial,
  GUI,
  save.tables.locally,
  n
)

Arguments

Value

A data frame with the movements for the target tag with updated 'Valid' column.

Check if the dependencies required to open a GUI are installed, and if opening a GUI does not throw an error. Some code adapted from RGtk2's .onLoad function.

Description

Check if the dependencies required to open a GUI are installed, and if opening a GUI does not throw an error. Some code adapted from RGtk2's .onLoad function.

Usage

checkGUI(GUI = c("needed", "always", "never"), save.tables.locally)

Arguments

Value

An updated GUI argument (character string)

Find out if a tag moved in an impossible direction

Description

Find out if a tag moved in an impossible direction

Usage

checkImpassables(
  movements,
  tag,
  bio,
  spatial,
  detections,
  dotmat,
  GUI,
  save.tables.locally,
  n
)

Arguments

Value

A list of movements with updated 'Valid' columns

Find if a tag is standing still in an array

Description

Find if a tag is standing still in an array

Usage

checkInactiveness(
  movements,
  tag,
  detections,
  n,
  inactive.warning,
  inactive.error,
  dist.mat,
  GUI,
  save.tables.locally
)

Arguments

Value

A list of movements with updated 'Valid' columns

warn users if they are about to run into an unfixed bug.

Description

warn users if they are about to run into an unfixed bug.

Usage

checkIssue79(arrays, spatial)

Value

No return value, called for side effects.

Check if tags are jumping over arrays

Description

Check if tags are jumping over arrays

Usage

checkJumpDistance(
  movements,
  tag,
  bio,
  detections,
  spatial,
  arrays,
  dotmat,
  paths,
  jump.warning,
  jump.error,
  GUI,
  save.tables.locally,
  n
)

Arguments

Value

A list of movements with updated 'Valid' columns

Check that the tag linearly moved along the sections

Description

Check that the tag linearly moved along the sections

Usage

checkLinearity(secmoves, tag, spatial, arrays, GUI, save.tables.locally, n)

Arguments

Value

A list of section movements with updated 'Valid' columns

Check the number of detections (total and per event) of a given tag. Works for both array and section movements.

Description

Check the number of detections (total and per event) of a given tag. Works for both array and section movements.

Usage

checkMinimumN(movements, min.total.detections, min.per.event, tag, n)

Arguments

Value

A data frame containing the movements with valid/invalid notes

Check if there are detections matching the target tags.

Description

Check if there are detections matching the target tags.

Usage

checkNoDetections(input, bio)

Arguments

Value

No return value, called for side effects.

Check report compatibility

Description

Checks if pandoc is up and running and creates a "Report" folder, if necessary

Usage

checkReport(report)

Arguments

Value

An updated report argument (logical)

Verify number of detections in section movements

Description

Verify number of detections in section movements

Usage

checkSMovesN(
  secmoves,
  tag,
  section.warning,
  section.error,
  GUI,
  save.tables.locally,
  n
)

Arguments

Value

A list of section movements with updated 'Valid' columns

check tag speeds against defined thresholds (in m/s)

Description

check tag speeds against defined thresholds (in m/s)

Usage

checkSpeeds(
  movements,
  tag,
  detections,
  valid.movements,
  speed.warning,
  speed.error,
  GUI,
  save.tables.locally,
  n
)

Arguments

Value

A list of movements with updated 'Valid' columns

Check for target data in the unknown receivers

Description

Check for target data in the unknown receivers

Usage

checkTagsInUnknownReceivers(detections.list, deployments, spatial)

Arguments

Value

A list containing an updated spatial list and a TRUE/FALSE object indicating whether or not Standard station names must be reprocessed.

A list containing:

• spatial: A list containing the spatial elements of the study, with data for the unknown receivers, if relevant.

• deployments: A list containing the receiver deployments, with data for the unknown receivers, if relevant.

• detections.list: A list containing the detections for each tag, with updated station names.

Verify that the source data has been compiled using actel's preload function

Description

Verify that the source data has been compiled using actel's preload function

Usage

checkToken(token, timestamp)

Arguments

Value

No return value. Called for side effects.

Find detections from unknown receivers

Description

Find detections from unknown receivers

Usage

checkUnknownReceivers(input)

Arguments

Value

No return value, called for side effects.

check.R arguments

Description

check.R arguments

Arguments

Draw a section on the outside of the circle

Description

Draw a section on the outside of the circle

Usage

circularSection(
  from,
  to,
  units = "hours",
  template = "clock24",
  limits = c(1, 0),
  fill = "white",
  border = "black"
)

Arguments

Value

No return value, adds to an existing plot.

CJS.R arguments

Description

CJS.R arguments

Arguments

Collect summary information on the tags detected but that are not part of the study.

Description

Collect summary information on the tags detected but that are not part of the study.

Usage

collectStrays(input)

Arguments

Value

No return value, called for side effects.

Combine a list of vectors

Description

Intended to combine vectors where, for each position, only one of the vectors contains data (i.e. the remaining are NA's).

Usage

combine(input)

Arguments

Value

A vectorized combination of the data in the different list vectors.

Combine multiple CJS models

Description

Combine multiple CJS models

Usage

combineCJS(..., estimate = NULL, fixed.efficiency = NULL, silent = FALSE)

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.

Combine ALS detections

Description

Finds the detections' files and processes them.

Usage

compileDetections(
  path = "detections",
  start.time = NULL,
  stop.time = NULL,
  tz,
  save.detections = FALSE,
  record.source = FALSE
)

Arguments

Value

A data frame with all the detections

Complete a Distances Matrix

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)

Convert code spaces

Description

Unifies CodeSpace names, to avoid having different names depending on ALS vendor.

Usage

convertCodes(input)

Arguments

Value

A data frame with standardized code spaces.

Convert Times

Description

Converts the ALS timestamps (UTC) to the designated study area time zone. Can also trim the data by time.

Usage

convertTimes(input, start.time, stop.time, tz)

Arguments

Value

A data frame with corrected timestamps.

circular:::circlePlotRad

Description

This function is an EXACT copy of the function circlePlotRad() in the circular package. As the function is not exported by the original package, I have copied it here to resolve the note thrown by devtools::check()

Usage

copyOfCirclePlotRad(
  xlim = c(-1, 1),
  ylim = c(-1, 1),
  uin = NULL,
  shrink = 1,
  tol = 0.04,
  main = NULL,
  sub = NULL,
  xlab = NULL,
  ylab = NULL,
  control.circle = circular::circle.control()
)

Arguments

Details

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

Value

No return value, adds to an existing plot.

circular:::RosediagRad

Description

This function is an EXACT copy of the function RosediagRad() in the circular package. As the function is not exported by the original package, I have copied it here to resolve the note thrown by devtools::check()

Usage

copyOfRosediagRad(
  x,
  zero,
  rotation,
  bins,
  upper,
  radii.scale,
  prop,
  border,
  col,
  ...
)

Arguments

Details

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

Value

No return value, adds to an existing plot.

Find and list arrays which failed during the movements of the tags

Description

Find and list arrays which failed during the movements of the tags

Usage

countArrayFailures(moves, paths, dotmat)

Arguments

Value

NULL if no arrays failed, or a list containing information on the arrays that failed

Count backwards movements

Description

Count backwards movements

Usage

countBackMoves(movements, arrays)

Arguments

Value

A list containing:

• sum.back.moves The number of backwards movements for the target tag

• max.back.moves The maximum number of consecutive backwards movements for the target tag

collapse event indexes into ranges

Description

collapse event indexes into ranges

Usage

createEventRanges(x)

Arguments

Value

a string of isolated events and event ranges

Upon invalidating detections, recombines the remaining valid detections into new events, and merges them with the remaining events.

Description

Upon invalidating detections, recombines the remaining valid detections into new events, and merges them with the remaining events.

Usage

createNewEvents(displayed.moves, all.moves, detections, event)

Arguments

Value

A data frame containing the movements for the target tag

Standardize serial numbers, stations and arrays in the detections

Description

Matches the ALS serial number to the deployments to rename the serial number. The corresponding deployment is then used to update the Standard Station name and the array based in the spatial object.

Usage

createStandards(detections, spatial, deployments, discard.orphans = FALSE)

Arguments

Value

A data frame with standardized station names.

Include the deployment in the serial number of the receive

Description

Include the deployment in the serial number of the receive

Usage

createUniqueSerials(input)

Arguments

Value

A list of deployments, with unique serial numbers per deployment.

Deprecated function.

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.

darken colours

Description

Copied from https://gist.github.com/Jfortin1/72ef064469d1703c6b30

Usage

darken(color, factor = 1.4)

Arguments

Value

The darker colour code

Import RData in a list format

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

Convert hh:mm:ss time to hh.hhh

Description

Convert hh:mm:ss time to hh.hhh

Usage

decimalTime(input, unit = c("h", "m", "s"))

Arguments

Value

A number or vector of numbers corresponding to the decimal hour equivalent of the character input.

Delete temporary files

Description

At the end of the function actel or emergencyBreak, removes temporary files.

Usage

deleteHelpers()

Value

No return value, called for side effects.

Detections Widget (Single table version)

Description

Detections Widget (Single table version)

Usage

detectionsSingleWidget(event, tag, to.print, silent)

Arguments

Value

A vector of detection validities.

Detections Widget (Tabbed version)

Description

Detections Widget (Tabbed version)

Usage

detectionsTabbedWidget(event, tag, to.print, silent)

Arguments

Value

A vector of detection validities.

Discard early detections

Description

Discard early detections

Usage

discardFirst(input, bio, trim)

Arguments

Value

the updated detections list

Calculate Distances Matrix

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)

Break the dot data frame into a list

Description

Break the dot data frame into a list

Usage

dotList(input, spatial)

Arguments

Value

A list containing detailed information on the arrays

Create numerical distances between dot elements

Description

Create numerical distances between dot elements

Usage

dotMatrix(input)

Arguments

Value

A matrix of the distance (in number of arrays) between pairs of arrays

Find arrays valid for efficiency calculation

Description

Find arrays valid for efficiency calculation

Usage

dotPaths(input, disregard.parallels)

Arguments

Value

A list of the all array paths between each pair of arrays.

Calculate estimated last-array efficiency

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)

Compile detection matrix for last array

Description

Compile detection matrix for last array

Usage

dualMatrix(array, replicates, spatial, detections.list)

Arguments

Value

A matrix of detection histories per tag for the last array.

Compile inter-array detection matrix

Description

Compile inter-array detection matrix

Usage

efficiencyMatrix(movements, arrays, paths, dotmat)

Arguments

Value

A matrix of detection histories per tag.

Standard procedure when aborting

Description

Wraps up the report in R's temporary folder before the function end.

Usage

emergencyBreak(the.function.call)

Value

No return value, called for side effects.

Create a Template Distances Matrix

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

Event Widget (Single table version)

Description

Event Widget (Single table version)

Usage

eventsSingleWidget(
  tag,
  displayed.moves,
  all.moves,
  detections,
  trigger,
  first.time,
  type
)

Arguments

Value

The movements list, a vector of event validities, and a note on whether or not the widget should be restarted.

Event Widget (Tabbed version)

Description

Event Widget (Tabbed version)

Usage

eventsTabbedWidget(
  tag,
  displayed.moves,
  all.moves,
  detections,
  trigger,
  first.time,
  type
)

Arguments

Value

The movements list, a vector of event validities, and a note on whether or not the widget should be restarted.

Example biometric data

Description

A dataset containing the tag numbers and respective biometrics of 60 fish.

Format

A data frame with 60 rows and 7 variables:

Release.date

The date and time of release

Release.site

The release site

Serial.nr

The serial number of the implanted tag

Signal

The Signal emitted by the implanted tag

Group

The group of the tagged fish

Total.Length.mm

The length of the tagged fish

Mass.g

The mass of the tagged fish

Source

Data collected by the authors.

Example deployment data

Description

A dataset containing the deployed receivers.

Format

A data frame with 17 rows and 4 variables:

Receiver

The receiver serial number

Station.name

The name given to the receiver

Start

The date and time of the deployment

Stop

The date and time of the retrieval

Source

Data collected by the authors.

Example detection data

Description

A dataset containing the detections of the deployed ALS, for the 60 fish.

Format

A data frame with 14549 rows and 4 variables:

Timestamp

The date and time of the detections

Receiver

The ALS serial number

CodeSpace

The code space of the detected tag

Signal

The signal of the detected tag

Sensor.Value

The data recorded by the sensor (dummy values)

Sensor.Unit

The unit of the sensor data

Source

Data collected by the authors.

Example distances matrix

Description

A matrix containing the distances between stations and release sites

Format

A 18 * 18 matrix

Source

Data collected by the authors.

Example migration results

Description

A list with the results of a migration analysis ran on the example data. Note: Many objects were trimmed to reduce package size. Use exampleWorkspace() To run an analysis on the example data and obtain a full results object.

Usage

example.results

Format

A list of outputs from migration()

Source

Data collected by the authors.

Example spatial data

Description

A dataset containing the positions of the deployed hydrophone stations and release sites.

Format

A data frame with 18 rows and 6 variables:

Station.name

The name of the hydrophone station or release site

Latitude

The latitude of the hydrophone station or release site in WGS84

Longitude

The longitude of the hydrophone station or release site in WGS84

x

The x coordinate of the hydrophone station or release site in EPSG 32632

y

The y coordinate of the hydrophone station or release site in EPSG 32632

Array

If documenting a hydrophone station, the array to which the station belongs. If documenting a release site, the first array(s) where the fish is expected to be detected.

Section

The Section to which the hydrophone station belongs (irrelevant for the release sites).

Type

The type of spatial object (must be either 'Hydrophone' or 'Release')

Source

Data collected by the authors.

Deploy Example Data

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

Collect summary information on the tags detected but that are not part of the study.

Description

Collect summary information on the tags detected but that are not part of the study.

Usage

excludeTags(input, exclude.tags)

Arguments

Value

A list of detections for each tag that does not contain the excluded tags.

Handler for event expansion

Description

Handler for event expansion

Usage

expandEvent(
  displayed.moves,
  all.moves,
  detections,
  tag,
  GUI,
  save.tables.locally
)

Arguments

Value

An updated movements table

Explorative Analysis

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

Extract Code Spaces from transmitter names

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)

Extract signals from transmitter names

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)

nearsq helper

Description

Finds the largest x for which n %% x == 0

Usage

fact(n)

Arguments

Details

Obtained here: https://stackoverflow.com/questions/32017327/calculate-the-optimal-grid-layout-dimensions-for-a-given-amount-of-plots-in-r

Value

An integer

Find all arrays linked to an array in a given direction

Description

Find all arrays linked to an array in a given direction

Usage

findDirectChains(array, array.list, direction = c("before", "after"))

Arguments

Value

The array list with all linked arrays.

Find efficiency peers for each array

Description

Find efficiency peers for each array

Usage

findPeers(
  array,
  array.list,
  peer.direction = c("before", "after"),
  disregard.parallels
)

Arguments

Value

The array list with efficiency peers.

Calculate number of seconds at each location per day

Description

Calculate number of seconds at each location per day

Usage

findSecondsPerSection(res, frame, the.range, num.step)

Arguments

Value

A data frame containing the number of seconds spent at each location for a specific timeframe

Find the shortest paths between arrays

Description

Find the shortest paths between arrays

Usage

findShortestChains(input)

Arguments

Value

The array list with all paths between arrays with distance > 1.

Determine if the first array after release has failed

Description

Determine if the first array after release has failed

Usage

firstArrayFailure(tag, bio, spatial, first.array, paths, dotmat)

Arguments

Value

NULL if no arrays failed, or a list of arrays that failed.

Prepare intra-array matrices for selected arrays

Description

Prepare intra-array matrices for selected arrays

Usage

getDualMatrices(replicates, CJS = NULL, spatial, detections.list)

Arguments

Value

A list of dual matrices for each relevant array.

Assemble residency tables per tag

Description

Assemble residency tables per tag

Usage

getResidency(movements, spatial)

Arguments

Value

a list containing residency tables for each tag.

Extract speeds from the analysis results.

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

Extract timestamps from the analysis results.

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

Generate default ggplot colours

Description

Copied from: https://stackoverflow.com/questions/8197559/emulate-ggplot2-default-color-palette.

Usage

gg_colour_hue(n)

Arguments

Value

a vector of colours with the same length as n

Calculate number/percentage of tags at each location for each day

Description

Calculate number/percentage of tags at each location for each day

Usage

globalRatios(positions, section.order)

Arguments

Value

A list containing:

• absolutes: A data frame containing the absolute number of tags at each location per day,

• percentages: A data frame containing the percentage of tag relative to the total number of active tags at each location per day.

Opens a new window that allows the user to determine movement event invalidity

Description

Opens a new window that allows the user to determine movement event invalidity

Usage

graphicalInvalidate(detections, moves, tag, trigger)

Arguments

Value

A data frame with the movement events for the target tag and an updated 'Valid' column.

Opens a new window that allows the user to determine detection invalidity

Description

Opens a new window that allows the user to determine detection invalidity

Usage

graphicalInvalidateDetections(
  detections,
  displayed.moves,
  all.moves,
  event,
  tag,
  silent = FALSE
)

Arguments

Value

A data frame with the movement events for the target tag and an updated 'Valid' column.

Group movements

Description

Crawls trough the detections of each tag and groups them based on ALS arrays and time requirements.

Usage

groupMovements(
  detections.list,
  bio,
  spatial,
  speed.method,
  max.interval,
  tz,
  dist.mat
)

Arguments

Value

A list containing the movement events for each tag.

Incorporate intra-array estimates in the overall CJS object

Description

Incorporate intra-array estimates in the overall CJS object

Usage

includeIntraArrayEstimates(m, efficiency = NULL, CJS = NULL)

Arguments

Value

A list containing the updated overall CJS and the intra-array CJS results

Include tags that were never detected

Description

Include tags that were never detected

Usage

includeMissing(x, status.df)

Arguments

Value

A matrix of detection histories per tag, including tags that were never detected.

Temporarily include missing receivers in the spatial object

Description

Temporarily include missing receivers in the spatial object

Usage

includeUnknownReceiver(spatial, deployments, unknown.receivers)

Arguments

Value

A list containing:

• spatial: A list containing the spatial elements of the study, with data for the unknown receivers, if relevant.

• deployments: A list containing the receiver deployments, with data for the unknown receivers, if relevant.

Allow the user to determine a given set of detections invalid

Description

Allow the user to determine a given set of detections invalid

Usage

invalidateDetections(displayed.moves, all.moves, detections, tag, event)

Arguments

Value

A data frame with the movement events for the target tag and an updated 'Valid' column.

Allow the user to determine a given movement event invalid

Description

Allow the user to determine a given movement event invalid

Usage

invalidateEvents(
  displayed.moves,
  all.moves,
  detections,
  tag,
  GUI,
  save.tables.locally
)

Arguments

Value

A data frame with the movement events for the target tag and an updated 'Valid' column.

Assign live times to arrays

Description

Assign live times to arrays

Usage

liveArrayTimes(arrays, deployments, spatial)

Arguments

Value

an expanded array list

Load Biometrics file

Description

Load Biometrics file

Usage

loadBio(input, tz)

Arguments

Value

A data frame with the biometrics information

Load deployments file and Check the structure

Description

Load deployments file and Check the structure

Usage

loadDeployments(input, tz)

Arguments

Value

A data frame with the deployments information

Load ALS detections

Description

If there are previously compiled detections present, offers the chance to reuse. Otherwise triggers combineDetections.

Usage

loadDetections(
  start.time = NULL,
  stop.time = NULL,
  tz,
  force = FALSE,
  save.detections = FALSE,
  record.source = FALSE
)

Arguments

Value

A data frame with all the detections

Load distances matrix

Description

Load distances matrix

Usage

loadDistances(input = "distances.csv", spatial)

Arguments

Value

A matrix of the distances (in metres) between stations (if a 'distances.csv' is present)

Load spatial.dot

Description

Load spatial.dot

Usage

loadDot(
  string = NULL,
  input = NULL,
  spatial,
  disregard.parallels,
  preloading = FALSE
)

Arguments

Value

A list containing:

• dot: A data frame containing the connections between arrays

• arrays: A list containing detailed information on the arrays

• dotmat: A matrix of the distance (in number of arrays) between pairs of arrays

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

DEPRECATED

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

Load Spatial File

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'))

Load, structure and check the inputs

Description

Load, structure and check the inputs

Usage

loadStudyData(
  tz,
  override = NULL,
  start.time,
  stop.time,
  save.detections = FALSE,
  section.order = NULL,
  exclude.tags,
  disregard.parallels = TRUE,
  discard.orphans = FALSE
)

Arguments

Value

A list containing:

• bio: A data frame corresponding to 'biometrics.csv'

• sections: A vector of the study area sections (or NULL in the case of the explore function)

• deployments: A list corresponding to 'deployments.csv'

• spatial: A list corresponding to 'spatial.csv'

• dot: A data frame containing the connections between arrays

• arrays: A list containing detailed information on the arrays

• dotmat: A matrix of the distance (in number of arrays) between pairs of arrays

• dist.mat: A matrix of the distances (in metres) between stations (if a 'distances.csv' is present)

• detections.list: A list containing the detection data for each tag

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

cleanly extract lowest signal from signals string

Description

cleanly extract lowest signal from signals string

Usage

lowestSignal(x)

Arguments

Value

a vector of lowest signals

Match POSIX values

Description

Match POSIX values

Usage

match.POSIXt(this, there)

Arguments

Value

a vector with the matches

TRUE/FALSE wrapper for match

Description

Looks for matches of a list on a target, but returns TRUE/FALSE instead of the position where the match was found.

Usage

matchl(input, match)

Arguments

Value

A logical vector.

Calculate CJS for each group for each array

Description

Calculate CJS for each group for each array

Usage

mbGroupCJS(mat, status.df, fixed.efficiency = NULL)

Arguments

Value

A list containing CJS results split by group.

Calculate CJS for each group.release combination

Description

Calculate CJS for each group.release combination

Usage

mbSplitCJS(mat, fixed.efficiency = NULL)

Arguments

Value

A list containing CJS results split by group and release site

Migration Analysis

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

Convert numeric time to HH:MM

Description

Convert numeric time to HH:MM

Usage

minuteTime(x, format = c("h", "m", "s"), seconds = TRUE)

Arguments

Value

a string or vector of strings corresponding to the character hour equivalent of the numeric input.

movements.R arguments

Description

movements.R arguments

Arguments

Calculate time and speed

Description

Triggers movementTimes and also calculates the speed between events.

Usage

movementSpeeds(movements, speed.method, dist.mat)

Arguments

Value

The movement data frame with speed calculations for the target tag.

Calculate movement times

Description

Determines the duration of an event and the time from an event to the next.

Usage

movementTimes(movements, type = c("array", "section"))

Arguments

Value

The movement data frame with time calculations for the target tag.

Edited rose diagram function

Description

Adapted from the rose.diag function of the circular package.

Usage

myRoseDiag(
  x,
  pch = 16,
  cex = 1,
  axes = TRUE,
  shrink = 1,
  bins = 24,
  upper = TRUE,
  ticks = TRUE,
  tcl = 0.025,
  tcl.text = 0.125,
  radii.scale = c("sqrt", "linear"),
  border = NULL,
  col = c("lightblue", "#c0ff3e80", "#ffc0cb80", "#F0E4424D", "#0072B24D", "#D55E004D"),
  tol = 0.04,
  uin = NULL,
  xlim = c(-1, 1),
  ylim = c(-1, 1),
  prop = 1,
  digits = 2,
  plot.info = NULL,
  units = NULL,
  template = NULL,
  zero = NULL,
  rotation = NULL,
  main = NULL,
  sub = NULL,
  xlab = "",
  ylab = "",
  add = TRUE,
  control.circle = circular::circle.control()
)

Arguments

Details

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

Value

A list with the zero, rotation and next.points values, to be parsed to an overlaying graphic.

Consider NA's as FALSE

Description

Aimed to be used in a vector of TRUE/FALSE's, where NA's are present and should be considered as false.

Usage

na.as.false(input)

Arguments

Value

A logical vector.

Find optimum plotting grid

Description

Calculates the optimal distribution of plots in a square grid.

Usage

nearsq(n, tol = 5/3 + 0.001)

Arguments

Details

Obtained here: https://stackoverflow.com/questions/32017327/calculate-the-optimal-grid-layout-dimensions-for-a-given-amount-of-plots-in-r

Value

a vector of the number of rows and number of columns needed to distribute the desired number of plots.

Trim movements table to contain only uni-directional movements

Description

Trim movements table to contain only uni-directional movements

Usage

oneWayMoves(movements, arrays)

Arguments

Value

A data frame with the uni-directional movements for the target tags.

Skips all validity checks for a tag and allows the user to freely invalidate events

Description

Skips all validity checks for a tag and allows the user to freely invalidate events

Usage

overrideValidityChecks(moves, detections, tag, GUI, save.tables.locally, n)

Arguments

Value

A data frame containing the movements for the target tag

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

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!

Plot detections for a single tag

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!

Plot array live times

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!

Plot moves for one ore more tags

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!

Plot global/group residency

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!

Plot residency for a single tag

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!

Plot sensor data for a single tag

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!

Print circular graphics for time series.

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

Load a dataset before running an analysis

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

Run quality checks on preloaded detections

Description

Run quality checks on preloaded detections

Usage

preloadDetections(input, tz, start.time = NULL, stop.time = NULL)

Arguments

Value

A data frame with all the detections

print Rmd fragment for inclusion in the report

Description

print Rmd fragment for inclusion in the report

Usage

printArrayOverview(array.overview)

Arguments

Value

An rmd string to be included in the report.

Print biometric graphics

Description

Searches for columns containing biometric data and prints graphics per animal group

Usage

printBiometrics(bio)

Arguments

Value

A string of file locations in rmd syntax, to be included in printRmd

Print circular graphics for each array

Description

Prints the time of first entry point on each of the arrays. Contains functions adapted from the circular R package.

Usage

printCircular(times, bio, suffix = NULL)

Arguments

Details

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

Value

A string of file locations in rmd syntax, to be included in printRmd

Print DOT diagram

Description

Print DOT diagram

Usage

printDot(dot, spatial, print.releases)

Arguments

Value

No return value, called to plot and save graphic.

Print dotplots

Description

Prints dotplots of multiple variables.

Usage

printDotplots(status.df, valid.dist)

Arguments

Value

No return value, called to plot and save graphic.

Print efficiency fragment

Description

Prints the ALS inter-array efficiency for inclusion in printRmd.

Usage

printEfficiency(
  CJS = NULL,
  efficiency = NULL,
  intra.CJS,
  type = c("migration", "residency")
)

Arguments

Value

A rmd string to be included in the report.

Print Rmd report

Description

Creates a Rmd report and converts it to html.

Usage

printExploreRmd(
  override.fragment,
  biometric.fragment,
  individual.plots,
  circular.plots,
  sensor.plots,
  spatial,
  deployments,
  detections,
  valid.detections,
  detections.y.axis
)

Arguments

Value

No return value, called for side effects.

print the distribution of tags per location

Description

print the distribution of tags per location

Usage

printGlobalRatios(global.ratios, group.ratios, time.ratios, spatial, rsp.info)

Arguments

Value

No return value, called to plot and save graphic.

print the individual locations per day

Description

print the individual locations per day

Usage

printIndividualResidency(ratios, global.ratios, spatial, rsp.info)

Arguments

Value

A string of file locations in rmd syntax, to be included in printRmd

Print individual graphics

Description

Prints the individual detections for each tag, overlaying the points in time considered crucial during the analysis.

Usage

printIndividuals(
  detections.list,
  movements,
  valid.movements,
  spatial,
  status.df = NULL,
  rsp.info,
  y.axis = c("auto", "stations", "arrays"),
  extension = "png"
)

Arguments

Value

A string of file locations in rmd syntax, to be included in printRmd

Print a simple barplot with the number of tags last seen at each section

Description

Print a simple barplot with the number of tags last seen at each section

Usage

printLastArray(status.df)

Value

No return value, called to plot and save graphic.

Print a simple barplot with the number of tags last seen at each section

Description

Print a simple barplot with the number of tags last seen at each section

Usage

printLastSection(input, spatial)

Arguments

Value

No return value, called to plot and save graphic.

Print Rmd report

Description

Creates a Rmd report and converts it to html.

Usage

printMigrationRmd(
  override.fragment,
  biometric.fragment,
  section.overview,
  efficiency.fragment,
  display.progression,
  array.overview.fragment,
  survival.graph.size,
  individual.plots,
  circular.plots,
  sensor.plots,
  spatial,
  deployments,
  valid.detections,
  detections,
  detections.y.axis
)

Arguments

Value

No return value, called for side effects.

Print progression diagram

Description

Print progression diagram

Usage

printProgression(dot, overall.CJS, spatial, status.df, print.releases)

Arguments

Value

No return value, called to plot and save graphic.

Print Rmd report

Description

Creates a Rmd report and converts it to html.

Usage

printResidencyRmd(
  override.fragment,
  biometric.fragment,
  efficiency.fragment,
  individual.detection.plots,
  individual.residency.plots,
  array.circular.plots,
  section.arrival.circular.plots,
  section.departure.circular.plots,
  sensor.plots,
  spatial,
  deployments,
  detections,
  valid.detections,
  last.seen,
  detections.y.axis
)

Arguments

Value

No return value, called for side effects.

Print arrival and departure times per section

Description

Print arrival and departure times per section

Usage

printSectionTimes(section.times, bio, detections)

Arguments

Value

No return value, called to plot and save graphic.

Print sensor data for each individual tag

Description

Print sensor data for each individual tag

Usage

printSensorData(
  detections,
  spatial,
  rsp.info,
  colour.by = c("auto", "stations", "arrays"),
  extension = "png"
)

Arguments

Value

A string of file locations in rmd syntax, to be included in printRmd

Print survival graphic

Description

Prints survival graphics per animal group.

Usage

printSurvivalGraphic(section.overview)

Arguments

Value

No return value, called to plot and save graphic.

Standard detections file created for actel

Description

Standard detections file created for actel

Usage

processStandardFile(input)

Arguments

Value

A data frame of standardized detections from the input file.

Thelma new export files

Description

Processes Thelma ALS files.

Usage

processThelmaNewFile(input)

Arguments

Value

A data frame of standardized detections from the input file.

Thelma old export files

Description

Processes Thelma ALS files.

Usage

processThelmaOldFile(input)

Arguments

Value

A data frame of standardized detections from the input file.

Vemco files

Description

Processes Vemco ALS files

Usage

processVemcoFile(input)

Arguments

Value

A data frame of standardized detections from the input file.

Read dot file or string

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

Recover latest actel crash log

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

Find the location where the tag spent most time per day

Description

Find the location where the tag spent most time per day

Usage

resPositions(ratios, timestep = c("days", "hours"))

Arguments

Value

A data frame containing the section in which each tag spent more time per day.

calculate residency ratios per tag

Description

calculate residency ratios per tag

Usage

resRatios(res, timestep = c("days", "hours"), tz)

Arguments

Value

A list containing the residency ratios for each tag.

compile output of dailyRatios

Description

compile output of dailyRatios

Usage

resRatiosIndOut(input, slots, tz, tag)

Arguments

Value

A data frame with the daily ratios table for the target tag

Create status.df

Description

Combines the timetable and the original biometrics.

Usage

res_assembleOutput(res.df, bio, spatial, tz)

Arguments

Value

A data frame containing all the final data for each tag.

Calculate array efficiency for residency analysis

Description

Calculate array efficiency for residency analysis

Usage

res_efficiency(arrmoves, bio, spatial, arrays, paths, dotmat)

Arguments

Value

A list containing:

• absolutes: A data frame with the number of tags detected and missed at each array.

• max.efficiency: A vector of efficiency values calculated disregarding potentially missed tags.

• min.efficiency: A vector of efficiency values calculated taking into account potentially missed tags.

• values.per.tag: A list containing details on the arrays that have failed for each tag.

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

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)

Draw rings at relative points

Description

Adapted from RosediagRad() (from the circular package) to draw rings inside the circular plot. Called if rings = TRUE in myRoseDiag

Usage

ringsRel(
  plot.params,
  border,
  rings.lty,
  ring.text,
  ring.text.pos,
  ring.text.cex
)

Arguments

Details

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

Value

No return value, adds to an existing plot.

Draw mean value in the axis margin

Description

Computes and draws the mean value for a given dataset, may also plot standard error of the mean or standard deviation ranges.

Usage

roseMean(
  input,
  col = c("cornflowerblue", "chartreuse3", "deeppink"),
  mean.length = c(0.0125, -0.0125),
  mean.lwd = 4,
  box.range = c("none", "std.error", "sd"),
  fill = "white",
  horizontal.border = "black",
  vertical.border = "black",
  box.size = c(1.015, 0.985),
  edge.length = c(0.025, -0.025),
  edge.lwd = 2
)

Arguments

Value

No return value, adds to an existing plot.

Compress array-movements into section-movements

Description

Compress array-movements into section-movements

Usage

sectionMovements(movements, spatial, valid.dist)

Arguments

Value

A data frame containing the section movements for the target tag.

Create Standard Names for spatial elements

Description

Includes standard names and also reprints 'spatial.csv'

Usage

setSpatialStandards(input)

Arguments

Value

A data frame with the same information as the input plus a Standard.name column.

Load shapefile and convert to a raster object.

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)

Analytical CJS model

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)

Removes invalid events

Description

Remove invalid movement events and recalculate times/speeds.

Usage

simplifyMovements(movements, discard.first, tag, bio, speed.method, dist.mat)

Arguments

Value

The movement data frame containing only valid events for the target tag.

Calculate time and speed since release.

Description

Calculate time and speed since release.

Usage

speedReleaseToFirst(tag, bio, movements, dist.mat, speed.method)

Arguments

Value

The movement data frame containing time and speed from release to first event.

Split detections by tag

Description

Splits the detections' table by tags and selects only detections from target tags

Usage

splitDetections(detections, bio, exclude.tags = NULL)

Arguments

Value

A list of detections for each tag.

Split a dataframe every nth row

Description

Idea from here: https://stackoverflow.com/questions/7060272/split-up-a-dataframe-by-number-of-rows

Usage

splitN(x, n, row.names = FALSE)

Arguments

Value

A list of equal-sized dataframes

Split signals from multi-signal input

Description

Split signals from multi-signal input

Usage

splitSignals(x)

Arguments

Value

a list of split signals

Find original station name

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

Calculate the standard error of the mean for circular data

Description

Calculate the standard error of the mean for circular data

Usage

std.error.circular(x, na.rm = TRUE, silent = FALSE)

Arguments

Value

The standard error of the mean (numeric value).

stop function but paste error to the report too

Description

stop function but paste error to the report too

Usage

stopAndReport(...)

Arguments

Value

No return value, called for side effects.

Store summary information on the stray tags detected in a permanent file.

Description

Store summary information on the stray tags detected in a permanent file.

Usage

storeStrays()

Value

No return value, called for side effects.

Subset a character string counting from the right end

Description

Allows to quickly remove a given number of characters from the end of a string

Usage

substrRight(input, n)

Arguments

Value

A trimmed string or vector of trimmed strings.

Handler for table interaction events

Description

Handler for table interaction events

Usage

tableInteraction(
  moves,
  detections,
  tag,
  trigger,
  GUI,
  force = FALSE,
  save.tables.locally
)

Arguments

Value

A data frame with the updated movements table

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

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)

Transfer validity updates from valid movements to all movements

Description

Transfer validity updates from valid movements to all movements

Usage

transferValidity(from, to)

Arguments

Value

A data frame with the movement events for the target tag and an updated 'Valid' column.

Process spatial elements

Description

Creates a list containing multiple spatial elements required throughout the analyses

Usage

transformSpatial(spatial, bio, arrays, dotmat, first.array = NULL)

Arguments

Value

The stations, release sites and array order.

Calculate Transition Layer

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)

update array-movement validity based on the section-movements

Description

update array-movement validity based on the section-movements

Usage

updateValidity(arrmoves, secmoves)

Value

A list with the updated array movements.

Wrap frequently used code to handle user input

Description

Wrap frequently used code to handle user input

Usage

userInput(question, choices, tag, hash)

Arguments

user_interaction.R arguments

Description

user_interaction.R arguments

Arguments

Compare original detections with the valid movements and exclude invalid detections

Description

Compare original detections with the valid movements and exclude invalid detections

Usage

validateDetections(detections.list, movements)

Arguments

Value

A list containing the valid detections per tag.

Transform vectors into data frames with specific columns

Description

Used to prepare lists of vectors with partially matching names for combination with do.call(rbind.data.frame, x)

Usage

vectorsIntoTables(input, columns)

Arguments

Value

A list of tables with matching columns

widget_setups.R arguments

Description

widget_setups.R arguments

Arguments