R/generics.R

Defines functions maximum.targets space.plot spp.plot selections `space.target<-` space.target space.held `amount.target<-` amount.target amount.held logging.file score prob.subset dp.subset pu.subset spp.subset

Documented in amount.held amount.target dp.subset logging.file maximum.targets prob.subset pu.subset score selections space.held space.plot space.target spp.plot spp.subset

#' @include RcppExports.R raptr-internal.R
NULL

#' Solve RAP object
#'
#' This function uses Gurobi to find prioritizations using the input parameter
#' and data stored in a [RapUnsolved()] object, and returns a
#' [RapSolved()] object with outputs in it.
#'
#' @param a [RapUnsolved()] or [RapSolved()] object.
#'
#' @param b `missing` to generate solutions using Gurobi. Prioritizations
#'   can be specified using  `logical`, `numeric`, or
#'   [base::matrix()] objects. This may be useful for evaluating the
#'   performance of solutions obtained using other software.
#'
#' @param verbose `logical` should messages be printed during creation of
#'   the initial model matrix?.
#'
#' @param ... not used.
#'
#' @return [RapSolved()] object
#'
#' @note This function is used to solve a [RapUnsolved()] object that
#'   has all of its inputs generated. The rap function (without lower case 'r')
#'   provides a more general interface for generating inputs and outputs.
#'
#' @seealso [RapUnsolved()], [RapSolved()].
#'
#' @examples
#' \dontrun{
#' # load RapUnsolved object
#' data(sim_ru)
#' # solve it using Gurobi
#' sim_rs <- solve(sim_ru)
#'
#' # evaluate manually specified solution using planning unit indices
#' sim_rs2 <- solve(sim_ru, seq_len(10))
#'
#' # evaluate manually specifed solution using binary selections
#' sim_rs3 <- solve(sim_ru, c(rep(TRUE, 10), rep(FALSE, 90)))
#'
#' #  evaluate multiple manually specified solutions
#' sim_rs4 <- solve(sim_ru, matrix(sample(c(0, 1), size = 500, replace = TRUE),
#'                  ncol = 100, nrow = 5))
#' }
#' @name solve
#'
#' @rdname solve
#'
#' @importFrom Matrix solve
#'
#' @export solve
NULL

#' Plot object
#'
#' This function plots the solutions contained in [RapSolved()]
#' objects. It can be used to show a single solution, or the the selection
#' frequencies of planning units contained in a single [RapSolved()]
#' object. Additionally, two [RapSolved()] objects can be supplied to
#' plot the differences between them.
#'
#' @param x [RapSolved()] object.
#'
#' @param y Available inputs are: `NULL` to plot selection frequencies,
#'   `numeric` number to plot a specific solution,
#'   `0` to plot the best solution, and a [RapSolved()]
#'   object to plot differences in solutions between objects. Defaults to
#'   `NULL`.
#'
#' @param i Available inputs are: `NULL` to plot selection frequencies.
#'   `numeric` to plot a specific solution, `0` to plot the best
#'   solution. This argument is only used when `y` is a
#'   [RapSolved()] object. Defaults to `NULL`.
#'
#' @param j Available inputs are: `NULL` to plot selection frequencies.
#'   `numeric` to plot a specific solution, `0` to plot the best
#'   solution. This argument is only used when `y` is a
#'   [RapSolved()] object. Defaults to argument `j`.
#'
#' @param basemap `character` object indicating the type of basemap to use
#'   (see [basemap()]). Valid options include `"none"`,
#'   `"roadmap"`, `"mobile"`, `"satellite"`, `"terrain"`,
#'   `"hybrid"`, `"mapmaker-roadmap"`, `"mapmaker-hybrid"`.
#'   Defaults to `"none"` such that no basemap is shown.
#'
#' @param pu.color.palette `character` vector of colors to indicate
#'   planning unit statuses.
#'   If plotting selection frequencies (i.e., `j = NULL`), then
#'   defaults to a `c("PuBu", "#FFFF00", "#FF0000")`.
#'   Here, the first element corresponds to a color palette
#'   (per [RColorBrewer::brewer.pal()]) and the last two elements
#'   indicate the colors for locked in and locked out planning units.
#'   Otherwise, the parameter defaults to a `character` vector of
#'   `c("grey30", "green", "yellow", "black", "gray80", "red", "orange")`.
#'
#' @param alpha `numeric` value to indicating the transparency level for
#'   coloring the planning units.
#'
#' @param grayscale `logical` should the basemap be gray-scaled?
#'
#' @param main `character` title for the plot. Defaults to `NULL` and
#'   a default title is used.
#'
#' @param force.reset `logical` if basemap data has been cached, should it
#'   be re-downloaded?
#'
#' @name plot
#'
#' @details
#' This function requires the \pkg{RgoogleMaps} package to be installed
#' in order to create display a basemap.
#'
#' @seealso [RapSolved()].
#'
#' @examples
#' \dontrun{
#' # load example data set with solutions
#' data(sim_rs)
#'
#' # plot selection frequencies
#' plot(sim_rs)
#'
#' # plot best solution
#' plot(sim_rs, 0)
#'
#' # plot second solution
#' plot(sim_rs, 2)
#'
#' # plot different between best and second solutions
#' plot(sim_rs, sim_rs, 0 ,2)
#' }
NULL

#' Names
#'
#' This function sets or returns the species names in an object.
#'
#' @param x [RapData()], [RapUnsolved()], or
#'   [RapSolved()] object.
#'
#' @param value new species names.
#'
#' @name names
#'
#' @seealso [RapData()], [RapUnsolved()],
#'   [RapSolved()].
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_rs)
#'
#' # show names
#' names(sim_rs)
#'
#' # change names
#' names(sim_rs) <- c('spp1', 'spp2', 'spp3')
#'
#' # show new names
#' names(sim_rs)
#' }
NULL

#' Print objects
#'
#' Prints objects.
#'
#' @param x [GurobiOpts()], [RapUnreliableOpts()],
#'   [RapReliableOpts()], [RapData()],
#'   [RapUnsolved()], [RapResults()], or
#'   [RapSolved()] object.
#'
#' @param header `logical` should object header be included?
#'
#' @param ... not used.
#'
#' @name print
#'
#' @seealso [GurobiOpts()], [RapUnreliableOpts()],
#'   [RapReliableOpts()], [RapData()],
#'   [RapUnsolved()], [RapResults()],
#'   [RapSolved()].
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_ru, sim_rs)
#'
#' # print GurobiOpts object
#' print(GurobiOpts())
#'
#' # print RapReliableOpts object
#' print(RapReliableOpts())
#'
#' # print RapUnreliableOpts object
#' print(RapUnreliableOpts())
#'
#' # print RapData object
#' print(sim_ru@@data)
#'
#' # print RapUnsolved object
#' print(sim_ru)
#'
#' # print RapResults object
#' print(sim_rs@@results)
#'
#' # print RapSolved object
#' print(sim_rs)
#' }
NULL

#' Show objects
#'
#' Shows objects.
#'
#' @param object [GurobiOpts()], [RapUnreliableOpts()],
#'   [RapReliableOpts()], [RapData()],
#'   [RapUnsolved()], [RapResults()], or
#'   [RapSolved()] object.
#'
#' @name show
#'
#' @seealso [GurobiOpts()], [RapUnreliableOpts()],
#'   [RapReliableOpts()], [RapData()],
#'   [RapUnsolved()], [RapResults()],
#'   [RapSolved()].
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_ru, sim_rs)
#'
#' # show GurobiOpts object
#' GurobiOpts()
#'
#' # show RapReliableOpts object
#' RapReliableOpts()
#'
#' # show RapUnreliableOpts object
#' RapUnreliableOpts()
#'
#' # show RapData object
#' sim_ru@@data
#'
#' # show RapUnsolved object
#' sim_ru
#'
#' # show RapResults object
#' sim_rs@@results
#'
#' # show RapSolved object
#' sim_rs
#' }
NULL

#' Convert object to list
#'
#' Convert [GurobiOpts()] object to list.
#'
#' @param x [GurobiOpts()] object.
#'
#' @param ... not used.
#'
#' @name as.list
#'
#' @return `list`
#'
#' @note This function will not include the `NumberSolutions` slot, the
#'  `MultipleSolutionsMethod` slot, or the `TimeLimit` slot if it is
#'  not finite.
#'
#' @seealso `GurobiOpts`.
#'
#' @examples
#' \dontrun{
#' # make GuboriOpts object
#' x <- GurobiOpts()
#'
#' # convert to list
#' as.list(x)
#' }
NULL

#' Summary of solutions
#'
#' Extracts summary of solutions in a [RapResults()] or
#' [RapSolved()] object.
#'
#' @param object [RapResults()], or [RapSolved()] object.
#'
#' @param ... not used.
#'
#' @details This table follows Marxan conventions
#'   (<https://marxansolutions.org/>). The
#'   columns are:
#' \describe{
#' \item{Run_Number}{The index of each solution in the object.}
#' \item{Status}{The status of the solution. The values in this column
#' correspond to outputs from the Gurobi software package (<https://www.gurobi.com/documentation/6.5/refman/optimization_status_codes.html>).}
#' \item{Score}{The objective function for the solution.}
#' \item{Cost}{Total cost associated with a solution.}
#' \item{Planning_Units}{Number of planning units selected in a solution.}
#' \item{Connectivity_Total}{The total amount of shared boundary length between
#' all planning units. All solutions in the same object should have equal
#' values for this column.}
#' \item{Connectivity_In}{The amount of shared boundary length among planning
#' units selected in the solution.}
#' \item{Connectivity_Edge}{The amount of exposed boundary length in the
#' solution.}
#' \item{Connectivity_Out}{The number of shared boundary length among planning
#' units not selected in the solution.}
#' \item{Connectivity_Fraction}{The ratio of shared boundary length in the
#' solution (`Connectivity_In`) to the total amount of boundary length
#' (`Connectivity_Edge`). This ratio is an indicator of solution quality.
#' Solutions with a lower ratio will have less planning units and will be more
#' efficient.}
#' }
#'
#' @name summary
#'
#' @return `data.frame`
#'
#' @seealso [RapResults()], [RapSolved()].
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_rs)
#'
#' # show summary
#' summary(sim_rs)
#' }
NULL

#' Update object
#'
#' This function updates parameters or data stored in an existing
#' [GurobiOpts()], [RapUnreliableOpts()],
#' [RapReliableOpts()], [RapData()],
#' [RapUnsolved()], or [RapSolved()] object.
#'
#' @param object [GurobiOpts()], [RapUnreliableOpts()],
#'   [RapReliableOpts()], [RapData()],
#'   [RapUnsolved()], or [RapSolved()] object.
#'
#' @param Threads `integer` number of cores to use for processing.
#'
#' @param MIPGap `numeric` MIP gap specifying minimum solution quality.
#'
#' @param Method `integer` Algorithm to use for solving model.
#'
#' @param Presolve `integer` code for level of computation in presolve.
#'
#' @param TimeLimit `integer` number of seconds to allow for solving.
#'
#' @param NumberSolutions `integer` number of solutions to generate.
#'
#' @param MultipleSolutionsMethod `integer` name of method to obtain
#'   multiple solutions (used when `NumberSolutions` is greater than one).
#'   Available options are `"benders.cuts"`, `"solution.pool.0"`,
#'   `"solution.pool.1"`, and `"solution.pool.2"`. The
#'   `"benders.cuts"` method produces a set of distinct solutions that
#'   are all within the optimality gap. The `"solution.pool.0"`
#'   method returns all solutions identified whilst trying to find
#'   a solution that is within the specified optimality gap. The
#'   `"solution.pool.1"` method finds one solution within the optimality
#'   gap and a number of additional solutions that are of any level of quality
#'   (such that the total number of solutions is equal to
#'   `number_solutions`). The `"solution.pool.2"` finds a
#'   specified number of solutions that are nearest to optimality. The
#'   search pool methods correspond to the parameters used by the Gurobi
#'   software suite (see <https://www.gurobi.com/documentation/8.0/refman/poolsearchmode.html#parameter:PoolSearchMode>).
#'   Defaults to `"benders.cuts"`.
#'
#' @param NumericFocus `integer` how much effort should Gurobi focus on
#'   addressing numerical issues? Defaults to `0L` such that minimal effort
#'   is spent to reduce run time.
#'
#' @param BLM `numeric` boundary length modifier.
#'
#' @param failure.multiplier `numeric` multiplier for failure planning
#'   unit.
#'
#' @param max.r.level `numeric` maximum R failure level for approximation.
#'
#' @param formulation `character` indicating new problem formulation to
#'   use. This can be either "unreliable" or "reliable". The default is
#'   `NULL` so that formulation in `object` is used.
#'
#' @param species `integer` or `character` denoting species for which
#'   targets or name should be updated.
#'
#' @param space `integer` denoting space for which targets should be
#'   updated.
#'
#' @param name `character` to rename species.
#'
#' @param amount.target `numeric` vector for new area targets (%) for the
#'   specified species.
#'
#' @param space.target `numeric` vector for new attribute space targets
#'   (%) for the specified species and attribute spaces.
#'
#' @param pu `integer` planning unit indices that need to be updated.
#'
#' @param status `integer` new statuses for specified planning units.
#'
#' @param cost `numeric` new costs for specified planning units.
#'
#' @param ... parameters passed to [update.RapReliableOpts()],
#'   [update.RapUnreliableOpts()], or [update.RapData()].
#'
#' @param solve `logical` should the problem be solved? This argument is
#'   only valid for [RapUnsolved()] and [RapSolved()]
#'   objects. Defaults to `TRUE`.
#'
#' @name update
#'
#' @return [GurobiOpts-class],
#'   [RapUnreliableOpts-class],
#'   [RapReliableOpts-class], [RapData-class],
#'   [RapUnsolved-class], or [RapSolved-class] object
#'   depending on argument to `x`.
#'
#' @seealso [GurobiOpts-class],
#'   [RapUnreliableOpts-class],
#'   [RapReliableOpts-class], [RapData-class],
#'   [RapUnsolved-class], [RapSolved-class].
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_ru, sim_rs)
#'
#' # GurobiOpts
#' x <- GurobiOpts(MIPGap = 0.7)
#' y <- update(x, MIPGap = 0.1)
#' print(x)
#' print(y)
#'
#' # RapUnreliableOpts
#' x <- RapUnreliableOpts(BLM = 10)
#' y <- update(x, BLM = 2)
#' print(x)
#' print(y)
#'
#' # RapReliableOpts
#' x <- RapReliableOpts(failure.multiplier = 2)
#' y <- update(x, failure.multiplier = 4)
#' print(x)
#' print(y)
#'
#' # RapData
#' x <- sim_ru@@data
#' y <- update(x, space.target = c(0.4, 0.7, 0.1))
#' print(space.target(x))
#' print(space.target(y))
#'
#' ## RapUnsolved
#' x <- sim_ru
#' y <- update(x, amount.target = c(0.1, 0.2, 0.3), BLM = 3, solve = FALSE)
#' print(x@@opts@@BLM); print(amount.target(x))
#' print(y@@opts@@BLM); print(space.target(y))
#'
#' ## RapSolved
#' x <- sim_rs
#' y <- update(x, space.target = c(0.4, 0.6, 0.9), BLM = 100, Presolve = 1L,
#'             solve = FALSE)
#' print(x@@opts@@BLM); print(amount.target(x))
#' print(y@@opts@@BLM); print(space.target(y))
#' }
NULL

#' Subset species
#'
#' Subset species from a [RapData()], [RapUnsolved()], or
#' [RapSolved()] object.
#'
#' @param x [RapData()], [RapUnsolved()], or
#'   [RapSolved()] object.
#'
#' @param species `integer`, or `character` vectors to specify the
#'   index or species names to subset.
#'
#' @return [RapData()] or [RapUnsolved()] object depending
#'   on input object.
#'
#' @seealso [RapData()], [RapUnsolved()],
#'   [RapSolved()].
#'
#' @rdname spp.subset
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_ru)
#'
#' # generate new object with only species 1
#' sim_ru2 <- spp.subset(sim_ru, 1)
#' }
#' @export
spp.subset <- function(x, species) UseMethod("spp.subset")

#' Subset planning units
#'
#' Subset planning units from a [RapData()],
#' [RapUnsolved()], or [RapSolved()] object.
#'
#' @param x [RapData()], [RapUnsolved()], or
#'   [RapSolved()] object.
#'
#' @param pu `integer` vector to specify the index of planning units to
#'  subset.
#'
#' @return [RapData()] or [RapUnsolved()] object depending
#'   on input object.
#'
#' @seealso [RapData()], [RapUnsolved()],
#'   [RapSolved()].
#'
#' @rdname pu.subset
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_ru)
#'
#' # generate new object with first 10 planning units
#' sim_ru2 <- pu.subset(sim_ru, seq_len(10))
#' }
#' @export
pu.subset <- function(x, pu) UseMethod("pu.subset")

#' Subset demand points
#'
#' Subset demand points from a [RapData()],
#' [RapUnsolved()], or [RapSolved()] object.
#'
#' @param x [RapData()], [RapUnsolved()], or
#'   [RapSolved()] object.
#'
#' @param space `integer` vector to specify the index of the space to
#'   subset demand points from.
#'
#' @param species `integer` vector to specify the index of the species to
#'   subset demand points from.
#'
#' @param points `integer` vector to specify the index of demand points to
#'   subset.
#'
#' @return [RapData()] or [RapUnsolved()] object depending
#'   on input object.
#'
#' @seealso [RapData()], [RapUnsolved()],
#'   [RapSolved()].
#'
#' @rdname dp.subset
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_ru)
#'
#' # generate new object with first 10 planning units
#' sim_ru2 <- dp.subset(sim_ru, 1, 1, seq_len(10))
#' }
#' @export
dp.subset <- function(x, space, species, points) UseMethod("dp.subset")

#' Subset probabilities above a threshold
#'
#' This function subsets out probabilities assigned to planning units above a
#' threshold. It effectively sets the probability that species inhabit planning
#' units to zero if they are below the threshold.
#'
#' @param x [RapData()], [RapUnsolved()], or
#'   [RapSolved()] object.
#'
#' @param species `integer` vector specifying the index of the species to
#'   which the threshold should be applied.
#'
#' @param threshold `numeric` probability to use a threshold.
#'
#' @return [RapData()] or [RapUnsolved()] object depending
#'   on input object.
#'
#' @seealso [RapData()], [RapUnsolved()],
#'   [RapSolved()].
#'
#' @rdname prob.subset
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_ru)
#'
#' # generate new object with first 10 planning units
#' sim_ru2 <- prob.subset(sim_ru, seq_len(3), c(0.1, 0.2, 0.3))
#' }
#' @export
prob.subset <- function(x, species, threshold) UseMethod("prob.subset")

#' Solution score
#'
#' Extract solution score from [RapResults()] or
#' [RapSolved()] object.
#'
#' @param x [RapResults()] or [RapSolved()] object.
#'
#' @param y Available inputs include: `NULL` to return all scores,
#'  `integer` number specifying the solution for which the score should
#'  be returned, and `0` to return score for the best solution.
#'
#' @return `matrix` or `numeric` vector with solution score(s)
#'  depending on arguments.
#'
#' @seealso [RapResults()], [RapSolved()].
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_rs)
#'
#' # score for the best solution
#' score(sim_rs, 0)
#'
#' # score for the second solution
#' score(sim_rs, 2)
#'
#' # score for all solutions
#' score(sim_rs, NULL)
#' }
#' @export
score <- function(x, y) UseMethod("score")

#' Log file
#'
#' This function returns the Gurobi log file (*.log) associated with solving
#' an optimization problem.
#'
#' @param x [RapResults()] or [RapSolved()] object.
#'
#' @param y Available inputs include: `NULL` to return all values,
#'  `integer` number specifying the solution for which the log file should
#'  be returned, and `0` to return log file for the best solution.
#'
#' @note The term logging file was used due to collisions with the `log`
#'   function.
#'
#' @seealso [RapResults()], [RapSolved()].
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_rs)
#'
#' # log file for the best solution
#' cat(logging.file(sim_rs, 0))
#'
#' # log file for the second solution
#' cat(logging.file(sim_rs, 2))
#'
#' # log files for all solutions
#' cat(logging.file(sim_rs, NULL))
#' }
#' @export
logging.file <- function(x, y) UseMethod("logging.file")

#' Extract amount held for a solution
#'
#' This function returns the amount held for each species in a solution.
#'
#' @param x [RapResults()] or [RapSolved()] object.
#'
#' @param y Available inputs include: `NULL` to return all values,
#'  `integer` number specifying the solution for which the value should
#'  be returned, and `0` to return the value for the best solution.
#'
#' @param species `NULL` for all species or `integer` indicating
#'   species.
#'
#' @return [base::matrix()] or `numeric` vector depending on
#'   arguments.
#'
#' @seealso [RapResults()], [RapSolved()].
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_rs)
#'
#' # amount held (%) in best solution for each species
#' amount.held(sim_rs, 0)
#'
#' # amount held (%) in best solution for species 1
#' amount.held(sim_rs, 0, 1)
#'
#' # amount held (%) in second solution for each species
#' amount.held(sim_rs, 2)
#'
#' # amount held (%) in each solution for each species
#' amount.held(sim_rs, NULL)
#' }
#' @export
amount.held <- function(x, y, species) UseMethod("amount.held")

#' Amount targets
#'
#' This function sets or returns the target amounts for each species.
#'
#' @param x [RapData()], [RapUnsolved()], or
#'   [RapSolved()] object.
#'
#' @param species `NULL` for all species or `integer` indicating
#'   species.
#'
#' @param value `numeric` new target.
#'
#' @return `numeric` vector.
#'
#' @seealso [RapData()], [RapResults()],
#'   [RapSolved()].
#'
#' @export
#'
#' @name amount.target
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_rs)
#'
#' # extract amount targets for all species
#' amount.target(sim_rs)
#'
#' # set amount targets for all species
#' amount.target(sim_rs) <- 0.1
#'
#' # extract amount targets for first species
#' amount.target(sim_rs, 1)
#'
#' # set amount targets for for first species
#' amount.target(sim_rs, 1) <- 0.5
#' }
#' @export
amount.target <- function(x, species) UseMethod("amount.target")

#' @rdname amount.target
#'
#' @export
`amount.target<-` <- function(x, species, value) UseMethod("amount.target<-")

#' Extract attribute space held for a solution
#'
#' This function returns the attribute space held for each species in a
#' solution.
#'
#' @param x [RapResults()] or [RapSolved()] object.
#'
#' @param y Available inputs include: `NULL` to return all values,
#'  `integer` number specifying the solution for which the value should
#'  be returned, and `0` to return the value for the best solution.
#'
#' @param species `NULL` for all species or `integer` indicating
#'   species.
#'
#' @param space `NULL` for all spaces or `integer` indicating a
#'   specific space.
#'
#' @return `matrix` object.
#'
#' @seealso [RapResults()], [RapSolved()].
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_rs)
#'
#' # space held (%) for each species in best solution
#' space.held(sim_rs, 0)
#'
#' # space held (%) for each species in second solution
#' space.held(sim_rs, 2)
#'
#' # space held (%) for each species in each solution
#' space.held(sim_rs)
#' }
#' @export
space.held <- function(x, y, species, space) UseMethod("space.held")

#' Attribute space targets
#'
#' This function sets or returns the attribute space targets for each species.
#'
#' @param x [RapData()], [RapUnsolved()], or [RapSolved()] object.
#'
#' @param species `NULL` for all species or `integer` indicating species.
#'
#' @param space `NULL` for all spaces or `integer` indicating a space.
#'
#' @param value `numeric` new target.
#'
#' @return A `numeric` or `matrix` objects.
#'
#' @seealso [RapData()], [RapResults()], [RapSolved()].
#'
#' @name space.target
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_rs)
#'
#' # extract space targets for all species
#' space.target(sim_rs)
#'
#' # set space targets for all species
#' space.target(sim_rs) <- 0.1
#'
#' # extract target for first species for first space
#' space.target(sim_rs, 1, 1)
#'
#' # set space targets for first species for first space
#' space.target(sim_rs, 1, 1) <- 0.5
#' }
#' @export
space.target <- function(x, species, space) UseMethod("space.target")

#' @rdname space.target
#'
#' @export
`space.target<-` <- function(x, species, space, value)
  UseMethod("space.target<-")

#' Extract solution selections
#'
#' Extract selections for a given solution from a [RapResults()] or
#' [RapSolved()] object.
#'
#' @param x [RapResults()] or [RapSolved()] object.
#'
#' @param y `NULL` to return all values, `integer` 0 to return values
#'   for the best solution, `integer` value greater than 0 for `y`'th
#'   solution value.
#'
#' @return [base::matrix()] or `numeric` vector depending on
#'   arguments.
#'
#' @seealso [RapResults()], [RapSolved()].
#'
#' @examples
#' \dontrun{
#' # load data
#' data(sim_rs)
#'
#' # selections for the best solution
#' selections(sim_rs, 0)
#'
#' # selections for the second solution
#' selections(sim_rs, 2)
#'
#' # selections for each solution
#' selections(sim_rs)
#' }
#' @export
selections <- function(x, y) UseMethod("selections")

#' Plot species
#'
#' This function plots the distribution of species across the study area.
#'
#' @inheritParams plot
#'
#' @param x [RapData()], [RapUnsolved()], or
#'   [RapSolved()] object.
#'
#' @param species `character` name of species, or `integer` index for
#'   species.
#'
#' @param y `NULL` `integer` 0 to return values for the best
#'   solution, `integer` value greater than 0 for `y`'th solution
#'   value.
#'
#' @param prob.color.palette `character` name of color palette to denote
#'   probability of occupancy of the species in planning units (see
#'   [RColorBrewer::brewer.pal()]). Defaults to `"YlGnBu"`.
#'
#' @param pu.color.palette `character` vector of colors to indicate planning
#'   unit statuses. Defaults to `c("grey30", "green", "black", "red")` which
#'   indicate not selected, selected, locked in, and locked out (respectively).
#'
#' @param ... not used.
#'
#' @inherit plot details
#'
#' @examples
#' \dontrun{
#' # load RapSolved objects
#' data(sim_ru, sim_rs)
#'
#' # plot first species in sim_ru
#' spp.plot(sim_ru, species = 1)
#'
#' # plot "bimodal" species in sim_rs
#' spp.plot(sim_rs, species = "bimodal")
#' }
#' @export
spp.plot <- function(x, species, ...) UseMethod("spp.plot")

#' Plot space
#'
#' This function plots the distribution of planning units and the distribution
#' of demand points for a particular species in an attribute space.
#' Note that this function only works for attribute spaces with one, two, or
#' three dimensions.
#'
#' @param x [RapData()], [RapUnsolved()], or [RapSolved()] object.
#'
#' @param species `character` name of species, or `integer` index for
#'   species.
#'
#' @param space `integer` index of attribute space.
#'
#' @param y `integer` number specifying the solution to be plotted. The
#'   value `0` can be used to plot the best solution.
#'
#' @param pu.color.palette `character` vector of colors indicate planning unit
#'   statuses. Defaults to `c("grey30", "green", "black", "red")` which
#'   indicate not selected, selected, locked in, and locked out (respectively).
#'
#' @param main `character` title for the plot. Defaults to `NULL` and
#'   a default title is used.
#'
#' @param ... not used.
#'
#' @examples
#' \dontrun{
#' # load RapSolved objects
#' data(sim_ru, sim_rs)
#'
#' # plot first species in first attribute space
#' space.plot(sim_ru, 1, 1)
#'
#' # plot distribution of solutions for first species in first attribute space
#' space.plot(sim_rs, 1, 1)
#' }
#' @export
space.plot <- function(x, species, space, ...) UseMethod("space.plot")

#' Maximum targets
#'
#' This function accepts a [RapUnsolved()] object and returns a
#' `data.frame` containing the amount-based and space-based targets for
#' each species and attribute space. These are calculated using a
#' prioritization that contains all the available planning units. Note that the
#' maximum amount-based targets are always 1.
#'
#' @param x [RapUnsolved()] or [RapSolved()] object.
#'
#' @param verbose `logical` should messages be printed during
#'   calculations? Defaults to `FALSE`.
#'
#' @return `data.frame` object.
#'
#' @examples
#' \dontrun{
#' # load RapSolved objects
#' data(sim_ru)
#'
#' # calculate maximum metrics
#' maximum.targets(sim_ru)
#' }
#' @export
maximum.targets <- function(x, verbose) UseMethod("maximum.targets")
paleo13/rapr documentation built on Feb. 12, 2024, 3:27 a.m.