kernel: Discrete Movement Kernel
In openCR: Open Population Capture-Recapture
make.kernel 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 make.kernel
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 predict.openCR (make.kernel) or
plot.mask (plot type "kernel") or lines ( plot types "gr", "fr", "Fr") (not used by summary method)
object
kernel object from make.kernel
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. In press.
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
}
openCR documentation built on Sept. 25, 2022, 5:06 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| make.kernel | 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. In press. 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
}
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.