A07-telemetry.qmd

# Telemetry {#sec-telemetry}

In some capture--recapture studies there are additional data from radiotelemetry of a sample of animals. Telemetry fixes provide an unbiased sample of animal activity, unlike detections at fixed points (traps, cameras or hair snares) or from searching circumscribed areas. Telemetry data therefore provide a direct estimate of the spatial scale of activity, which is represented in spatially explicit capture--recapture (SECR) by the parameter $\sigma$. Telemetry data also reduce uncertainty regarding the location of animals' centres relative to detectors, so detection histories of telemetered animals may improve estimates of other parameters. These are *potential* benefits -- we do not consider whether they are realised *in practice*.

Previous examples are @sgpsmspo13, @whc18, @Linden2018. Combining data types has 
been considered generally by @Gopalaswamy2012, @Chandler2021, @Ruprecht2021, @Margenau2022 and others.

This chapter explains and demonstrates the use of telemetry data in the R package **secr**, particularly the use of the 'telemetry' detector type. 

::: {.callout-warning}

Telemetry is used in **secr** to augment SECR analyses, particularly the estimation of population density. **secr** is not intended for the detailed analysis of telemetry data *per se*. There is no provision in the data structure for recording the time of each fix, except as each relates to a discrete sampling occasion. Nor is there provision for associating behavioural or environmental covariates with each fix. 

:::

## Example  {#sec-telemetryexample}

We start with a concrete example based on a simulated dataset. 
```{r}
#| label: demosims
#| message: false
#| warning: false
#| code-fold: true
#| code-summary: "Show simulation code"

# Code to simulate capthist objects (trCH, teCH)

# detectors
te <- make.telemetry()
tr <- make.grid(detector = "multi", nx = 8, ny = 8)

# spatial population
set.seed(123)
pop4 <- sim.popn(tr, D = 5, buffer = 100, seed = 567)

# select 12 telemetered individuals from larger population
pop4C <- subset(pop4, sample.int(nrow(pop4), 12))

# renumber = FALSE (keep original animalID) needed for matching
trCH <- sim.capthist(tr,  popn = pop4, renumber = FALSE, 
    detectfn = "HHN", detectpar = list(lambda0 = 0.1, 
    sigma = 25), seed = 123)
session(trCH) <- 'Trapping'
teCH <- sim.capthist(te, popn = pop4C, renumber = FALSE, 
    detectfn = "HHN", detectpar = list(lambda0 = 1, sigma = 25),
    noccasions = 10, seed = 345)
session(teCH) <- 'Telemetry'
```

The first step is to combine the capthist objects `trCH` (trapping data) and `teCH` (telemetry fixes).

```{r}
#| label: chunk1
#| echo: false
#| ref-label: demosims
```

```{r}
#| label: load
#| message: false
#| warning: false
combinedCH <- addTelemetry(trCH, teCH)
```

Generating plots is straightforward. By default, `plot.capthist` displays the captures and ignores telemetry fixes. The plot type "telemetry" displays the fixes and distinguishes those of animals that also appear in the (unplotted) capture data of the combined object.

```{r}
#| label: fig-telemetryfig
#| fig-width: 6
#| fig-height: 3.5
#| fig-cap: |
#|   Simulated trapping and telemetry data. The 5-day trapping study (left) yielded
#|   29 recaptures. Telemetry data were obtained on 10 occasions
#|   for each of 12 animals (right). Points for animals that were both trapped and telemetered
#|   are ringed in black. Colours distinguish individuals.
par(mfrow = c(1,2), mar = c(2,2,3,2))
plot(traps(trCH), border = 150, bty = 'o') # base plot
plot(combinedCH, title = 'Trapping', tracks = TRUE, rad = 4, add = TRUE)
plot(traps(trCH), border = 150, bty = 'o') # base plot
plot(combinedCH, title = 'Telemetry', type = 'telemetry', 
     tracks = TRUE, add = TRUE)
```

Next we fit trapping-only and joint trapping-and-telemetry models:
```{r}
#| label: telemetryfit
#| cache: true
mask <- make.mask(traps(trCH), buffer = 100, type = 'trapbuffer', 
    nx = 32)
args <- list(mask = mask, detectfn = 'HHN', trace = FALSE)
fits <- list.secr.fit(list(trCH, combinedCH), constant = args, 
    names = c('tr','combined'))
collate(fits)[1,,,]
```
Here, telemetry data greatly improves the precision of the estimated scale of movement $\sigma$, but the effect on estimates of the other two parameters is small. 

## Standalone telemetry data 

Telemetry data are stored in modified **secr** capthist objects. A capthist object may comprise telemetry fixes only ('standalone telemetry') or telemetry fixes in association with capture--recapture data (composite telemetry and capture--recapture). This section describes standalone telemetry data. A composite capthist is formed by combining a telemetry-only object and a standard capthist object with `addTelemetry`, as described in @sec-composite.

### The 'traps' object for telemetry data

Telemetry data differ from all other SECR data in that the detection process does not constrain where animals are detected (telemetry provides a spatially unbiased sample of each animal's activity). That is clearly not the case for area-search and point detectors, which inevitably constrain where animals are detected. Nevertheless, for compatibility with the rest of **secr**, we associate telemetry data with a notional detector located at a point. The 'traps' object for telemetry data comprises the coordinates of this point plus the usual attributes of a 'traps' object in **secr** (detector type, usage, etc.). Remember that the point is only a 'notional' detector - it is never visited.

The function `make.telemetry` generates a suitable object:

```{r}
#| label: demotelem
te <- make.telemetry()
summary(te)
str(te)
```

The attribute `telemetrytype` is always 'independent' for standalone telemetry data; other possible values for composite data are described later.

### Detector type

Every 'traps' object has an associated detector type (attribute `detector`, commonly 'multi' or 'proximity'). This may be a vector with a different value for each occasion. The detector type for telemetry data is 'telemetry'. In a standalone telemetry capthist, all elements of `detector` are 'telemetry'.

### But where are the data?

As for any other detector type, the body of a telemetry capthist is a 3-D array whose elements are the number of detections for each combination of animal, occasion and detector. Coordinates are stored separately in the 'telemetryxy' attribute. Use one of these functions to reveal the telemetry component of a capthist object `CH`:

1. `str(CH)`
2. `summary(CH)`
3. `plot(CH, type = 'telemetry')`
4. `telemetryxy(CH)`   

The attribute 'telemetryxy' is a list with one component for each animal. The fixes of each animal are sorted in chronological order.

### Data input

Data for a telemetry-only object should be read with function `read.telemetry`, a simplified version of `read.capthist`. The input format for telemetry fixes follows the 'XY' format for captures, with one line per fix (see [secr-datainput.pdf]). 

The first few lines of a text file containing telemetry data collected on 5 occasions might look like this --
```
1  10 1  -83.3  -20.04
1  10 2  -57.91  -4.77
1  10 3 -112.96  -7.51
1  10 4  -77.71 -75.79
1  10 5  -85.81 -42.45
1 101 1  143.06 170.48
1 101 2   99.22 145.49
etc.
```
The first column is a session code, the next an animal identifier ('10', '101'), the third an occasion number (1..noccasions) and the last two are the x and y coordinates. GPS coordinates should be projected (i.e. not latitude and longitude), and in metres if possible. 

A file named 'telemetrydemo.txt' may be read with
```{r}
#| label: readtelemetry
CHt <- read.telemetry(file = "data/telemetrydemo.txt")
head(CHt)
telemetryxy(CHt)[['10']]  # coordinates of first animal
```

Input may be from a text file (named in argument 'file') or dataframe (argument 'data'). 
The body of the resulting capthist object merely tallies the number of detections per animal per session and occasion. The fixes for one session are stored separately in an attribute that is a list of dataframes, one per animal. Use `telemetryxy(CHt)` to retrieve this list.

The summary of a telemetry-only capthist is quirky: 
```{r}
#| label: summarytelemetry
summary(CHt)
```

Even though each fix is counted as a 'detection' in the body of the final capthist object, none of the telemetered animals is considered to have been 'detected' in a conventional SECR sense. The telemetry-only capthist object includes a trivial traps object with a single point. The telemetry type of the traps for a telemetry-only capthist defaults to 'independent'.

## Combining telemetry and capture--recapture {#sec-composite}

For the purpose of density estimation and modelling, standalone telemetry data are added to an existing spatial capture--recapture (capthist) data object with the function `addTelemetry`. The relationship between the telemetry and capture--recapture samples is determined by the `type` argument (default 'concurrent'). We first explain the possible telemetry types.

### Types of telemetry data

**secr** distinguishes three types of telemetry data -- independent, dependent and concurrent -- that differ in how they relate to other SECR samples (capture--recapture data). Each type corresponds to a particular probability model.
<!-- [probability model](05-theory-special-topics.qmd#sec-telemetrylikelihood). -->


```{r}
#| label: fig-telemetryschematic
#| eval: true
#| echo: false
#| fig-width: 6
#| fig-asp: 0.6
#| out-width: 90%
#| fig-cap: |
#|   Schematic relationship of capture--recapture data to three types of telemetry
#|   data. Vertical overlap indicates individuals that appear in both datasets.
par(mfrow=c(1,1), mar = c(0,3,2,2), xpd = TRUE, cex=1)
txtcex <- 0.85
plot (0,0, type='n', xlim=c(0,160), ylim=c(0,60), xlab='', ylab='', axes = F)

rect1 <- cbind(x=c(0,15,15,0,0), y=c(0,0,30,30,0))
rect2 <- cbind(x=c(0,15,15,0,0), y=c(0,0,10,10,0))
rect2a <- cbind(x=c(0,15,15,0,0), y=c(0,0,7.5,7.5,0))
rect2b <- cbind(x=c(0,15,15,0,0), y=c(0,0,15,15,0))
rect3 <- cbind(x=c(0,15,15,0,0), y=c(0,0,20,20,0))
rect4 <- cbind(x=c(0,15,15,0,0), y=c(0,0,25,25,0))

## IT
polygon(secr::shift(rect1, c(0,20)), lwd = 1.5, col='lightgrey')       ## capture
polygon(secr::shift(rect2b, c(17.5,5)), lwd = 1.5)                     ## telemetry     

## DT
polygon(secr::shift(rect1, c(40,20)), lwd = 1.5, col = 'lightgrey')    ## capture
polygon(secr::shift(rect2, c(55,20)), lwd = 1.5)                       ## telemetry     

## CT
polygon(secr::shift(rect1, c(82.5,20)), lwd = 1.5, col ='lightgrey')   ## capture
polygon(secr::shift(rect3, c(100,10)), lwd = 1.5)

text (c(13,52,94), rep(57,3), c('a. Independent','b. Dependent','c. Concurrent'), cex=txtcex)
mtext(side=2, at=27.5, line=2, cex=txtcex, 'Individuals')
axis(2, line=1, at=c(5,50), lab = F, lwd = 1.5)

rect5 <- cbind(x=c(0,6.5,6.5,0,0), y=c(0,0,4,4,0))
polygon(secr::shift(rect5, c(130,45)), col='lightgrey')
polygon(secr::shift(rect5, c(130,40)))
text (rep(139,2), c(47,42), c('Capture','Telemetry'), adj=0, cex=txtcex)

polygon(c(125,125,165,165), c(38,51,51,38))
```

1. Independent telemetry

Independent telemetry data have no particular relationship to spatial capture--recapture data except that they may be modelled using a shared value of the spatial-scale parameter $\sigma$, and possibly other spatial parameters. Telemetered animals do not have detection histories.

2. Dependent telemetry

Dependent telemetry data relate to a sample of animals detected during the capture--recapture study: an animal must be caught in that study to become telemetered, and no animal is telemetered and not otherwise detected (i.e. no detection history is all-zero).

3. Concurrent telemetry

Concurrent telemetry data are obtained for a sample of animals from the same regional population as the capture--recapture study. Telemetered animals appear stochastically in the capture--recapture sample with probability related to their location. Detection histories of some animals may be all-zero, and these are modelled. Whether the capture--recapture phase precedes or follows telemetry is not material.

### What exactly does `addTelemetry` do?

The `addTelemetry` function forms a composite capthist object. Its usage follows -
```
addTelemetry (detectionCH, telemetryCH, type = c("concurrent", "dependent", 
    "independent"), collapsetelemetry = TRUE, verify = TRUE) 
```
Capture--recapture data in the argument 'detectionCH' form the basis for `addTelemetry`. The base capthist is modified in these ways --

* For all telemetry types `addTelemetry` extends the capture--recapture 'traps' object by adding a single (notional) detector location (duplicating the first). 
* By default, the 'detector' attribute is extended by a single sampling occasion with type 'telemetry'; all telemetry data are associated with this occasion, regardless of how many occasions there were in the telemetry input. If `collapsetelemetry = FALSE` distinct telemetry occasions are retained.
* The 'usage' attribute is set to zero for the notional telemetry detector on capture occasions and for capture detectors on telemetry occasions. Other usage data from 'detectionCH' is retained.
* All-zero detection histories are generated for the 'concurrent' data type.  
* The coordinates of telemetry fixes are transferred from `telemetryCH` as the attribute 'telemetryxy' of the output. 
* If the data are independent then the labels of telemetered animals are prefixed by 'T' to reduce the chance of identity conflicts with animals in 'detectionCH'. 
* By default, `addtelemetry` calls `verify.capthist` to check its output.

### Composite data, different sessions

We use `addTelemetry` to combine telemetry data and capture--recapture data from the same session, or possibly for each of several sessions when the detectionCH and telemetryCH are parallel (equal-length) multi-session objects. It is also feasible to concatenate telemetry and capture--recapture data as separate sessions of a multi-session object with `MS.capthist`. The effect is similar to a single-session composite capthist with telemetrytype 'independent', because **secr** treats sessions as independent (i.e. individual histories do not span session boundaries). See the next section for an example.

## Model fitting

### Standalone telemetry data

We can estimate $\sigma$ for a half-normal circular home-range model directly:
```{r}
#| label: rpsv
RPSV (CHt, CC = TRUE)
```
Note the CC argument (named for @cc58) that is required to scale the result correctly.

More laboriously:
```{r}
#| label: fitindep
#| cache: true
fit0 <- secr.fit(CHt, buffer = 300, detectfn = 'HHN', 
                 trace = FALSE)
predict(fit0)
```

The detection function (argument `detectfn`) must be either hazard half-normal (14, 'HHN') or hazard exponential (16, 'HEX')[^telemetry1]. The default detection function for a dataset with any telemetry component is 'HHN'. For telemetry-only data the likelihood is conditional on the number of observations, so the argument `CL` is set internally to TRUE. A large `buffer` value here brings $\hat \sigma$ from `secr.fit` closer to $\hat \sigma$ from `RPSV`. See [below](#sec-telemetryhabitatmask) for more on the `buffer` argument.

See [Technical notes](#sec-telemetrytechnotes) for potential numerical problems.

[^telemetry1]:This constraint arises from the need internally to normalise the probability density function for each telemetry fix. The normalising constant for these functions is $1/(2\pi \sigma^2)$, whereas for most other possible values of `detectfn` it is hard to compute or the function does not correspond to a probability density.

### Composite telemetry and capture--recapture data

Fitting a model to composite data should raise no further problems: `secr.fit` receives all the information it requires in the composite capthist input. The likelihood is a straightforward extension of the usual SECR likelihood, with some subtle differences in the case of dependent or concurrent telemetry.
<!-- (@sec-specialtopics, [Telemetry](05-theory-special-topics.qmd#sec-telemetrylikelihood)). -->

The use of detection functions expressed in terms of the hazard provides a more natural link between the model for the activity distribution and the model for detection probability.  When a hazard function is used `secr.fit` automatically flips the default model for the first detection parameter from 'g0 ~ 1' to 'lambda0 ~ 1'.

Our introductory [example](#sec-telemetryexample) fitted a model to single-session composite data. We can compare the results when the telemetry and trapping data are in separate sessions:
```{r}
#| label: ms
#| cache: true
#| cache-rebuild: false
msCH <- MS.capthist(trCH, teCH)
fit.ms <- secr.fit(msCH, mask=mask, detectfn = 'HHN', 
                   trace = FALSE)
predict(fit.ms)
```

Note: If the order of `teCH` and `trCH` had been reversed in `msCH` we would need to use details=list(autoini=2) to base parameter starting values on the trapping data, or provide start values manually.

### Habitat mask for telemetry data {#sec-telemetryhabitatmask}

The centres of both detected and telemetry-only animals are assumed to lie on the habitat mask. Ensure the mask is large enough to encompass telemetry-only animals. A conservative approach is to buffer around the individual telemetry centroids. Using `teCH` from before:

```{r}
#| label: mask
centroids <- data.frame(t(sapply(telemetryxy(teCH), 
    apply, 2, mean)))
mask1 <- make.mask(centroids, buffer = 100, type = 'trapbuffer')
```

For composite telemetry and capture--recapture, buffering should include the detector sites:
```{r}
#| label: mask2
tmpxy <- rbind(centroids, data.frame(traps(trCH))) 
mask2 <- make.mask(tmpxy, buffer = 100, type = 'trapbuffer')
```

```{r}
#| label: fig-maskplot
#| fig-width: 6
#| fig-height: 3.5
#| fig-cap: |
#|   Habitat masks prepared by buffering around telemetry sites (left) or both
#|   telemetry and detector sites (right).
par(mfrow = c(1,2))
plot(mask1)
plot(teCH, add = TRUE, title = 'Telemetry only')
plot(mask2)
plot(traps(trCH), add = TRUE)
plot(teCH, add = TRUE, title = 'Telemetry and detector sites')
```

The mask generated automatically by `secr.fit` buffers around both detector sites and telemetry fixes, as shown here. The 'buffer' argument in `make.mask` can be problematic when used with a standalone telemetry traps object because the notional detector location is an arbitrary point - it is better to use the centroid coordinates as input. 

## Simulation

Simulation of joint capture--recapture and telemetry data is a 2-step operation in **secr**, with the steps depending on the type of telemetry sampling. Here is an example of each type.

We choose to fix the number of observations per animal at 25 using the `exactN` argument of `sim.capthist`. The same effect can be achieved by increasing the number of occasions to 25 and setting `exactN = 1`.

### Independent telemetry

For independent data there is no specified connection between the populations sampled, so we separately generate telemetry and capture--recapture datasets and stick them together. 

```{r}
#| label: simI
# detectors
te <- make.telemetry()
tr <- make.grid(nx = 8, ny = 8, detector = "proximity")
pop1 <- sim.popn(tr, D = 10, buffer = 200)
pop2 <- sim.popn(core = tr, buffer = 200, Nbuffer = 20, 
                 Ndist = 'fixed')
trCH <- sim.capthist(tr,  popn = pop1, detectfn = "HHN", 
    detectpar = list(lambda0 = 0.1, sigma = 25))
teCH <- sim.capthist(te,  popn = pop2, detectfn = "HHN", 
    detectpar = list(sigma = 25), noccasions = 1, exactN = 25)
CHI <- addTelemetry(trCH, teCH, type = 'independent')
session(CHI) <- 'Independent'
summary(CHI)
```

### Dependent telemetry

For dependent data the telemetry sample is drawn from animals caught during the capture--recapture phase. This example uses the previously constructed 'traps' objects (`tr` and `te`). The original numbering of animals must be conserved (`renumber = FALSE`).

```{r}
#| label: simD
pop3 <- sim.popn(tr, D = 10, buffer = 200)
trCH <- sim.capthist(tr,  popn = pop3, detectfn = "HHN", 
    detectpar = list(lambda0 = 0.1, sigma = 25), renumber = 
    FALSE, savepopn = TRUE)

## select trapped animals from saved popn
pop3D <- subset(attr(trCH, 'popn'), rownames(trCH))
## sample 12 detected animals for telemetry
pop3Dt <- subset(pop3D, sample.int(nrow(pop3D), 12))  
## simulate telemetry
teCHD <- sim.capthist(te, popn = pop3Dt, renumber = FALSE, 
    detectfn = "HHN", detectpar = list(sigma = 25), 
    noccasions = 1, exactN = 25)
CHD <- addTelemetry(trCH, teCHD, type = 'dependent')
session(CHD) <- 'Dependent'
summary(CHD)
```

### Concurrent telemetry

For concurrent telemetry a sample of animals is taken from the regional population without reference to whether or not each animal was detected in the capture--recapture phase. The original numbering of animals must be conserved (`renumber = FALSE`), as for dependent telemetry.

```{r}
#| label: simC
set.seed(567) 
pop4 <- sim.popn(tr, D = 10, buffer = 200)
# select 15 individuals at random from larger population
pop4C <- subset(pop4, sample.int(nrow(pop4), 15))
# original animalID (renumber = FALSE) are needed for matching
trCH <- sim.capthist(tr,  popn = pop4, renumber = FALSE, 
    detectfn = "HHN", detectpar = list(lambda0 = 0.1, 
    sigma = 25))
teCHC <- sim.capthist(te, popn = pop4C, renumber = FALSE, 
    detectfn = "HHN", detectpar = list(sigma = 25), noccasions =
    1, exactN = 25)
CHC <- addTelemetry(trCH, teCHC, type = 'concurrent')
session(CHC) <- 'Concurrent'
summary(CHC)
```

### Plotting to compare simulated data

```{r}
#| label: fig-plotsim
#| fig-width: 6
#| fig-height: 2.5
#| fig-cap: |
#|   Simulated telemetry data in relation to a capture--recapture grid (red crosses).
#|   Independently telemetered individuals are not recognised if they are caught on the
#|   grid. Dependent telemetry is restricted to animals caught on the grid. Individuals
#|   telemetered concurrently may or may not be caught, but are recognised when they
#|   are.
par(mfrow = c(1,3), mar = c(2,2,4,2), xpd = TRUE)
plot(traps(CHI), border = 200, gridlines = FALSE, bty = 'o')
plot(CHI, type = 'telemetry', tracks = TRUE, add = TRUE)

plot(traps(CHD), border = 200, gridlines = FALSE, bty = 'o')
plot(CHD, type = 'telemetry', tracks = TRUE, add = TRUE)

plot(traps(CHC), border = 200, gridlines = FALSE, bty = 'o')
plot(CHC, type = 'telemetry', tracks = TRUE, add = TRUE)
```

## Technical notes {#sec-telemetrytechnotes}

### Assumption of common $\sigma$

Joint analysis of telemetry and capture--recapture data usually relies on the assumption that the same value of the parameter $\sigma$ applies in both sampling processes. This does not hold when

* telemetry fixes have large measurement error that inflates $\sigma$, or

* the tendency of an animal to interact with a detector after encountering it varies systematically with distance from the home-range centre, or

* activity is not stationary and the telemetry and capture--recapture data relate to different time intervals.

The assumption may be avoided altogether by modelling distinct values of $\sigma$ on trapping and telemetry occasions. This is readily achieved using the automatic predictor `tt` in the formula for sigma, as in `secr.fit(CH, detectfn = 'HHN', model = sigma~tt, ...)`. The model then has one level of sigma for non-telemetry occasions (tt = 'nontelemetry') and another for telemetry occasions (tt = 'telemetry'). However, this sacrifices much of the benefit from a joint analysis when the telemetry data are dependent or concurrent, and all benefit for independent telemetry data.

### Numerical problems

Fitting joint telemetry and SECR models can be difficult - the usual computations in **secr** may fail to return a likelihood. The problem is often due to a near-zero value in a component of the telemetry likelihood. This occurs particularly in large datasets. The problem may be fixed by scaling the offending values by an arbitrary large number given in the details argument 'telemetryscale'. The required magnitude for 'telemetryscale' may be found by experimentation (try 1e3, 1e6, 1e9, 1e12 etc.). This ad hoc solution must be applied consistently if models are to be compared by AIC.

```{r}
#| label: telemscale
#| eval: true
#| cache: true
te <- make.telemetry()
teCH2 <- sim.capthist(te, popn = list(D = 2, buffer = 200), 
    detectfn = "HHN", exactN = 100, detectpar = list(sigma = 25),
    noccasions = 1)
mask <- make.mask(traps(teCH2), buffer = 300, type = 
    'trapbuffer')
# fails
fit1 <- secr.fit(teCH2, mask = mask, detectfn = 'HHN', CL = TRUE, 
    trace = FALSE, details = list(telemetryscale = 1)) 
predict(fit1)
# succeeds
fit1000 <- secr.fit(teCH2, mask = mask, detectfn = 'HHN', 
    CL = TRUE, trace = FALSE, details = list(telemetryscale = 
    1e3)) 
predict(fit1000)
```

Numerical problems may also be caused by inappropriate starting values, poor model specification, or an unknown bug. It may help to use the longer-tailed detection function 'HEX' instead of 'HHN'.

### Learned response

Learned responses (b, bk) are not expected in telemetry data. However, they may make sense for the 'SECR' occasions of a composite dataset (combined stationary detectors and telemetry). There is no way to avoid a global learned response (b) from propagating to the telemetry occasions (i.e. modelling different telemetry sigmas for animals detected or not detected in the pre-telemetry phase). A site-specific learned response, however, cannot propagate to the telemetry phase if there is a single telemetry 'occasion' because (i) no animal is detected at the notional telemetry detector in the pre-telemetry phase, and (ii) there is no opportunity for learning within the telemetry phase if all detections are on one occasion.

## Limitations {#telemetrylimitations}

Some important functions of **secr** have yet to be updated to work with telemetry data. These are listed in @sec-telemetryappendix2. Other limitations are described here.

### Incompatible with area search

Telemetry data may not be combined with area-search (polygon) data except as independent data in distinct sessions. This is because the polygon data types presently implemented in **secr** must be constant across a session.

If the 'independent data, distinct-session' solution is inadequate you might try rasterizing the search area (function `discretize`).

### Incompatible with mark--resight

Telemetry data may not be combined with mark-resight except possibly in distinct sessions (this has not been tested).

### Incompatible with hybrid heterogeneity model

The `secr.fit` code for hybrid heterogeneity models (hcov) has yet to be updated.

### Non-Euclidean distance 

Non-Euclidean distance methods cannot be used with telemetry data at present (a very large distance matrix would be required).

## Telemetry-related functions.  {#sec-telemetryappendix2}

|  Function   | Purpose         |
|-------------|---------------------------------------------|
| `addTelemetry` | combine capture-recapture and telemetry data in new capthist |
| `make.telemetry` | build a traps object for standalone telemetry data |
| `read.telemetry` | input telemetry fixes from text file or dataframe |
| `telemetered` | determine which animals in a capthist object have telemetry data |
| `telemetrytype` | extract or replace the 'telemetrytype' attribute of a traps object |
| `telemetryxy` | extract or replace telemetry coordinates from capthist |
| `xy2CH` | make a standalone telemetry capthist from a composite capthist |

: Functions specifically for telemetry data. {#tbl-telemetryfunctions .sm}

|  Function   | Purpose         |
|-------------|---------------------------------------------|
| `derived`  | Horvitz-Thompson-like density estimate |
| `join` | combine sessions of multi-session capthist object |
| `make.capthist` | build capthist object                   |
| `moves` | sequential movements* |
| `MS.capthist` | form multi-session capthist from separate sessions |
| `plot.capthist` | plotting (type = 'telemetry') |
| `rbind.capthist` | concatenate rows of capthist |
| `RPSV`, `MMDM`, `ARL`, `dbar` | indices of home-range size* |
| `secr.fit` | model fitting |
| `sim.capthist` | generate capthist data |
| `subset.capthist` | select subset of animals, occasions or detectors |
| `summary.capthist` | summary |
| `verify.capthist` | perform integrity checks |
| `verify.traps` | perform integrity checks |

: Telemetry-ready general functions. Functions marked with an asterisk (*) use the telemetry coordinates if the capthist is telemetry-only, otherwise the detection sites. {#tbl-telemetrygeneralfunctions .sm}

|  Function   | Purpose         |
|-------------|---------------------------------------------|
| `reduce.capthist` | change detector type or collapse occasions |
| `sim.secr` | parametric bootstrap fitted model|
| `simulate` | simulate from fitted model |
| `secr.test` | another parametric boostrap |
| `fxTotal` | |
| `fxiContour` | |

: General functions  not ready for telemetry.  {#tbl-telemetrynonfunctions .sm}

[secr-datainput.pdf]: https://www.otago.ac.nz/density/pdfs/secr-datainput.pdf
```{=html}
<script data-collect-dnt="true" async src="https://scripts.simpleanalyticscdn.com/latest.js"></script>
```