userdist: Non-Euclidean Distances

Description

Non-Euclidean distances have a variety of uses, some obscure. You probably do not need them unless you have data from linear habitats, covered in the forthcoming package secrlinear. On the other hand, they open up some intriguing possibilities for the advanced user. The key is to provide an appropriate value for the component `userdist' of the details argument of secr.fit. details$userdist is either a function to compute non-Euclidean distances between detectors and mask points, or a pre-computed matrix of such distances. Pre-computing assumes the matrix is fixed (not dependent on any estimated coefficients). If details$userdist is a function then it should take the form userdist(xy1, xy2, mask)

Arguments

xy1

2-column matrix of x-y coordinates of $k$ detectors

xy2

2-column matrix of x-y coordinates of $m$ mask points

mask

habitat mask defining a non-Euclidean habitat geometry

Details

The matrix returned by the function must have exactly $k$ rows and $m$ columns. The function name may be almost anything you like. The non-Euclidean habitat geometry may or may not require access to local density (D), local (mask) covariates, and the estimation of additional coefficients (beta variables). In order that secr.fit can assemble these data, there is a mechanism for the user to indicate which, if any, variables are required: when called with no arguments the function should return a character vector of variable names. These may include covariates of `mask', the dynamically computed density `D`, and a special real parameter `noneuc' for which one or more coefficients will be fitted. `noneuc' is like 'D' in that it may be modelled as a function of any mask covariates, session, Session, x, y, etc. The actual meaning attributed to `noneuc' depends entirely on how it is used inside the function. The function may require no variables and not require estimation of additional coefficients. This is the case for a simple linear geometry as described in documentation for the package `secrlinear'. ll{ Value Interpretation '' no covariates etc. required 'D' density at each mask point 'noneuc' a multi-purpose real parameter defined for each mask point c('D', 'noneuc') both of the preceding c('noneuc','habclass') both noneuc and the mask covariate 'habclass' } The last case does not estimate a coefficient for habclass, it merely makes the raw value available to whatever algorithm you implement. The `xy2' and `mask' parameters of the userdist function overlap in practice: xy1 and xy2 only define the points between which distances are required, whereas mask is a carrier for any and all additional information needed by the algorithm. Full documentation of the secr capability for non-Euclidean distances is in the separate document ../doc/secr-noneuclidean.pdf, which includes example code for the analysis of Sutherland et al. (2014).

Compatibility

User-specified distances are compatible with some but not all features of secr. Functions with a `userdist' argument are certainly compatible, and others may be. User-specified distances cannot be used with polygon or transect detectors. When using sim.capthist to simulate detections of a new population from sim.popn you must provide userdist as a function rather than a matrix. This is because new animals are not restricted to locations on the `mask' grid.

References

Sutherland, C., Fuller, A. K. and Royle, J. A. (2014) Modelling non-Euclidean movement and landscape connectivity in highly structured ecological networks. Methods in Ecology and Evolution (in press).

Examples

Run this code

## see secr-noneuclidean.pdf