| make.kernel {openCR} | R Documentation |
Discrete Movement Kernel
Description
Functions to create, plot and summarise a discrete representation of a movement kernel.
Usage
make.kernel(movementmodel = c("BVN", "BVE", "BVC", "BVT","RDE", "RDG", "RDL", "UNI"),
kernelradius = 10, spacing, move.a, move.b,
sparsekernel = FALSE, clip = FALSE, normalize = TRUE,
stat = c('estimate','lcl', 'ucl'), session = 1, r0 = 1/sqrt(pi), ...)
## S3 method for class 'kernel'
plot(x, type = "kernel", contour = FALSE, levels = NULL, text = FALSE,
title = NULL, add = FALSE, xscale = 1, ...)
## S3 method for class 'kernel'
summary(object, ...)
Arguments
movementmodel |
character or function or openCR object |
kernelradius |
integer radius of kernel in grid cells |
spacing |
numeric spacing between cell centres |
move.a |
numeric parameter of kernel |
move.b |
numeric parameter of kernel |
sparsekernel |
logical; if TRUE then only cardinal and intercardinal axes are included |
clip |
logical; if TRUE then corner cells are removed |
normalize |
logical; if TRUE then cell values are divided by their sum |
stat |
character; predicted statistic to use for move.a (openCR object only) |
session |
integer; session for move.a, move.b if input is fitted model |
r0 |
numeric; effective radius of zero cell for movement models |
x |
kernel object from |
type |
character; plot style (see Details) |
contour |
logical; if TRUE then contour lines are overlaid on any plot |
levels |
numeric vector of contour levels |
text |
logical; if TRUE then cell probabilities are overprinted, rounded to 3 d.p. |
title |
character; if NULL a title is constructed automatically |
add |
logical; if TRUE a line is added to an existing plot (types "gr", "fr", "Fr") |
xscale |
numeric multiplier for distance axis (0.001 for distances in km) |
... |
other arguments passed to |
object |
kernel object from |
Details
A kernel object is a type of mask with cell probabilities stored in the covariate ‘kernelp’. All kernels are truncated at kernelradius x spacing.
The movementmodel may also be a function or a previously fitted openCR model that includes movement. If a fitted openCR object, parameter values and kernel attributes are derived from that object and other arguments are ignored.
The parameter ‘move.a’ is a scale parameter in metres, except for the UNIzi and INDzi models for which it is the zero-inflation parameter (‘move.b’ is the zero-inflation parameter for BVNzi, BVEzi and RDEzi).
'Sparse' kernels include only those grid cells that lie on 4 axes (N-S, E-W, NW-SE, NE-SW); cell probabilities are adjusted to maintain nearly the same distance distribution as the non-sparse equivalents.
Movement models are listed in Movement models and further described in the vignettes openCR-vignette.pdf.
Plot type may be one or more of –
| `kernel' | coloured 2-D depiction | |
| `gr' | cross-section through the origin of g(r) (the 2-D kernel) |
|
| `fr' | continuous probability density f(r) |
|
| `Fr' | cumulative probability distribution F(r) |
|
Type “kernel" by default includes an informative title with font size from the graphical parameter ‘cex.main’. Set title = "" to suppress the title.
Useful properties of theoretical (not discretized) kernels may be recovered with matchscale, pkernel, dkernel and qkernel.
The obscure argument r0 controls the value assigned to the central cell of a discretized kernel. For positive r0 the value is F(r0*cellsize), where F is the cumulative probability distribution of distance moved. Otherwise the cell is assigned the value g(0)*cellarea, where g() is the 2-D kernel probability density (this fails where g(0) is undefined or infinite).
Value
make.kernel returns an object of class c('kernel','mask','data.frame').
The kernel object has attributes:
| Attribute | Description |
| movementmodel | saved input |
| K2 | saved kernelradius |
| move.a | saved input |
| move.b | saved input |
| distribution | empirical cumulative distribution function |
The empirical cumulative distribution is a dataframe with columns for the sorted cell radii ‘r’ and the associated cumulative probability ‘cumprob’ (one row per cell).
summary.kernel returns an object with these components, displayed with the corresponding print method.
| Component | Description |
| k2 | kernel radius in mask cells |
| spacing | cell width |
| ncells | number of cells in kernel |
| movementmodel | movement model code |
| move.a | first (scale) parameter |
| move.b | second (shape) parameter |
| mu | mean of logs (RDL only; from move.a) |
| s | SD of logs (RDL only; from move.b) |
| expectedmove | mean movement (untruncated) |
| expectedmovetr | mean movement (trucated at kernel radius) |
| expectedmoveemp | mean computed directly from kernel cell values as sum(r.p) |
| ptruncated | proportion of theoretical distribution truncated at radius |
| expectedq50 | theoretical (untruncated) median |
| expectedq90 | theoretical (untruncated) 90th percentile |
| expectedq50tr | theoretical truncated median |
| expectedq90tr | theoretical truncated 90th percentile |
The empirical mean in expectedmoveemp is usually the most pertinent property of a fitted kernel.
Note
The plot method for kernels supercedes the function plotKernel that has been removed.
References
Clark, J. S, Silman, M., Kern, R., Macklin, E. and HilleRisLambers, J. (1999) Seed dispersal near and far: patterns across temperate and tropical forests. Ecology 80, 1475–1494.
Efford, M. G. and Schofield, M. R. (2022) A review of movement models in open population capture–recapture. Methods in Ecology and Evolution 13, 2106–2118. https://doi.org/10.1111/2041-210X.13947
Ergon, T. and Gardner, B. (2014) Separating mortality and emigration: modelling space use, dispersal and survival with robust-design spatial capture–recapture data. Methods in Ecology and Evolution 5, 1327–1336.
Nathan, R., Klein, E., Robledo-Arnuncio, J. J. and Revilla, E. (2012) Dispersal kernels: review. In: J. Clobert et al. (eds) Dispersal Ecology and Evolution. Oxford University Press. Pp. 187–210.
See Also
Movement models, mask, matchscale, dkernel, pkernel, qkernel
Examples
k <- make.kernel(movementmodel = 'BVT', spacing = 10, move.a = 20, move.b = 1)
summary(k)
# read a previously fitted movement model packaged with 'openCR'
fit <- readRDS(system.file("exampledata", "spmOV.RDS", package = "openCR"))
k <- make.kernel(fit)
plot(k)
if (interactive()) {
spotHeight(k, dec = 3) # click on points; Esc to exit
}