Functions to create, plot and summarise a discrete representation of a movement kernel.
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 kernel
plot(x, type = "kernel", contour = FALSE, levels = NULL, text = FALSE,
title = NULL, add = FALSE, xscale = 1, ...)
# S3 method for kernel
summary(object, ...)
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.
character or function or openCR object
integer radius of kernel in grid cells
numeric spacing between cell centres
numeric parameter of kernel
numeric parameter of kernel
logical; if TRUE then only cardinal and intercardinal axes are included
logical; if TRUE then corner cells are removed
logical; if TRUE then cell values are divided by their sum
character; predicted statistic to use for move.a (openCR object only)
integer; session for move.a, move.b if input is fitted model
numeric; effective radius of zero cell for movement models
kernel object from make.kernel
character; plot style (see Details)
logical; if TRUE then contour lines are overlaid on any plot
numeric vector of contour levels
logical; if TRUE then cell probabilities are overprinted, rounded to 3 d.p.
character; if NULL a title is constructed automatically
logical; if TRUE a line is added to an existing plot (types "gr", "fr", "Fr")
numeric multiplier for distance axis (0.001 for distances in km)
other arguments passed to predict.openCR (make.kernel) or
plot.mask (plot type "kernel") or lines ( plot types "gr", "fr", "Fr") (not used by summary method)
kernel object from make.kernel
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).
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.
Movement models, mask, matchscale, dkernel, pkernel, qkernel
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
}
Run the code above in your browser using DataLab