Package 'glatos'

Description

Subset method for vdat_list that retains attributes

Usage

## S3 method for class 'vdat_list'
x[i]

Arguments

Description

Plot detection locations of acoustic transmitters over time.

Usage

abacus_plot(
  det,
  location_col = "glatos_array",
  locations = NULL,
  show_receiver_status = NULL,
  receiver_history = NULL,
  out_file = NULL,
  x_res = 5,
  x_format = "%Y-%m-%d",
  outFile = NULL,
  ...
)

Arguments

Details

NAs are not allowed in any of the two required columns.

The locations vector is used to control which locations will appear in the plot and in what order they will appear. If no locations vector is supplied, the function will plot only those locations that appear in the det data frame and the order of locations on the y-axis will be alphebetical from top to bottom.

By default, the function does not distinguish detections from different transmitters and will therefore plot all transmitters the same color. If more than one fish is desired in a single plot, a vector of colors must be passed to the function using the 'col =' argument. The color vector must be the same length as the number of rows in the detections data frame or the colors will be recycled.

Plotting options (i.e., line width and color) can be changed using optional graphical parameters http://www.statmethods.net/advgraphs/parameters.html that are passed to "points" (see ?points).

Value

An image to the default plot device or a file containing the image if out_file is specified.

Author(s)

T. R. Binder, edited by A. Dini

Examples

# get path to example detection file
det_file <- system.file("extdata", "walleye_detections.csv",
  package = "glatos"
)
det <- read_glatos_detections(det_file)

# subset one transmitter
det2 <- det[det$animal_id == 153, ]

# plot without control table and main tile and change color to red
abacus_plot(det2,
  locations = NULL,
  main = "TagID: 32054", col = "red"
)

# example with locations specified
abacus_plot(det2, locations = c(
  "DRF", "DRL", "FMP", "MAU", "PRS", "RAR",
  "DRM", "FDT"
), main = "TagID: 32054", col = "red")

# plot with custom y-axis label and lines connecting symbols
abacus_plot(det2, main = "TagID: 32054", type = "o", pch = 20, col = "red")

# plot with custom x-axis resolution - 10 bins
abacus_plot(det2, main = "TagID: 32054", x_res = 10)

# plot with custom x-axis resolution - monthly bins
abacus_plot(det2, main = "TagID: 32054", x_res = "month")

# plot with custom x-axis resolution - 8-week bins
abacus_plot(det2, main = "TagID: 32054", x_res = "8 weeks")

# plot with custom x-axis format
abacus_plot(det2, main = "TagID: 32054", x_res = "months", x_format = "%b-%y")

# plot with custom x axis limits
xLim <- as.POSIXct(c("2012-01-01", "2014-01-01"), tz = "UTC")
abacus_plot(det2, main = "TagID: 32054", xlim = xLim)

# example with receiver locations
# get example receiver location data
rec_file <- system.file("extdata", "sample_receivers2.csv",
  package = "glatos"
)
rec <- read_glatos_receivers(rec_file)

abacus_plot(det2,
  locations = c(
    "DRF", "DRL", "FMP", "MAU", "PRS", "RAR",
    "DRM", "FDT"
  ), receiver_history = rec,
  main = "TagID: 32054", col = "red"
)

# example with grey box plotted in background (using panel.first)

# set time range covered by rectangle
rect_x_rng <- as.POSIXct(c("2012-07-31", "2013-04-15"), tz = "UTC")
# get number of unique locations (y-axis)
n_locs <- length(unique(det2$glatos_array))

# plot as grey box in background
abacus_plot(det2,
  locations = NULL,
  main = "TagID: 32054", col = "red",
  panel.first = rect(rect_x_rng[1], 1, rect_x_rng[2], n_locs,
    col = "grey",
    border = NA
  )
)

Description

Speed up or slow down playback of video

Usage

adjust_playback_time(
  scale_factor = 1,
  input,
  output_dir = getwd(),
  output = "new.mp4",
  overwrite = FALSE,
  diagnostic_mode = FALSE
)

Arguments

Details

A simple wrapper for av::av_encode_video.

adjust_playback_time adjusts playback speed of video. scale_factor controls the magnitude of speed-up or slow-down by modifying the presentation timestamp of each video frame. Values of scale_factor < 1 speed up playback and > 1 slow down playback. In addition to changing playback, function can change output format by specifying a different file extension in output.

Value

One video animation will be written to output_dir and the path and name of output file with be returned.

Note

Input argument 'ffmpeg' was removed in glatos version 0.7.0.

Author(s)

Todd Hayden, Tom Binder, Chris Holbrook

Examples

## Not run: 

# load example frames
frames <- system.file("extdata", "frames", package = "glatos")

# make video animation
out_file <- file.path(tempdir(), "animation_av.mp4")
make_video(
  input_dir = frames,
  input_ext = ".png",
  output = out_file
)

# slow video down by a factor of 10
path <- file.path(tempdir(), "animation_av.mp4")
adjust_playback_time(
  scale_factor = 10,
  input = path,
  output_dir = tempdir(),
  output = "animation_av_slow.mp4",
  diagnostic_mode = FALSE,
  overwrite = TRUE
)

# slow video down by a factor of 10 and change format of output video
adjust_playback_time(
  scale_factor = 10,
  input = path,
  output_dir = tempdir(),
  output = "animation_av_slow.wmv",
  diagnostic_mode = FALSE,
  overwrite = TRUE
)

# speed up video
adjust_playback_time(
  scale_factor = 0.5,
  input = path,
  output_dir = tempdir(),
  output = "animation_av_fast.mp4",
  diagnostic_mode = FALSE,
  overwrite = TRUE
)

## End(Not run)

Description

The function below aggregates timedelta of first_detection and last_detection, excluding overlap between detections. Any overlap between two detections is converted to a new detection using the earlier first_detection and the latest last_detection. If the first_detection and last_detection are the same, a timedelta of one second is assumed.

Usage

aggregate_total_no_overlap(detections)

Arguments

Description

The function below aggregates timedelta of first_detection and last_detection of each detection into a final timedelta then returns a float of the number of days. If the first_detection and last_detection are the same, a timedelta of one second is assumed.

Usage

aggregate_total_with_overlap(detections)

Arguments

Description

Estimate (by simulation) probability of collision for co-located telemetry transmitters with pulse-period-modulation type encoding

Usage

calc_collision_prob(
  delayRng = c(60, 180),
  burstDur = 5,
  maxTags = 50,
  nTrans = 10000
)

Arguments

Details

Calculates the detection probability associated with collision, given delay range (delayRng), burst duration (burstDur), maximum number of co-located tags (maxTags), and number of simulated transmission per tag (nTrans). The simulation estimates detection probability due only to collisions (i.e., when no other variables influence detection probability) and assuming that all tags are co-located at a receiver for the duration of the simulation.

Value

A data frame containing summary statistics:

Author(s)

C. Holbrook ([email protected]) and T. Binder

References

For application example, see:

Binder, T.R., Holbrook, C.M., Hayden, T.A. and Krueger, C.C., 2016. Spatial and temporal variation in positioning probability of acoustic telemetry arrays: fine-scale variability and complex interactions. Animal Biotelemetry, 4(1):1.
http://animalbiotelemetry.biomedcentral.com/articles/10.1186/s40317-016-0097-4

Examples

# parameters analagous to Vemco tag, global coding, 45 s nominal delay
foo <- calc_collision_prob(
  delayRng = c(45, 90), burstDur = 5.12, maxTags = 50,
  nTrans = 10000
)

# plot probabilities of detection
plot(med ~ nTags,
  data = foo, type = "p", pch = 20, ylim = c(0, 1),
  xlab = "# of transmitters within range", ylab = "Probability of detection"
)

# plot probability of collision by subtracting detection probability from 1
plot((1 - med) ~ nTags,
  data = foo, type = "p", pch = 20, ylim = c(0, 1),
  xlab = "# of transmitters within range", ylab = "Probability of collision"
)

Description

Check path to Innovasea program VDAT.exe

Usage

check_vdat(vdat_exe_path = NULL)

Arguments

Value

Character string with command for calling VDAT.exe via system2's command argument.

Examples

## Not run: 

# use Windows system PATH variable
check_vdat()


# use path to directory containing VDAT.exe
check_vdat(vdat_exe_path = "C:/Program Files/Innovasea/Fathom")


# use full path to VDAT.exe
check_vdat(vdat_exe_path = "C:/Program Files/Innovasea/Fathom/VDAT.exe")

## End(Not run)

Description

Check path to Innovasea program VUE.exe

Usage

check_vue(vue_exe_path = NULL)

Arguments

Value

Character string with command for calling VUE.exe via system2's command argument.

Examples

## Not run: 

# use Windows system PATH variable
check_vue()


# use path to directory containing VUE.exe
check_vue(vue_exe_path = "C:/Program Files (x86)/VEMCO/VUE")


# use full path to VUE.exe
check_vue(vue_exe_path = "C:/Program Files (x86)/VEMCO/VUE/VUE.exe")

## End(Not run)

Description

Convert glatos_detections and glatos_receiver objects to ATT for compatibility with the Animal Tracking Toolbox https://github.com/vinayudyawer/ATT, now part of VTrack https://github.com/RossDwyer/VTrack.

Usage

convert_glatos_to_att(detectionObj, receiverObj, crs = sf::st_crs(4326))

Arguments

Details

This function takes 2 lists containing detection and reciever data and transforms them into one list containing 3 tibble objects. The input that AAT uses to get this data product is located here: https://github.com/vinayudyawer/ATT/blob/master/README.md and our mappings are found here: https://github.com/ocean-tracking-network/glatos/issues/75#issuecomment-982822886 in a comment by Ryan Gosse.

Note that the Tag.Detections element of the output can contain fewer records than detectionObj because detections are omitted if they do not match a station deployment-recovery interval in receiverObj. For example, in the walleye data example, walleye_detections contains 7180 rows but Tag.Detectons output only contains 7083 rows.

Value

a list of 3 tibbles containing tag detections, tag metadata, and station metadata, to be ingested by VTrack/ATT

Author(s)

Ryan Gosse

Examples

#--------------------------------------------------
# EXAMPLE #1 - loading from the vignette data

library(glatos)
wal_det_file <- system.file("extdata", "walleye_detections.csv",
  package = "glatos"
)
walleye_detections <- read_glatos_detections(wal_det_file) # load walleye data

rec_file <- system.file("extdata", "sample_receivers.csv",
  package = "glatos"
)
rcv <- read_glatos_receivers(rec_file) # load receiver data

ATTdata <- convert_glatos_to_att(walleye_detections, rcv)

Description

Convert glatos_detections and transmitter, receiver, and animal metadata from the OTN ERDDAP to ATT format for use in the Animal Tracking Toolbox https://github.com/vinayudyawer/ATT, now part of VTrack https://github.com/RossDwyer/VTrack.

Usage

convert_otn_erddap_to_att(
  detectionObj,
  erdTags,
  erdRcv,
  erdAni,
  crs = sf::st_crs(4326)
)

Arguments

Details

This function takes 4 data frames containing detection, and ERDDAP data from the tags, receivers, and animals tables, and transforms them into 3 tibble objects inside of a list. The input that AAT uses to get this data product is located here: https://github.com/vinayudyawer/ATT/blob/master/README.md and our mappings are found here: https://github.com/ocean-tracking-network/glatos/issues/75#issuecomment-982822886 in a comment by Ryan Gosse. The OTN ERDDAP instance is here: https://members.oceantrack.org/erddap/tabledap/index.html but please note that this only contains public data.

Value

a list of 3 tibbles containing tag detections, tag metadata, and station metadata, to be ingested by VTrack/ATT

Author(s)

Ryan Gosse

Examples

#--------------------------------------------------
# EXAMPLE #1 - loading from the OTN ERDDAP + vignettes

library(glatos)

# get path to example files from OTN ERDDAP
ani_erd_file <- system.file("extdata", "otn_aat_animals.csv",
  package = "glatos"
)
animals <- read.csv(ani_erd_file) # load the CSVs from ERDDAP

tags_erd_file <- system.file("extdata", "otn_aat_tag_releases.csv",
  package = "glatos"
)
tags <- read.csv(tags_erd_file)

rcv_erd_file <- system.file("extdata", "otn_aat_receivers.csv",
  package = "glatos"
)
stations <- read.csv(rcv_erd_file)

# Remove first row; (blank or metadata about the column)
animals <- animals[-1, ]
tags <- tags[-1, ]
stations <- stations[-1, ]

# get blue shark example data
shrk_det_file <- system.file("extdata", "blue_shark_detections.csv",
  package = "glatos"
)
blue_shark_detections <- read_otn_detections(shrk_det_file) # load shark data

ATTdata <- convert_otn_erddap_to_att(
  detectionObj = blue_shark_detections,
  erdTags = tags,
  erdRcv = stations,
  erdAni = animals
)

Description

Convert glatos_detections, OTN tagging metadata and OTN deployment metadata to ATT format for use in the Animal Tracking Toolbox https://github.com/vinayudyawer/ATT, now part of VTrack https://github.com/RossDwyer/VTrack.

Usage

convert_otn_to_att(
  detectionObj,
  taggingSheet,
  deploymentObj = NULL,
  deploymentSheet = NULL,
  timeFilter = TRUE,
  crs = sf::st_crs(4326)
)

Arguments

Details

This function takes 3 data frames containing detections, tagging metadata, and deployment metadata from either read_otn_deployments or prepare_deploy_sheet and transforms them into 3 tibble objects inside of a list. The input that AAT uses to get this data product is located here: https://github.com/vinayudyawer/ATT/blob/master/README.md and our mappings are found here: https://github.com/ocean-tracking-network/glatos/issues/75#issuecomment-982822886 in a comment by Ryan Gosse.

Value

a list of 3 tibbles containing tag detections, tag metadata, and station metadata, to be ingested by VTrack/ATT

Author(s)

Ryan Gosse

Examples

## Not run: 
#--------------------------------------------------
# EXAMPLE #1 - loading from Deployment Object

library(glatos)

dets_path <- system.file("extdata", "blue_shark_detections.csv",
  package = "glatos"
)
deploy_path <- system.file("extdata", "hfx_deployments.csv",
  package = "glatos"
)
tag_path <- system.file("extdata", "otn_nsbs_tag_metadata.xls",
  package = "glatos"
)

dets <- read_otn_detections(dets_path)
tags <- prepare_tag_sheet(tag_path, 5, 2)
deploy <- read_otn_deployments(deploy_path)

ATTdata <- convert_otn_to_att(dets, tags, deploymentObj = deploy)

## End(Not run)
#--------------------------------------------------
# EXAMPLE #2 - loading from Deployment Sheet

library(glatos)

dets_path <- system.file("extdata", "blue_shark_detections.csv",
  package = "glatos"
)
deploy_path <- system.file("extdata", "hfx_deploy_simplified.xlsx",
  package = "glatos"
)
tag_path <- system.file("extdata", "otn_nsbs_tag_metadata.xls",
  package = "glatos"
)

dets <- read_otn_detections(dets_path)
tags <- prepare_tag_sheet(tag_path, 5, 2)
deploy <- prepare_deploy_sheet(deploy_path, 1, 1)

ATTdata <- convert_otn_to_att(dets, tags, deploymentSheet = deploy)

Description

Simulate a random walk as series of equal-length steps with turning angles drawn from a normal distribution.

Usage

crw(
  theta = c(0, 5),
  stepLen = 10,
  initPos = c(0, 0),
  initHeading = 0,
  nsteps = 10000
)

Arguments

Details

First, nsteps turn angles are drawn from a normal distribution. Second, the cumulative sum of the vector of turn angles defines the heading within each step. The x and y component vectors in each are then calculated and summed to obtain the simualted path.

Value

A two-column data frame containing:

Note

Adapted from code provided by Tom Binder.

Author(s)

C. Holbrook ([email protected])

Examples

foo <- crw(
  theta = c(0, 5), stepLen = 10, initPos = c(0, 0), initHeading = 0,
  nsteps = 10
)
plot(foo, type = "o", pch = 20, asp = c(1, 1))

Description

Uses crw() to simulate a random walk as series of equal-length steps with turning angles drawn from a normal distribution inside a polygon.

Usage

crw_in_polygon(
  polyg,
  theta = c(0, 10),
  stepLen = 100,
  initPos = c(NA, NA),
  initHeading = NA,
  nsteps = 30,
  inputCRS = NA,
  cartesianCRS = NA,
  sp_out = TRUE,
  show_progress = TRUE
)

Arguments

Details

If initPos = NA, then a starting point is randomly selected within the polygon boundary. A path is simulated forward using crw(). Initial heading is also randomly selected if initHeading = NA. When a step crosses the polygon boundary, a new heading for that step is drawn and the turn angle standard deviation is enlarged slightly for each subsequent point that lands outside the polygon.

If input polyg object is a data.frame with x and y columns and sp_out = TRUE, then output object coordinate system is defined by inputCRS. Coordinate system on output will be same as input if polyg contains a valid CRS.

Value

When sp_out = TRUE, an sf object containing one POINT feature for each vertex in the simulated path.
OR
When sp_out = FALSE, a two-column data frame containing:

in the same units as polyg.

Note

The path is constructed in segments based on the minimum distance between the previous point and the closest polygon boundary.

Simulations are conducted within the coordinate system specified by argument cartesianCRS.

EPSG 3175 (cartesianCRS = 3175) is recommended projected coordinate system for the North American Great Lakes Basin and St. Lawrence River system. https://spatialreference.org/ref/epsg/nad83-great-lakes-and-st-lawrence-albers/.

Author(s)

C. Holbrook [email protected]

See Also

crw, transmit_along_path, detect_transmissions

Examples

# Example 1 - data.frame input
mypolygon <- data.frame(x = c(-50, -50, 50, 50), y = c(-50, 50, 50, -50))

path_df <- crw_in_polygon(mypolygon,
  theta = c(0, 20), stepLen = 10,
  initPos = c(0, 0), initHeading = 0, nsteps = 50, sp_out = FALSE
)

class(path_df) # note object is data.frame

plot(path_df,
  type = "o", pch = 20, asp = c(1, 1),
  xlim = range(mypolygon$x), ylim = range(mypolygon$y)
)

polygon(mypolygon, border = "red")


# Example 2 - data.frame input; input CRS specified
mypolygon <- data.frame(
  x = c(-84, -85, -85, -84),
  y = c(45, 44, 45, 45)
)
path_df <- crw_in_polygon(mypolygon,
  theta = c(0, 20),
  stepLen = 1000,
  initPos = c(-84.75, 44.75),
  initHeading = 0,
  nsteps = 50,
  inputCRS = 4326,
  cartesianCRS = 3175,
  sp_out = FALSE
)
plot(path_df,
  type = "o", pch = 20, asp = c(1, 1),
  xlim = range(mypolygon$x), ylim = range(mypolygon$y)
)
class(path_df) # note object is data.frame
polygon(mypolygon, border = "red")


# Example 3 - sf POLYGON input
data(great_lakes_polygon)

# simulate in great lakes polygon
path_sf <- crw_in_polygon(great_lakes_polygon,
  theta = c(0, 25),
  stepLen = 10000,
  initHeading = 0,
  nsteps = 100,
  cartesianCRS = 3175
)

# plot
plot(sf::st_geometry(great_lakes_polygon),
  col = "lightgrey",
  border = "grey"
)
points(sf::st_coordinates(path_sf), type = "o", pch = 20, col = "red")

# zoom in
plot(sf::st_geometry(great_lakes_polygon),
  col = "lightgrey",
  xlim = sf::st_bbox(path_sf)[c("xmin", "xmax")],
  ylim = sf::st_bbox(path_sf)[c("ymin", "ymax")]
)
points(sf::st_coordinates(path_sf), type = "o", pch = 20, col = "red")


# Example 4 - SpatialPolygonsDataFrame input
data(greatLakesPoly)

# simulate in great lakes polygon
path_sp <- crw_in_polygon(greatLakesPoly,
  theta = c(0, 25),
  stepLen = 10000,
  initHeading = 0,
  nsteps = 100,
  cartesianCRS = 3175,
  sp_out = TRUE
)

# plot
plot(sf::st_as_sfc(greatLakesPoly), col = "lightgrey", border = "grey")
points(sf::st_coordinates(sf::st_as_sf(path_sp)),
  type = "o", pch = 20,
  col = "red"
)

# zoom in
plot(sf::st_as_sfc(greatLakesPoly),
  col = "lightgrey", border = "grey",
  xlim = sf::st_bbox(path_sp)[c("xmin", "xmax")],
  ylim = sf::st_bbox(path_sp)[c("ymin", "ymax")]
)
points(sf::st_coordinates(sf::st_as_sf(path_sp)),
  type = "o", pch = 20,
  col = "red"
)

Description

Simulates detection of transmitter signals in a receiver network based on detection range curve (detection probability as a function of distance), location of transmitter, and location of receivers.

Usage

detect_transmissions(
  trnsLoc = NA,
  recLoc = NA,
  detRngFun = NA,
  trnsColNames = list(time = "time", x = "x", y = "y"),
  recColNames = list(x = "x", y = "y"),
  inputCRS = NA,
  sp_out = TRUE,
  show_progress = TRUE
)

Arguments

Details

Distances between each signal transmission and receiver are calculated using geodist::geodist() (measure = "haversine") if input crs is geographic (i.e., longitude, latitude) and using simple Euclidean distances if input crs is Cartesian (e.g., UTM). If crs is missing, the an arbitrary Cartesian coordinate system with base unit of 1 meter is assumed. Computation time is fastest if coordinates are are in a Cartesian (projected) coordinate system and slowest if coordinates are in a geographic (long lat) coordinate system.

The probability of detecting each signal on each receiver is determined from the detection range curve. Detection of each signal on each receiver is determined stochastically by draws from a Bernoulli distribution with probability p (detection prob.).

This function was written to be used along with transmit_along_path().

Value

When sp_out = TRUE, an sf object containing one POINT feature with coordinates of each receiver and transmission location of each simulated detection (i.e., two geography columns names rec_geometry and trns_geometry) and the the following columns:

When sp_out = FALSE, a data.frame with columns containing coordinates of receiver locations of each simulation detection:

and the columns described above.

Author(s)

C. Holbrook ([email protected])

See Also

transmit_along_path() to simulate transmissions along a path (i.e., create trnsLoc).

Examples

# Example 1 - data.frame input (make a simple path in polygon)

mypoly <- data.frame(
  x = c(0, 0, 1000, 1000),
  y = c(0, 1000, 1000, 0)
)

mypath <- crw_in_polygon(mypoly,
  stepLen = 100,
  nsteps = 50,
  sp_out = FALSE
)

plot(mypath, type = "l", xlim = c(0, 1000), ylim = c(0, 1000))

# add receivers
recs <- expand.grid(x = c(250, 750), y = c(250, 750))
points(recs, pch = 15, col = "blue")

# simulate tag transmissions
mytrns <- transmit_along_path(mypath,
  vel = 2.0, delayRng = c(60, 180),
  burstDur = 5.0, sp_out = FALSE
)
points(mytrns, pch = 21) # add to plot

# Define detection range function (to pass as detRngFun)
# that returns detection probability for given distance
# assume logistic form of detection range curve where
#   dm = distance in meters
#   b = intercept and slope
pdrf <- function(dm, b = c(0.5, -1 / 120)) {
  p <- 1 / (1 + exp(-(b[1] + b[2] * dm)))
  return(p)
}
pdrf(c(100, 200, 300, 400, 500)) # view detection probs. at some distances

# simulate detection
mydtc <- detect_transmissions(
  trnsLoc = mytrns,
  recLoc = recs,
  detRngFun = pdrf,
  sp_out = FALSE
)

points(mydtc[, c("trns_x", "trns_y")], pch = 21, bg = "red")

# link transmitter and receiver locations for each detection\
with(mydtc, segments(
  x0 = trns_x,
  y0 = trns_y,
  x1 = rec_x,
  y1 = rec_y,
  col = "red"
))


# Example 2 - spatial (sf) input

data(great_lakes_polygon)

set.seed(610)
mypath <- crw_in_polygon(great_lakes_polygon,
  stepLen = 100,
  initPos = c(-83.7, 43.8),
  initHeading = 0,
  nsteps = 50,
  cartesianCRS = 3175
)

plot(sf::st_geometry(mypath), type = "l")

# add receivers
recs <- expand.grid(
  x = c(-83.705, -83.70),
  y = c(43.810, 43.815)
)
points(recs, pch = 15, col = "blue")

# simulate tag transmissions
mytrns <- transmit_along_path(mypath,
  vel = 2.0, delayRng = c(60, 180),
  burstDur = 5.0
)
points(sf::st_coordinates(mytrns), pch = 21) # add to plot

# Define detection range function (to pass as detRngFun)
# that returns detection probability for given distance
# assume logistic form of detection range curve where
#   dm = distance in meters
#   b = intercept and slope
pdrf <- function(dm, b = c(2, -1 / 120)) {
  p <- 1 / (1 + exp(-(b[1] + b[2] * dm)))
  return(p)
}
pdrf(c(100, 200, 300, 400, 500)) # view detection probs. at some distances

# simulate detection
mydtc <- detect_transmissions(
  trnsLoc = mytrns,
  recLoc = recs,
  detRngFun = pdrf
)

# view transmissions that were detected
sf::st_geometry(mydtc) <- "trns_geometry"

points(sf::st_coordinates(mydtc$trns_geometry), pch = 21, bg = "red")

# link transmitter and receiver locations for each detection
segments(
  x0 = sf::st_coordinates(mydtc$trns_geometry)[, "X"],
  y0 = sf::st_coordinates(mydtc$trns_geometry)[, "Y"],
  x1 = sf::st_coordinates(mydtc$rec_geometry)[, "X"],
  y1 = sf::st_coordinates(mydtc$rec_geometry)[, "Y"],
  col = "red"
)

Description

Make bubble plots showing the number of fish detected across a defined set of receiver locations.

Usage

detection_bubble_plot(
  det,
  location_col = "glatos_array",
  receiver_locs = NULL,
  map = NULL,
  out_file = NULL,
  background_ylim = c(41.3, 49),
  background_xlim = c(-92.45, -75.87),
  symbol_radius = 1,
  col_grad = c("white", "red"),
  scale_loc = NULL
)

Arguments

Details

Data are summarized using summarize_detections.

If receiver_locs is specified (not NULL) then the plot will show all receivers in receiver_locs including any that detected none of the transmitters in det. Although this is helpful to view locations where fish were not detected, the user will usually want to take care to include only receivers that were in the water during the period of interest. If you are using a glatos receiver locations file to specify location for plotting, you will likely want to filter the receiver data by depoyment and receovery dates to exclude deployments that occured outside of the period of interest.

"col_grad" is used in a call to colorRampPalette, which will accept a vector containing any two colors return by colors as character strings.

Value

A data frame produced by glatos::summarize_detections(det, location_col = location_col, receiver_locs = receiver_locs, summ_type = "location")

If not out_file is specified, then an image is printed to the default plot device. If out_file is specified, then an image of specified type is written to out_file.

Author(s)

T. R. Binder, edited by A. Dini

See Also

summarize_detections()

Examples

# get path to example detection file
det_file <- system.file("extdata", "walleye_detections.csv",
  package = "glatos"
)
det <- read_glatos_detections(det_file)

# call with defaults
detection_bubble_plot(det, map = great_lakes_polygon)

# change symbol size and color
detection_bubble_plot(det, symbol_radius = 2, col_grad = c("grey90", "grey10"))

# Add all receivers

# get path to example receiver file
rec_file <- system.file("extdata", "sample_receivers.csv",
  package = "glatos"
)
rec <- read_glatos_receivers(rec_file)

detection_bubble_plot(det, receiver_locs = rec)


#' #Subset receivers to include on receivers that were deployed during the
#' detection interval.

# get path to example receiver file
rec_file <- system.file("extdata", "sample_receivers.csv",
  package = "glatos"
)
rec <- read_glatos_receivers(rec_file)

first <- min(det$detection_timestamp_utc) # time of first detection
last <- max(det$detection_timestamp_utc) # time of last detection

# Subset receiver deployments oustide the detection period.
# !is.na(rec$recover_date_time) eliminates receivers that have been
# deployed but not yet recovered.
plot_rec <- rec[rec$deploy_date_time < last &
  rec$recover_date_time > first &
  !is.na(rec$recover_date_time), ]

detection_bubble_plot(det, receiver_locs = plot_rec)

Description

Reduce detection data into discrete detection events, defined by movement between receivers (or receiver groups, depending on location), or sequential detections at the same location that are separated by a user-defined threshold period of time.

Usage

detection_events(
  det,
  location_col = "glatos_array",
  time_sep = Inf,
  condense = TRUE
)

Arguments

Details

mean_latitude and mean_longitude columns in the output dataframe are the mean GPS locations for the detections comprising that detection event. For example, if the a fish was detected at 3 receiver stations in a glatos_array and glatos_array was selected as the location, then GPS location for that event will be the mean of the latitude and longitude for those three receiver stations (weighted based on the number of detections that occurred on each station).

Value

A data.table or tibble object (if input is either type; output class to match input) or data.frame otherwise. Structure depends on value of condense argument:

If condense = TRUE, a data.frame, data.table, or tibble with the following columns:

If `condense = FALSE`, a data.frame, data.table, or tibble matching the
input data frame `det` with the following columns added:

Author(s)

T. R. Binder, T. A. Hayden, C. M. Holbrook

Examples

# get path to example detection file
det_file <- system.file("extdata", "walleye_detections.csv",
  package = "glatos"
)
det <- read_glatos_detections(det_file)

filt0 <- detection_events(det) # no time filter

# 7-day filter
filt_7d <- detection_events(det, time_sep = 604800)

# 7-day filter but return do not condense result
filt_7d <- detection_events(det, time_sep = 604800, condense = FALSE)

Description

Uses a third-order polynomial, logit, or, probit model to determine detection range based on a expected percentage of detections for acoustic telemetry receivers. This function is to be used after a preliminary range test which uses multiple distances away from representative receiver. Preliminary detection efficiency is to be determined in Vemco's Range Testing software and exported as a csv.

Usage

detection_range_model(
  formula,
  data,
  percentage = NULL,
  link = NULL,
  subset = NULL,
  summary_stats = TRUE,
  model_frame = NULL
)

Arguments

Details

If a third order polynomial model is selected, the formula call can be in two different formats. The preferred and default format is y ~ -1 + x + I(x ^ 2) + I(x ^ 3) + offset(y-intercept). model_frame needs to be set "data_frame"to properly extract parameters and determine distances away from a receiver given a percentage of interest. If using the base::poly() within the formula as such y ~ -1 + poly(x, 3, raw = TRUE) + offset(y-intercept), then model_frame argument needs to be set to "matrix". Both formula formats have offset() which sets the y-intercept. The y-intercept needs to be set to 100, as x = 0 m away from a receiver you expect to hear a tag 100\

A third order polynomial will handle preliminary detection efficiency percentages (y variable) as whole numbers as the model is not bound by 0 and 1. While both logit and probit models have to use percentages as decimals as the models are bound by 0 and 1.

Additionally, its been noticed that with fewer data points a third order polynomial often fits the data better however this does not mean that neither a logit or probit model should not be assessed as well.

Value

A tibble object that consists of the percentage of interest, the predicted distance from the model, and model summary statistics:

If a third order polynomial is selected the following summary statistics are displayed: degrees of freedom, chi-square test, person's goodness of fit test, slopes, slopes' standard error, slopes' p-value, residual standard error, r squared and adjusted r squared values, and aic value.

If a logit or probit model is selected the following summary statistics are displayed: degrees of freedom, chi-square (deviance), person's goodness of fit test, slope, slope's standard error, slope's p-value, z-value, null deviance, and aic value.

Author(s)

Benjamin L. Hlina

References

This function was developed for an ongoing study which followed detection range efficiency methods similar to:

Brownscombe, J.W., L.P. Griffin, J.M. Chapman, D. Morley, A. Acosta, G.T. Crossin, S.J. Iverson, A.J. Adams, S.J. Cooke, and A.J. Danylchuk. 2020. A practical method to account for variation in detection range in acoustic telemetry arrays to accurately quantify the spatial ecology of aquatic animals. Methods in Ecology and Evolution 11(1):82–94.

Examples

sample_detection_efficiency

# third order polynomial: # ave_percent is a whole number

m <- detection_range_model(
  avg_percent ~ -1 + distance_m + I(distance_m^2) +
    I(distance_m^3) + offset(intercept),
  data = sample_detection_efficiency,
  percentage = c(10, 50, 90),
  link = "polynomial",
  model_frame = "data_frame"
)

# logit model: aver percent is in decimal form

m1 <- detection_range_model(avg_percent_d ~ distance_m,
  data = sample_detection_efficiency,
  percentage = c(10, 50, 90),
  link = "logit",
  summary_stats = TRUE
)

# probit model: aver percent is in decimal form

m2 <- detection_range_model(avg_percent_d ~ distance_m,
  data = sample_detection_efficiency,
  percentage = c(10, 50, 90),
  link = "probit",
  summary_stats = TRUE
)

m
m1
m2

# for further instruction see vignettes

Description

Identify possible false detections based on "short interval" criteria (e.g., GLATOS 'min_lag') .

Usage

false_detections(det, tf, min_lag_col = "min_lag", show_plot = FALSE, ...)

Arguments

Details

Detections are identified as potentially false when min_lag > tf.

A new column (passed_filter), indicating if each record (row) passed the filter, is added to the input data frame.

This function was written specifically with GLATOS standard detection export in mind, but if min_lag is absent and min_lag_col is not specified, then min_lag will be calculated using min_lag.

A common rule of thumb for choosing tf for VEMCO PPM encoded transmitters is 30 times the nominal delay (e.g., 3600 s for a transmitter with a 120 s nominal delay) - see Pincock (2012).

When show_plot = TRUE then the plot may be used to assess sensitivity of the proportion of detections removed to the choice of tf.

Value

A data frame consisting of det with an additional column 'passed_filter' indicating if each detection did (1) or did not (0) pass the criteria.

Author(s)

T. R. Binder, edited by A. Dini

References

Pincock, D.G., 2012. False detections: what they are and how to remove them from detection data. Vemco Division, Amirix Systems Inc., Halifax, Nova Scotia.
http://www.vemco.com/pdf/false_detections.pdf

Simpfendorfer, C.A., Huveneers, C., Steckenreuter, A., Tattersall, K., Hoenner, X., Harcourt, R. and Heupel, M.R., 2015. Ghosts in the data: false detections in VEMCO pulse position modulation acoustic telemetry monitoring equipment. Animal Biotelemetry, 3(1), p.55.
https://animalbiotelemetry.biomedcentral.com/articles/10.1186/s40317-015-0094-z

See Also

min_lag()

Examples

# get path to example detection file
det_file <- system.file("extdata", "walleye_detections.csv",
  package = "glatos"
)
det <- read_glatos_detections(det_file)

det <- false_detections(det, 3600)
head(det)

# plot sensitivity to tf
det <- false_detections(det, 3600, show_plot = TRUE)

Description

An sf POLYGON object with coastline of Flynn Island; and island within Higgins Lake, Michigan. Used as an example of a polygon representing a body of land (as opposed to water body).

Usage

flynn_island_polygon

Format

An object of class sf (inherits from data.frame) with 1 rows and 2 columns.

Author(s)

Chris Holbrook

Description

A transition object, created from flynn_island_polygon() for testing make_transition().

Format

A list comprised of a TransitionLayer and RasterLayer (see make_transition()).

Filename

flynn_island_transition.rds

Author(s)

Chris Holbrook

Examples

system.file("testdata", "flynn_island_transition.rds", package = "glatos")

Description

Round timestamp by fractional second and coerce to character

Usage

format_POSIXt(x, digits = 0, drop0trailing = TRUE)

Arguments

Details

Differs from e.g., format(x, format = "%Y-%m-%d %H:%M:%OS6") in that (1) rounding is used (not truncation) and (2) trailing 0s can be omitted (via drop0trailing).

Differs from lubridate::round_Date in that it is accurate for < 1 sec (see example 1 below for motivating example) but requires coercion to POSIXlt before rounding and coercing to character.

Value

A character vector in format like "%Y-%m-%d %H:%M:%OSn" (see strptime but see 'detail' for differences).

Examples

# Example 1 - motivating example: e.g., trouble with lubridate::round_Date
t1 <- as.POSIXct("2011-05-08 05:37:39.245541", tz = "UTC")
format(t1, digits = 6)

t2 <- lubridate::round_date(t1, unit = "0.00001s")
format(t2, digits = 6)

t3 <- format_POSIXt(t1, digits = 5)
format(t3, digits = 6)

# Example 2
t1 <- as.POSIXct(
  c(
    "2011-03-08 23:59:58",
    "2011-03-08 23:59:58.828867"
  ),
  tz = "UTC"
)
format_POSIXt(t1, digits = 5, drop0trailing = FALSE)
format_POSIXt(t1, digits = 5, drop0trailing = TRUE)

Description

Wrapper method for the calulation methods above.

Usage

get_days(dets, calculation_method = "kessel", time_interval_size = "1 day")

Arguments

Description

Get schema from local installation of Innovasea program VDAT.exe

Usage

get_local_vdat_template(vdat_exe_path = NULL)

Arguments

Details

A bug in vdat.exe version 9 (confirmed on vdat-9.3.0) will cause this function to return an empty list. Fixed in vdat.exe version 10 (confirmed on vdat-10.6.0).

Value

Schema (template) of VDAT CSV produced by installed version of VDAT.exe.

Examples

## Not run: 

# use if VDAT.exe in Windows system PATH variable
get_local_vdat_template()

# or specify path to VDAT.exe
get_local_vdat_template(
  vdat_exe_path =
    "C:/Program Files/Innovasea/Fathom/VDAT.exe"
)

## End(Not run)

Description

Get version of local installation of Innovasea program VDAT.exe

Usage

get_local_vdat_version(vdat_exe_path = NULL)

Arguments

Value

A list with version (version number) and long_version (full string returned by VDAT.exe).

Examples

## Not run: 

# use if VDAT.exe in Windows system PATH variable
get_local_vdat_version()

# or specify path to VDAT.exe
get_local_vdat_version(
  vdat_exe_path =
    "C:/Program Files/Innovasea/Fathom/VDAT.exe"
)

## End(Not run)

Description

Get version of local installation of Innovasea program VUE.exe

Usage

get_local_vue_version(vue_exe_path = NULL)

Arguments

Value

A list with version (version number) and long_version (full string returned by VUE.exe).

Examples

## Not run: 

# use if VUE.exe in Windows system PATH variable
get_local_vue_version()

# or specify path to VUE.exe
get_local_vue_version(
  vue_exe_path =
    "C:/Program Files (x86)/Vemco/VUE"
)

## End(Not run)

glatos is an R package with functions useful to members of the Great Lakes Acoustic Telemetry Observation System https://glatos.glos.us. Functions may be generally useful for processing, analyzing, simulating, and visualizing acoustic telemetry data, but are not strictly limited to acoustic telemetry applications.

Package status

glatos is hosted by the Ocean Tracking Network on github.

• For recent changes, see NEWS.

• To report a bug, ask a question, or propose something new, submit an Issue or email the maintainer (Chris Holbrook): [email protected].

Installation

To install the latest release (0.8.0 'very-refreshing-lemonade'):

library(remotes) # for install_github
install_github('ocean-tracking-network/glatos', build_vignettes = TRUE)

To install the development version, an earlier version, or to see frequently asked questions about installation, see https://github.com/ocean-tracking-network/glatos/wiki/installation-instructions.

Contents

Data loading and processing

1. read_glatos_detections and read_otn_detections provide fast data loading from standard GLATOS and OTN data files to a single structure that is compatible with other glatos functions.

2. read_glatos_receivers and read_otn_deployments reads receiver location histories from standard GLATOS and OTN data files to a single structure that is compatible with other glatos functions.

3. read_glatos_workbook reads project-specific receiver history and fish taggging and release data from a standard glatos workbook file.

4. read_vemco_tag_specs reads transmitter (tag) specifications and operating schedule.

5. real_sensor_values converts 'raw' transmitter sensor (e.g., depth, temperature) to 'real'-scale values (e.g., depth in meters) using transmitter specification data (e.g., from read_vemco_tag_specs).

6. prepare_tag_sheet and prepare_deploy_sheet load OTN metadata sheets for Tagging and Deployment of Receivers and formats them for converting to ATT Data.

7. vue_convert and vdat_convert extracts data from proprietary receiver files (.vrl, .vdat) using Innovasea's VUE and VDAT software (packaged with Fathom Connect software).

8. read_vdat_csv reads data from a CSV file produced by Innovasea's Fathom Connect or VDAT software (or with vdat_convert()). Data from an "interleaved" (not "split") Fathom CSV format are read into R as a vdat_list object.

9. read_vue_detection_csv, and read_vue_event_csv read data from a CSV file exported from Innovasea's VUE software.

Filtering and summarizing

1. min_lag facilitates identification and removal of false positive detections by calculating the minimum time interval (min_lag) between successive detections.

2. false_detections removes potential false positive detections using "short interval" criteria (see min_lag).

3. detection_events distills detection data down to a much smaller number of discrete detection events, defined as a change in location or time gap that exceeds a threshold.

4. summarize_detections calculates number of fish detected, number of detections, first and last detection timestamps, and/or mean location of receivers or groups, depending on specific type of summary requested.

5. residence_index calculates the relative proportion of time spent at each location.

6. REI calculates the relative activity at each receiver based on number of unique species and individual animals.

7. detection_range_model for estimating detection range at which a certain detection efficiency is expected, using output from Innovasea's range testing software.

Simulation functions for system design and evaluation

1. calc_collision_prob estimates the probability of collisions for pulse-position-modulation type co-located telemetry transmitters. This is useful for determining the number of fish to release or tag specifications (e.g., delay).

2. receiver_line_det_sim simulates detection of acoustic-tagged fish crossing a receiver line (or single receiver). This is useful for determining optimal spacing of receviers in a line and tag specifications (e.g., delay).

3. crw_in_polygon, transmit_along_path, and detect_transmissions individually simulate random fish movement paths within a water body (crw_in_polygon: a random walk in a polygon), tag signal transmissions along those paths (transmit_along_path: time series and locations of transmissions based on tag specs), and detection of those transmittions by receivers in a user-defined receiver network (detect_transmissions: time series and locations of detections based on detection range curve). Collectively, these functions can be used to explore, compare, and contrast theoretical performance of a wide range of transmitter and receiver network designs.

Visualization and data exploration

1. abacus_plot is useful for exploring movement patterns of individual tagged animals through time.

2. detection_bubble_plot is useful for exploring distribution of tagged individuals among receivers.

3. interpolate_path, make_frames, and make_video Interpolate spatio-temporal movements, between detections, create video frames, and stitch frames together to create animated video file.

4. adjust_playback_time modify playback speed of videos and optionally convert between video file formats.

Data Exporting

1. convert_glatos_to_att converts the glatos detection and receiver objects to a format supported by VTrack/ATT.

2. convert_otn_erddap_to_att converts the OTN detection and ERDDAP csvs of OTN animals, tags and stations to a format supported by VTrack/ATT.

3. convert_otn_to_att converts the OTN detections and metadata sheets to the ATT format. Also accepts deployment metadata from the OTN website in CSV format.

Description

Functions useful to members of the Great Lakes Acoustic Telemetry Observation System https://glatos.glos.us; many more broadly relevant to simulating, processing, analysing, and visualizing acoustic telemetry data.

Author(s)

Maintainer: Christopher Holbrook [email protected]

Authors:

• Todd Hayden

• Thomas Binder

• Jon Pye

Other contributors:

• Mike O'Brien [contributor]

• Alex Nunes [contributor]

• Benjamin Hlina [contributor]

• Angela Dini [contributor]

• Ryan Gosse [contributor]

See Also

Useful links:

• https://github.com/ocean-tracking-network/glatos

• Report bugs at https://github.com/ocean-tracking-network/glatos/issues

Description

Creates, checks, or validates a glatos_animals object.

Usage

glatos_animals(..., validate = TRUE)

as_glatos_animals(x, validate = TRUE)

is_glatos_animals(x)

validate_glatos_animals(x)

Arguments

Construction

glatos_animals() creates a glatos_animals from individual vectors (one for each column) and optionally checks for required column names and classes using validate_glatos_animals().

Coercion

as_glatos_animals() coerces a data.frame, or object that inherits from data.frame, to glatos_animals and optionally checks for required column names and classes using validate_glatos_animals().

Validation

is_glatos_animals() checks class attribute for "glatos_animals"

validate_glatos_animals() checks for required column names and classes

Examples

#  glatos_animals
x <- data.frame(
  animal_id = c("120", "107", "109"),
  tag_id_code = c("32024", "32012", "32014"),
  tag_code_space = c("A69-9001", "A69-9001", "A69-9001"),
  utc_release_date_time = as.POSIXct(
    c(
      "2011-03-28 00:00:00",
      "2011-03-28 00:01:00",
      "2011-03-28 00:05:00"
    ),
    tz = "UTC"
  ),
  release_latitude = c(41.56093, 41.56093, 41.56093),
  release_longitude = c(-83.645, -83.645, -83.645)
)

ga_df1 <- glatos_animals(
  animal_id = x$animal_id,
  tag_id_code = x$tag_id_code,
  tag_code_space = x$tag_code_space,
  utc_release_date_time = x$utc_release_date_time
)


# as_glatos_animals
ga_df2 <- as_glatos_animals(x)


# sf input

library(sf)

x_sf <- sf::st_as_sf(x,
  coords = c("release_longitude", "release_latitude")
)

ga_sf <- as_glatos_animals(x_sf)


# tibble input

x_tbl <- dplyr::as_tibble(x)

ga_tbl <- as_glatos_animals(x_tbl)


# All below will error as invalid

# data.frame input; missing column name
library(dplyr) # for rename
x2 <- rename(x,
  fish_name = animal_id,
  release_timestamp = utc_release_date_time
)

try(
  ga2 <- as_glatos_animals(x2)
)

# data.frame input; wrong column class
x3 <- mutate(x,
  animal_id = as.integer(animal_id),
  utc_release_date_time = as.character(utc_release_date_time)
)

try(
  ga3 <- as_glatos_animals(x3)
)

# Validation and checking

validate_glatos_animals(x)

is_glatos_animals(x) # FALSE

is_glatos_animals(ga_df1) # TRUE

Description

Check column names and classes of a list or data.frame against requirements

Check column classes of a list or data.frame against requirements

Usage

glatos_check_col_names(x, req_cols)

glatos_check_col_classes(x, req_cols)

Arguments

Description

Creates, checks, or validates a glatos_detections object.

Usage

glatos_detections(..., validate = TRUE)

as_glatos_detections(x, validate = TRUE)

is_glatos_detections(x)

validate_glatos_detections(x)

Arguments

Construction

glatos_detections() creates a glatos_detections object from individual vectors (one for each column) and optionally checks for required column names and classes using validate_glatos_detections().

Coercion

as_glatos_detections() coerces a data.frame, or object that inherits from data.frame, to glatos_detections and optionally checks for required column names and classes using validate_glatos_detections().

Validation

is_glatos_detections() checks class attribute for "glatos_detections"

validate_glatos_detections() checks for required column names and classes

Examples

#  glatos_detections
x <- data.frame(
  animal_id = c("153", "153", "153", "153"),
  detection_timestamp_utc = as.POSIXct(
    c(
      "2012-04-29 01:48:37",
      "2012-04-29 01:52:55",
      "2012-04-29 01:55:12",
      "2012-04-29 01:56:42"
    ),
    tz = "UTC"
  ),
  deploy_lat = c(43.39165, 43.39165, 43.39165, 43.39165),
  deploy_long = c(-83.99264, -83.99264, -83.99264, -83.99264)
)

gd_df1 <- glatos_detections(
  animal_id = x$animal_id,
  detection_timestamp_utc =
    x$detection_timestamp_utc,
  deploy_lat = x$deploy_lat,
  deploy_long = x$deploy_long
)


# as_glatos_detections
gd_df2 <- as_glatos_detections(x)


# sf input

library(sf)

# use remove = FALSE to keep required columns
x_sf <- sf::st_as_sf(x,
  coords = c("deploy_long", "deploy_lat"),
  remove = FALSE
)

gd_sf <- as_glatos_detections(x_sf)


# tibble input
library(dplyr)

x_tbl <- dplyr::as_tibble(x)

gd_tbl <- as_glatos_detections(x_tbl)


# All below will error as invalid

# data.frame input; missing column name
library(dplyr) # for rename
x2 <- rename(x,
  fish_id = animal_id,
  det_date_time = detection_timestamp_utc
)

try(
  gd2 <- as_glatos_detections(x2)
)

# data.frame input; wrong column class
x3 <- mutate(x,
  animal_id = as.integer(animal_id),
  detection_timestamp_utc = as.character(detection_timestamp_utc)
)

try(
  gr3 <- as_glatos_detections(x3)
)

# Validation and checking

validate_glatos_detections(x)

is_glatos_detections(x) # FALSE

is_glatos_detections(gd_df1) # TRUE

Description

Creates, checks, or validates a glatos_receivers object.

Usage

glatos_receivers(..., validate = TRUE)

as_glatos_receivers(x, validate = TRUE)

is_glatos_receivers(x)

validate_glatos_receivers(x)

Arguments

Construction

glatos_receivers() creates a glatos_receivers from individual vectors (one for each column) and optionally checks for required column names and classes using validate_glatos_receivers().

Coercion

as_glatos_receivers() coerces a data.frame, or object that inherits from data.frame, to glatos_receivers and optionally checks for required column names and classes using validate_glatos_receivers().

Validation

is_glatos_receivers() checks class attribute for "glatos_receivers"

validate_glatos_receivers() checks for required column names and classes

Examples

#  glatos_receivers
x <- data.frame(
  station = c("WHT-009", "FDT-001", "FDT-004", "FDT-003"),
  deploy_lat = c(43.7, 45.9, 45.9, 45.9),
  deploy_long = c(-82.5, -83.5, -83.5, -83.5),
  deploy_date_time = as.POSIXct(
    c(
      "2010-09-22 18:05:00",
      "2010-11-12 15:07:00",
      "2010-11-12 15:36:00",
      "2010-11-12 15:56:00"
    ),
    tz = "UTC"
  ),
  recover_date_time = as.POSIXct(
    c(
      "2012-08-15 16:52:00",
      "2012-05-15 13:25:00",
      "2012-05-15 14:15:00",
      "2012-05-15 14:40:00"
    ),
    tz = "UTC"
  ),
  ins_serial_no = c("109450", "442", "441", "444")
)

gr_df1 <- glatos_receivers(
  station = x$station,
  deploy_lat = x$deploy_lat,
  deploy_long = x$deploy_long,
  deploy_date_time = x$deploy_date_time,
  recover_date_time = x$recover_date_time,
  ins_serial_no = x$ins_serial_no
)


# as_glatos_receivers
gr_df2 <- as_glatos_receivers(x)


# sf input

library(sf)

# use remove = FALSE to keep required columns
x_sf <- sf::st_as_sf(x,
  coords = c("deploy_long", "deploy_lat"),
  remove = FALSE
)

gr_sf <- as_glatos_receivers(x_sf)


# tibble input
library(dplyr)

x_tbl <- dplyr::as_tibble(x)

gr_tbl <- as_glatos_receivers(x_tbl)

# All below will error as invalid

# data.frame input; missing column name
x2 <- rename(x,
  receiver_loc = station,
  deploy_timestamp = deploy_date_time
)

try(
  gr2 <- as_glatos_receivers(x2)
)

# data.frame input; wrong column class
x3 <- mutate(x,
  ins_serial_no = as.integer(ins_serial_no),
  deploy_date_time = as.character(deploy_date_time)
)

try(
  gr3 <- as_glatos_receivers(x3)
)

# Validation and checking

validate_glatos_receivers(x)

is_glatos_receivers(x) # FALSE

is_glatos_receivers(gr_df1) # TRUE

Description

These functions are gone, no longer available.

Details

• check_dependencies: Removed in glatos 0.7.0.

• install_ffmpeg: Removed in glatos 0.7.0.

• make_video_ffmpeg: Removed in glatos 0.7.0. Use make_video instead.

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("<function>-deprecated").

These functions still work but will be removed (defunct) in the next version.

• vrl2_csv: This function is deprecated, and will be removed in the next version of this package. Use vue_convert instead.

Usage

vrl2csv(
  vrl,
  outDir = NA,
  overwrite = TRUE,
  vueExePath = NA,
  showProgress = TRUE
)

Arguments

vrl2csv

For vrl2csv, use vue_convert.

Description

An sf POLYGON object with Great Lakes coastline, used as default map background in several glatos functions.

Usage

great_lakes_polygon

Format

An object of class sf (inherits from data.frame) with 1 rows and 2 columns.

Details

Created from shoreline shapefile (see 'data-raw/data-great_lakes_polygon.r).

Author(s)

Todd Hayden (coerced to sf via by C. Holbrook)

Examples

## Not run: 
plot(sf::st_geometry(great_lakes_polygon))

## End(Not run)

Deprecated A SpatialPolygonDataFrame with Great Lakes coastline and some major tributaries.

Description

A SpatialPolygonDataFrame with Great Lakes coastline and some major tributaries. This is used as a default map background in several glatos functions.

Usage

greatLakesPoly

Format

An object of class SpatialPolygonsDataFrame with 4 rows and 8 columns.

Details

This dataset is deprecated and will be removed in a future version. Use great_lakes_polygon instead.

Author(s)

Todd Hayden

Description

A TransitionLayer object that only allows transitions to occur within water (i.e., prohibits movement onto land).

Usage

greatLakesTrLayer

Format

An object of class TransitionLayer of dimension 667 x 667 x 1.

Details

This dataset was developed for non-linear interpolation of fish movement paths from telemetry data and is used by default in interpolate_path.

Created from great_lakes_polygon; see 'data-raw/data-greatLakesTrLayer.r'.

Author(s)

Todd Hayden (rebuilt by C. Holbrook)

See Also

interpolate_path, gdistance

Examples

## Not run: 
raster::plot(raster::raster(greatLakesTrLayer))

## End(Not run)

Description

An sf POLYGON object with coastline of Higgins Lake, Michigan. Used as an example of a polygon representing a water body.

Usage

higgins_lake_polygon

Format

An object of class sf (inherits from data.frame) with 1 rows and 2 columns.

Author(s)

Chris Holbrook

Description

A transition object, created from higgins_lake_polygon() for testing make_transition().

Format

A list comprised of a TransitionLayer and RasterLayer (see make_transition()).

Filename

higgins_lake_transition.rds

Author(s)

Chris Holbrook

Examples

system.file("testdata", "higgins_lake_transition.rds", package = "glatos")

Description

Interpolate new positions within a spatiotemporal path data set (e.g., detections of tagged fish) at regularly-spaced time intervals using linear or non-linear interpolation.

Usage

interpolate_path(
  det,
  trans = NULL,
  start_time = NULL,
  int_time_stamp = 86400,
  lnl_thresh = 0.9,
  out_class = NULL,
  show_progress = TRUE
)

Arguments

Details

Non-linear interpolation uses the gdistance package to find the shortest pathway between two locations (i.e., receivers) that avoid 'impossible' movements (e.g., over land for fish). The shortest non-linear path between two locations is calculated using a transition matrix layer that represents the 'cost' of an animal moving between adjacent grid cells. The transition matrix layer (see gdistance) is created from a polygon shapefile using make_transition or from a RasterLayer object using transition. In make_transition, each cell in the output transition layer is coded as water (1) or land (0) to represent possible (1) and impossible (0) movement paths.

Linear interpolation is used for all points when trans is not supplied. When trans is supplied, then interpolation method is determined for each pair of sequential observed detections. For example, linear interpolation will be used if the two geographical positions are exactly the same and when the ratio (linear distance:non-linear distance) between two positions is less than lnl_thresh. Non-linear interpolation will be used when ratio is greater than lnl_thresh. When the ratio of linear distance to non-linear distance is greater than lnl_thresh, then the distance of the non-linear path needed to avoid land is greater than the linear path that crosses land. lnl_thresh can be used to control whether non-linear or linear interpolation is used for all points. For example, non-linear interpolation will be used for all points when lnl_thresh > 1 and linear interpolation will be used for all points when lnl_thresh = 0.

All linear interpolation is done by stats::approx() with argument ties = "ordered" controlling how tied x values are handled. See stats::approxfun().

Value

A dataframe with animal_id, bin_timestamp, latitude, longitude, and record_type.

Author(s)

Todd Hayden, Tom Binder, Chris Holbrook

Examples

#--------------------------------------------------
# EXAMPLE #1 - simple interpolate among lakes

# get polygon of the Great Lakes
data(great_lakes_polygon) # glatos example data
plot(sf::st_geometry(great_lakes_polygon), xlim = c(-92, -76))

# make sample detections data frame
pos <- data.frame(
  animal_id = 1,
  deploy_long = c(-87, -82.5, -78),
  deploy_lat = c(44, 44.5, 43.5),
  detection_timestamp_utc = as.POSIXct(c(
    "2000-01-01 00:00",
    "2000-02-01 00:00", "2000-03-01 00:00"
  ), tz = "UTC")
)

# add to plot
points(deploy_lat ~ deploy_long, data = pos, pch = 20, cex = 2, col = "red")

# interpolate path using linear method
path1 <- interpolate_path(pos)
nrow(path1) # now 61 points
sum(path1$record_type == "interpolated") # 58 interpolated points

# add linear path to plot
points(latitude ~ longitude, data = path1, pch = 20, cex = 0.8, col = "blue")

# load a transition matrix of Great Lakes
# NOTE: This is a LOW RESOLUTION TransitionLayer suitable only for
#       coarse/large scale interpolation only. Most realistic uses
#       will need to create a TransitionLayer; see ?make_transition.
data(greatLakesTrLayer) # glatos example data; a TransitionLayer

# interpolate path using non-linear method (requires 'trans')
path2 <- interpolate_path(pos, trans = greatLakesTrLayer)

# add non-linear path to plot
points(latitude ~ longitude,
  data = path2, pch = 20, cex = 1,
  col = "green"
)

# can also force linear-interpolation with lnlThresh = 0
path3 <- interpolate_path(pos, trans = greatLakesTrLayer, lnl_thresh = 0)

# add new linear path to plot
points(latitude ~ longitude,
  data = path3, pch = 20, cex = 1,
  col = "magenta"
)

#--------------------------------------------------
# EXAMPLE #2 - walleye in western Lake Erie
## Not run: 


# get example walleye detection data
det_file <- system.file("extdata", "walleye_detections.csv",
  package = "glatos"
)
det <- read_glatos_detections(det_file)

# take a look
head(det)

# extract one fish and subset date
det <- det[det$animal_id == 22 &
  det$detection_timestamp_utc > as.POSIXct("2012-04-08") &
  det$detection_timestamp_utc < as.POSIXct("2013-04-15"), ]

# get polygon of the Great Lakes
data(great_lakes_polygon) # glatos example data; an sf object

# convert polygon to terra::spatVector
great_lakes_polygon <- terra::vect(great_lakes_polygon)

# crop polygon to western Lake Erie
maumee <- terra::crop(great_lakes_polygon,
  y = terra::ext(-83.7, -82.5, 41.3, 42.4)
)


plot(maumee, col = "grey")
points(deploy_lat ~ deploy_long,
  data = det, pch = 20, col = "red",
  xlim = c(-83.7, -80)
)


# make transition layer object
tran <- make_transition(sf::st_as_sf(maumee), res = c(0.1, 0.1))

# plot to check output
plot(tran$rast, xlim = c(-83.7, -82.0), ylim = c(41.3, 42.7))
plot(maumee, add = TRUE)

# not high enough resolution- bump up resolution, will take some time
tran1 <- make_transition(sf::st_as_sf(maumee), res = c(0.001, 0.001))

# plot to check resolution- much better
plot(tran1$rast, xlim = c(-83.7, -82.0), ylim = c(41.3, 42.7))
plot(maumee, add = TRUE)


# add fish detections to make sure they are "on the map"
# plot unique values only for simplicity
foo <- unique(det[, c("deploy_lat", "deploy_long")])
points(foo$deploy_long, foo$deploy_lat, pch = 20, col = "red")

# call with "transition matrix" (non-linear interpolation), other options
# note that it is quite a bit slower than linear interpolation
pos2 <- interpolate_path(det,
  trans = tran1$transition,
  out_class = "data.table"
)

plot(maumee, col = "grey")
points(latitude ~ longitude, data = pos2, pch = 20, col = "red", cex = 0.5)

## End(Not run)

Description

For each event (row in detection events data frame), the function sequences from first_detection to last_detection by time_interval_size, then counts the number of unique intervals.

Usage

interval_count(detections, time_interval_size)

Arguments

Description

An 'all-touched-capable' rasterizer that depends only on sf and raster.

Usage

jarasterize(
  x,
  res,
  value = 1,
  bg_value = 0,
  all_touched = TRUE,
  silent = FALSE
)

Arguments

Value

A raster::rasterLayer object.

Examples

# Example 1. lon lat WGS input

poly1 <- great_lakes_polygon

plot(sf::st_geometry(poly1))

rast1 <- jarasterize(poly1, res = c(0.1, 0.05))

## Not run: 
# compare to polygon
x11(width = 12, height = 8)
raster::plot(rast1)
plot(sf::st_geometry(poly1), add = TRUE)

## End(Not run)

# Example 2. projected input; 5 km cell size

poly2 <- sf::st_transform(poly1, crs = 3175)

rast2 <- jarasterize(poly2, res = 5000)

## Not run: 
# compare to polygon
x11(width = 12, height = 8)
raster::plot(rast2)
plot(sf::st_geometry(poly2), add = TRUE)

## End(Not run)

# Example 3. projected input; 5 km cell size; all_touched = FALSE

rast3 <- jarasterize(poly2, res = 5000, all_touched = FALSE)

## Not run: 
# compare to polygon
x11(width = 12, height = 8)
raster::plot(rast3)
plot(sf::st_geometry(poly2), add = TRUE)

## End(Not run)

Description

Function for extracting features (points, lines, polygons) from kml files and writing them to csv files.

Usage

kml_to_csv(filePath, type = c("points", "lines", "polygons"))

Arguments

Details

kmz files are not supported. Make sure exports from Google earth are saved as kml. Or extract (unzip) kml from kmz.

Value

A csv file (same name as input filePath but with csv extension) is written to directory containing input filePath with five columns

name

Feature name

feature_type

Feature type

seq

Sequential position in feature

longitude

Longitude

latitude

Latitude

altitude

Altitude

Examples

# Get example kml with two polygons
kml_file <- system.file("extdata", "example_polygons.kml",
  package = "glatos"
)

kml_to_csv(kml_file)

Description

Convert standard GLATOS receiver location and animal release data to a KML (or optionally KMZ) file (e.g., for viewing in Google Earth). (NOTE: EARLY DEVELOPMENT VERSION).

Usage

kml_workbook(
  wb = NULL,
  wb_file = NULL,
  receiver_locs = NULL,
  animals = NULL,
  kmz = FALSE,
  show_ongoing_recs = TRUE,
  end_date = NULL,
  out_file = NULL,
  wb_version = NULL,
  ...
)

Arguments

Details

Receiver locations will be visible between deployment and recovery timestamps at each location. Release locations will be displayed when the display window includes the date of release.

Value

A KML (and optionally, KMZ) file, written to the directory that contains the input GLATOS workbook, or out_file otherwise. Path to output file is returned.

Author(s)

C. Holbrook [email protected]

Examples

## Not run: 
# get path to example GLATOS Data Workbook
wb_file <- system.file("extdata",
  "walleye_workbook.xlsm",
  package = "glatos"
)

# read workbook directly
kml_workbook(wb_file = wb_file)

# now with bigger label and point and out_file
kml_workbook(
  wb_file = wb_file, labelSize = 20, iconSize = 1,
  out_file = "bigger.kml"
)

# read workbook directly; output kmz
kml_workbook(wb_file = wb_file, kmz = TRUE)

# get path to example GLATOS Data Workbook
wb <- read_glatos_workbook(wb_file)
kml_workbook(wb = wb, kmz = TRUE, out_file = "bigger.kmz")

## End(Not run)

Description

Sea Lamprey positions from a positional acoustic telemetry array in Lake George, North Channel of the St. Marys River during the 2012 spawning year.

Usage

lamprey_tracks

Format

A data frame with 21043 rows and 14 variables:

DETECTEDID

transmitter identifier (channel, frequency, code space, and ID code)

DATETIME

position timestamp, in UTC

X,Y

horizontal and vertical position on local grid, in meters

D

assumed depth at time of detection, in meters (NOT from depth/pressure sensor)

LAT,LON

position latitude and longitude, decimal degrees (west is negative); CRS: WGS84

n

?

HPE

horizontal position error; calculated by VEMCO

HPEm

horizontal position error, in meters; calculated by VEMCO

TEMP

temperature at time of detection (from temperature sensor)

DEPTH

depth at time of detection (from pressure sensor)

ACCEL

acceleration at time of detection (from accelerometer)

DRX

receivers that detected the associated transmission

Details

Data were collected as part of the GLATOS project SMRSL http://glatos.glos.us/home/project/SMRSL

Positions were calculated using the Vemco Positioning System.

Source

Chris Holbrook, US Geological Survey ([email protected])

Description

Create a set of frames (png image files) showing geographic location data (e.g., detections of tagged fish or interpolated path data) at discrete points in time on top of a Great Lakes shapefile and optionally stitches frames into a video animation (mp4 file).

Usage

make_frames(
  proc_obj,
  recs = NULL,
  out_dir = getwd(),
  background_ylim = c(41.3, 49),
  background_xlim = c(-92.45, -75.87),
  show_interpolated = TRUE,
  tail_dur = 0,
  animate = TRUE,
  ani_name = "animation.mp4",
  frame_delete = FALSE,
  overwrite = FALSE,
  preview = FALSE,
  bg_map = NULL,
  show_progress = TRUE,
  ...
)

Arguments

Details

To customize fish location points (from proc_obj): Add any argument that can be passed to points. The following values will create the default plot:

• cex: symbol size; default = 2

• col: symbol color; default = "blue"

• pch: symbol type; default = 16

To customize receiver location points (from recs): Add prefix recs. to any argument that can be passed to points. The following values will create the default plot:

• recs.cex: symbol size; default = 1.5

• recs.pch: symbol type; default = 16

To customize timeline: Add add prefix timeline. to any argument of axis. Note all elements of the timeline except the sliding symbol (see 'slider' below) are created by a call to axis. The following values will create the default plot:

• timeline.at: a sequence with locations of labels (with first and last being start and end) along x-axis; in units of longitude; by default this will center the timeline with five equally-spaced labels in the middle 80% of background_xlim.

• timeline.pos: location along the y-axis; in units of latitude; by default this will place the timeline up from the bottom 6% of the range of background_ylim

• timeline.labels: text used for labels; default = format(labels, "\%Y-\%m-\%d"), where labels are values of proc_obj$bin_timestamp

• timeline.col: color of line; default = "grey70"

• timeline.lwd: width of line; default = 20 times the aspect ratio of the plot device

• timeline.cex.axis: size of labels; default = 2

To customize time slider (symbol that slides): Add prefix timeline. to any argument that can be passed to points. The following values will create the default plot:

• timeslider.bg: a single value with symbol bg color; default = "grey40"

• timeslider.cex: a single value with symbol size; default = 2

• timeslider.col: a single value with symbol type; default = "grey20"

• timeslider.pch: a single value with symbol type; default = 21

To customize parameters controlled by par: Add prefix par. to any argument that can be passed to par. Note that par.mar controls whitespace behind default timeslider. The following values will create the default plot:

• par.oma: plot outer margins; default = c(0,0,0,0)

• par.mar: plot inner margins; default = c(6,0,0,0)

If animate = TRUE then the animation output file name (ani_name argument) will be passed to the output argument in make_video(). Default values for all other make_video() arguments will be used. Note that the default frame rate is 24 frames per second (framerate argument in make_video()), which will determine the total length (duration) of the output video. For example, a video containing 240 images (frames) will run for 10 seconds at these default parameters. Note that output video duration, dimensions (size), and other ouput video characteristics can be modified by calling make_video() directly. To do this, set animate = FALSE and then use make_video() to create a video from the resulting set of images.

Value

Sequentially-numbered png files (one for each frame) and one mp4 file will be written to out_dir.

Note

Customizing plot elements with input argument ... The option to allow customization of plot elements with input argument ... provides a great deal of flexibility, but users will need to be familiar with each associated graphics functions (e.g., axis for timeline arguments). We expect that this will require some trial and error and that input argument preview = TRUE will be useful while exploring optional plot arguments.

Author(s)

Todd Hayden, Tom Binder, Chris Holbrook

Examples

## Not run: 

# load detection data
det_file <- system.file("extdata", "walleye_detections.csv",
  package = "glatos"
)
dtc <- read_glatos_detections(det_file)

# take a look
head(dtc)

# load receiver location data
rec_file <- system.file("extdata",
  "sample_receivers.csv",
  package = "glatos"
)
recs <- read_glatos_receivers(rec_file)

# call with defaults; linear interpolation
pos1 <- interpolate_path(dtc)

# make frames, preview the first frame
myDir <- paste0(getwd(), "/frames1")
make_frames(pos1, recs = recs, out_dir = myDir, preview = TRUE)

# make frames but not animation
myDir <- paste0(getwd(), "/frames2")
make_frames(pos1, recs = recs, out_dir = myDir, animate = FALSE)

# make sequential frames, and animate.  Make animation and frames.
# change default color of fish markers to red and change marker and size.

myDir <- paste0(getwd(), "/frames3")
make_frames(pos1,
  recs = recs, out_dir = myDir, animate = TRUE,
  ani_name = "animation3.mp4", col = "red", pch = 16, cex = 3
)

# make sequential frames, animate, add 5-day tail
myDir <- paste0(getwd(), "/frames4")
make_frames(pos1,
  recs = recs, out_dir = myDir, animate = TRUE,
  ani_name = "animation4.mp4", tail_dur = 5
)

# make animation, remove frames.
myDir <- paste0(getwd(), "/frames5")
make_frames(pos1,
  recs = recs, out_dir = myDir, animate = TRUE,
  ani_name = "animation5.mp4", frame_delete = TRUE
)

## End(Not run)

Description

Create transition layer for interpolate_path() spatial object.

Usage

make_transition(poly, res, receiver_points = NULL, epsg = 3175, buffer = NULL)

Arguments

Details

make_transition uses jarasterize() to convert a polygon shapefile into a raster layer and geo-corrected transition layer interpolate_path(). Raster cell values on land equal 0, cells in water equal 1. Output is a two-object list containing the raster layer and transition layer.

If receiver_points is provided, any receiver not in water is buffered by the distance from the receiver to the nearest water. This allows all receivers to be coded as in water if the receiver is on land.

Poly object is transformed into planer map projection specified by epsg argument for calculation of transition object if receiver_points is provided. Output is projected to crs of input poly.

output transition layer is corrected for projection distortions using gdistance::geoCorrection. Adjacent cells are connected by 16 directions and transition function returns 0 (land) for movements between land and water and >0 for all over-water movements.

Note that this function underwent breaking changes between 0.7.3 and 0.8.0 (uses jasterize instead of gdalUtilities::gdal_rasterize see NEWS).

Value

A list with two elements:

transition

a geo-corrected transition raster layer where land = 0 and water = 1 (see gdistance::Transition)

rast

rasterized input layer of class raster

Author(s)

Todd Hayden, Chris Holbrook

Examples

# Example 1 - read from sf polygon object
# use example polygon for Great lakes

# calculate resolution in degrees (from meters)
#  note this applies to cell at center, cell sizes will vary
res <- scale_meters_to_degrees(5000, sf = great_lakes_polygon)

# make_transition layer
tst <- make_transition(great_lakes_polygon, res = res)

## Not run: 
# plot raster layer (notice water = 1, land = 0)
raster::plot(tst$rast)

# compare to polygon
plot(sf::st_geometry(great_lakes_polygon), add = TRUE)

## End(Not run)

# Example 2 - add 1 km buffer (same resolution)

# make_transition layer
tst2 <- make_transition(great_lakes_polygon,
  res = res,
  buffer = 3000
)

## Not run: 
# plot raster layer (notice water = 1, land = 0)
raster::plot(tst2$rast)

# compare to polygon
plot(sf::st_geometry(great_lakes_polygon), add = TRUE)

## End(Not run)

# Example 3 - read from ESRI Shapefile and include receiver file
# to account for any receivers outside of great lakes polygon

# path to polygon shapefile
poly <- system.file("extdata", "shoreline.zip", package = "glatos")
poly <- sf::st_read(paste0("/vsizip/", poly))

# read in glatos receivers object
rec_file <- system.file("extdata", "sample_receivers.csv",
  package = "glatos"
)
recs <- read_glatos_receivers(rec_file)

# change a coordinate to on-land to show impact...
recs[1, "deploy_lat"] <- recs[1, "deploy_lat"] + 4

# make_transition layer (roughly 500 m res)
tst <- make_transition(poly, res = c(0.065, 0.046), receiver_points = recs)

## Not run: 
# plot raster layer
# notice the huge circle rasterized as "water"  north of Lake Superior.
# This occurred because we had a "receiver" deployed at that locations
raster::plot(tst$rast)
points(recs$deploy_long, recs$deploy_lat, col = "red", pch = 20)

# plot transition layer
raster::plot(raster::raster(tst$transition))

## End(Not run)

# Example 4- transition layer of Lake Huron only with receivers

# transform to great lakes projection
poly <- sf::st_transform(great_lakes_polygon, crs = 3175)

# set attribute-geometry relationship to constant.
# this avoids error when cropping
sf::st_agr(poly) <- "constant"

# crop Great lakes polygon file
poly <- sf::st_crop(
  x = poly, xmin = 829242.55, ymin = 698928.27,
  xmax = 1270000.97, ymax = 1097196.15
)

# read in glatos receivers object
rec_file <- system.file("extdata", "sample_receivers.csv",
  package = "glatos"
)
recs <- read_glatos_receivers(rec_file)

# extract receivers in "HECWL" project
# all receiver stations except one is in Lake Huron
recs <- recs[recs$glatos_project == "HECWL", ]

# remove two stations not in Lake Huron
recs <- recs[!recs$glatos_array %in% c("MAU", "LVD"), ]

# convert recs to simple feature  object (sf)
recs <- sf::st_as_sf(recs,
  coords = c("deploy_long", "deploy_lat"),
  crs = 4326
)

# transform receivers to same projection as great lakes polygon
recs <- sf::st_transform(recs, crs = 3175)

## Not run: 
# check by plotting
plot(sf::st_geometry(poly), col = NA)
plot(sf::st_geometry(recs), col = "red", add = TRUE)

## End(Not run)

# create slightly higher resolution transition layer
#   (note that res in in meters here because crs is 3175)
tst1 <- make_transition(poly, res = 5000, receiver_points = recs)

## Not run: 
# plot raster layer
raster::plot(tst1$rast)

plot(sf::st_geometry(recs),
  add = TRUE, col = "red", pch = 20
)

# plot transition layer
raster::plot(raster::raster(tst1$transition))

## End(Not run)

Description

Stitch a sequence of images into a video animation. A simple wrapper for av::av_encode_video.

Usage

make_video(
  input_dir = getwd(),
  input_ext = ".png",
  output = "animation.mp4",
  duration = NULL,
  start_frame = 1,
  end_frame = NULL,
  size = NULL,
  overwrite = FALSE,
  verbose = FALSE,
  ...
)

Arguments

Details

This function was overhauled in glatos v 0.4.1 to simplify inputs and to no longer require an external program (ffmpeg.exe). As a result input arguments have changed, as described above. Starting with glatos v 0.7.0, any calls to make_video using the arguments from glatos v 0.4.0 or earlier will fail.

make_video is a simple wrapper of av::av_encode_video. It is intended to allow creation of videos from images (frames) created by glatos::make_frames as simple as possible. More advanced features of av, can be used by including any argument of av::av_encode_video in the call to make_video, or by calling av::av_encode_video directly. More information about the av package is available at https://cran.r-project.org/web/packages/av/index.html and https://docs.ropensci.org/av/.

A directory of sequenced image files (.png, .jpeg) are passed to input_dir argument. The input_ext argument specifies the type of files to be stitched into a video. The images passed to the function must all have the same size, height, and format.

Function can create .mp4, .mov, .mkv, .flv .wmv, or .mpeg animations. Format of created animation is determined by file extension of output.

If start_frame or end_frame are specified, then only frames within the specified range will be included in the output video.

If duration is specified, then the output framerate will be determined by the number of input frames and the framerate (default is 24 frames per second). E.g., a video of 10 second duration containing 240 frames will have an output frame rate of 24 fps. In some cases (when number of frames is small) the number of frames may not divide evently into the specified duration, so the output duration may differ from that specified. If the output frame rate exceeds 30 fps, then a warning will alert the user that some individual frame content may not be visible to users. Video duration may also be controlled by setting the framerate argument of av::av_encode_video. See ... above.

Value

One video animation will be written disk and the path and file name will be returned.

Author(s)

Todd Hayden, Chris Holbrook

Examples

## Not run: 

# load frames
frames <- system.file("extdata", "frames", package = "glatos")

# make .mp4 video
make_video(
  input_dir = frames,
  input_ext = ".png",
  output = file.path(tempdir(), "animation1.mp4")
)

# set duration to 10 seconds
make_video(
  input_dir = frames,
  input_ext = ".png",
  output = file.path(tempdir(), "animation2.mp4"),
  duration = 10
)

# set size of ouput video
make_video(
  input_dir = frames,
  input_ext = ".png",
  output = file.path(tempdir(), "animation3.mp4"),
  size = c(320, 240)
)

# start animation on frame 10, end on frame 20
make_video(
  input_dir = frames,
  input_ext = ".png",
  output = file.path(tempdir(), "animation_4.mp4"),
  start_frame = 10,
  end_frame = 20
)

# make move backwards- start animation of frame 20 and end on frame 10
make_video(
  input_dir = frames,
  input_ext = ".png",
  output = file.path(tempdir(), "animation_5.mp4"),
  start_frame = 20,
  end_frame = 10
)

# make .wmv video
make_video(
  input_dir = frames,
  input_ext = ".png",
  output = file.path(tempdir(), "animation1.wmv")
)


#--- Examples using more advanced features of av_encode_video

# resize output video by specifying a scale filter
make_video(
  input_dir = frames,
  input_ext = ".png",
  output = file.path(tempdir(), "animation_6.mp4"),
  vfilter = "scale=320:240"
)

# slow the video by 10 times
make_video(
  input_dir = frames,
  input_ext = ".png",
  output = file.path(tempdir(), "animation_7.mp4"),
  vfilter = "setpts=10*PTS"
)

# slow video by 10 times and scale to 320x240 resolution
make_video(
  input_dir = frames,
  input_ext = ".png",
  output = file.path(tempdir(), "animation_8.mp4"),
  vfilter = "scale=320:240, setpts=10*PTS"
)

## End(Not run)

Description

Calculate minimum time interval (min_lag) between successive detections and add to detection data set for identifying potential false detections.

Usage

min_lag(det)

Arguments

Details

min_lag is loosely based on the the "short interval" described by Pincock (2012) and replicates the min_lag column in the standard glatos detection export file. In this case (GLATOS), min_lag is defined for each detection as the shortest interval (in seconds) between either the previous or next detection (whichever is closest) of the same transmitter code (defined here as combination of transmitter_codespace and transmitter_id) on the same receiver.

A new column (min_lag) is added to the input dataframe that represents the time (in seconds) between the current detection and the next detection (either before or after) of the same transmitter on the same receiver. This function replicates the 'min_lag' column included in the standard glatos export.

Value

A column min_lag (defined above) is added to input object.

Author(s)

Chris Holbrook, Todd Hayden, Angela Dini

References

Pincock, D.G., 2012. False detections: what they are and how to remove them from detection data. Vemco Division, Amirix Systems Inc., Halifax, Nova Scotia.
http://www.vemco.com/pdf/false_detections.pdf

See Also

false_detections()

Examples

# load example detection file
det_file <- system.file("extdata", "walleye_detections.csv",
  package = "glatos"
)
det <- read_glatos_detections(det_file)

# rename existing min_lag column
colnames(det)[colnames(det) == "min_lag"] <- "min_lag.x"

# calculate min_lag
det <- min_lag(det)

head(det)

Description

An example animal data file from the OTN ERDDAP

Format

CSV

Filename

otn_aat_animals.csv

Source

Ryan Gosse, Ocean Tracking Network

Examples

system.file("extdata", "otn_aat_animals.csv", package = "glatos")

Description

An example receiver station data file from the OTN ERDDAP

Format

CSV

Filename

otn_aat_receivers.csv

Source

Ryan Gosse, Ocean Tracking Network

Examples

system.file("extdata", "otn_aat_receivers.csv", package = "glatos")

Description

An example tag release data file from the OTN ERDDAP

Format

CSV

Filename

otn_aat_tag_releases.csv

Source

Ryan Gosse, Ocean Tracking Network

Examples

system.file("extdata", "otn_aat_tag_releases.csv", package = "glatos")

Description

Calculates latitude and longitude for new point that is x meters away at bearing y from a geographic location (Longitude, Latitude) using great circle distances.

Usage

point_offset(
  lon = NA,
  lat = NA,
  offsetDist = NA,
  offsetDir = NA,
  distUnit = "m"
)

Arguments

Examples

lat <- rep(44.0, 17)
lon <- rep(-83.0, 17)

offsetDir <- c(
  NA, "N", "NNE", "NE", "ENE", "E", "ESE", "SE", "SSE", "S",
  "SSW", "SW", "WSW", "W", "WNW", "NW", "NNW"
)

offsetDist <- seq(100, 1700, by = 100)
distUnit <- "m"

point_offset(lon, lat, offsetDist, offsetDir, distUnit)

Description

Create heat maps to display the spatial distribution of acoustic telemetry positions. Most useful when used on data with high spatial resultion, such as VPS positional telemetry data.

Usage

position_heat_map(
  positions,
  projection = "LL",
  fish_pos_int = "fish",
  abs_or_rel = "absolute",
  resolution = 10,
  interval = NULL,
  x_limits = NULL,
  y_limits = NULL,
  utm_zone = NULL,
  hemisphere = "N",
  legend_gradient = "y",
  legend_pos = c(0.99, 0.2, 1, 0.8),
  output = "plot",
  folder = "position_heat_map",
  out_file = NULL
)

Arguments

Details

When an 'interval' argument is supplied, the number of unique fish x interval combinations that occurred in each grid cell is calculated instead of raw number of positions. For example, in 4 hours there are a total of 4 1-h intervals. If fish 'A' was positioned in a single grid cell during 3 of the 4 intervals, than the number of intervals for that fish and grid combination is 3. Intervals are determined by applying the findInterval function (base R) to a sequence of timestamps (class: POSIXct) created using seq(from = min(positions[, DATETIME]), to = min(positions[, DATETIME]), by = interval), where interval is the user-assigned interval duration in seconds. Number of intervals is a more robust surrogate than number of positions for relative time spent in each grid in cases where spatial or temporal variability in positioning probability are likely to significantly bias the distribution of positions in the array.

Calculated values (i.e., fish, positions, intervals) can be returned as absolute or relative, which is specified using the abs_or_rel argument; "absolute" is the actual value, "relative" is the absolute value divided by the total number of fish appearing in the 'positions' dataframe. Units for plots: fish = number of unique fish (absolute) or \ 'positions' dataframe (relative); positions = number of positions (absolute) or mean number of positions per fish in 'positions' dataframe (relative); intervals = number of unique fish x interval combinations (absolute) or mean number of unique fish x interval combinations per fish in 'positions' dataframe (relative).

Value

A list object containing 1) a matrix of the calculated values (i.e., fish, positions, intervals), with row and column names indicating location of each grid in UTM, 2) a character string specifying the UTM zone of the data in the matrix, 3) the bounding box of the data in UTM, 4) and the bounding box of the data in latitude (Y) and longitude (X), 5) a character string displaying the function call (i.e., a record of the arguments passed to the function).

In addition, the user specifies an image output for displaying the heat map. Options are a "plot" (displayed in R), "png" (png file saved to specified folder), and "kmz" for viewing the png image as an overlay in Google Earth (kmz file saved to specified folder).

Author(s)

Thomas R. Binder

Examples

data(lamprey_tracks)
phm <- position_heat_map(lamprey_tracks)

Description

Loads the OTN receiver deployment metadata sheet to prepare it for use in convert_otn_to_att

Usage

prepare_deploy_sheet(
  path,
  header_line = 5,
  sheet_name = 1,
  combine_arr_stn = TRUE
)

Arguments

Details

The function takes the path to the deployment sheet, what line to start reading from, and what sheet in the excel file to use. It converts column names to be used by convert_otn_to_att.

Value

a data.frame created from the excel file.

Author(s)

Ryan Gosse

Examples

#--------------------------------------------------
# EXAMPLE #1 - loading from NSBS simplified Deployments

library(glatos)
deploy_path <- system.file("extdata", "hfx_deploy_simplified.xlsx",
  package = "glatos"
)

deploy <- prepare_deploy_sheet(deploy_path,
  header_line = 1,
  sheet_name = 1
)

Description

Loads the OTN tagging metadata sheet to prepare it for use in convert_otn_to_att

Usage

prepare_tag_sheet(path, header_line = 5, sheet_name = 2)