polyCub (version 0.6.1)

polyCub.iso: Cubature of Isotropic Functions over Polygonal Domains

Description

Conducts numerical integration of a two-dimensional isotropic function \(f(x,y) = f_r(||(x,y)-\boldsymbol{\mu}||)\), with \(\mu\) being the center of isotropy, over a polygonal domain. It internally solves a line integral along the polygon boundary using integrate where the integrand requires the antiderivative of \(r f_r(r)\)), which ideally is analytically available and supplied to the function as argument intrfr. The two-dimensional integration problem thereby reduces to an efficient adaptive quadrature in one dimension. See Meyer and Held (2014, Supplement B, Section 2.4) for mathematical details.

.polyCub.iso is a “bare-bone” version of polyCub.iso.

Usage

polyCub.iso(polyregion, f, intrfr, ..., center, control = list(),
  check.intrfr = FALSE, plot = FALSE)
.polyCub.iso(polys, intrfr, ..., center, control = list(),
  .witherror = FALSE)

Arguments

polyregion

a polygonal domain. The following classes are supported: "owin", "gpc.poly", "'>SpatialPolygons", "'>Polygons", and "'>Polygon" (for these we have an internal xylist method).

f

a two-dimensional real function. As its first argument it must take a coordinate matrix, i.e., a numeric matrix with two columns, and it must return a numeric vector of length the number of coordinates.

intrfr

analytical antiderivative of \(r f_r(r)\) from 0 to R (first argument, not necessarily named "R", must be vectorized). If missing, intrfr is approximated numerically using integrate configured with control.

...

further arguments for f or intrfr.

center

numeric vector of length 2, the center of isotropy.

control

list of arguments passed to integrate, the quadrature rule used for the line integral along the polygon boundary.

check.intrfr

logical (or numeric vector) indicating if (for which r's) the supplied intrfr function should be checked against a numeric approximation. This check requires f to be specified. If TRUE, the set of test r's defaults to a seq of length 20 from 1 to the maximum absolute x or y coordinate of any edge of the polyregion.

plot

logical indicating if an image of the function should be plotted together with the polygonal domain, i.e., plotpolyf(polyregion, f, …).

polys

something like owin$bdry, but see xylist.

.witherror

logical indicating if an upper bound for the absolute integration error should be attached as an attribute to the result?

Value

The approximate integral of the isotropic function f over polyregion. If the intrfr function is provided (which is assumed to be exact), an upper bound for the absolute integration error is appended to the result as attribute "abs.error". It equals the sum of the absolute errors reported by all integrate calls (there is one for each edge of polyregion).

References

Hedevang, E. (2013). Personal communication at the Summer School on Topics in Space-Time Modeling and Inference (May 2013, Aalborg, Denmark).

Meyer, S. and Held, L. (2014). Power-law models for infectious disease spread. The Annals of Applied Statistics, 8 (3), 1612-1639. DOI-Link: https://doi.org/10.1214/14-AOAS743, arXiv:1308.5115

See Also

system.file("include", "polyCubAPI.h", package = "polyCub") for a full C-implementation of this cubature method (for a single polygon). The corresponding C-routine polyCub_iso can be used by other R packages, notably surveillance, via LinkingTo: polyCub (in the DESCRIPTION) and #include <polyCubAPI.h> (in suitable /src files). Note that the intrfr function must then also be supplied as a C-routine. An example can be found in the package tests.

Other polyCub-methods: polyCub.SV, polyCub.exact.Gauss, polyCub.midpoint, polyCub

Examples

# NOT RUN {
## we use the example polygon and f (exponential decay) from
example(plotpolyf)

## numerical approximation of 'intrfr'
(intISOnum <- polyCub.iso(letterR, f, center = fcenter))

## analytical 'intrfr'
## intrfr(R) = int_0^R r*f(r) dr, for f(r) = dexp(r), gives
intrfr <- function (R, rate = 1) pgamma(R, 2, rate) / rate
(intISOana <- polyCub.iso(letterR, intrfr = intrfr, center = fcenter))

stopifnot(all.equal(intISOana, intISOnum, check.attributes = FALSE))


### polygon area: f(r) = 1, f(x,y) = 1, center does not really matter

## intrfr(R) = int_0^R r*f(r) dr = int_0^R r dr = R^2/2
intrfr.const <- function (R) R^2/2
(area.ISO <- polyCub.iso(letterR, intrfr = intrfr.const, center = c(0,0)))

stopifnot(all.equal(spatstat::area.owin(spatstat::owin(poly = letterR)),
                    area.ISO, check.attributes = FALSE))
## the hole is subtracted correctly
# }