Calculate the suitability of a set of observations

This function measures how suitable an observation is given set of metrics that tend to increase the favorability of a location. Z-scores are first calculated for each metric (with an optional threshold). These are then standardized between [0,1], and a weighted mean between all metrics is performed to find the global suitability. Values of zero indicate that all of the least-favorable values are coincident at that observation; values of one indicate that the location sees all of the most favorable conditions for each metric.

getSuitability(
  x,
  group.var = NULL,
  weights = NULL,
  suit.name = "Suit",
  stdev = 2,
  keep.vars = FALSE
)

Arguments

x: a numeric vector, data.frame, or data.table with metrics representing values that tend to increase (or decrease, if negative weights are provided) the favorability of an observation
group.var: (Optional) A character string representing the name of the column with group IDs, such that z-scores and suitabilities are calculated only within groups.
weights: (Optional) A named list of numerics or vector of class numeric by which to weigh favorability observations in the final suitability estimate. If NULL, all weights are given equal (positive) importance. If a negative weight is provided, the assumption is that higher values *decrease* favorability. If vector, it must be be of the same length as the number of variable columns in x. If named list, the names should correspond with the favorability metrics to consider, and the values to the strength of the weights. Missing values are assumed to have a zero weight.
suit.name: The name of the output net suitability column. Default is suit.name = 'Suit'. If NULL, only thresheld z-scores are calculated
stdev: The threshold value for z-scores (see rescaleSD). Default is stdev = 2
keep.vars: Should the thresheld z-scores for each variable be kept? Default is keep.vars = FALSE

Examples

# Creata dummy data
x <- data.table(A = c(1:10),
                B = c(11:20),
                C = c(21:30),
                D = c(31:40),
                ID = rep(c("a","b"),5))

# Create weights, don't consider 'C'
weights <- list(A = 1,
                B = 2,
                D = -1)
                
# Get suitabilities
getSuitability(x, group.var = 'ID', weights = weights, keep.vars = TRUE)
#>             A         B         D      Suit
#>  1: 0.5459431 0.5459431 0.7040569 0.5854715
#>  2: 0.5459431 0.5459431 0.7040569 0.5854715
#>  3: 0.5854715 0.5854715 0.6645285 0.6250000
#>  4: 0.5854715 0.5854715 0.6645285 0.6052358
#>  5: 0.6250000 0.6250000 0.6250000 0.6250000
#>  6: 0.6250000 0.6250000 0.6250000 0.6250000
#>  7: 0.6645285 0.6645285 0.5854715 0.6447642
#>  8: 0.6645285 0.6645285 0.5854715 0.6447642
#>  9: 0.7040569 0.7040569 0.5459431 0.6250000
#> 10: 0.7040569 0.7040569 0.5459431 0.6645285