% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/polyCub.iso.R
\name{polyCub.iso}
\alias{polyCub.iso}
\alias{.polyCub.iso}
\title{Cubature of Isotropic Functions over Polygonal Domains}
\usage{
polyCub.iso(polyregion, f, intrfr, ..., center, control = list(),
  check.intrfr = FALSE, plot = FALSE)

.polyCub.iso(polys, intrfr, ..., center, control = list(),
  .witherror = FALSE)
}
\arguments{
\item{polyregion}{a polygonal domain.
The following classes are supported:
\code{"\link[spatstat.geom]{owin}"} from package \pkg{spatstat.geom},
\code{"gpc.poly"} from \pkg{gpclib},
\code{"\link[sp:SpatialPolygons-class]{SpatialPolygons}"},
\code{"\link[sp:Polygons-class]{Polygons}"},
and \code{"\link[sp:Polygon-class]{Polygon}"} from package \pkg{sp}, as well as
\code{"\link[sf:st_polygon]{(MULTI)POLYGON}"} from package \pkg{sf}.
(For these classes, \pkg{polyCub} knows how to get an \code{\link{xylist}}.)}

\item{f}{a two-dimensional real-valued 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.}

\item{intrfr}{a \code{function(R, ...)}, which implements the (analytical)
antiderivative of \eqn{r f_r(r)} from 0 to \code{R}. The first argument
must be vectorized but not necessarily named \code{R}.\cr
If \code{intrfr} is missing, it will be approximated numerically via
\preformatted{
  integrate(function(r, ...) r * f(cbind(x0 + r, y0), ...),
            0, R, ..., control = control)
}
where \code{c(x0, y0)} is the \code{center} of isotropy.
Note that \code{f} will \emph{not} be checked for isotropy.}

\item{...}{further arguments for \code{f} or \code{intrfr}.}

\item{center}{numeric vector of length 2, the center of isotropy.}

\item{control}{list of arguments passed to \code{\link{integrate}}, the
quadrature rule used for the line integral along the polygon boundary.}

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

\item{plot}{logical indicating if an image of the function should be plotted
together with the polygonal domain, i.e.,
\code{\link{plotpolyf}(polyregion, f, \dots)}.}

\item{polys}{something like \code{owin$bdry}, but see \code{\link{xylist}}.}

\item{.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
\code{f} over \code{polyregion}.\cr
If the \code{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 \code{"abs.error"}. It equals the sum of the absolute errors
reported by all \code{\link{integrate}} calls
(there is one for each edge of \code{polyregion}).
}
\description{
\code{polyCub.iso} numerically integrates a radially symmetric function
\eqn{f(x,y) = f_r(||(x,y)-\boldsymbol{\mu}||)}{f(x,y) = f_r(||(x,y)-\mu||)},
with \eqn{\mu} being the center of isotropy, over a polygonal domain.
It internally approximates a line integral along the polygon boundary using
\code{\link{integrate}}. The integrand requires the antiderivative of
\eqn{r f_r(r)}), which should be supplied as argument \code{intrfr}
(\code{f} itself is only required if \code{check.intrfr=TRUE}).
The two-dimensional integration problem thereby reduces to an efficient
adaptive quadrature in one dimension.
If \code{intrfr} is not available analytically, \code{polyCub.iso} can use a
numerical approximation (meaning \code{integrate} within \code{integrate}),
but the general-purpose cubature method \code{\link{polyCub.SV}} might be
more efficient in this case.
See \bibcitet{|meyer.held2014|Supplement B, Section 2.4}
for mathematical details.

\code{.polyCub.iso} is a \dQuote{bare-bone} version of \code{polyCub.iso}.
}
\examples{
## we use the example polygon and f (exponential decay) from
example(plotpolyf)

## numerical approximation of 'intrfr' (not recommended)
(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, f, intrfr = intrfr, center = fcenter,
                          check.intrfr = TRUE))
## f is only used to check 'intrfr' against a numerical approximation

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)))

if (require("spatstat.geom")) { # check against area.owin()
    stopifnot(all.equal(area.owin(owin(poly = letterR)),
                        area.ISO, check.attributes = FALSE))
}
}
\references{
\bibshow{*}
}
\seealso{
\code{system.file("include", "polyCubAPI.h", package = "polyCub")}
for a full C-implementation of this cubature method (for a \emph{single}
polygon). The corresponding C-routine \code{polyCub_iso} can be used by
other \R packages, notably \CRANpkg{surveillance}, via \samp{LinkingTo: polyCub}
(in the \file{DESCRIPTION}) and \samp{#include <polyCubAPI.h>} (in suitable
\file{/src} files). Note that the \code{intrfr} function must then also be
supplied as a C-routine. An example can be found in the package tests.

Other cubature methods: 
\code{\link{polyCub}()},
\code{\link{polyCub.SV}()},
\code{\link{polyCub.midpoint}()}
}
\author{
Sebastian Meyer

The basic mathematical formulation of this efficient integration for radially
symmetric functions was ascertained with great support by
Emil Hedevang (Dept. of Mathematics, Aarhus University, Denmark)
during the Summer School on Topics in
Space-Time Modeling and Inference (May 2013, Aalborg, Denmark).
}
\concept{cubature methods}
\keyword{math}
\keyword{spatial}
