A spatial interaction function for use in twinstim
can be constructed via the siaf function.
It checks the supplied function elements, assigns defaults for
missing arguments, and returns all checked arguments in a list.
However, for standard applications it is much easier to use one of the
pre-defined spatial interaction functions, e.g.,
siaf.gaussian.
siaf(f, F, Fcircle, effRange, deriv, Deriv, simulate, npars,
validpars = NULL)list of checked arguments.
the spatial interaction function. It must accept
two arguments, the first one being a (2-column) coordinate matrix, the
second one a parameter vector. For marked twinstim, it must
accept the type of the event (integer code) as its third argument
(either a single type for all locations or separate types for each
location).
function computing the integral of \(f(s)\) (passed as
second argument) over a polygonal "owin" domain (first argument).
The third and fourth argument are
the parameter vector and the (single) type, respectively.
There may be additional arguments, which can then be specified in
the control.siaf$F argument list of twinstim. If the F
function is missing, a general default (polyCub)
will be used, with extra arguments method (default: "SV")
and corresponding accuracy parameters.
optional function for fast calculation of the
(two-dimensional) integral of \(f(s)\) over a circle with radius
r (first argument). Further arguments are as for f. It
must not be vectorized (will always be called with single radius
and a single type). If this function is specified, integration of
the siaf over the spatial influence region of an event will
be faster if the region is actually circular. This is the case if
the event is located at least a distance eps.s from the border
of the observation region W, or if the distance to the border
is larger than the effective integration range (if specified, see
effRange below).
optional function returning the “effective”
range of \(f(s)\) for the given set of parameters (the first and
only argument) such that the circle with radius effRange
contains the numerically essential proportion of the
integral mass. For the Gaussian kernel the default is
function (logsd) 6*exp(logsd). The return value must be a
vector of length nTypes (effective range for each type). This
function is only used if Fcircle is also specified.
optional derivative of \(f(s)\) with respect to
the parameters. It takes the same arguments as f but
returns a matrix with as many rows as there were coordinates in the
input and npars columns. This derivative is necessary for the
calculation of the score function in twinstim(), which is
advantageous for the numerical log-likelihood maximization.
function computing the integral of deriv (passed as
second argument) over a polygonal "owin" domain (first
argument). The return value is thus a vector of length npars.
The third argument is the parameter vector and the fourth argument
is a (single) type and must be named type.
There may be additional arguments, which can then be specified in
the control.siaf$Deriv argument list of twinstim. If the
Deriv function is missing, a general default
(polyCub) will be used, with extra arguments
method (default: "SV") and corresponding accuracy parameters.
optional function returning a sample drawn from the
spatial kernel (only required for the simulation of twinstim
models). Its first argument is the size of the sample to
generate, next the parameter vector, an optional single event type,
and an optional upper bound for the radius within which to simulate
points. The function must return a two-column matrix of the
sampled locations.
Note that the simulation method actually samples only one location
at a time, thus it is sufficient to have a working
function(n=1, pars, type, ub).
the number of parameters of the spatial interaction
function f (i.e. the length of its second argument).
optional function taking one argument, the parameter vector, indicating if it
is valid. This approach to specify parameter constraints is rarely
needed, because usual box-constrained parameters can be taken into
account by using L-BFGS-B as the optimization method in
twinstim (with arguments lower and upper), and
positivity constraints by using log-parametrizations.
This component is not necessary (and ignored) if npars == 0.
Sebastian Meyer
siaf.gaussian for a pre-defined spatial interaction
function, and tiaf for the temporal interaction function.