Define GAT Merge Pattern

This function reads in the shapefile to be aggregated and the parameters to use. It returns a list of the following elements:

• A character vector in which the old IDs are replaced with the merged IDs, for the crosswalk.

• A data frame defining the polygons to be merged.

• An integer representing the number of merges completed.

• A string that includes any warnings generated during the merging.

defineGATmerge(
  area,
  gatvars,
  mergevars,
  exclist = NULL,
  pwrepeat = FALSE,
  adjacent = TRUE,
  pop = NULL,
  minfirst = FALSE,
  progressbar = TRUE
)

Arguments

area

A spatial layer representing areas to be aggregated.

gatvars

A list of objects created by GAT. It contains the strings myidvar, aggregator1, aggregator2, and boundary, which are all variables in the area, the boolean popwt, and the numbers minvalue1 and minvalue2. Both aggregator1 and aggregator2 must be numeric and myidvar must contain unique values.

mergevars

A list of string objects needed to aggregate the areas in the GAT tool. It contains mergeopt1, similar1, and similar2. The valid options for mergeopt1 are "closest", "least", and "similar". If "similar" is selected, similar1 and similar2 must be numeric variables in the area and similar2 cannot equal zero.

exclist

The settings to define areas to be excluded.

pwrepeat

A boolean denoting whether population weighting (if used) should be recalculated each time two areas are merged (TRUE) or if area centroids should be weighted with area populations (FALSE). If population weighting is not used, this option is ignored.

adjacent

A boolean denoting whether to force GAT to merge only adjacent areas.

pop

A spatial layer containing underlying population values.

minfirst

A boolean denoting whether or not to select the most desirable neighbor only from among the neighbors that have values below the desired minimum. If no neighbors are below the desired minimum, the most desirable of all eligible neighbors is selected.

progressbar

A boolean denoting whether to display the progress bar.

Details

For details on how merges are assigned, see vignette("gat_tech_notes", package = "gatpkg").

Examples

if (interactive()) {
gatvars <- list(
  myidvar = "ID",             # character variable of unique values
  aggregator1 = "TOTAL_POP",  # numeric variable
  minvalue1 = 5000,
  maxvalue1 = 15000,
  aggregator2 = "TOTAL_POP",  # numeric variable
  minvalue2 = 5000,
  maxvalue2 = 15000,
  boundary = "COUNTY",        # character variable of non-unique values
  rigidbound = TRUE,          # boolean to enforce boundary
  popwt = FALSE,              # boolean for population weighting
  popvar = "Pop"              # aggregation variable in population laayer
)

mergevars <- list(
  mergeopt1 = "similar",    # string can be similar, closest, or least
  similar1 = "AREAWATR",    # numeric variable
  similar2 = "AREALAND",    # numeric variable without any zeros
  centroid = "geographic"
)

exclist <- list(
  var1 = "TOTAL_POP", math1 = "less than", val1 = 500,
  var2 = "NONE", # if not "NONE", define math2 & val2
  var3 = "NONE"  # if not "NONE", define math3 & val3
)
my_merge <- defineGATmerge(
    area = hftown, pop = hfpop, gatvars = gatvars, mergevars = mergevars,
    exclist = exclist, progressbar = FALSE, pwrepeat = FALSE)
}