kpoints: Find solution to k-points algorithm

In DrylandEcology/rMultivariateMatching: Multivariate matching for site selection and interpolation using multi-dimensional datasets

Description

Determine a number (k) of points that maximize the areal coverage of a study area using a set of matching variables to determine similarity among sites.

Usage

kpoints(
  matchingvars,
  criteria = 1,
  klist = 200,
  min_area = 50,
  n_starts = 10,
  iter = 50,
  raster_template = NULL,
  verify_stop = FALSE,
  savebest = FALSE
)

Arguments

matchingvars	data frame generated using makeInputdata or formatted such that: rownames are 'cellnumbers' extracted using the extract function, columns 2 and 3 correspond to x and y coordinates, and additional columns correspond to potential matching variables extracted using the rasterToPoints function. Note that the 'cellnumbers' column must be present (and correspond to the cellnumbers of the raster used for raster_template for the kpoints function to work.
criteria	single value or vector of length equal to the number of matching variables, where values corresponds to the matching criterion for each matching variable in x. If a single value, this will be used as matching criteria for all variables. Default value is 1, corresponding to using raw data for kpoints algorithm.
klist	single value or vector of values of k to find solutions for. Default value is 200.
min_area	minimum value for change in area represented between iterations. If the change in area represented is at or below min_area for five consecutive iterations, the kpoints algorithm will assume convergence on an optimal solution and stop. Default value is 50.
n_starts	the number of random starts (k randomly selected points). For determining the optimal number of points, a small value (e.g., 10) should be sufficient. For finding the final solution for the desired number of points, a larger number (e.g., 100) should be used. Default value is 10.
iter	maximum number of iterations before the kpoints algorithm will stop. This parameter prevents kpoints from searching indefinitely for a solution. Default value is 50.
raster_template	one of the raster layers used for input data. See area.
verify_stop	boolean. Indicates whether the algorithm should display figures to evaluate stopping criteria. Displays a plot of areal coverage vs iteration for each of n_starts. Default is FALSE.
savebest	boolean. Saves solution for kpoints as .csv file of k Subset sites.

Value

A list, including:

• solutions A data frame of the final solution of k Subset cells. Rownames correspond to the cellnumbers, and the 'x' and 'y' coordinates of the cells are included.

• solution_areas The area (in km2) represented by the Subset cells.

• totalarea The area of the entire study area (in km2).

• klist The number of Subset cells (k) selected by the kpoints function.

• iter This records the value used in the kpoints function for finding the solution.

• n_starts This records the value used in the kpoints function for finding the solution.

• criteria This records the values used in the kpoints function for finding the solution.

• min_area This records the value used in the kpoints function for finding the solution.

Author(s)

Rachel R. Renne

Examples

# Load targetcells data for Target Cells
data(targetcells)

# Create data frame of potential matching variables for Target Cells
allvars <- makeInputdata(targetcells)

# Restrict data to matching variables of interest
matchingvars <- allvars[,c("cellnumbers","x","y","bioclim_01","bioclim_04",
                       "bioclim_09","bioclim_12","bioclim_15","bioclim_18")]

# Create raster_template
raster_template <- targetcells[[1]]

# Create vector of matching criteria
criteria <- c(0.7,42,3.3,66,5.4,18.4)

# Verify stopping criteria for 200 points
# Note: n_starts should be >= 10, it is 1 here to reduce run time.
results1 <- kpoints(matchingvars,criteria = criteria, klist = 200,
                    n_starts = 1, min_area = 50, iter = 50,
                    raster_template = raster_template,
                    verify_stop = TRUE, savebest = FALSE)

DrylandEcology/rMultivariateMatching documentation built on Dec. 17, 2021, 5:30 p.m.