# Spatial Interaction Function Objects

`twinstim_siaf.Rd`

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`

.

## Arguments

- f
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).- F
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.- Fcircle
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).- effRange
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.- deriv
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.- Deriv
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.- simulate
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)`

.- npars
the number of parameters of the spatial interaction function

`f`

(i.e. the length of its second argument).- validpars
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`

.

## See also

`siaf.gaussian`

for a pre-defined spatial interaction
function, and `tiaf`

for the temporal interaction function.