Package 'TelemetrySpace'

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.1
Built: 2026-05-22 10:43:37 UTC
Source: https://github.com/trackyverse/TelemetrySpace

Help Index

The 'TelemetrySpace' package.

Description

Spatial point process and random field models for electronic tagging data

Author(s)

Maintainer: Michael O'Brien [email protected] (ORCID)

Authors:

References

Stan Development Team (2017). RStan: the R interface to Stan. R package version 2.16.2. http://mc-stan.org

See Also

Useful links:

Fits a Bayesian Spatial Point Process model to estimate individual centers of activity from acoustic telemetry data using Stan

Description

Fits a Bayesian Spatial Point Process model to estimate individual centers of activity from acoustic telemetry data using Stan

Usage

COA_Standard(
  nind,
  nrec,
  ntime,
  ntrans,
  y,
  recX,
  recY,
  xlim,
  ylim,
  decay = "gaussian",
  ndraws = NULL,
  ...
)

Arguments

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 generated_quantities. Changes the number of draws. Default is 10.
...

Additional arguments passed to sampling from rstan. This can include setting chains, iter, warmup, and control. Please see rstan::sampling() for more info.

Value

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.

See Also

rstan::sampling()

Fits a test-tag integrated Bayesian Spatial Point Process model to estimate individual centers of activity from acoustic telemetry data using Stan

Description

Fits a test-tag integrated Bayesian Spatial Point Process model to estimate individual centers of activity from acoustic telemetry data using Stan

Usage

COA_TagInt(
  nind,
  nrec,
  ntime,
  ntest,
  ntrans,
  y,
  test,
  recX,
  recY,
  xlim,
  ylim,
  testX,
  testY,
  decay = "gaussian",
  ndraws = NULL,
  ...
)

Arguments

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 generated_quantities. Changes the number of draws. Default is 10.
...

Additional arguments passed to sampling from rstan. This can include setting chains, iter, warmup, and control. Please see rstan::sampling() for more info.

Value

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.

See Also

rstan::sampling()

Fits a time-varying Bayesian Spatial Point Process model to estimate individual centers of activity from acoustic telemetry data using Stan

Description

Fits a time-varying Bayesian Spatial Point Process model to estimate individual centers of activity from acoustic telemetry data using Stan

Usage

COA_TimeVarying(
  nind,
  nrec,
  ntime,
  ntrans,
  y,
  recX,
  recY,
  xlim,
  ylim,
  decay = "gaussian",
  ndraws = NULL,
  ...
)

Arguments

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 generated_quantities. Changes the number of draws. Default is 10.
...

Additional arguments passed to sampling from rstan. This can include setting chains, iter, warmup, and control. Please see rstan::sampling() for more info.

Value

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

Description

Calculate Euclidean distance between receivers and activity centers

Usage

distf(x, y)

Arguments

x

Data frame or matrix containing 2-dimensional coordinates
y

Data frame or matrix containing 2-dimensional coordinates

Value

'distf' returns a matrix containing the Euclidean distance between each location in dataframe x with that in dataframe y

Example array extent

Description

Example array extent used in each model

Usage

example_extent

Format

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.

Black sea bass detection data

Description

Detection data from a tagged black sea bass aggregated to the hour.

Usage

fishdat

Format

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

Description

Example model parameters for COA_standard()

Usage

model_param_ex

Format

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.

Receiver locations from a black sea bass array

Description

Projected and scaled receiver coordinates. Scaling is recommended to reduce computation time and prevent convergence issues.

Usage

rlocs

Format

A data frame with three variables: Station Receiver ID, east East-West coordinate, north North-South coordinate.

Stationary test transmitter data

Description

Detection data from a stationary, known-location test tag aggregated to the hour.

Usage

testdat

Format

A data frame with five variables: Station Receiver ID, Transmitter Transmitter ID, east East-West coordinate, north North-South coordinate, hour Hour of monitoring.

Location of a stationary test transmitter placed in the black sea bass array

Description

Projected and scaled as for the receiver coordinates.

Usage

testloc

Format

A data frame with two variables: east East-West coordinate, north North-South coordinate.

Counts of detection per time steps for test tag

Description

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.

Usage

testY

Format

An array with dimensions of 1 by 10 (number of time steps) by 30 (number of receivers).

Counts of detection per time steps

Description

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.

Usage

Y

Format

An array with dimensions of 1 by 10 (number of time steps) by 30 (number of receivers).