Update vignettes (#216)

Update vignettes
Rebuild sites
Tweak grammar in some docs

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: prioritizr
 Type: Package
-Version: 7.1.1.4
+Version: 7.1.1.5
 Title: Systematic Conservation Prioritization in R
 Description:
     Systematic conservation prioritization using mixed integer linear

NEWS.md

@@ -1,3 +1,10 @@
+# prioritizr 7.1.1.5
+
+- The _Tasmania tutorial_ has been reworked into the _Getting started_ tutorial. This tutorial now provides short introduction to using the package.
+- The _Salt Spring Island tutorial_ has been reworked into the _Connectivity tutorial_. This tutorial now explores different approaches for incorporating connectivity.
+- The _prioritizr_ vignette has been renamed to the _Package overview_ vignette.
+- New _Calibrating trade-offs tutorial_ showcasing methods for running calibration analyses. It outlines blended and hierarchical approaches for generating a set of different prioritizations based on different parameters. It also covers different approaches for selecting a candidate prioritization based on different trade-offs.
+
 # prioritizr 7.1.1.4
 
 - Update tests to reduce run time and pass given slightly different results

R/ConservationProblem-proto.R

@@ -9,13 +9,13 @@ NULL
 #'
 #' This class is used to represent conservation planning problems. A
 #' conservation planning problem has spatially explicit planning units.
-#' A prioritization involves making a decision on each planning unit (e.g. is
+#' A prioritization involves making a decision on each planning unit (e.g., is
 #' the planning unit going to be turned into a protected area?). Each
 #' planning unit is associated with a cost that represents the cost incurred
 #' by applying the decision to the planning unit. The problem also has a set
 #' of representation targets for each feature. Further, it also has
 #' constraints used to ensure that the solution meets additional
-#' objectives (e.g. certain areas are locked into the solution). Finally,
+#' objectives (e.g., certain areas are locked into the solution). Finally,
 #' a conservation planning problem---unlike an optimization problem---also
 #' requires a method to solve the problem. **This class represents a
 #' planning problem, to actually build and then solve a planning problem,

R/Parameter-proto.R

@@ -22,7 +22,7 @@ NULL
 #' \item{$default}{`numeric` vector of default values.}
 #'
 #' \item{$class}{`character` name of the class that the values inherit
-#'   from (e.g. `"integer"`.}
+#'   from (e.g., `"integer"`.}
 #'
 #' \item{$lower_limit}{`numeric` vector specifying the minimum
 #'   permitted value for each element in `$value`.}

R/ScalarParameter-proto.R

@@ -22,7 +22,7 @@ NULL
 #' \item{$default}{`numeric` scalar default value.}
 #'
 #' \item{$class}{`character` name of the class that `$value` should
-#'   inherit from (e.g. `integer`).}
+#'   inherit from (e.g., `integer`).}
 #'
 #' \item{$lower_limit}{`numeric` scalar value that is the minimum value
 #'   that `$value` is permitted to be.}

R/add_absolute_targets.R

@@ -9,7 +9,7 @@ NULL
 #' planning units for which their summed feature values are equal to or greater
 #' than 10.
 #'
-#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
+#' @param x [problem()] (i.e., [`ConservationProblem-class`]) object.
 #'
 #' @param targets Object that specifies the targets for each feature.
 #'   See the Targets format section for more information.

R/add_binary_decisions.R

@@ -9,16 +9,16 @@ NULL
 #' the planning unit to include in a protected area network. If no decision is
 #' added to a problem then this decision class will be used by default.
 #'
-#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
+#' @param x [problem()] (i.e., [`ConservationProblem-class`]) object.
 #'
 #' @details Conservation planning problems involve making decisions on planning
-#'   units. These decisions are then associated with actions (e.g. turning a
+#'   units. These decisions are then associated with actions (e.g., turning a
 #'   planning unit into a protected area). Only a
 #'   single decision should be added to a `ConservationProblem` object.
 #'   Note that if multiple decisions are added to a problem object, then the
 #'   last one to be added will be used.
 #'
-#' @return Object (i.e. [`ConservationProblem-class`]) with the decisions added
+#' @return Object (i.e., [`ConservationProblem-class`]) with the decisions added
 #'   to it.
 #'
 #' @seealso

R/add_boundary_penalties.R

@@ -7,11 +7,11 @@ NULL
 #' that spatially clump planning units together based on the overall
 #' boundary length (perimeter).
 #'
-#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
+#' @param x [problem()] (i.e., [`ConservationProblem-class`]) object.
 #'
 #' @param penalty `numeric` penalty that is used to scale the importance
 #'   of selecting planning units that are spatially clumped together compared
-#'   to the main problem objective (e.g. solution cost when the argument to
+#'   to the main problem objective (e.g., solution cost when the argument to
 #'   `x` has a minimum set objective per [add_min_set_objective()]).
 #'   Higher `penalty` values prefer solutions with a higher degree of spatial
 #'   clumping, and smaller `penalty` values prefer solutions with a smaller
@@ -36,19 +36,19 @@ NULL
 #'   allocated to the same zone. Cell values must range between 1 and -1, where
 #'   negative values favor solutions that spread out planning units. The default
 #'   argument to `zones` is an identity
-#'   matrix (i.e. a matrix with ones along the matrix diagonal and zeros
+#'   matrix (i.e., a matrix with ones along the matrix diagonal and zeros
 #'   elsewhere), so that penalties are incurred when neighboring planning units
 #'   are not assigned to the same zone. If the cells along
 #'   the matrix diagonal contain markedly smaller values than those found
 #'   elsewhere in the matrix, then solutions are preferred that surround
 #'   planning units with those allocated to different zones
-#'   (i.e. greater spatial fragmentation).
+#'   (i.e., greater spatial fragmentation).
 #'
 #' @param data `NULL`, `data.frame`, `matrix`, or `Matrix`
 #'   object containing the boundary data. These data describe the total
 #'   amount of boundary (perimeter) length  for each planning unit,
 #'   and the amount of boundary (perimeter) length shared between different
-#'   planning units (i.e. planning units that are adjacent to each other).
+#'   planning units (i.e., planning units that are adjacent to each other).
 #'   See the Data format section for more information.
 #'
 #' @details
@@ -75,14 +75,14 @@ NULL
 #'   Note that the boundary data must be supplied
 #'   using one of the other formats below if the planning unit data
 #'   in the argument to `x` do not explicitly contain spatial information
-#'   (e.g. planning unit data are a `data.frame` or `numeric` class).}
+#'   (e.g., planning unit data are a `data.frame` or `numeric` class).}
 #'
 #' \item{`data` as a `matrix`/`Matrix` object}{where rows and columns represent
 #'   different planning units and the value of each cell represents the
 #'   amount of shared boundary length between two different planning units.
 #'   Cells that occur along the matrix diagonal represent the amount of
 #'   exposed boundary associated with each planning unit that has
-#'   no neighbor (e.g. these value might pertain to boundaries along a
+#'   no neighbor (e.g., these value might pertain to boundaries along a
 #'   coastline).}
 #'
 #' \item{`data` as a `data.frame` object}{with the columns `"id1"`,
@@ -91,7 +91,7 @@ NULL
 #'   column contains the amount of shared boundary length between these
 #'   two planning units.
 #'   This format follows the the standard *Marxan* format for boundary
-#'   data (i.e. per the "bound.dat" file).}
+#'   data (i.e., per the "bound.dat" file).}
 #'
 #' }
 #'
@@ -101,11 +101,11 @@ NULL
 #' (indexed by \eqn{i} or \eqn{j}), \eqn{Z} represent
 #' the set of management zones (indexed by \eqn{z} or \eqn{y}), and
 #' \eqn{X_{iz}}{Xiz} represent the decision
-#' variable for planning unit \eqn{i} for in zone \eqn{z} (e.g. with binary
+#' variable for planning unit \eqn{i} for in zone \eqn{z} (e.g., with binary
 #' values one indicating if planning unit is allocated or not). Also, let
 #' \eqn{p} represent the argument to `penalty`, \eqn{E_z}{Ez} represent the
 #' argument to `edge_factor`, \eqn{B_{ij}}{Bij} represent the matrix argument
-#' to `data` (e.g. generated using [boundary_matrix()]), and
+#' to `data` (e.g., generated using [boundary_matrix()]), and
 #' \eqn{W_{zz}}{Wzz} represent the matrix argument to `zones`.
 #'
 #' \deqn{
@@ -121,7 +121,7 @@ NULL
 #' benefit and not minimize some measure of cost, the term \eqn{p} is
 #' replaced with \eqn{-p}.
 #'
-#' @return Object (i.e. [`ConservationProblem-class`]) with the penalties
+#' @return Object (i.e., [`ConservationProblem-class`]) with the penalties
 #'  added to it.
 #'
 #' @seealso
@@ -214,7 +214,7 @@ NULL
 #'
 #' # create zone matrix which favors clumping planning units in zones 1 and 2
 #' # together, and favors planning units in zone 3 being spread out
-#' # (i.e. negative clumping)
+#' # (i.e., negative clumping)
 #' zm10 <- diag(3)
 #' zm10[3, 3] <- -1
 #' print(zm10)

R/add_cbc_solver.R

@@ -22,7 +22,7 @@ NULL
 #' Although formal benchmarks examining the performance of this solver for
 #' conservation planning problems have yet to be completed, preliminary
 #' analyses suggest that it performs much faster than the other open-source
-#' solvers (i.e. [add_rsymphony_solver()], [add_rsymphony_solver()]), and
+#' solvers (i.e., [add_rsymphony_solver()], [add_rsymphony_solver()]), and
 #' so we recommend using this solver if the *Gurobi* and *IBM CPLEX* solvers
 #' are unavailable.
 #'
@@ -45,7 +45,7 @@ NULL
 #'
 #' @inheritSection add_gurobi_solver Start solution format
 #'
-#' @return Object (i.e. [`ConservationProblem-class`]) with the solver
+#' @return Object (i.e., [`ConservationProblem-class`]) with the solver
 #'  added to it.
 #'
 #' @seealso

R/add_connectivity_penalties.R

@@ -6,11 +6,11 @@ NULL
 #' Add penalties to a conservation planning [problem()] to favor
 #' solutions that select planning units with high connectivity between them.
 #'
-#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
+#' @param x [problem()] (i.e., [`ConservationProblem-class`]) object.
 #'
 #' @param penalty `numeric` penalty that is used to scale the importance
 #'   of selecting planning units with strong connectivity between them compared
-#'   to the main problem objective (e.g. solution cost when the argument to
+#'   to the main problem objective (e.g., solution cost when the argument to
 #'   `x` has a minimum set objective set using
 #'   [add_min_set_objective()]). Higher `penalty` values
 #'   can be used to obtain solutions with a high degree of connectivity,
@@ -26,7 +26,7 @@ NULL
 #'   the level of connectivity between planning units allocated to the
 #'   same zone. Cell values must lay between 1 and -1, where negative
 #'   values favor solutions with weak connectivity. The default argument to
-#'   `zones` is an identity matrix (i.e. a matrix with ones along the
+#'   `zones` is an identity matrix (i.e., a matrix with ones along the
 #'   matrix diagonal and zeros elsewhere), so that planning units are
 #'   only considered to be connected when they are allocated to the same zone.
 #'   This argument is required when the argument to `data` is a
@@ -72,7 +72,7 @@ NULL
 #'   *Marxan* format. The data can be used to denote symmetric or
 #'   asymmetric relationships between planning units. By default,
 #'   input data is assumed to be symmetric unless asymmetric data is
-#'   also included (e.g. if data is present for planning units 2 and 3, then
+#'   also included (e.g., if data is present for planning units 2 and 3, then
 #'   the same amount of connectivity is expected for planning units 3 and 2,
 #'   unless connectivity data is also provided for planning units 3 and 2).
 #'   If the argument to `x` contains multiple zones, then the columns
@@ -86,7 +86,7 @@ NULL
 #'   containing four-dimensions where cell values
 #'   indicate the strength of connectivity between planning units
 #'   when they are assigned to specific management zones. The first two
-#'   dimensions (i.e. rows and columns) indicate the strength of
+#'   dimensions (i.e., rows and columns) indicate the strength of
 #'   connectivity between different planning units and the second two
 #'   dimensions indicate the different management zones. Thus
 #'   the `data[1, 2, 3, 4]` indicates the strength of
@@ -101,7 +101,7 @@ NULL
 #' (indexed by \eqn{i} or \eqn{j}), \eqn{Z} represent the set
 #' of management zones (indexed by \eqn{z} or \eqn{y}), and \eqn{X_{iz}}{Xiz}
 #' represent the decision variable for planning unit \eqn{i} for in zone
-#' \eqn{z} (e.g. with binary
+#' \eqn{z} (e.g., with binary
 #' values one indicating if planning unit is allocated or not). Also, let
 #' \eqn{p} represent the argument to `penalty`, \eqn{D} represent the
 #' argument to `data`, and \eqn{W} represent the argument
@@ -177,7 +177,7 @@ NULL
 #' }
 #' # create a symmetric connectivity matrix where the connectivity between
 #' # two planning units corresponds to their spatial proximity
-#' # i.e. planning units that are further apart share less connectivity
+#' # i.e., planning units that are further apart share less connectivity
 #' centroids <- rgeos::gCentroid(sim_pu_polygons, byid = TRUE)
 #' d_matrix <- (1 / (as(dist(centroids@coords), "Matrix") + 1))
 #'
@@ -220,7 +220,7 @@ NULL
 #'     # find if planning units are adjacent
 #'     if (adjacent_units[i, j]) {
 #'       # find if planning units lay north and south of each other
-#'       # i.e. they have the same x-coordinate
+#'       # i.e., they have the same x-coordinate
 #'       if (centroids@coords[i, 1] == centroids@coords[j, 1]) {
 #'         if (centroids@coords[i, 2] > centroids@coords[j, 2]) {
 #'           # if i is north of j add 10 units of connectivity

R/add_contiguity_constraints.R

@@ -7,12 +7,12 @@ NULL
 #' that all selected planning units are spatially connected with each other
 #' and form a single contiguous unit.
 #'
-#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
+#' @param x [problem()] (i.e., [`ConservationProblem-class`]) object.
 #'
 #' @param zones `matrix` or `Matrix` object describing the
 #'   connection scheme for different zones. Each row and column corresponds
 #'   to a different zone in the argument to `x`, and cell values must
-#'   contain binary `numeric` values (i.e. one or zero) that indicate
+#'   contain binary `numeric` values (i.e., one or zero) that indicate
 #'   if connected planning units (as specified in the argument to
 #'   `data`) should be still considered connected if they are allocated to
 #'   different zones. The cell values along the diagonal
@@ -21,7 +21,7 @@ NULL
 #'   arguments to `zones` must be symmetric, and that a row or column has
 #'   a value of one then the diagonal element for that row or column must also
 #'   have a value of one. The default argument to `zones` is an identity
-#'   matrix (i.e. a matrix with ones along the matrix diagonal and zeros
+#'   matrix (i.e., a matrix with ones along the matrix diagonal and zeros
 #'   elsewhere), so that planning units are only considered connected if they
 #'   are both allocated to the same zone.
 #'
@@ -44,16 +44,16 @@ NULL
 #'
 #' \item{`data` as a `NULL` value}{indicating that connection data should be
 #'   calculated automatically using the [adjacency_matrix()] function.
-#'   This is the default argument. 
+#'   This is the default argument.
 #'   Note that the connection data must be manually defined
 #'   using one of the other formats below when the planning unit data
-#'   in the argument to `x` is not spatially referenced (e.g.
+#'   in the argument to `x` is not spatially referenced (e.g.,
 #'   in `data.frame` or `numeric` format).}
 #'
 #' \item{`data` as a `matrix`/`Matrix` object}{where rows and columns represent
 #'   different planning units and the value of each cell indicates if the
 #'   two planning units are connected or not. Cell values should be binary
-#'   `numeric` values (i.e. one or zero). Cells that occur along the
+#'   `numeric` values (i.e., one or zero). Cells that occur along the
 #'   matrix diagonal have no effect on the solution at all because each
 #'   planning unit cannot be a connected with itself.}
 #'
@@ -66,7 +66,7 @@ NULL
 #'   or not. This data can be used to describe symmetric or
 #'   asymmetric relationships between planning units. By default,
 #'   input data is assumed to be symmetric unless asymmetric data is
-#'   also included (e.g. if data is present for planning units 2 and 3, then
+#'   also included (e.g., if data is present for planning units 2 and 3, then
 #'   the same amount of connectivity is expected for planning units 3 and 2,
 #'   unless connectivity data is also provided for planning units 3 and 2).}
 #'
@@ -76,7 +76,7 @@ NULL
 #' In early versions, this function was named as the
 #' `add_connected_constraints()` function.
 #'
-#' @return Object (i.e. [`ConservationProblem-class`]) with the constraints
+#' @return Object (i.e., [`ConservationProblem-class`]) with the constraints
 #'  added to it.
 #'
 #' @seealso

R/add_cplex_solver.R

@@ -18,12 +18,12 @@ NULL
 #' @details
 #' [*IBM CPLEX*](https://www.ibm.com/analytics/cplex-optimizer) is a
 #' commercial optimization software. It is faster than
-#' the available open source solvers (e.g. [add_lpsymphony_solver()] and
+#' the available open source solvers (e.g., [add_lpsymphony_solver()] and
 #' [add_rsymphony_solver()].
 #' Although formal benchmarks examining the performance of this solver for
 #' conservation planning problems have yet to be completed, preliminary
 #' analyses suggest that it performs slightly slower than the *Gurobi*
-#' solver (i.e. [add_gurobi_solver()]).
+#' solver (i.e., [add_gurobi_solver()]).
 #' We recommend using this solver if the *Gurobi* solver is not available.
 #' Licenses are available for the *IBM CPLEX* software to academics at no cost
 #' (see <https://www.ibm.com/products/ilog-cplex-optimization-studio>).
@@ -39,7 +39,7 @@ NULL
 #'   export CPLEX_BIN="/opt/ibm/ILOG/CPLEX_Studio128/cplex/bin/x86-64_linux/cplex"
 #' ```
 #' Note that you may need to change the version
-#' number in the file path (i.e. `"CPLEX_Studio128"`). For more information
+#' number in the file path (i.e., `"CPLEX_Studio128"`). For more information
 #' on installing the pkg{cplexAPI} package, please see the
 #' [official installation instructions for the package](https://github.com/cran/cplexAPI/blob/master/inst/INSTALL).
 #'

R/add_cuts_portfolio.R

@@ -9,7 +9,7 @@ NULL
 #'  [add_gap_portfolio()] when the *Gurobi* software is not
 #'  available.
 #'
-#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
+#' @param x [problem()] (i.e., [`ConservationProblem-class`]) object.
 #'
 #' @param number_solutions `integer` number of attempts to generate
 #'   different solutions. Defaults to 10.
@@ -22,11 +22,11 @@ NULL
 #
 #' @section Notes:
 #' In early versions (< 4.0.1), this function was only compatible with
-#' *Gurobi* (i.e. [add_gurobi_solver()]). To provide functionality with
+#' *Gurobi* (i.e., [add_gurobi_solver()]). To provide functionality with
 #' exact algorithm solvers, this function now adds constraints to the
 #' problem formulation to generate multiple solutions.
 #'
-#' @return Object (i.e. [`ConservationProblem-class`]) with the portfolio
+#' @return Object (i.e., [`ConservationProblem-class`]) with the portfolio
 #'  added to it.
 #'
 #' @seealso

R/add_default_decisions.R

@@ -7,7 +7,7 @@ NULL
 #' [problem()]. The default types are binary and are added using
 #' the [add_binary_decisions()] function.
 #'
-#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
+#' @param x [problem()] (i.e., [`ConservationProblem-class`]) object.
 #'
 #' @inherit add_binary_decisions return
 #'

R/add_default_portfolio.R

@@ -6,7 +6,7 @@ NULL
 #' Generate a portfolio for a conservation planning [problem()]
 #' that contains a single solution.
 #'
-#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
+#' @param x [problem()] (i.e., [`ConservationProblem-class`]) object.
 #'
 #' @seealso
 #' See [portfolios] for an overview of all functions for adding a portfolio.

R/add_default_solver.R

@@ -10,7 +10,7 @@ NULL
 #' run time and solution quality of some of the available solvers when applied
 #' to different sized datasets.
 #'
-#' @param x [problem()] (i.e. [`ConservationProblem-class`]) object.
+#' @param x [problem()] (i.e., [`ConservationProblem-class`]) object.
 #'
 #' @param ... arguments passed to the solver.
 #'