| Title: | Spatial point process and random field models for electronic tagging data |
|---|---|
| Description: | A collection of tools to fit spatial models to several types of telemetry data. Models are provided to account for the detection process when estimating individual centers of activity from acoustic telemetry data and to incorporate data from stationary test transmitters when available. Bayesian versions of models are fitted using Stan (http://mc-stan.org/). Maximum likelihood versions are fitted using Template Model Builder (https://kaskr.github.io/adcomp/index.html). |
| Authors: | Megan Winton [aut] (ORCID: <https://orcid.org/0000-0003-2628-7022>), Michael O'Brien [cre, aut] (ORCID: <https://orcid.org/0000-0003-1420-6395>), Benjamin L. Hlina [aut] (ORCID: <https://orcid.org/0000-0002-4178-4900>) |
| Maintainer: | Michael O'Brien <[email protected]> |
| License: | GPL (>=3) |
| Version: | 1.3.3 |
| Built: | 2026-06-29 17:45:15 UTC |
| Source: | https://github.com/trackyverse/TelemetrySpace |
Spatial point process and random field models for electronic tagging data
Maintainer: Michael O'Brien [email protected] (ORCID)
Authors:
Michael O'Brien [email protected] (ORCID)
Megan Winton [email protected] (ORCID)
Benjamin L. Hlina [email protected] (ORCID)
Stan Development Team (2017). RStan: the R interface to Stan. R package version 2.16.2. http://mc-stan.org
Useful links:
Report bugs at https://github.com/trackyverse/TelemetrySpace/issues
These functions structure and build data components that are needed by the model. Each function will either return an object that is properly built and structured for 'Stan“ or will produce an object to be latter used in the pre-process phase of analysis.
build_aeqd(array_sf) build_bbox(coord_df, buffer = NULL) build_counts(df, nrec, rec_id, rec_names = NULL) build_init(coord_df, nind, tstep) build_ntrans(df, type = c("mean", "min", "max", "custom"), custom_delay = NULL) build_pixel_grid(bnd_sf, res, crs) build_rec_coords(obj_sf) build_time_bin(df, unit = "1 hour") build_tstep(x)build_aeqd(array_sf) build_bbox(coord_df, buffer = NULL) build_counts(df, nrec, rec_id, rec_names = NULL) build_init(coord_df, nind, tstep) build_ntrans(df, type = c("mean", "min", "max", "custom"), custom_delay = NULL) build_pixel_grid(bnd_sf, res, crs) build_rec_coords(obj_sf) build_time_bin(df, unit = "1 hour") build_tstep(x)
array_sf |
the receiver array as an |
coord_df |
a |
buffer |
a |
df |
a |
nrec |
a |
rec_id |
a |
rec_names |
an optional |
nind |
a |
tstep |
a |
type |
can either be |
custom_delay |
Only needed when |
bnd_sf |
a |
res |
the resolution desired. |
crs |
the Azimuthal Equidistant projection desired. If the supplied
projection string does not contain |
obj_sf |
a |
unit |
a |
x |
a 3-dimensional count array. |
build_aeqd()- Azimuthal Equidistant projection is needed by the model
which relies on creating a centroid and creating equal distances from the
centroid. This function quickly creates the project string
needed to transform an exisiting crs to Azimuthal Equidistant projection.
build_bbox()- builds the boundary box of receiver array needed by the model.
build_counts() - builds a 3-dimensional count array. The models need the
counts at each recevier for each time bin for each individual structure in 3-dimensional array.
This functions takes in a detection data.frame, creates a count data.frame and then transforms it
into a 3-dimensional array that will be pased to the Stan model.
build_init()- builds the initial values to supply to the model. Supplying these values
can helps the model know where to intially start.
build_ntrans() - builds the nubmer of transmissions to be expected within a given time bin.
build_pixel_grid() - builds barrier grid for the model.
We need to convert the boundary into pixels that can be used to recongize where to estimate
detection probablity. The boundary that is supplied needs to be in UTMs, with the returned
values being in Azimuthal Equidistant projection. To build this projection see build_aeqd().
When supplying the desired resolution remember that this is in m so
a value of 1 would be quite small while of 1000 is 1 km which makes a less dense grid.
build_rec_coords() - builds receiver coordinates as the models need the
easting and northing (i.e., x and y) coordinates of the receivers.
build_time_bin()- builds and adds time bins to the detection data.frame.
build_tstep() - builds the number of total time steps that exist whithin the
supplied 3-dimensional count array.
build_aeqd()- retruns a vector containing the site specific projection string for
the array to be able to transform the crs.
build_bbox()- returns a data.frame containing two columns named xlim and ylim which are the
minimum and maximum values +/- a buffer for x and y.
build_counts() - returns a 3-dimensional array containing the number of detections for the following dimensions,
the number of invividuals, by the number of time bins, by the number of receivers.
build_init()- returns a list containing two matrices named sx and sy. Each
matrix is the mean of either recX or recY produced by build_rec_coords() by the
number of individuals by the number of timesteps.
build_ntrans() - retruns a single value vector.
build_pixel_grid() - returns a list contain the the number of pixels n_pixel, the pixel x coordinates
(pix_x) and the pixel y coordinates (pix_y).
build_rec_coords() - a data.frame containing two columns named recX and recY which are the
receiver locations transformed into Azimuthal Equidistant projection.
build_time_bin()- returns a data.frame that has had the columns time_bin and timeadded. time is an
index value of time_bin and is needed by the model. This will further be used by build_counts().
build_tstep() - a numerical value that is the number of timesteps.
Fits a Bayesian Spatial Point Process model to estimate individual centers of activity from acoustic telemetry data using Stan
COA_Standard( nind, nrec, ntime, ntrans, y, recX, recY, xlim, ylim, decay = "gaussian", ndraws = NULL, ... )COA_Standard( nind, nrec, ntime, ntrans, y, recX, recY, xlim, ylim, decay = "gaussian", ndraws = NULL, ... )
nind |
Number of tagged individuals |
nrec |
Number of receivers |
ntime |
Number of time steps |
ntrans |
Number of expected transmissions per tag per time interval |
y |
Array of detection data, where row = individual, column = time step, and matrix = receiver |
recX |
Receiver coordinates in the east-west direction (should be projected and scaled for computational efficiency) |
recY |
Receiver coordinates in the north-south direction (should be projected and scaled for computational efficiency) |
xlim |
East-west boundaries of spatial extent (receiver array + buffer) |
ylim |
North-south boundaries of spatial extent (receiver array + buffer). |
decay |
desired decay function. Currently one of "gaussian" or "logistic". Default is "gaussian". |
ndraws |
to be passed to |
... |
Additional arguments passed to |
COA_Standard returns an object of class stanfit returned by rstan::sampling. See the rstan package documentation for details.
This function returns a list containing the following components: 1) a summary of the detection function parameters; 2) the time required for model fitting; 3) the estimated COAs for each individual in each time step and 95 percent credible interval; and 4) a dataframe containing values for each parameter and latent parameter from chain iterations. These can be used to plot posterior distributions and the credible interval around each estimated COA.
Fits a test-tag integrated Bayesian Spatial Point Process model to estimate individual centers of activity from acoustic telemetry data using Stan
COA_TagInt( nind, nrec, ntime, ntest, ntrans, y, test, recX, recY, xlim, ylim, testX, testY, decay = "gaussian", ndraws = NULL, ... )COA_TagInt( nind, nrec, ntime, ntest, ntrans, y, test, recX, recY, xlim, ylim, testX, testY, decay = "gaussian", ndraws = NULL, ... )
nind |
Number of tagged individuals |
nrec |
Number of receivers |
ntime |
Number of time steps |
ntest |
Number of test tags |
ntrans |
Number of expected transmissions per tag per time interval |
y |
Array of detection data, where row = individual, column = time step, and matrix = receiver |
test |
Array of test tag detection data, where row = individual tag, column = time step, and matrix = receiver |
recX |
Receiver coordinates in the east-west direction (should be projected and scaled for computational efficiency) |
recY |
Receiver coordinates in the north-south direction (should be projected and scaled for computational efficiency) |
xlim |
East-west boundaries of spatial extent (receiver array + buffer) |
ylim |
North-south boundaries of spatial extent (receiver array + buffer) |
testX |
Test tag coordinates in the east-west direction (should be projected and scaled for computational efficiency) |
testY |
Test tag coordinates in the north-south direction (should be projected and scaled for computational efficiency) |
decay |
desired decay function. Currently one of "gaussian" or "logistic". Default is "gaussian". |
ndraws |
to be passed to |
... |
Additional arguments passed to |
COA_TagInt_Bayes returns an object of class stanfit returned by rstan::sampling. See the 'rstan' package documentation for details.
This function returns a list containing the following components: 1) a summary of the detection function parameters; 2) the time required for model fitting; 3) time-varying detection probabilites for each receiver; 4) the estimated COAs for each individual in each time step and 95 percent credible interval; and 5) a dataframe containing values for each parameter and latent parameter from chain iterations. These can be used to plot posterior distributions and the credible interval around each estimated COA.
Fits a time-varying Bayesian Spatial Point Process model to estimate individual centers of activity from acoustic telemetry data using Stan
COA_TimeVarying( nind, nrec, ntime, ntrans, y, recX, recY, xlim, ylim, decay = "gaussian", ndraws = NULL, ... )COA_TimeVarying( nind, nrec, ntime, ntrans, y, recX, recY, xlim, ylim, decay = "gaussian", ndraws = NULL, ... )
nind |
Number of tagged individuals |
nrec |
Number of receivers |
ntime |
Number of time steps |
ntrans |
Number of expected transmissions per tag per time interval |
y |
Array of detection data, where row = individual, column = time step, and matrix = receiver |
recX |
Receiver coordinates in the east-west direction (should be projected and scaled for computational efficiency) |
recY |
Receiver coordinates in the north-south direction (should be projected and scaled for computational efficiency) |
xlim |
East-west boundaries of spatial extent (receiver array + buffer) |
ylim |
North-south boundaries of spatial extent (receiver array + buffer) |
decay |
desired decay function. Currently one of "gaussian" or "logistic". Default is "gaussian". |
ndraws |
to be passed to |
... |
Additional arguments passed to |
COA_TimeVarying returns an object of class stanfit returned by rstan::sampling. See the 'rstan' package documentation for details.
This function returns a list containing the following components: 1) a summary of the detection function parameters; 2) the time required for model fitting; 3) time-varying detection probabilites for each receiver; 4) the estimated COAs for each individual in each time step and 95 percent credible interval; and 5) a dataframe containing values for each parameter and latent parameter from chain iterations. These can be used to plot posterior distributions and the credible interval around each estimated COA.
Calculate Euclidean distance between receivers and activity centers
distf(x, y)distf(x, y)
x |
Data frame or matrix containing 2-dimensional coordinates |
y |
Data frame or matrix containing 2-dimensional coordinates |
'distf' returns a matrix containing the Euclidean distance between each location in dataframe x with that in dataframe y
Example array extent used in each model
example_extentexample_extent
A data frame with two variables and two row: ylim is the minimum
and maximum extent on the y-axis (i.e., latitudinal) for the array and
xlim is the minimum and maximum extent on the x-axis (i.e., longitudinal)
for the array.
Detection data from a tagged black sea bass aggregated to the hour.
fishdatfishdat
A data frame with five variables: Station Receiver ID, Transmitter Transmitter ID,
east East-West coordinate, north North-South coordinate, hour Hour of monitoring.
Example model parameters for COA_standard()
model_param_exmodel_param_ex
A data frame with four variables and one row:
nind which is the number of individuals, nrec is the number of receivers
in the array, tsteps is the number of time steps used in the example,
and ntrans is the number of expected transmissions within a time step.
sf objectA MULTIPOLYGON sf object that is Parry Sound which is a large embayment on
Georgian Bay, Lake Huron
psps
A sf object with a single geomety feature. Current coordinate reference system is
WGS 84.
data.frame for a tagged Lake TroutA data.frame that contains detections data for a tagged Lake Trout in
Parry Sound which is a large embayment on Georgian Bay, Lake Huron
ps_det_exampleps_det_example
A data.frame with 5 columns and 577 rows.
The detection timestamp as POSIXct with a tz of UTC
The receiver station number
The tag serial number
The minimum delay between transmissions in seconds
The maximum delay between transmissions in seconds
data.frame for a test tagA data.frame that contains detections data for aan internal transmitter
of a VR2AR deployed in Parry Sound which is a large embayment on Georgian Bay, Lake Huron
ps_det_test_tagps_det_test_tag
A data.frame with 7 columns and 200 rows.
The detection timestamp as POSIXct with a tz of UTC
The receiver station number the tag was detected on
The serial number of the VR2AR receiver
The tag id value from of the VR2AR receiver
The station number of the tag
The minimum delay between transmissions in seconds
The maximum delay between transmissions in seconds
A data.frame that contains the locations of 80 acoustic telemetry receivers deployed
in Parry Sound which is a large embayment on Georgian Bay, Lake Huron
ps_rec_locps_rec_loc
An object of class tbl_df (inherits from tbl, data.frame) with 80 rows and 3 columns.
A data.frame with 3 columns and 80 rows.
The station number of the receiver
The latitude of the deployed receiver
The longitude of the deployed receiver
A data.frame that contains the tag_station_no and the deployment latitude and longitude of
the test tag deployed in Parry Sound which is a large embayment on Georgian Bay, Lake Huron
ps_test_tag_locps_test_tag_loc
An object of class data.table (inherits from data.frame) with 1 rows and 3 columns.
A data.frame with 3 columns and 1 rows.
The station number of the tag
The latitude of the deployed tag
The longitude of the deployed tag
Projected and scaled receiver coordinates. Scaling is recommended to reduce computation time and prevent convergence issues.
rlocsrlocs
A data frame with three variables: Station Receiver ID, east East-West coordinate,
north North-South coordinate.
Detection data from a stationary, known-location test tag aggregated to the hour.
testdattestdat
A data frame with five variables: Station Receiver ID, Transmitter Transmitter ID,
east East-West coordinate, north North-South coordinate, hour Hour of monitoring.
Projected and scaled as for the receiver coordinates.
testloctestloc
A data frame with two variables: east East-West coordinate, north North-South coordinate.
Array of counts of detection per time step per receiver for the test tag. Originally with dimensions of 1 (individual) x 30 (receivers) x 10 (time steps), changed to 1 x 10 x 30 on 2026-05-13 for computational efficiency.
testYtestY
An array with dimensions of 1 by 10 (number of time steps) by 30 (number of receivers).
Array of counts of detection per time step per receiver. Originally with dimensions of 1 (individual) x 30 (receivers) x 10 (time steps), changed to 1 x 10 x 30 on 2026-05-13 for computational efficiency.
YY
An array with dimensions of 1 by 10 (number of time steps) by 30 (number of receivers).