1
#' @include RcppExports.R raptr-internal.R misc.R generics.R RapReliableOpts.R RapUnreliableOpts.R GurobiOpts.R RapData.R RapUnsolved.R RapResults.R RapSolved.R
2
NULL
3

4
#' Generate prioritizations using RAP
5
#'
6
#' This is a general function to create Rap objects from scratch and solve them
7
#' to generate solutions.
8
#'
9
#' @param pus [sp::SpatialPolygons()] object representing planning
10
#'   units.
11
#'
12
#' @param species [raster::raster()] object with species distribution
13
#'   data.
14
#'
15
#' @param spaces `list` of [raster::raster()] objects. Each
16
#'   elements denotes the spatial distribution for each space. Defaults to
17
#'   `NULL`.
18
#'
19
#' @param formulation `character` to indicate if the `"unreliable"` or
20
#'   `"reliable"` formulation should be used to generate prioritizations.
21
#'   Defaults to `"unreliable"`.
22
#'
23
#' @param solve `logical` should solutions be generated?
24
#'
25
#' @param ... arguments are passed to [GurobiOpts()],
26
#'   [make.RapData()], and [RapReliableOpts()] or
27
#'   [RapUnreliableOpts()] functions.
28
#'
29
#' @note Type `vignette("raptr")` to see the package vignette for a
30
#'   tutorial.
31
#'
32
#' @return [RapSolved()] object if `solve` is `TRUE`,
33
#'  otherwise an [RapUnsolved()] is returned.
34
#'
35
#' @seealso [GurobiOpts()], [RapReliableOpts()],
36
#'   [RapUnreliableOpts()] [RapData()],
37
#'   [RapResults()], [RapUnsolved()],
38
#'   [RapSolved()].
39
#'
40
#' @export
41
rap <- function(pus, species, spaces = NULL,
42
                formulation = c("unreliable", "reliable")[1], solve = TRUE,
43
                ...) {
44
  # set formulation
45 4
  match.arg(formulation, c("unreliable", "reliable"))
46 4
  if (formulation == "unreliable") {
47 4
    opts <- "RapUnreliableOpts"
48
  } else {
49 4
    opts <- "RapReliableOpts"
50
  }
51
  # check for unrecognised args
52 4
  all.args <- names(list(...))
53 4
  valid.args <- c(unlist(lapply(c(opts, "make.RapData", "GurobiOpts"),
54 4
                                function(fn) names(formals(fn)))),
55 4
                  "b", "verbose")
56 4
  invalid.args <- all.args[!all.args %in% valid.args]
57 4
  if (length(invalid.args) > 0)
58 0
    stop("Unrecognised arguments: ", paste(invalid.args, collapse = ", "))
59
  # create unsolved object
60 4
  x <- RapUnsolved(opts = do.call(opts, parseArgs(opts, object = NULL,
61 4
                                                  skip = NULL, ...)),
62 4
                  data = do.call(make.RapData,
63 4
                                 append(list(pus = pus, species = species,
64 4
                                             spaces = spaces),
65 4
                                        parseArgs("make.RapData",
66 4
                                                  object = NULL,
67 4
                                                  skip = NULL, ...))))
68
  # solve object if specified
69 4
  if (solve) {
70 0
    x <- do.call("solve", append(append(list(a = x),
71 0
                                        parseArgs2(c("b", "verbose"), ...)),
72 0
                                 parseArgs("GurobiOpts", object = NULL,
73 0
                                           skip = NULL, ...)))
74
  }
75
  # return object
76 4
  return(x)
77
}

Read our documentation on viewing source code .

Loading