Spatial Interaction Function Objects

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.

Usage

siaf(f, F, Fcircle, effRange, deriv, Deriv, simulate, npars,
     validpars = NULL)

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.

Value

list of checked arguments.

Author

Sebastian Meyer

See also

siaf.gaussian for a pre-defined spatial interaction function, and tiaf for the temporal interaction function.