densityHeat.lpp {spatstat.linnet} | R Documentation |
Kernel Density on a Network using Heat Equation
Description
Given a point pattern on a linear network, compute a kernel estimate of intensity, by solving the heat equation.
Usage
## S3 method for class 'lpp'
densityHeat(x, sigma=NULL, ...,
at=c("pixels", "points"), leaveoneout=TRUE,
weights = NULL,
dx = NULL, dt = NULL, iterMax = 1e+06,
finespacing = TRUE, verbose=FALSE)
Arguments
x |
Point pattern on a linear network (object of class |
sigma |
Smoothing bandwidth (standard deviation of the kernel).
A numeric value in the same units as the spatial coordinates of |
... |
Arguments passed to |
at |
String specifying whether to compute the intensity values
at a fine grid of pixel locations on the network
( |
leaveoneout |
Logical value indicating whether to compute a leave-one-out
estimator. Applicable only when |
weights |
Optional. Numeric vector of weights associated with the
points of |
dx |
Optional. Spacing of the sampling points along the network.
A single number giving a distance value in the same units as |
dt |
Optional. Time step in the heat equation solver. A single number. |
iterMax |
Maximum number of iterations. |
finespacing |
Logical value specifying whether the discrete approximation is required to be accurate along every segment of the network, no matter how short the segment is. See the section on Discretisation. |
verbose |
Logical value specifying whether to print progress reports. |
Details
The function densityHeat
is generic.
This is the method for the class "lpp"
of points on a linear
network.
Kernel smoothing is applied to the points of x
using a kernel based on path distances in the network.
If at="pixels"
(the default),
the result is a pixel image on the linear network (class
"linim"
) which can be plotted.
If at="points"
the result is a numeric vector giving the
density estimates at the data points of x
.
The smoothing operation is equivalent to the
“equal-split continuous” rule described in
Section 9.2.3 of Okabe and Sugihara (2012).
However, the actual computation is performed rapidly, by solving the classical
time-dependent heat equation on the network,
as described in McSwiggan et al (2016).
Computational time is short, but increases quadratically with
sigma
.
If at="points"
and leaveoneout=TRUE
,
a leave-one-out estimate is computed at each data point
(that is, the estimate at each data point x[i]
is based
on all of the points except x[i]
)
using the truncated series approximation
of McSwiggan et al (2019).
The argument sigma
specifies the smoothing bandwidth.
If sigma
is missing or NULL
,
the default is one-eighth of the length of the shortest side
of the bounding box of x
.
If sigma
is a function in the R language, it is assumed
to be a bandwidth selection rule, and it will be applied to x
to compute the bandwidth value.
Value
If at="pixels"
(the default),
a pixel image on the linear network (object of class "linim"
).
If at="points"
, a numeric vector with one entry for each point
of x
.
Infinite bandwidth
If sigma=Inf
, the resulting density estimate is
constant over all locations,
and is equal to the average density of points per unit length.
(If the network is not connected, then this rule
is applied separately to each connected component of the network).
Discretisation and Error Messages
The arguments dx
, dt
and iterMax
determine the discretisation of the network, according to
a set of rules. The argument finespacing
determines
which rule will be applied.
The arguments dx
, dt
, iterMax
are connected by several constraints; specifying one of these
arguments will affect the default values of the other two arguments.
The argument finespacing
specifies whether
a very fine spacing of sample points is required, in order to attain
hihg accuracy.
-
If
finespacing=TRUE
(the default), then the sample point spacingdx
must not exceed one-third of the length of the shortest segment of the network. This ensures that the discrete approximation is accurate along every segment, no matter how short the segment is. However, this may not be feasible if it implies a very large number of sample points, or a large number of iterations: in such cases, the code may terminate with an error about illegal values ofdx
,dt
oriterMax
. -
If
finespacing=FALSE
, then the sample point spacingdx
will be about one-half the width of a pixel in the default pixellation of the window ofx
. This is usually a much coarser resolution than the one selected byfinespacing=TRUE
. If it is too coarse, the pixel resolution can be refined using the argumentsdimyx
,eps
orxy
passed toas.mask
. For example,dimyx=512
would specify a 512 x 512 pixel grid. The default pixel resolution can be changed for the remainder of the R session byspatstat.options('npixel')
.
Author(s)
Adrian Baddeley Adrian.Baddeley@curtin.edu.au and Greg McSwiggan.
References
McSwiggan, G., Baddeley, A. and Nair, G. (2016) Kernel density estimation on a linear network. Scandinavian Journal of Statistics 44, 324–345.
McSwiggan, G., Baddeley, A. and Nair, G. (2019) Estimation of relative risk for events on a linear network. Statistics and Computing 30, 469–484.
Okabe, A. and Sugihara, K. (2012) Spatial analysis along networks. Wiley.
See Also
Examples
X <- runiflpp(3, simplenet)
D <- densityHeat(X, 0.2)
plot(D, style="w", main="", adjust=2)
densityHeat.lpp(X, 0.2, at="points")
Dw <- densityHeat(X, 0.2, weights=c(1,2,-1))