Package 'glatos'

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),
  b
  
#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 if track crosses polygon boundary

Usage

check_cross_boundary(path, boundary, EPSG)

Description

Check if in polygon

Usage

check_in_polygon(points, polygon, EPSG)

Description

Convert glatos_detections and glatos_receiver objects to ATT for compatibility with the Animal Tracking Toolbox (https://github.com/vinayudyawer/ATT).

Usage

convert_glatos_to_att(
  detectionObj,
  receiverObj,
  crs = sp::CRS("+init=epsg:4326")
)

Arguments

Details

This function takes 2 lists containing detection and reciever data and transforms them into one list containing 3 tibble::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://gitlab.oceantrack.org/GreatLakes/glatos/issues/83 in a comment by Ryan Gosse.

Value

a list of 3 tibble::tibbles containing tag dectections, 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).

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::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 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 tibble::tibbles containing tag dectections, 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(blue_shark_detections,
                                     tags, stations, 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).

Usage

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

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::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 in a comment by Ryan Gosse.

Value

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

Author(s)

Ryan Gosse

Examples

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

#--------------------------------------------------
# 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 = sp::bbox(sf::st_coordinates(sf::st_as_sf(path_sp)))[1,], 
  ylim = sp::bbox(sf::st_coordinates(sf::st_as_sf(path_sp)))[2,])
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 (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

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.

Usage

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

Format

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

Filename

flynn_island_transition.rds

Author(s)

Chris Holbrook

Description

Wrapper method for the calulation methods above.

Usage

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

Arguments

Description

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

This package is in early development and its content is evolving. To access the package or contribute code, join the project at (https://github.com/ocean-tracking-network/glatos). If you encounter problems or have questions or suggestions, please post a new issue or email [email protected] (maintainer: Chris Holbrook).

Installation

Installation instructions can be found at https://github.com/ocean-tracking-network/glatos/wiki/installation-instructions.

Data loading and processing

read_glatos_detections and read_otn_detections

Fast data loading from standard GLATOS and OTN data files to a single structure that is compatible with other glatos functions.

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.

read_glatos_workbook

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

read_vemco_tag_specs

Reads transmitter (tag) specifications and operating schedule.

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

Filtering and summarizing

min_lag

Facilitates identification and removal of false positive detections by calculating the minimum time interval (min\_lag) between successive detections.

false_detections

Removes potential false positive detections using "short interval" criteria (see min_lag).

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.

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.

residence_index

calculates the relative proportion of time spent at each location.

REI

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

Visualization and data exploration

abacus_plot

Useful for exploring movement patterns of individual tagged animals through time.

detection_bubble_plot

Useful for exploring distribution of tagged individuals among receivers.

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 using FFmpeg software.

adjust_playback_time

Modify playback speed of videos and optionally convert between video file formats. Requires FFmpeg.

Simulation functions for system design and evaluation

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

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

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.

Convert glatos data objects to other package classes

convert_glatos_to_att

Converts glatos_detections and glatos_receiver objects to ATT for compatibility with the Animal Tracking Toolbox(https://github.com/vinayudyawer/ATT) and the VTrack package.

convert_otn_erddap_to_att

Converts glatos_detections and transmitter, receiver, and animal metadata from the OTN ERDDAP to ATT format for compatibility with the Animal Tracking Toolbox(https://github.com/vinayudyawer/ATT) and the VTrack package.

Description

Constructor function for the class glatos_animals. Currently barebones and only used inside read_glatos_workbook.

Usage

glatos_animals(x)

Arguments

Value

A data.frame of class glatos_animals:

Note

This function may be developed in the future to dictate conversion constuction from a data frame.

Description

Constructor function for the class glatos_detections. Currently barebones and only used inside read_glatos_detections and read_otn_detections.

Usage

glatos_detections(x)

Arguments

Value

A data.frame of class glatos_detections:

Note

This function may be developed in the future to dictate conversion constuction from a data frame.

Description

Constructor function for the class glatos_receivers. Currently barebones and only used inside read_glatos_receivers.

Usage

glatos_receivers(x)

Arguments

Value

A data.frame of class glatos_receivers:

Note

This function may be developed in the future to dictate conversion constuction from a data frame.

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

Created from greatLakesPoly. This is used as a default map background in several glatos functions.

Usage

great_lakes_polygon

Format

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

Author(s)

Todd Hayden (coerced to sf by C. Holbrook)

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). This dataset was developed for non-linear interpolation of fish movement paths from telemetry data and is used by default in interpolate_path.

Usage

greatLakesTrLayer

Format

An object of class TransitionLayer of dimension 692 x 504 x 1.

Author(s)

Todd Hayden

See Also

interpolate_path, gdistance

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.

Usage

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

Format

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

Filename

higgins_lake_transition.rds

Author(s)

Chris Holbrook

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 codestats::approx with argument ties = "ordered" controlling how tied x values are handled. See 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_transition3(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_transition3(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

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("inst/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

Convert geographic positions to UTM

Usage

lonlat_to_utm(lonlat)

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

Deprecated Create transition layer from polygon shapefile

Description

Create transition layer for interpolate_path from polygon shapefile.

Usage

make_transition(
  in_file,
  output = "out.tif",
  output_dir = NULL,
  res = c(0.1, 0.1),
  invert = FALSE,
  all_touched = TRUE
)

Arguments

Details

make_transition uses gdal_rasterize to convert a polygon shapefile into a raster layer and geo-corrected transition layer interpolate_path. Raster cell values on land = 0 and water = 1. Function also writes a geotiff file (*.tif) of the input shapefile to the ouput directory. Both raster layer and geotif output have the same extents and geographic projection as input shapefile. Function requires that gdal is working on computer. To determine if gdal is installed on your computer, see gdal_rasterize.

Returned objects will be projected in longlat WGS84 (i.e., CRS("+init=epsg:4326"). If the input object is not recognizable in epsg:4326 then transformation will be attempted and a warning will tell the user this was done. Input shapefile must include an optional *.prj file that specifies the geographic projection.

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 1 for all over-water movements.

Value

A list with two elements:

transition

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

rast

rasterized input layer of class raster

Additonally, rasterized version of input shapefile (*.tif extension) is written to computer at output_dir

Note

This function has been deprecated and will be removed from the next version of glatos. Use make_transition3 instead.

Author(s)

Todd Hayden, Tom Binder, Chris Holbrook

Examples

## Not run: 

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

library(sf) #for loading great_lakes_polygon
library(raster) # for plotting rasters

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

# Make transition layer
tst <- make_transition(great_lakes_polygon, res = c(0.1, 0.1))

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

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


#Example 2 - read from SpatialPolygonsDataFrame
# use example polygon for Great lakes

library(raster) # for plotting rasters

#get polygon of the Great Lakes
data(greatLakesPoly) #glatos example data; a SpatialPolygonsDataFrame

# make_transition layer
tst <- make_transition(greatLakesPoly, res = c(0.1, 0.1))

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

#compare to polygon
plot(greatLakesPoly, add = TRUE)

# increase resolution and repeat if needed

#------------------------------------------
#Example 3 - read from ESRI Shapefile
# path to polygon shapefile
poly <- system.file("extdata", "shoreline.zip", package = "glatos")
poly <- unzip(poly, exdir = tempdir())

# make_transition layer
tst <- make_transition(poly[grepl("*.shp", poly)], res = c(0.1, 0.1))

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

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

# increase resolution- this may take some time...
tst1 <- make_transition(poly[grepl("*.shp", poly)], res = c(0.01, 0.01))

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

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

## End(Not run)

Deprecated Create transition layer from a spatial polygon

Description

Create transition layer for interpolate_path from SpatialPolygonsDataFrame.

Usage

make_transition2(
  poly,
  res = c(0.1, 0.1),
  extent_out = NULL,
  x_lim = NULL,
  y_lim = NULL
)

Arguments

Details

make_transition uses rasterize to convert a SpatialPolygonsDataFrame into a raster layer, and geo-corrected transition layer transition. Raster cell values on land = 0 and water = 1.

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

Value

A list with two elements:

transition

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

rast

rasterized input layer of class raster

Note

This function has been deprecated and will be removed from the next version of glatos. Use make_transition3 instead.

Author(s)

Todd Hayden, Tom Binder, Chris Holbrook

See Also

make_transition

Examples

library(raster) # for plotting rasters

# get polygon of the Great Lakes
data(greatLakesPoly) #glatos example data; a SpatialPolygonsDataFrame

# make_transition layer
tst <- make_transition2(greatLakesPoly, res = c(0.1, 0.1))

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

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

## Not run: 
# increase resolution- this may take some time...
tst1 <- make_transition2(greatLakesPoly, res = c(0.01, 0.01))

# plot raster layer
plot(tst1$rast)

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

## End(Not run)

Description

Create transition layer for interpolate_path from polygon shapefile.

Usage

make_transition3(poly, res = c(0.1, 0.1), receiver_points = NULL, epsg = 3175)

Arguments

Details

make_transition uses fasterize to convert a polygon shapefile into a raster layer and geo-corrected transition layer interpolate_path. Raster cell values on land equal 1 cells in water equal 0. Output is a two-object list containing the raster layer and transition layer. Both objects have the same extents and geographic projection as input shapefile.

@details 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 WGS84 (epsg- 4326).

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 1 for all over-water movements.

Value

A list with two elements:

transition

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

rast

rasterized input layer of class raster

Additonally, rasterized version of input shapefile (*.tif extension) is written to computer at output_dir

Author(s)

Todd Hayden, Tom Binder, Chris Holbrook

Examples

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

library(sp) #for loading greatLakesPoly
library(raster) # for plotting rasters

#get polygon of the Great Lakes
data(greatLakesPoly) #glatos example data; a SpatialPolygonsDataFrame

# make_transition layer
tst <- make_transition3(greatLakesPoly, res = c(0.1, 0.1))

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

#compare to polygon
plot(greatLakesPoly, add = TRUE)

#Example 2 - 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 <- unzip(poly, exdir = tempdir())
poly <- sf::st_read(poly[grepl("*.shp", 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
tst <- make_transition3(poly, res = c(0.1, 0.1), receiver_points = recs)

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

Example 3- transition layer of Lake Huron only with receivers

# read polygon shapefile
poly <- system.file("extdata", "shoreline.zip", package = "glatos")
poly <- unzip(poly, exdir = tempdir())
poly <- sf::st_read(poly[grepl("*.shp", poly)])


# transform to great lakes projection
poly <- sf::st_transform(poly, 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 to great lakes projection
recs <- sf::st_transform(recs, crs = 3175)

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

# create slightly higher resolution transition layer
tst1 <- make_transition3(poly, res = c(0.01, 0.01), receiver_points = recs)

# plot raster layer
raster::plot(tst1$rast)
 plot(sf::st_transform(sf::st_geometry(recs), crs = 4326), add = TRUE, col = "red", pch = 20)

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

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

Usage

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

Format

CSV

Filename

otn_aat_animals.csv

Source

Ryan Gosse, Ocean Tracking Network

Description

An example receiver station data file from the OTN ERDDAP

Usage

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

Format

CSV

Filename

otn_aat_receivers.csv

Source

Ryan Gosse, Ocean Tracking Network

Description

An example tag release data file from the OTN ERDDAP

Usage

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

Format

CSV

Filename

otn_aat_tag_releases.csv

Source

Ryan Gosse, Ocean Tracking Network

Description

Calculates latitude and longitude for new point that is x meters away at bearing y from a geographic location (Longitude, Latitude). uses "destPoint" function from "geosphere" package and calculations are based on 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)

Arguments

Details

The function takes the path to the tagging sheet, what line to start reading the headers 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 tagging

library(glatos)
tag_path <- system.file("extdata", "otn_nsbs_tag_metadata.xls",
                        package = "glatos")

tags <- prepare_tag_sheet(tag_path, 5, 2)

Description

Sample detection range data set from Lake Superior.

Usage

range_detection

Format

A data frame with 58309 rows and 30 variables

Details

Data from a stationary detection range test conducted in 2018. Data are in standard GLATOS detection export format and are intened to accompany detecton range analysis vignette.

Source

F. Zomer, T. Hayden

Description

A completed GLATOS workbook from St. Marys River Sea Lamprey project.

Usage

system.file("extdata", "SMRSL_GLATOS_20140828.xlsm", package="glatos")

Format

A macro-enabled Microsoft Excel workbook file (*.xlsm) with six worksheets:

project

project code, principal investigator and contact

locations

descriptions of receiver array locations

proposed

proposed receiver deployment locations and dates

deployment

receiver deployment data (what, where, when, how)

recovery

receiver recovery data (what, where, when, how)

tagging

animal collection, tagging, and recovery data

Filename

SMRSL_GLATOS_20140828.xlsm

Author(s)

Chris Holbrook

Source

http://glatos.glos.us/home/project/SMRSL

Description

An example detection file

Usage

system.file("extdata", "walleye_detections.zip", package="glatos")

Format

A zipped walleye detection file in detection file format 1.3:

Filename

walleye_detections.zip

Author(s)

Todd Hayden

Source

http://glatos.glos.us/home/project/HECWL

Description

Read data from a standard GLATOS detection (csv) file and return a data.frame of class glatos_detections.

Usage

read_glatos_detections(det_file, version = NULL)

Arguments

Details

Data are loaded using fread and timestamps are coerced to POSIXct using fastPOSIXct. All times must be in UTC timezone per GLATOS standard.

Column animal_id is considered a required column by many other functions in this package, so it will be created if any records are NULL. When created, it will be constructed from transmitter_codespace and transmitter_id, separated by '-'.

Value

A data.frame of class glatos_detections.

Author(s)

C. Holbrook [email protected]

Examples

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

#note that code above is needed to find the example file
#for real glatos data, use something like below
#det_file <- "c:/path_to_file/HECWL_detectionsWithLocs_20150321_132242.csv"

det <- read_glatos_detections(det_file)

Description

Read data from a standard GLATOS receiver location (csv) file and return a data.frame of class glatos_receivers.

Usage

read_glatos_receivers(rec_file, version = NULL)

Arguments

Details

Data are loaded using fread and timestamps are coerced to POSIXct using fastPOSIXct. All timestamps must be 'YYYY-MM-DD HH:MM' format and in UTC timezone per GLATOS standard.

Value

A data.frame of class glatos_receivers.

Author(s)

C. Holbrook ([email protected])

Examples

#get path to example receiver_locations file
rec_file <- system.file("extdata", 
  "sample_receivers.csv", package = "glatos")
  
#note that code above is needed to find the example file
#for real glatos data, use something like below
#rec_file <- "c:/path_to_file/GLATOS_receiverLocations_20150321_132242.csv"   

rcv <- read_glatos_receivers(rec_file)

Description

Read data from a GLATOS project workbook (xlsm file) and return a list of class glatos_workbook.

Usage

read_glatos_workbook(wb_file, read_all = FALSE, wb_version = NULL)

Arguments

Details

In the standard glatos workbook (v1.3), data in workbook sheets 'Deployment', 'Recovery', and 'Location' are merged on columns 'GLATOS_PROJECT', 'GLATOS_ARRAY', 'STATION_NO', 'CONSECUTIVE_DEPLOY_NO', AND 'INS_SERIAL_NO' to produce the output data frame receivers. Data in workbook sheets 'Project' and 'Tagging' are passed through to new data frames named 'project' and 'animals', respectively, and data from workbook sheet 'Proposed' is not included in result. If read_all = TRUE then each sheet in workbook will be included in result.

Data are read from the input file using read_excel in the 'readxl' package. If read_all = TRUE then the type of data in each user-defined column (and sheet) will be 'guessed' by read_excel. Therefore, if read_all = TRUE then the structure of those columnns should be carefully reviewed in the result. See read_excel for details.

Column animal_id is considered a required column by many other functions in this package, so it will be created if any records are NULL. When created, it will be constructed from tag_code_space and tag_id_code, separated by '-'.

Timezone attribute of all timestamp columns (class POSIXct) in output will be "UTC" and all 'glatos-specific' timestamp and timezone columns will be omitted from result.

Value

A list of class glatos_workbook with three elements (described below) containing data from the standard GLATOS Workbook sheets. If read_all = TRUE, then additional elements will be added with names corresponding to non-standard sheet names.

metadata

A list with data about the project and workbook.

animals

A data frame of class glatos_animals with data about tagged animals.

receivers

A data frame of class glatos_receivers with data about telemetry receivers.

Note

On warnings and errors about date and timestamp formats. Date and time columns are sometimes stored as text in Excel. When those records are loaded by this function, there are two possible outcomes.

1. If the records are formatted according to the GLATOS Data Dictionary specification (e.g., "YYYY-MM-DD" for dates and "YYYY-MM-DD HH:MM" for timestamps; see https:\glatos.glos.us) those records should be properly loaded into R, but the user is encouraged to verify that they were loaded correctly, so a warning points the user to those records in the workbook. Users may want to format as custom date in the workbook to avoid warnings in the future.
   
   

2. If the format of a date-as-text column is not consistent with GLATOS specification, then no data will be loaded and an error will alert the user to this condition.
   
   On cells with locked formatting in Excel: Occasionally the format of a cell in Excel will be locked. In those cases, it is sometimes possible to force date formatting in Excel by (1) highlighting the columns that need reformatting, (2) select 'Text-to-columns' in the 'Data' menu, (3) select 'Delimited' and 'next', (4) uncheck all delimiters and 'next', (5) choose 'Date: YMD' in the 'Column data format' box, and (6) 'Finish'.

Author(s)

C. Holbrook [email protected]

See Also

read_excel

Examples

#get path to example GLATOS Data Workbook
wb_file <- system.file("extdata", 
  "walleye_workbook.xlsm", package = "glatos")
  
#note that code above is needed to find the example file
#for real glatos data, use something like below
#wb_file <- "c:/path_to_file/HECWL_GLATOS_20150321.csv"
  
wb <- read_glatos_workbook(wb_file)

Description

Read data from a standard OTN deployment (csv) file and return a data.frame of class glatos_receivers.

Usage

read_otn_deployments(
  deployment_file,
  deploy_date_col = "deploy_date",
  recovery_date_col = "recovery_date",
  last_download_col = "last_download"
)

Arguments

Details

Data are loaded using fread package and timestamps are coerced to POSIXct using the fastPOSIXct. All times must be in UTC timezone per GLATOS standard.

Column names are changed to match GLATOS standard columns when possible. Otherwise, OTN columns and column names are retained.

Value

A data.frame of class glatos_receivers that includes OTN columns that do not map directly to GLATOS columns.

Author(s)

A. Nunes, [email protected]

Examples

#get path to example deployments file
deployment_file <- system.file("extdata", "hfx_deployments.csv",
                         package = "glatos")
dep <- read_otn_deployments(deployment_file)

Description

Read data from a standard OTN detection (csv) file and return a data.frame of class glatos_detections.

Usage

read_otn_detections(det_file)

Arguments

Details

Data are loaded using fread package and timestamps are coerced to POSIXct using the fastPOSIXct. All times must be in UTC timezone per GLATOS standard.

Column names are changed to match GLATOS standard columns when possible. Otherwise, OTN columns and column names are retained.

Value

A data.frame of class glatos_detections that includes OTN columns that do not map directly to GLATOS columns.

Author(s)

A. Nunes, [email protected]

Examples

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

Description

Read telemetry transmitter (tag) specification data from a file and return a list with tag specifications and tag operating schedule.

Usage

read_vemco_tag_specs(tag_file, file_format = NULL)

Arguments

Details

The file format vemco_xls is a MS Excel file provided to tag purchasers by Vemco.

This function is not endorsed or supported by any transmitter manufacturer.

Value

A list containing two data frames with tag specifications and tag operating schedule.

A list element called specs is a data frame contains tag specifications data in 17 columns:

serial_number

manufacturer

model

id_count

code_space

id_code

n_steps

sensor_type

sensor_range

sensor_units

sensor_slope

sensor_intercept

accel_algorithm

accel_sample_rate

sensor_transmit_ratio

est_battery_life_days

battery_life_stat

A list element called schedule is a data frame containing tag operating shedule data in 11 columns:

serial_number

code_space

id_code

step

next_step

status

duration_days

power

min_delay_secs

max_delay_secs

accel_on_time_secs

Author(s)

C. Holbrook, [email protected]

Examples

#get path to example Vemco tag spec file
spec_file <- system.file("extdata", 
  "lamprey_tag_specs.xls", package = "glatos")
my_tags <- read_vemco_tag_specs(spec_file, file_format = "vemco_xls")

Description

Get transmitter sensor (e.g., depth, temperature) conversion parameters (e.g., intercept, slope) from a Vemco transmitter specification object (e.g., from read_vemco_tag_specs, calculate 'real'-scale values (e.g., depth in meters), and add real values to detection data in a new column.

Usage

real_sensor_values(det, tag_specs)

Arguments

Details

Tag spec data are joined to detection data and then raw-scale sensor measurements are converted to real-scale using $sensor_value_real = sensor_intercept + (sensor_value * sensor_slope)$, where $sensor_value$ is in raw scale.

It is possible that transmitter_codespace and transmitter_id are not unique among transmitters, so users must ensure that the each combination of those columns occurs only once in tag_specs and is the correct record for the corresponding tags in det.

Value

The input data frame, data.table, or tibble with the following columns added (see column descriptions above):

• sensor_range

• sensor_units

• sensor_slope

• sensor_intercept

• accel_algorithm

• accel_sample_rate

• sensor_transmit_ratio

• sensor_value_real

Author(s)

Chris Holbrook, [email protected]

Examples

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

#get path to example Vemco tag spec file
spec_file <- system.file("extdata", 
  "lamprey_tag_specs.xls", package="glatos")
  
lamprey_tags <- read_vemco_tag_specs(spec_file, file_format = "vemco_xls")

#note use of '$specs' in tag_specs argument
dtc <- real_sensor_values(lamprey_detections, lamprey_tags$specs)

#now view records with sensor measurements
dtc[!is.na(dtc$sensor_value_real),]

Description

Estimate, by simulation, the probability of detecting an acoustic-tagged fish on a receiver line, given constant fish velocity (ground speed), receiver spacing, number of receivers, and detection range curve.

Usage

receiver_line_det_sim(
  vel = 1,
  delayRng = c(120, 360),
  burstDur = 5,
  recSpc = 1000,
  maxDist = 2000,
  rngFun,
  outerLim = c(0, 0),
  nsim = 1000,
  showPlot = FALSE
)

Arguments

Details

Virtual tagged fish (N=nsim) are "swum" through a virtual receiver line. The first element of recSpc determines spacing between first two receivers in the line, and each subsequent element of recSpc determine spacing of subsequent receivers along the line, such that the number of receivers is equal to length(recSpc) + 1. Each fish moves at constant velocity (vel) along a line perpendicular to the receiver line. The location of each fish path along the receiver line is random (drawn from uniform distribution), and fish can pass outside the receiver line (to the left of the first receiver or right of last receiver) if outerLim[1] or outerLim[2] are greater than 0 meters. Each fish starts and ends about maxDist meters from the receiver line.

A simulated tag signal is transmitted every delayRng[1] to delayRng[2] seconds. At time of each transmission, the distance is calculated between the tag and each receiver, and rngFun is used to calculate the probability (p) that the signal was detected on each receiver. Detection or non-detection on each receiver is determined by a draw from a Bernoulli distribution with probability p.

Value

A data frame with one column:

Author(s)

C. Holbrook [email protected]

References

For application example, see:

Hayden, T.A., Holbrook, C.M., Binder, T.R., Dettmers, J.M., Cooke, S.J., Vandergoot, C.S. and Krueger, C.C., 2016. Probability of acoustic transmitter detections by receiver lines in Lake Huron: results of multi-year field tests and simulations. Animal Biotelemetry, 4(1), p.19.
https://animalbiotelemetry.biomedcentral.com/articles/10.1186/s40317-016-0112-9

Examples

#EXAMPLE 1 - simulate detection on line of ten receivers
  
 #Define detection range function (to pass as rngFun) 
 # 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(5.5, -1/120)){
    p <- 1/(1+exp(-(b[1]+b[2]*dm)))
    return(p)
 }

 #preview detection range curve
 plot(pdrf(0:2000),type="l",ylab="Probability of detecting each coded burst", 
xlab="Distance between receiver and transmitter")

 #Simulate detection using pdrf; default values otherwise
 dp <- receiver_line_det_sim(rngFun=pdrf)
 dp

 #Again with only 10 virtual fish and optional plot to see simulated data
 dp <- receiver_line_det_sim(rngFun=pdrf, nsim=10, showPlot=T) #w/ optional plot
 dp

 #Again but six receivers and allow fish to pass to left and right of line
 dp <- receiver_line_det_sim(rngFun=pdrf, recSpc=rep(1000,5),
	outerLim=c(1000, 1000), nsim=10, showPlot=T)
 dp

 #Again but four receivers with irregular spacing
 dp <- receiver_line_det_sim(rngFun=pdrf, recSpc=c(2000,4000,2000),
 	outerLim=c(1000, 1000), nsim=10, showPlot=T)
 dp


#EXAMPLE 2 - summarize detection probability vs. receiver spacing
 
 #two receivers only, spaced 'spc' m apart
 #define scenarios where two receiver are spaced 
 spc <- seq(100,5000, 100) #two receivers spaced 100, 200, ... 5000 m
 #loop through scenarios, estimate detection probability for each
 for(i in 1:length(spc)){
   if(i==1) dp <- numeric(length(spc)) #pre-allocate
   dp[i] <- receiver_line_det_sim(recSpc=spc[i], rngFun=pdrf)
 }
 cbind(spc,dp) #view results  
 #plot results
 plot(spc, dp, type="o",ylim=c(0,1), 
   xlab="distance between receivers in meters",
  ylab="proportion of virtual fish detected") 
 # e.g., >95% virtual fish detected up to 1400 m spacing in this example


#EXAMPLE 3 - summarize detection probability vs. fish swim speed
 
 #define scenarios of fish movement rate
 swim <- seq(0.1, 5.0, 0.1) #constant velocity
 for(i in 1:length(swim)){
   if(i==1) dp <- numeric(length(swim)) #pre-allocate
   dp[i] <- receiver_line_det_sim(vel=swim[i], rngFun=pdrf)
 }
 cbind(swim,dp) #view results
 #plot results
 plot(swim, dp, type="o", ylim=c(0,1), xlab="fish movement rate, m/s",
  ylab="proportion of virtual fish detected")
 # e.g., >95% virtual fish detected up to 1.7 m/s rate in this example
 # e.g., declines linearly above 1.7 m/s


#EXAMPLE 4 - empirical detection range curve instead of logistic
 
 #create data frame with observed det. efficiency (p) at each distance (x)
 edr <- data.frame(
   x=c(0,363,444,530,636,714,794,889,920), #tag-receiver distance
   p=c(1,1,0.96,0.71,0.67,0.75,0.88,0.21,0)) # detection prob

 #now create a function to return the detection probability
 # based on distance and linear interpolation within edr
 # i.e., estimate p at given x by "connecting the dots" 
 edrf <- function(dm, my.edr=edr) {
   p <- approx(x=my.edr$x,y=my.edr$p,xout=dm, rule=2)$y
   return(p)
 }

 #preview empirical detection range curve
 plot(edrf(0:2000),type="l",
   ylab="probability of detecting each coded burst", 
  xlab="distance between receiver and transmitter, meters")

 #use empirical curve (edrf) in simulation
 dp <- receiver_line_det_sim(rngFun=edrf, nsim=10, showPlot=T) #w/ optional plot
 dp