| userdist {secr} | R Documentation |
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 distances
between detectors and mask points, or a pre-computed matrix of such
distances. Pre-computing assumes the matrix is static (i.e. fixed and
not dependent on any estimated coefficients). The functions
edist and nedist are useful for computing
static matrices of Euclidean or non-Euclidean distances (the latter is
useful when there are barriers to movement).
If details$userdist is a function then it should take the form
userdist(xy1, xy2, mask)
xy1 |
2-column matrix of x-y coordinates of |
xy2 |
2-column matrix of x-y coordinates of |
mask |
habitat mask defining a non-Euclidean habitat geometry |
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’.
| 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 secr-noneuclidean.pdf, which includes example code for the analysis of Sutherland et al. (2015).
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.
With a static userdist, region.N will generally not calculate population size for a region other than the original mask. If you want to supply a new mask in the ‘region’ argument, replace x$details$userdist with a distance matrix appropriate to the new mask, where ‘x’ is the name of the fitted model.
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.
Sutherland, C., Fuller, A. K. and Royle, J. A. (2015) Modelling non-Euclidean movement and landscape connectivity in highly structured ecological networks. Methods in Ecology and Evolution 6, 169–177.
## see secr-noneuclidean.pdf