| Title: | Enhance And Integrate the {crawl} Package For Spatial Analysis Of Telemetry Output |
|---|---|
| Description: | Utility functions to augment the the {crawl} package and integrate it with the {sf} package for spatial analysis of telemetry model output. The additional function are targeted toward analysis of marine mammal telemetry, but can be used or easily modified for other situations. |
| Authors: | Devin S. Johnson [aut, cre], Josh London [aut] |
| Maintainer: | Devin S. Johnson <[email protected]> |
| License: | CC0 |
| Version: | 0.1.62 |
| Built: | 2024-11-11 06:17:00 UTC |
| Source: | https://github.com/dsjohnson/crawlUtils |
crawl PackageThis package is a collection of functions that enhance the crawl package for
for analysis of animal telemetry data. The functions integrate crawl output and the sf package
for ease of model fitting and track prediction, notably in marine environments.
| Package: | crawlUtils |
| Type: | Package |
| Version: | 0.1.61 |
| Date: | September 11, 2024 |
| License: | CC0 |
| LazyLoad: | yes |
This software package is developed and maintained by scientists at the NOAA Fisheries Pacific Islands Fisheries Science Center and should be considered a fundamental research communication. The recommendations and conclusions presented here are those of the authors and this software should not be construed as official communication by NMFS, NOAA, or the U.S. Dept. of Commerce. In addition, reference to trade names does not imply endorsement by the National Marine Fisheries Service, NOAA. While the best efforts have been made to insure the highest quality, tools such as this are under constant development and are subject to change.
Devin S. Johnson Maintainer: Devin S. Johnson [email protected]
Silverman default bandwidth calculation
bw_silver(xy, ess = NULL)bw_silver(xy, ess = NULL)
xy |
Data coordinates |
ess |
An effective sample size. If left as |
Columns are added to the telemetry data set so that multiple data types can be used simultaneously within the same animal: FastGPS, Argos least-squares, and Argos Kalman filter.
cu_add_argos_cols(x, units = "meter")cu_add_argos_cols(x, units = "meter")
x |
Data frame containing location telemetry data and Argos quality information. See 'Details' for a description of the necessary data column names. |
units |
Units for movement and location error models. One of |
To use this function the data set must contain the following columns with
exact names: (1) "type", indicate the type of location,
(2) "quality" which indicates the Argos quality of the location, (3) The
Argos KF diagnostics: "error_semi_major_axis", "error_semi_minor_axis", and
"error_ellipse_orientation". If there are no Argos KF locations, the associated columns
need not be present. Values of type are 'FastGPS', 'Argos', or 'known'. For 'FastGPS' an error radius
of 100m is assumed. For 'known' an error radius of 20m is assumed. Values of
quality must be '3','2','1','0','A',or 'B' for type=='Argos' locations and '4'-'10' for type=='FastGPS'.
For other types it is ignored.
Devin S. Johnson
Add bout data from migr_evt
See cu_bout_det
cu_add_bouts(data, bout_tbl)cu_add_bouts(data, bout_tbl)
data |
Original data used by |
bout_tbl |
Results table produced by |
Devin S. Johnson
Label segments of telemetry data such that gaps between observed locations are less than or equal to the interval specified.
cu_add_gaps(x, gap = 7, time_unit = "days", ...)cu_add_gaps(x, gap = 7, time_unit = "days", ...)
x |
A data set of telemetry locations and times. |
gap |
specified maximum time interval for which a new bout is started. Defaults
to |
time_unit |
Unit of time of the gap specification. Defaults to |
... |
Ignored arguments |
Devin S. Johnson
Using this function the user can transform the Argos diagnostic data for location
error into a form usable as a covariance matrix to approximate the location error with a
bivariate Gaussian distribution. The resulting data.frame should be attached back to the data
with cbind to use with the crwMLE function.
cu_argosDiag2Cov(Major, Minor, Orientation)cu_argosDiag2Cov(Major, Minor, Orientation)
Major |
A vector containing the major axis information for each observation (na values are ok) |
Minor |
A vector containing the minor axis information for each observation (na values are ok) |
Orientation |
A vector containing the angle orientation of the Major axis from North (na values are ok) |
A data.frame with the following columns
ln.sd.x |
The log standard deviation of the location error in the x coordinate |
ln.sd.y |
The log standard deviation of the location error in the x coordinate |
rho |
The correlation of the bivariate location error ellipse |
Devin S. Johnson
Creates a data table that indicates the times of different bouts of movement. This method uses changes in the overall dispersion rate of the animal from the 'base' time to detect changes in overall movement from small scale local movement to large scale migration.
cu_bout_det( data, min_disp, migr_disp_cut = 1, min_bout_len = 3, grid_res = "day", base = "first", max_k = 100 )cu_bout_det( data, min_disp, migr_disp_cut = 1, min_bout_len = 3, grid_res = "day", base = "first", max_k = 100 )
data |
An |
min_disp |
The minimum dispersion rate to be considered a migration interval, e.g. 10 for a 10km dispersion minimum. |
migr_disp_cut |
The minimum per day dispersal rate to categorize a movement bout as "migratory" Defaults to 1. |
min_bout_len |
The mimimum length of time that a migration or non-migration event will take, e.g., 7 implies a minimum of 7 time intervals for a bout. |
grid_res |
The temporal resolution at which migrations are detected. e.g., "day" (default) implies migration start and end is detected on a daily resolution. |
base |
The location at which dispersion is measured. Can be one of |
max_k |
The maximum degrees of freedom used by |
Devin S. Johnson
Creates a data table that indicates the times of different bouts of movement. This method uses changes in the overall dispersion rate of the animal from the 'base' time to detect changes in overall movement from small scale local movement to large scale migration.
cu_bout_det_mbc( data, min_disp, migr_speed_cut = 1, min_bout_len = 3, Gmax = 3, grid_res = "day", base = "first" )cu_bout_det_mbc( data, min_disp, migr_speed_cut = 1, min_bout_len = 3, Gmax = 3, grid_res = "day", base = "first" )
data |
An |
min_disp |
The minimum dispersion rate to be considered a migration interval, e.g. 10 for a 10km dispersion minimum. |
migr_speed_cut |
The minimum speed to categorize a movement bout as "migratory" Defaults to 1 km/h. |
min_bout_len |
Minimum length for each bout, defaults to 3 |
Gmax |
Maximum number of movement clusters, defaults to 3. |
grid_res |
The temporal resolution at which migrations are detected. e.g., "day" (default) implies migration start and end is detected on a daily resolution. |
base |
The location at which dispersion is measured. Can be one of |
Devin S. Johnson
Summarizes a telemetry dataframe with a bout column into
a data frame with start and end times for each bout. For use with
cu_join_interval_tbl.
cu_bout_summary(x, ...)cu_bout_summary(x, ...)
x |
A telemetry data frame containing a |
... |
Ignored arguments |
Devin S. Johnson
A basic CTCRW model is fitted to a list of data sets where each element in the list represents the data for a single individual or deployment.
cu_crw_argos( data, move_phase = NULL, bm = FALSE, use_prior = TRUE, crw_control = NULL, fit = TRUE, skip_check = FALSE, ... )cu_crw_argos( data, move_phase = NULL, bm = FALSE, use_prior = TRUE, crw_control = NULL, fit = TRUE, skip_check = FALSE, ... )
data |
A data set containg the telemetry data for a single individual.
Will also accept a single |
move_phase |
An optional character value indicating a factor variable column in the data that designates different movement phases. |
bm |
Fit a Brownian Motion model rather than in integrated OU model. Defaults to |
use_prior |
Logical. Should a sensible mixture normal prior be use for the log beta and
log error scale parameters to impose a soft constraint for better numerical optimization.
Default is |
crw_control |
A named list passed to |
fit |
Logical. CTCRW parameters are estimated if |
skip_check |
See |
... |
Additional arguments passed to the |
A function is created to evaluate the covariance function of the fitted CRW movement model
cu_crw_covfun(x)cu_crw_covfun(x)
x |
A crwFit object created by a call to |
The function returns a function to evaluate the covariance of the fitted Integrated
Ornstein-Ulenbeck movement model. The returned function has 3 arguments: (1) t1
and (2) t2 both vectors of times to evaluate the covariance function of the fitted
IOU model, and (3) E (defaults to E=0). Which is the "zero" time of the process.
Typically E will be the time of the first observation.
Devin S. Johnson
Taylor, J. M., Cumberland, W. G., & Sy, J. P. (1994). A stochastic model for analysis of longitudinal AIDS data. Journal of the American Statistical Association, 89(427), 727-736.
Johnson, D. S., London, J. M., Lea, M. A., & Durban, J. W. (2008). Continuous‐time correlated random walk model for animal telemetry data. Ecology, 89(5), 1208-1215.
Using a correlation function created by cu_crw_covfun
from a fitted CRW model a covariance (correlation) matrix is created for observations
at the user provided times.
cu_crw_covmat(x, corr = TRUE, cf, E = 0)cu_crw_covmat(x, corr = TRUE, cf, E = 0)
x |
Either a |
corr |
Should the function return a correlation or covariance matrix? Defaults
to |
cf |
Covariance function created from a |
E |
The 'zero' time used for the covariance function. Defaults to |
If x is a crwFit object, then the cf and E
arguments are ignored. The resulting matrix is the covariance (correlation) matrix
for the observed location times conditioned on the first location. Therefore,
for n observed locations an (n-1) by (n-1) matrix will result. This is most
useful for the effective sample size computation for a kernel density estimate.
Devin S. Johnson
Estimates the number of independent locations in a CRW data set using the mutual information method of Bartoszek (2016).
cu_crw_ess(fit, aug = NULL)cu_crw_ess(fit, aug = NULL)
fit |
A |
aug |
Either a |
Uses the "mutual information" formulation of Bartoszek (2016) to calculate the equivalent number of independent animal locations.
Devin S. Johnson
Bartoszek, K. (2016). Phylogenetic effective sample size. Journal of Theoretical Biology. 407:371-386. (See https://arxiv.org/pdf/1507.07113.pdf).
Uses a list of CRW fitted models and desired prediction times to make location (and velocity) predictions for telemetered animals.
cu_crw_predict( fit, predTime = NULL, barrier = NULL, vis_graph = NULL, as_sf = TRUE, ... )cu_crw_predict( fit, predTime = NULL, barrier = NULL, vis_graph = NULL, as_sf = TRUE, ... )
fit |
A CRW fit object |
predTime |
A character string describing the desired frequency of prediction,
e.g., |
barrier |
An |
vis_graph |
A visibility graph constructed with the R package |
as_sf |
Logical. Return an |
... |
Additional arguments passed to the |
The R package pathroutr is necessary for use of the barrier rerouting.
it can be installed with the command
install.packages('pathroutr', repos='https://jmlondon.r-universe.dev').
See 'https://github.com/jmlondon/pathroutr' for a description of use and constructing the
viability vis_graph.
Devin S. Johnson
Uses a list of CRW fitted models and desired simulation times to make draws from the location (and velocity) posterior distribution for telemetered animals.
cu_crw_sample( fit, size = 8, predTime = NULL, barrier = NULL, vis_graph = NULL, as_sf = TRUE, ... )cu_crw_sample( fit, size = 8, predTime = NULL, barrier = NULL, vis_graph = NULL, as_sf = TRUE, ... )
fit |
A CRW fit object |
size |
The number of posterior draws. Defaults to 8 (See Details). |
predTime |
A character string describing the desired frequency of prediction,
e.g., |
barrier |
An |
vis_graph |
A visibility graph constructed with the R package |
as_sf |
Logical. Return an |
... |
Additional arguments passed to the |
The R package pathroutr is necessary for use of the barrier rerouting.
it can be installed with the command
install.packages('pathroutr', repos='https://jmlondon.r-universe.dev').
See 'https://github.com/jmlondon/pathroutr' for a description of use and constructing the
viability vis_graph.
Devin S. Johnson
Creates a data table that indicates the times of different bouts of movement. This method uses changes in the overall dispersion rate of the animal from the 'base' time to detect changes in overall movement from small scale local movement to large scale migration.
cu_disp_rate(bout_tbl, data, grid_res = "day", base = "first")cu_disp_rate(bout_tbl, data, grid_res = "day", base = "first")
bout_tbl |
A bout table for an individual animal created by |
data |
An |
grid_res |
The temporal resolution at which migrations are detected. e.g., "day" (default) implies migration start and end is detected on a daily resolution. |
base |
The location at which dispersion is measured. Can be one of |
Devin S. Johnson
Calculate an empirical utilization distribution
cu_empirical_ud(pts, grid, average = TRUE)cu_empirical_ud(pts, grid, average = TRUE)
pts |
an sf point object |
grid |
a |
average |
should an average UD be created from 1 or more pts layers |
grid with an additional column, npts or mean_pts
This function is intended for use after a predicted track or posterior simulation
is routed around barriers using the {pathroutr} package.
cu_extract_obst(x, obs)cu_extract_obst(x, obs)
x |
A |
obs |
Observed locations. Time column must be named |
Devin S. Johnson
The lowest 1-alpha percent of a utilization distribution is removed to give a highest prob\ reduce spatial extent of UDs for a animal with a small spatial scale of use relative to the study area
cu_hud(ud, prob = 0.9)cu_hud(ud, prob = 0.9)
ud |
A |
prob |
The percent cutoff for the highest utilization probability cells. Defaults to |
Devin S. Johnson
Takes a data set with a POSIX time column named 'datetime' and
another data set with start and end columns representing time intervals and
merges the two depending whether or not the 'datetime' column is within the interval of the second.
cu_join_interval_tbl(x, int_tbl)cu_join_interval_tbl(x, int_tbl)
x |
A data frame with a column labeled |
int_tbl |
A data frame with 'start' and 'end' columns that form non-overlapping intervals as well as at least one other column with interval level data. |
Devin S. Johnson
Calculate location rate statistics such as mean location rate per day or maximum number of locations per day for a telemetry
cu_location_rate(x, time_name, time_unit = "day", stat = mean, ...)cu_location_rate(x, time_name, time_unit = "day", stat = mean, ...)
x |
data set containing time of locations. |
time_name |
Character name of the POSIX time column when locations are observed. |
time_unit |
Time unit of the location summary. Defaults to |
stat |
Function used to summarize location times. Defaults to |
... |
Additional arguments passed to |
Devin S. Johnson
PLot the animal dispersion from the base location over time. Points
are colored to reflect estimated migration and non-migration phases.
See cu_bout_det
cu_plot_disp(data, bout_tbl)cu_plot_disp(data, bout_tbl)
data |
Original data used by |
bout_tbl |
Results table produced by |
Devin S. Johnson
Read and combine data downloaded from Wildlife Computers portal into individual directories.
cu_read_wc_dirs(x, remove_duplicates = TRUE)cu_read_wc_dirs(x, remove_duplicates = TRUE)
x |
Directory containing the individual telemetry data directories. |
remove_duplicates |
Locgical. Should observations with duplicated times be removed? The observation with the highest quality will be retained. |
Devin S. Johnson, Josh M. London
A weighted or unweighted Gaussian Kernel Density estimate for point spatial data
cu_sf_kde(x, w = NULL, bw = NULL, ref, ess = NULL, mask = FALSE)cu_sf_kde(x, w = NULL, bw = NULL, ref, ess = NULL, mask = FALSE)
x |
sf POINT object |
w |
Optional values, associated with |
bw |
Standard deviation scale bandwidth of Gaussian Kernel, must be units
of |
ref |
A terra SpatRaster |
ess |
A effective sample size to use instead of |
mask |
(TRUE/FALSE) mask resulting raster if ref is provided as a SpatRaster |
Please note that ks methods for estimation has been reverted to the Gussian method proposed in Venables & Ripley (2002). There was not enought evendence that the Chacon & Duong (2018) multivariate method(s) for bandwidth selection and kernal estimation were suitable for spatial random fields.
a terra SpatRaster class object containing kernel density estimate
Jeffrey S. Evans [email protected] and Devin S. Johnson [email protected]
Duong, T. & Hazelton, M.L. (2005) Cross-validation bandwidth matrices for multivariate kernel density estimation. Scandinavian Journal of Statistics, 32, 485-506.
Wand, M.P. & Jones, M.C. (1994) Multivariate plug-in bandwidth selection. Computational Statistics, 9, 97-116.
Venables, W. N. and Ripley, B. D. (2002) Modern Applied Statistics with S. Fourth edition. Springer.
Approximate contours for a UD
cu_ud_contour(ud, prob = seq(0.9, 0.1, -0.1), trim_pixel = TRUE)cu_ud_contour(ud, prob = seq(0.9, 0.1, -0.1), trim_pixel = TRUE)
ud |
A |
prob |
a vector of probabilities for the contours |
trim_pixel |
Logical. Should contour areas less than a pixel size be trimmed? defaults to |
Devin S. Johnson
Calculates the appropriate cellsize argument for making
a hexagon grid with st_make_grid.
hex_size(area = NULL, radius = NULL, sep = NULL)hex_size(area = NULL, radius = NULL, sep = NULL)
area |
A value (m^2) for the resulting area of a full hexagon cell |
radius |
The value for the distance (m) from the centroids to the edge of full hexagon cells. |
sep |
The distance (m) between centoids of the hexagon grid. |
Devin S. Johnson
See https://github.com/r-spatial/sf/issues/1505
sf::st_bbox for a list of sf or sfc objects.sf::st_bbox for a list of sf or sfc objects.
st_bbox_list(x, union = TRUE, as_sfc = FALSE)st_bbox_list(x, union = TRUE, as_sfc = FALSE)
x |
A list of |
union |
Logical. Should the bounding box of the union be returned instead of a list of bounding boxes. |
as_sfc |
Logical. Should the bounding box (boxes) be returned as |
Devin S. Johnson
Expand an sf bounding box by an expansion factor
st_expand(bbox, ef)st_expand(bbox, ef)
bbox |
An |
ef |
Expansion factor, must be positive and length 1, 2 or 4.
If |
Josh M. London
Predicate function to use with st_filter such that
such that elements of one spatial object are selected if
they are not contained at all in the other. See sf::st_within
st_not_within(x, y, sparse = TRUE, prepared = TRUE, ...)st_not_within(x, y, sparse = TRUE, prepared = TRUE, ...)
x |
object of class sf, sfc or sfg |
y |
object of class sf, sfc or sfg; if missing, x is used |
sparse |
ogical; should a sparse index list be returned (TRUE) or a dense logical matrix? See sf::st_within. |
prepared |
ogical; prepare geometry for x, before looping over y? See sf::st_within. |
... |
passed on to s2_options |
Converts sf data with EPSG = 4326 from -180/180 specification to 0/360 for plotting with the mapview package etc.
st_to_360(x)st_to_360(x)
x |
An sf data frame with EPSG=4326. |
Josh London
sf::st_union for a list of sf or sfc objects.sf::st_union for a list of sf or sfc objects.
st_union_list(x)st_union_list(x)
x |
A list of |
Devin S. Johnson