fxi {secr} | R Documentation

## Probability Density of Home Range Centre

### Description

Display contours of the probability density function for the estimated location of one or more range centres, compute values for particular points X, or compute mode of pdf. The pdf is given by f(X_j|ω_i) = Pr(ω_i|X)π(X_j), where π(X) is the probability density of range centres across the mask (Borchers and Efford 2008).

### Usage

    fxi.contour (object, i = 1, sessnum = 1, border = 100, nx = 64,
        levels = NULL, p = seq(0.1,0.9,0.1), plt = TRUE, add = FALSE,
        fitmode = FALSE, plotmode = FALSE, normal = TRUE, fill = NULL,
        SPDF = FALSE, ncores = 1, ...)
    fxi.secr(object, i = 1, sessnum = 1, X, normal = TRUE, ncores = 1)
    fxi.mode(object, i = 1, sessnum = 1, start = NULL, ...)

### Arguments

`object` | a fitted secr model
`i` | integer or character vector of individuals for which to plot contours, or a single individual as input to other functions
`sessnum` | session number if `object$capthist` spans multiple sessions
`border` | width of blank margin around the outermost detectors
`nx` | dimension of interpolation grid in x-direction
`levels` | numeric vector of confidence levels for Pr(X|wi)
`p` | numeric vector of contour levels as probabilities
`plt` | logical to plot contours
`add` | logical to add contour(s) to an existing plot
`fitmode` | logical to refine estimate of mode of each pdf
`plotmode` | logical to plot mode of each pdf
`X` | 2-column matrix of x- and y- coordinates
`normal` | logical; should values of pdf be normalised?
`fill` | vector of colours to fill contours (optional)
`SPDF` | logical; if TRUE the output is a SpatialPolygonsDataFrame
`ncores` | integer number of cores to be used for parallel processing
`start` | vector of x-y coordinates for maximization
`...` | additional arguments passed to `contour` or `nlm`

### Details

`fxi.contour` computes contours of probability density for one or more detection histories. Increase `nx` for smoother contours. If `levels` is not set, contour levels are set to approximate the confidence levels in `p`.

`fxi.secr` computes the probability density for one or more detection histories; `X` may contain coordinates for one or several points; a dataframe or vector (x then y) will be coerced to a matrix.

`fxi.mode` attempts to find the x- and y-coordinates corresponding to the maximum of the pdf for a single detection history (i.e. `i` is of length 1). `fxi.mode` calls `nlm`.

`fxi.contour` with `fitmode = TRUE` calls `fxi.mode` for each individual. Otherwise, the reported mode is an approximation (mean of coordinates of highest contour).

If `i` is character it will be matched to row names of object$capthist (restricted to the relevant session in the case of a multi-session fit); otherwise it will be interpreted as a row number.

Values of the pdf are optionally normalised by dividing by the integral of Pr(ω_i|X)π(X) over the habitat mask in `object`.

If `ncores` and length(i) are both greater than 1 then multiple worker processes will be run in separate cores to speed up the calculations.

If `start` is not provided to `fit.mode` then (from 2.9.4) the weighted mean of all detector sites is used (see Warning below).

The ... argument gives additional control over a contour plot; for example, set `drawlabels = FALSE` to suppress contour labels.

### Value

`fxi.contour` (SPDF = FALSE) –

Coordinates of the plotted contours are returned as a list with one component per polygon. The list is returned invisibly if plt = TRUE.

An additional component ‘mode’ reports the x-y coordinates of the highest point of each pdf (see Details).

`fxi.contour` (SPDF = TRUE) –

Contours are returned as a SpatialPolygonsDataFrame (see package sp) with one component per animal. The attributes dataframe has two columns, the x- and y-coordinates of the mode. The SpatialPolygonsDataFrame is returned invisibly if plt = TRUE.

`fxi.secr` –

Vector of probability densities

`fxi.mode` –

List with components ‘x’ and ‘y’

### Warnings

Use ncores > 1 only if there is adequate memory available for each worker process. Otherwise processing will slow to a crawl. This is a particular problem in `fxi.contour` with fitmode = TRUE. In Windows, check memory usage under the Performace tab of the Task Manager (Ctrl-Alt-Delete). If you abort a parallel job you may need to manually delete the stranded Rscript processes in Task Manager.

`fxi.mode` may fail to find the true mode unless a good starting point is provided. Note that the distribution may have multiple modes and only one is reported. The default value of `start` before secr 2.9.4 was the first detected location of the animal.

### Note

From secr 2.8.3, these functions work with both homogeneous and inhomogeneous Poisson density models, and `fxi.secr` accepts vector-valued `i`.

See `fx.total` for a surface summed across individuals.

### References

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximum likelihood methods for capture–recapture studies. Biometrics 64, 377–385.

### See Also

`pdot.contour`, `contour`, `fx.total`

### Examples

    fxi.secr(secrdemo.0, i = 1, X = c(365,605))

    ## contour first 5 detection histories
    plot(secrdemo.0$capthist)
    fxi.contour (secrdemo.0, i = 1:5, add = TRUE,
        plotmode = TRUE, drawlabels = FALSE)

    ## Not run:

      ## extract modes only
      ## these are more reliable than those from fit.mode called directly as
      ## they use a contour-based approximation for the starting point
      fxiout <- fxi.contour (secrdemo.0, i = 1:5, plt = FALSE, fitmode = TRUE)
      t(sapply(fxiout, "[[", "mode"))

      ## using fill colours
      ## lty = 0 suppresses contour lines
      ## nx = 256 ensures smooth outline
      plot(traps(captdata))
      fxi.contour(secrdemo.0, i = 1:5, add = TRUE, p = c(0.5,0.95), drawlabels
          = FALSE, nx = 256, fill = topo.colors(4), lty = 0)

      ## output as SpatialPolygonsDataFrame
      spdf <- fxi.contour(secrdemo.0, i = 1:3, plt = FALSE, p = c(0.5,0.95),
          nx = 256, SPDF = TRUE, fitmode = TRUE)

      ## save as ESRI shapefile
      library(maptools)
      writeSpatialShape(spdf, fn = "test")

      ## plot contours and modes
      plot(spdf)
      points(data.frame(spdf))

    ## End(Not run)

[Package secr version 3.2.1 Index]