Calculate irreplaceability scores for planning units selected in a solution using rarity weighted richness (based on Williams et al. 1996). Please note that this method is only recommended for large-scaled conservation planning exercises (i.e. more than 100,000 planning units) where irreplaceability scores cannot be calculated using the replacement cost method (replacement_cost()) in a feasible period of time. This is because rarity weighted richness scores cannot (i) account for the cost of different planning units, (ii) account for multiple management zones, and (iii) identify truly irreplaceable planning units---unlike the replacement cost metric which does not suffer any of these limitations.

rarity_weighted_richness(x, solution, ...)

# S4 method for ConservationProblem,numeric
rarity_weighted_richness(x, solution, rescale, ...)

# S4 method for ConservationProblem,matrix
rarity_weighted_richness(x, solution, rescale, ...)

# S4 method for ConservationProblem,data.frame
rarity_weighted_richness(x, solution, rescale, ...)

# S4 method for ConservationProblem,Spatial
rarity_weighted_richness(x, solution, rescale, ...)

# S4 method for ConservationProblem,sf
rarity_weighted_richness(x, solution, rescale, ...)

# S4 method for ConservationProblem,Raster
rarity_weighted_richness(x, solution, rescale, ...)

## Arguments

x problem() (i.e. ConservationProblem) object. numeric, matrix, data.frame, Raster, Spatial, or sf::sf() object. See the Details section for more information. not used. logical flag indicating if replacement cost values---excepting infinite (Inf) and zero values---should be rescaled to range between 0.01 and 1. Defaults to TRUE.

## Value

A numeric, matrix, RasterLayer, Spatial, or sf::sf() object containing the rarity weighted richness scores for each planning unit in the solution.

## Details

Rarity weighted richness scores are calculated using the following terms . Let $$I$$ denote the set of planning units (indexed by $$i$$), let $$J$$ denote the set of conservation features (indexed by $$j$$), let $$r_{ij}$$ denote the amount of feature $$j$$ associated with planning unit $$i$$, and let $$M_j$$ denote the maximum value of feature $$j$$ in $$r_{ij}$$ in all planning units $$i \in I$$. To calculate the rarity weighted richness (RWR) for planning unit $$k$$:

$$\mathit{RWR}_{k} = \sum_{j}^{J} \frac{ \frac{r_{kj}}{M_j} }{ \sum_{i}^{I} r_{ij}}$$

The argument to solution must correspond to the planning unit data in the argument to x in terms of data representation, dimensionality, and spatial attributes (if applicable). This means that if the planning unit data in x is a numeric vector then the argument to solution must be a numeric vector with the same number of elements; if the planning unit data in x is a RasterLayer then the argument to solution must also be a RasterLayer with the same number of rows and columns and the same resolution, extent, and coordinate reference system; if the planning unit data in x is a Spatial object then the argument to solution must also be a Spatial object and have the same number of spatial features (e.g. polygons) and have the same coordinate reference system; if the planning unit data in x is a sf::sf() object then the argument to solution must also be a sf::sf() object and have the same number of spatial features (e.g. polygons) and have the same coordinate reference system; if the planning units in x are a data.frame then the argument to solution must also be a data.frame with each column correspond to a different zone and each row correspond to a different planning unit, and values correspond to the allocations (e.g. values of zero or one).

Solutions must have planning unit statuses set to missing (NA) values for planning units that have missing (NA) cost data. For problems with multiple zones, this means that planning units must have missing (NA) allocation values in zones where they have missing (NA) cost data. In other words, planning units that have missing (NA) cost values in x should always have a missing (NA) value the argument to solution. If an argument is supplied to solution where this is not the case, then an error will be thrown.

## References

Williams P, Gibbons D, Margules C, Rebelo A, Humphries C, and Pressey RL (1996) A comparison of richness hotspots, rarity hotspots and complementary areas for conserving diversity using British birds. Conservation Biology, 10: 155--174.

## Examples

# seed seed for reproducibility
set.seed(600)

data(sim_pu_raster, sim_features)

# create minimal problem with binary decisions
p1 <- problem(sim_pu_raster, sim_features) %>%
add_default_solver(gap = 0, verbose = FALSE)
# \dontrun{
# solve problem
s1 <- solve(p1)

# print solution
print(s1)#> class      : RasterLayer
#> dimensions : 10, 10, 100  (nrow, ncol, ncell)
#> resolution : 0.1, 0.1  (x, y)
#> extent     : 0, 1, 0, 1  (xmin, xmax, ymin, ymax)
#> crs        : NA
#> source     : memory
#> names      : layer
#> values     : 0, 1  (min, max)
#>
# plot solution
plot(s1, main = "solution", axes = FALSE, box = FALSE)
# calculate irreplaceability scores
rwr1 <- rarity_weighted_richness(p1, s1)

# print irreplaceability scores
print(rwr1)#> class      : RasterLayer
#> dimensions : 10, 10, 100  (nrow, ncol, ncell)
#> resolution : 0.1, 0.1  (x, y)
#> extent     : 0, 1, 0, 1  (xmin, xmax, ymin, ymax)
#> crs        : NA
#> source     : memory
#> names      : layer
#> values     : 0, 1  (min, max)
#>
# plot irreplaceability scores
plot(rwr1, main = "rarity weighted richness", axes = FALSE, box = FALSE)# }