gail: Geo-Assignment of Irregular Locations
In jelsema/GAIL: Geo-Assigment of Irregular Locations

Description Usage Arguments Details Value See Also

Stochastic allocation of irregular spatial units to nearby regular spatial units. Both sets of of spatial units are assummed to be represented by their centroid (hence they should be POINT objects, and not POLYGON objects). Several methods are available for allocating irregular units, including equal probability, inverse centroid distance, and use of an index variable. Alternatively the user may specify a custom function to determine allocation probabilities.

1 2	gail(sp_units, cases, suid, num_cases, max_dist, RAP = gail_rap, seed = NULL, unit_value = "m", convert = FALSE, ...)

`sp_units`	Data frame of regular spatial units, see details.
`cases`	Data frame containing the the cases, see details.
`suid`	Column name in both `cases` and `sp_units` which contains the spatial unit identification / name.
`num_cases`	Column name from `cases` containing the number of cases, see details.
`max_dist`	The maximum distance at which two locations can be considered neighbors.
`RAP`	Function to be used for calculating assignment probabilities, see details.
`seed`	If given, sets the seed for the RNG.
`unit_value`	The units of distance, default to meters. See units::set_units.
`convert`	Logical, convert returned object to `Spatial*` type objects (from sp).
`...`	Space for additional arguments (e.g., for `RAP`).

sp_units is the set of spatial units that are the "destination", the cases will be aggregated to this set of units. It should not contain duplicate spatial units, and should not have any spatial units on a different scale. It must either be an object of class sf with POINT or POLYGON geometry, or it must have variables longitude and latitude to be convertable into an object of class sf.
cases contains the units (and associated number of cases) to be allocated. As with sp_units, this must either already have class sf or have latitude and longitude to be converted to an sf object.

The dataset of cases should be aggregated and have a column for the number of cases. If the column given by num_cases does not exist in cases, then cases will be aggregated by suid to create the column.

Cases will first be allocated deterministically by exact matches with suid. Any remaining cases will be allocated stochastically.
RAP : The argument controls how irregular spatial units are allocated to regular spatial units. There are several formats this can take. If RAP is a function, it will be used. Otherwise gail_rap is used. By default the internal function gail_rap is used with arguments method and index_var (see documentation of gail_rap) determined by:
- If RAP is a column name from sp_units then method="index" and index_var = RAP .
- If RAP="icd" then method="icd" and index_var = NULL .
- Otherwise, method="equal" and index_var = NULL .

The user may also specify only method and/or index_val to control the behavior of gail_rap appropriately.

Returns a list containing four elements:

rap_method: The method of stochastic allocation
units_reg: A copy of the input sp_units with the number of cases detrministically allocated.
units_irr: The irregular spatial units and the number of cases which were stochastically allocated from these units to the regular spatial unit.
sp_units: A copy of the input sp_units along with the number of cases (following allocation).