diff --git a/.Rbuildignore b/.Rbuildignore index 4a61761..bd3bbcb 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -16,6 +16,7 @@ check.log test.log gp.log spell.log +examples.log README.Rmd inst/extdata/dictionary.txt ^_pkgdown\.yml$ @@ -23,3 +24,4 @@ inst/extdata/dictionary.txt ^CONTRIBUTING\.Rmd$ ^CRAN-RELEASE$ ^\.github$ +inst/WORDLIST diff --git a/.github/workflows/R-CMD-check-mac-osx.yaml b/.github/workflows/R-CMD-check-macos.yaml similarity index 99% rename from .github/workflows/R-CMD-check-mac-osx.yaml rename to .github/workflows/R-CMD-check-macos.yaml index 6e7a588..13ec387 100644 --- a/.github/workflows/R-CMD-check-mac-osx.yaml +++ b/.github/workflows/R-CMD-check-macos.yaml @@ -12,7 +12,7 @@ on: - main - master -name: Mac OSX +name: macOS jobs: R-CMD-check: diff --git a/.gitignore b/.gitignore index 463dacc..6a5b723 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,7 @@ test.log check.log spell.log gp.log +examples.log # system files .directory # do not ignore the following files diff --git a/DESCRIPTION b/DESCRIPTION index 009c538..9d1008a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: oppr Type: Package -Version: 1.0.3 +Version: 1.0.4 Title: Optimal Project Prioritization Description: A decision support tool for prioritizing conservation projects. Prioritizations can be developed by maximizing expected feature richness, @@ -51,8 +51,8 @@ Suggests: roxygen2 (>= 6.1.0), rmarkdown (>= 1.10), gurobi (>= 8.0.0), - ggtree (>= 2.4.2), Rsymphony (>= 0.1.28), + ggtree (>= 2.4.2), lpsymphony (>= 1.10.0), shiny (>= 1.2.0), rhandsontable (>= 0.3.7), @@ -69,8 +69,9 @@ SystemRequirements: C++11 URL: https://prioritizr.github.io/oppr/ BugReports: https://github.com/prioritizr/oppr/issues VignetteBuilder: knitr -RoxygenNote: 7.1.1 +RoxygenNote: 7.2.1 Encoding: UTF-8 +Language: en-US Collate: 'internal.R' 'pproto.R' diff --git a/Makefile b/Makefile index 21359fa..2e3ca57 100644 --- a/Makefile +++ b/Makefile @@ -43,7 +43,7 @@ quickcheck: check: echo "\n===== R CMD CHECK =====\n" > check.log 2>&1 - R --slave -e "devtools::check(build_args = '--no-build-vignettes', args = '--no-build-vignettes', run_dont_test = TRUE, vignettes = FALSE)" >> check.log 2>&1 + R --slave -e "devtools::check(remote = TRUE, build_args = '--no-build-vignettes', args = '--no-build-vignettes', run_dont_test = TRUE, vignettes = FALSE)" >> check.log 2>&1 cp -Rf doc inst/ touch inst/doc/.gitkeep @@ -66,7 +66,17 @@ quickbuild: R --slave -e "devtools::build(vignettes = FALSE)" cp -Rf doc inst/ +urlcheck: + R --slave -e "devtools::document();urlchecker::url_check()" + +spellcheck: + R --slave -e "devtools::document();devtools::spell_check()" + +examples: + R --slave -e "devtools::run_examples(run_donttest = TRUE, run_dontrun = TRUE);warnings()" > examples.log 2>&1 + rm -f Rplots.pdf + install: - R --slave -e "devtools::install_local('../oppr', force = TRUE, upgrade = 'never')" + R --slave -e "devtools::install_local('.', force = TRUE, upgrade = 'never')" .PHONY: initc data docs readme site test check checkwb build install man diff --git a/NEWS.md b/NEWS.md index 3fda79f..66b1e4b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,14 @@ -# oppr 1.0.3 (released) +# oppr 1.0.4 + +- CRAN release. +- Fix compiler warnings raised by CRAN checks. +- Remove references to the *ggtree* package in documentation. +- Fix memory issues encountered during installation on CRAN Windows server. +- Fix compatibility issues with upcoming version of the *Matrix* package + (version 1.4-2). +- Fix broken URLs in package documentation. + +# oppr 1.0.3 - CRAN release. - Fix URLs for CRAN. @@ -46,7 +56,7 @@ - Fix "Non-file package-anchored link(s) in documentation object" warnings in R-devel checks. -# oppr 1.0.2 (released) +# oppr 1.0.2 - CRAN release. @@ -54,7 +64,7 @@ - Replace `tibble::as.tibble` with `tibble::as_tibble` to avoid warnings. -# oppr 1.0.1 (released) +# oppr 1.0.1 - CRAN release. @@ -62,7 +72,7 @@ - Fix compatibility issues with upcoming _tibble_ (3.0.0) R package. -# oppr 1.0.0 (released) +# oppr 1.0.0 - CRAN release. @@ -71,7 +81,7 @@ - Fix warnings in R-devel CRAN checks related to documentation. - Add citation for the research article that accompanies this package. -# oppr 0.0.4 (released) +# oppr 0.0.4 - CRAN release. @@ -80,7 +90,7 @@ - Fix typo. - Fix broken links to Gurobi academic licenses. -# oppr 0.0.3 (released) +# oppr 0.0.3 - CRAN release. @@ -88,7 +98,7 @@ - Retain debugging symbols to conform with CRAN policies. -# oppr 0.0.2 (released) +# oppr 0.0.2 - CRAN release. @@ -97,7 +107,7 @@ - Fix address sanitizer issues causing CRAN checks to fail. - Tests successfully complete when the _shiny_ R package is not installed. -# oppr 0.0.1 (released) +# oppr 0.0.1 - CRAN release. diff --git a/R/ProjectProblem-proto.R b/R/ProjectProblem-proto.R index f5a583c..f5dbf4f 100644 --- a/R/ProjectProblem-proto.R +++ b/R/ProjectProblem-proto.R @@ -400,7 +400,7 @@ ProjectProblem <- pproto( self$project_names()) }, pf_matrix = function(self) { - m <- methods::as(as.matrix( + m <- as_Matrix(as.matrix( self$data$projects[, self$data$features[[self$data$feature_name_column]], drop = FALSE]), "dgCMatrix") m@x[is.na(m@x)] <- 0 @@ -410,11 +410,13 @@ ProjectProblem <- pproto( }, epf_matrix = function(self) { # extract persistence probabilities, but not accounting for baseline - m <- as(self$pf_matrix() * matrix(self$project_success_probabilities(), - ncol = self$number_of_features(), - nrow = self$number_of_projects()), - "dgCMatrix") - m <- as(m, "dgCMatrix") + m <- as_Matrix( + self$pf_matrix() * + matrix(self$project_success_probabilities(), + ncol = self$number_of_features(), + nrow = self$number_of_projects()), + "dgCMatrix") + m <- as_Matrix(m, "dgCMatrix") m <- Matrix::drop0(m) # if include baseline probabilities, then account for probabilities of # each project persisting and the baseline project not failing @@ -430,7 +432,7 @@ ProjectProblem <- pproto( ## overwrite baseline data m[bp, ] <- bpp ## coerce data type - m <- as(m, "dgCMatrix") + m <- as_Matrix(m, "dgCMatrix") m <- Matrix::drop0(m) } rownames(m) <- self$project_names() @@ -438,7 +440,7 @@ ProjectProblem <- pproto( m }, pa_matrix = function(self) { - m <- methods::as(as.matrix( + m <- as_Matrix(as.matrix( self$data$projects[, self$data$actions[[self$data$action_name_column]], drop = FALSE]), "dgCMatrix") rownames(m) <- self$data$projects[[self$data$project_name_column]] diff --git a/R/add_lpsolveapi_solver.R b/R/add_lpsolveapi_solver.R index 70b35c8..8ce2f7e 100644 --- a/R/add_lpsolveapi_solver.R +++ b/R/add_lpsolveapi_solver.R @@ -85,7 +85,7 @@ add_lpsolveapi_solver <- function(x, gap = 0, presolve = FALSE, # extract parameters p <- as.list(self$parameters) # extract constraints - m <- methods::as(x$A(), "dgTMatrix") + m <- as_Matrix(x$A(), "dgTMatrix") mrhs <- x$rhs() msense <- x$sense() # manually add in locked constraints diff --git a/R/add_lpsymphony_solver.R b/R/add_lpsymphony_solver.R index d8a9984..91356ea 100644 --- a/R/add_lpsymphony_solver.R +++ b/R/add_lpsymphony_solver.R @@ -10,7 +10,7 @@ NULL #' #' @inheritParams add_gurobi_solver #' -#' @details [*SYMPHONY*](https://projects.coin-or.org/SYMPHONY) is an +#' @details [*SYMPHONY*](https://github.com/coin-or/SYMPHONY) is an #' open-source integer programming solver that is part of the Computational #' Infrastructure for Operations Research (COIN-OR) project, an initiative #' to promote development of open-source tools for operations research (a diff --git a/R/add_max_phylo_div_objective.R b/R/add_max_phylo_div_objective.R index 4ddb809..f7a0a72 100644 --- a/R/add_max_phylo_div_objective.R +++ b/R/add_max_phylo_div_objective.R @@ -252,7 +252,7 @@ add_max_phylo_div_objective <- function(x, budget, tree) { bm[, bo, drop = FALSE], fp$edge.length[bo], rep(0, y$number_of_features()), y$feature_weights()[fp$tip.label], - methods::as(as.matrix(solution), "dgCMatrix")) + as_Matrix(as.matrix(solution), "dgCMatrix")) }, apply = function(self, x, y) { assertthat::assert_that(inherits(x, "OptimizationProblem"), diff --git a/R/add_max_richness_objective.R b/R/add_max_richness_objective.R index 9b0347b..bbefb52 100644 --- a/R/add_max_richness_objective.R +++ b/R/add_max_richness_objective.R @@ -200,7 +200,7 @@ add_max_richness_objective <- function(x, budget) { y$epf_matrix()[, y$feature_phylogeny()$tip.label, drop = FALSE], bm[, bo, drop = FALSE], rep(0, ncol(bm)), rep(0, y$number_of_features()), w, - methods::as(as.matrix(solution), "dgCMatrix")) + as_Matrix(as.matrix(solution), "dgCMatrix")) }, apply = function(self, x, y) { assertthat::assert_that(inherits(x, "OptimizationProblem"), diff --git a/R/add_max_targets_met_objective.R b/R/add_max_targets_met_objective.R index 00a4e4a..c04ff29 100644 --- a/R/add_max_targets_met_objective.R +++ b/R/add_max_targets_met_objective.R @@ -233,7 +233,7 @@ add_max_targets_met_objective <- function(x, budget) { y$action_costs(), y$pa_matrix(), y$epf_matrix(), bm[, bo, drop = FALSE], fp$edge.length[bo], y$targets$output()$value, w, - methods::as(as.matrix(solution), "dgCMatrix")) + as_Matrix(as.matrix(solution), "dgCMatrix")) }, apply = function(self, x, y) { assertthat::assert_that(inherits(x, "OptimizationProblem"), diff --git a/R/add_min_set_objective.R b/R/add_min_set_objective.R index e051866..360f64a 100644 --- a/R/add_min_set_objective.R +++ b/R/add_min_set_objective.R @@ -175,7 +175,7 @@ add_min_set_objective <- function(x) { y$epf_matrix()[, y$feature_phylogeny()$tip.label, drop = FALSE], bm[, bo, drop = FALSE], fp$edge.length[bo], rep(0, y$number_of_features()), rep(0, y$number_of_features()), - methods::as(as.matrix(solution), "dgCMatrix")) + as_Matrix(as.matrix(solution), "dgCMatrix")) }, apply = function(self, x, y) { assertthat::assert_that(inherits(x, "OptimizationProblem"), diff --git a/R/add_rsymphony_solver.R b/R/add_rsymphony_solver.R index b24ae95..c87e9b2 100644 --- a/R/add_rsymphony_solver.R +++ b/R/add_rsymphony_solver.R @@ -10,7 +10,7 @@ NULL #' #' @inheritParams add_gurobi_solver #' -#' @details [*SYMPHONY*](https://projects.coin-or.org/SYMPHONY) is an +#' @details [*SYMPHONY*](https://github.com/coin-or/SYMPHONY) is an #' open-source integer programming solver that is part of the Computational #' Infrastructure for Operations Research (COIN-OR) project, an initiative #' to promote development of open-source tools for operations research (a diff --git a/R/data.R b/R/data.R index fd976fa..33e8ecb 100644 --- a/R/data.R +++ b/R/data.R @@ -3,7 +3,7 @@ NULL #' Simulated data #' -#' Simulated data for prioritizing conservations projects. +#' Simulated data for prioritizing conservation projects. #' #' @usage data(sim_actions) #' @usage data(sim_projects) diff --git a/R/internal.R b/R/internal.R index 780d1f0..924b8b2 100644 --- a/R/internal.R +++ b/R/internal.R @@ -300,3 +300,61 @@ lp_solve_status <- function(x) { warning("solver returned unrecognized code") as.character(x) } + +#' Convert to Matrix +#' +#' Convert an object to a matrix class provided by the \pkg{Matrix} package. +#' +#' @param object object. +#' +#' @param class `character` name of new classes. +#' +#' @details +#' This function is a wrapper that is designed to provide +#' compatibility with older and newer versions of the \pkg{Matrix} package. +#' +#' @return `Matrix` object. +#' +#' @noRd +as_Matrix <- function(object, class) { + # assert valid argument + assertthat::assert_that( + assertthat::is.string(class), + assertthat::noNA(class) + ) + # if we just want to convert to generic Matrix class then do that... + if (identical(class, "Matrix")) { + return(methods::as(object, class)) + } + # convert matrix + if (utils::packageVersion("Matrix") >= as.package_version("1.4-2")) { + if (identical(class, "dgCMatrix")) { + c1 <- "dMatrix" + c2 <- "generalMatrix" + c3 <- "CsparseMatrix" + } else if (identical(class, "dgTMatrix")) { + c1 <- "dMatrix" + c2 <- "generalMatrix" + c3 <- "TsparseMatrix" + } else if (identical(class, "dsCMatrix")) { + c1 <- "dMatrix" + c2 <- "symmetricMatrix" + c3 <- "CsparseMatrix" + } else if (identical(class, "dsTMatrix")) { + c1 <- "dMatrix" + c2 <- "symmetricMatrix" + c3 <- "TsparseMatrix" + } else if (identical(class, "lgCMatrix")) { + c1 <- "lMatrix" + c2 <- "generalMatrix" + c3 <- "CsparseMatrix" + } else { + stop("argument to \"class\" not recognized") + } + out <- methods::as(methods::as(methods::as(object, c1), c2), c3) + } else { + out <- methods::as(object, class) + } + # return result + out +} diff --git a/R/plot_feature_persistence.R b/R/plot_feature_persistence.R index 1aa7541..b0959a5 100644 --- a/R/plot_feature_persistence.R +++ b/R/plot_feature_persistence.R @@ -132,8 +132,8 @@ plot_feature_persistence <- function(x, solution, n = 1, symbol_hjust = 0.007, feature_probs <- rcpp_expected_persistences( x$pa_matrix(), x$epf_matrix()[, x$feature_names(), drop = FALSE], - methods::as(diag(x$number_of_features()), "dgCMatrix"), - methods::as(as.matrix(solution), "dgCMatrix"))[1, ] + as_Matrix(diag(x$number_of_features()), "dgCMatrix"), + as_Matrix(as.matrix(solution), "dgCMatrix"))[1, ] ## create plotting data d <- tibble::tibble(name = x$feature_names(), diff --git a/R/plot_phylo_persistence.R b/R/plot_phylo_persistence.R index fbaf5eb..ab6ffcf 100644 --- a/R/plot_phylo_persistence.R +++ b/R/plot_phylo_persistence.R @@ -9,23 +9,28 @@ NULL #' #' @inheritParams plot.ProjectProblem #' -#' @details This function requires the \pkg{ggtree} (Yu *et al.* 2017). -#' Since this package is distributed exclusively -#' through [Bioconductor](https://bioconductor.org), and is not -#' available on the -#' [Comprehensive R Archive Network](https://cran.r-project.org/), -#' please execute the following command to install it: -#' `source("https://bioconductor.org/biocLite.R");biocLite("ggtree")`. -#' If the installation process fails, please consult the package's [online documentation](https://bioconductor.org/packages/release/bioc/html/ggtree.html). -#' -#' In this plot, each phylogenetic branch is colored according to probability -#' that it is expected to persist into the future (see Faith 2008). -#' Features that directly benefit from at least a single -#' completely funded project with a non-zero cost are depicted with an -#' asterisk symbol. Additionally, features that indirectly benefit from funded -#' projects---because they are associated with partially funded projects that -#' have non-zero costs and share actions with at least one completely funded -#' project---are depicted with an open circle symbol. +#' @details +#' This function requires the \pkg{ggtree} (Yu *et al.* 2017). +#' Since this package is distributed exclusively +#' through [Bioconductor](https://bioconductor.org), and is not +#' available on the +#' [Comprehensive R Archive Network](https://cran.r-project.org/), +#' please execute the following commands to install it: +#' ``` +#' if (!require(remotes)) install.packages("remotes") +#' remotes::install_bioc("ggtree") +#' ``` +#' If the installation process fails, please consult the package's +#' [online documentation](https://bioconductor.org/packages/release/bioc/html/ggtree.html). +#' +#' In this plot, each phylogenetic branch is colored according to probability +#' that it is expected to persist into the future (see Faith 2008). +#' Features that directly benefit from at least a single +#' completely funded project with a non-zero cost are depicted with an +#' asterisk symbol. Additionally, features that indirectly benefit from funded +#' projects---because they are associated with partially funded projects that +#' have non-zero costs and share actions with at least one completely funded +#' project---are depicted with an open circle symbol. #' #' @references #' Faith DP (2008) Threatened species and the potential loss of @@ -38,7 +43,7 @@ NULL #' covariates and other associated data. *Methods in Ecology and #' Evolution*, **8**: 28--36. #' -#' @return A [ggtree::ggtree()] object, or a +#' @return A `ggtree::ggtree()` object, or a #' [tidytree::treedata()] object if `return_data` is #' `TRUE`. #' @@ -176,7 +181,7 @@ plot_phylo_persistence <- function(x, solution, n = 1, symbol_hjust = 0.007, ## pre-compute probabilities that each branch will persist branch_probs <- rcpp_expected_persistences( x$pa_matrix(), x$epf_matrix()[, tree$tip.label, drop = FALSE], - branch_matrix(tree), methods::as(as.matrix(solution), "dgCMatrix")) + branch_matrix(tree), as_Matrix(as.matrix(solution), "dgCMatrix")) # Main processing ## format tree data for plotting diff --git a/R/problem.R b/R/problem.R index 4f292ba..9e0c9ff 100644 --- a/R/problem.R +++ b/R/problem.R @@ -33,12 +33,12 @@ NULL #' given the funded projects in a solution, the combined benefits of multiple #' projects can be encoded by creating additional projects that represent #' "combined projects". For instance, a habitat restoration project might -#' cost \$100 and mean that a feature has a 40% chance of persisting, and -#' a pest eradication project might cost \$50 and mean that a feature has a +#' cost $100 and mean that a feature has a 40% chance of persisting, and +#' a pest eradication project might cost $50 and mean that a feature has a #' 60% chance of persisting. Due to non-linear effects, funding both of these #' projects might mean that a species has a 90% chance of persistence. #' This can be accounted for by creating a third project, representing the -#' funding of both projects, which costs \$150 and provides a 90% chance +#' funding of both projects, which costs $150 and provides a 90% chance #' of persistence. #' #' @param actions [base::data.frame()] or [tibble::tibble()] diff --git a/R/project_cost_effectiveness.R b/R/project_cost_effectiveness.R index fd5d5f4..de4bc53 100644 --- a/R/project_cost_effectiveness.R +++ b/R/project_cost_effectiveness.R @@ -94,8 +94,8 @@ project_cost_effectiveness <- function(x) { bp_obj <- x$objective$evaluate(x, tibble::as_tibble(bpm)) # generate solutions for other projects bpm <- bpm[rep(1, x$number_of_projects()), , drop = FALSE] - pp <- methods::as(x$pa_matrix(), "lgCMatrix") | - methods::as(bpm, "lgCMatrix") + pp <- as_Matrix(x$pa_matrix(), "lgCMatrix") | + as_Matrix(bpm, "lgCMatrix") pp <- tibble::as_tibble(round(as.matrix(pp))) # evaluate solutions pp_obj <- x$objective$evaluate(x, pp) diff --git a/R/replacement_costs.R b/R/replacement_costs.R index c8f9ac6..8ae3f96 100644 --- a/R/replacement_costs.R +++ b/R/replacement_costs.R @@ -5,7 +5,7 @@ NULL #' #' Calculate the replacement cost for priority actions in a project #' prioritization [problem()] (Moilanen *et al.* 2009). Actions associated -#' with larger replacement cost values are more irreplaceabe, and may +#' with larger replacement cost values are more irreplaceable, and may #' need to be implemented sooner than actions with lower replacement cost #' values. #' diff --git a/R/solution_statistics.R b/R/solution_statistics.R index 72fa785..f3e8d8e 100644 --- a/R/solution_statistics.R +++ b/R/solution_statistics.R @@ -101,14 +101,14 @@ solution_statistics <- function(x, solution) { out <- tibble::as_tibble(cbind(out, stats::setNames(as.data.frame( rcpp_funded_projects( x$pa_matrix(), - methods::as(as.matrix(solution[, x$action_names()]), "dgCMatrix"))), + as_Matrix(as.matrix(solution[, x$action_names()]), "dgCMatrix"))), x$project_names()))) # add in columns for feature persistences out <- tibble::as_tibble(cbind(out, stats::setNames(as.data.frame( rcpp_expected_persistences( x$pa_matrix(), x$epf_matrix(), - methods::as(diag(x$number_of_features()), "dgCMatrix"), - methods::as(as.matrix(solution[, x$action_names()]), "dgCMatrix"))), + as_Matrix(diag(x$number_of_features()), "dgCMatrix"), + as_Matrix(as.matrix(solution[, x$action_names()]), "dgCMatrix"))), x$feature_names()))) # return output out diff --git a/R/solvers.R b/R/solvers.R index a4f33eb..d7edd51 100644 --- a/R/solvers.R +++ b/R/solvers.R @@ -25,7 +25,7 @@ NULL #' suite. This solver uses the \pkg{gurobi} package to solve problems.} #' #' \item{[add_rsymphony_solver()]}{ -#' [*SYMPHONY*](https://projects.coin-or.org/SYMPHONY) is an +#' [*SYMPHONY*](https://github.com/coin-or/SYMPHONY) is an #' open-source integer programming solver that is part of the Computational #' Infrastructure for Operations Research (COIN-OR) project, an initiative #' to promote development of open-source tools for operations research (a diff --git a/README.Rmd b/README.Rmd index 34a28ed..94df5af 100644 --- a/README.Rmd +++ b/README.Rmd @@ -11,7 +11,7 @@ output: [![lifecycle](https://img.shields.io/badge/Lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html) [![R-CMD-check-Ubuntu](https://img.shields.io/github/workflow/status/prioritizr/oppr/Ubuntu/master.svg?label=Ubuntu)](https://github.com/prioritizr/oppr/actions) [![R-CMD-check-Windows](https://img.shields.io/github/workflow/status/prioritizr/oppr/Windows/master.svg?label=Windows)](https://github.com/prioritizr/oppr/actions) -[![R-CMD-check-Mac-OSX](https://img.shields.io/github/workflow/status/prioritizr/oppr/Mac%20OSX/master.svg?label=Mac%20OSX)](https://github.com/prioritizr/oppr/actions) +[![R-CMD-check-macOS](https://img.shields.io/github/workflow/status/prioritizr/oppr/macOS/master.svg?label=macOS)](https://github.com/prioritizr/oppr/actions) [![Coverage Status](https://codecov.io/github/prioritizr/oppr/coverage.svg?branch=master)](https://codecov.io/github/prioritizr/oppr?branch=master) [![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/oppr)](https://CRAN.R-project.org/package=oppr) diff --git a/README.md b/README.md index 911f097..ec6fd40 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![lifecycle](https://img.shields.io/badge/Lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html) [![R-CMD-check-Ubuntu](https://img.shields.io/github/workflow/status/prioritizr/oppr/Ubuntu/master.svg?label=Ubuntu)](https://github.com/prioritizr/oppr/actions) [![R-CMD-check-Windows](https://img.shields.io/github/workflow/status/prioritizr/oppr/Windows/master.svg?label=Windows)](https://github.com/prioritizr/oppr/actions) -[![R-CMD-check-Mac-OSX](https://img.shields.io/github/workflow/status/prioritizr/oppr/Mac%20OSX/master.svg?label=Mac%20OSX)](https://github.com/prioritizr/oppr/actions) +[![R-CMD-check-macOS](https://img.shields.io/github/workflow/status/prioritizr/oppr/macOS/master.svg?label=macOS)](https://github.com/prioritizr/oppr/actions) [![Coverage Status](https://codecov.io/github/prioritizr/oppr/coverage.svg?branch=master)](https://codecov.io/github/prioritizr/oppr?branch=master) [![CRAN\_Status\_Badge](http://www.r-pkg.org/badges/version/oppr)](https://CRAN.R-project.org/package=oppr) @@ -85,7 +85,7 @@ data(sim_features) print(sim_features) ``` - ## # A tibble: 5 x 2 + ## # A tibble: 5 × 2 ## name weight ## ## 1 F1 0.211 @@ -115,7 +115,7 @@ data(sim_actions) print(sim_actions) ``` - ## # A tibble: 6 x 4 + ## # A tibble: 6 × 4 ## name cost locked_in locked_out ## ## 1 F1_action 94.4 FALSE FALSE @@ -155,7 +155,7 @@ data(sim_projects) print(sim_projects, width = Inf) ``` - ## # A tibble: 6 x 13 + ## # A tibble: 6 × 13 ## name success F1 F2 F3 F4 F5 F1_action ## ## 1 F1_project 0.919 0.791 NA NA NA NA TRUE @@ -178,7 +178,7 @@ prioritization problem. Here our goal is to maximize the overall probability that each feature is expected to persist into the future (i.e. the feature richness), whilst also accounting for the relative importance of each feature and the fact that our resources are limited -such that we can only spend at most $400 on funding management actions. +such that we can only spend at most \$400 on funding management actions. Now, let’s build a project prioritization problem object that represents our goal. @@ -225,7 +225,7 @@ s <- solve(p) print(s, width = Inf) ``` - ## # A tibble: 1 x 21 + ## # A tibble: 1 × 21 ## solution status obj cost F1_action F2_action F3_action F4_action F5_action ## ## 1 1 OPTIMAL 1.75 395. 1 1 0 1 1 diff --git a/cran-comments.md b/cran-comments.md index e75a855..03360ec 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,3 +1,11 @@ +Dear CRAN maintainers, + +Thank you very much for reviewing this submission. This submission aims to address the warnings and errors raised by CRAN's checks. It also contains updates to ensure compatibility with the current and upcoming version of the Matrix package. + +Cheers, + +Jeff + # Test environments * [Ubuntu 20.04, R-release](https://github.com/prioritizr/oppr/actions?query=workflow%3AUbuntu) @@ -13,6 +21,16 @@ # Notes +* checking CRAN incoming feasibility ... NOTE + Found the following (possibly) invalid DOIs: + DOI: 10.1111/2041-210X.13264 + From: DESCRIPTION + inst/CITATION + Status: Service Unavailable + Message: 503 + + **This NOTE is a false positive and the DOI is valid. Specifically, the DOI pertains to a scientific article published in the peer reviewed journal Methods in Ecology and Evolution.** + * checking package dependencies ... NOTE Package suggested but not available for checking: 'gurobi' diff --git a/docs/404.html b/docs/404.html index b4c664c..9d9937d 100644 --- a/docs/404.html +++ b/docs/404.html @@ -32,7 +32,7 @@ oppr - 1.0.3 + 1.0.4 @@ -50,7 +50,7 @@
  • - + @@ -91,7 +91,7 @@

    Page not found (404)

    -

    Site built with pkgdown 1.6.1.9001.

    +

    Site built with pkgdown 2.0.6.

    diff --git a/docs/articles/index.html b/docs/articles/index.html index a61cc3b..906679a 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -1,75 +1,12 @@ - - - - - - - -Articles • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Articles • oppr - - - - - - - - - - - +
    -
    -
- - -
+

Articles

@@ -123,33 +53,27 @@

Articles

All vignettes

-
-
Optimal Project Prioritization
-
-
-
+
Optimal Project Prioritization
+
+
- - - - + diff --git a/docs/articles/oppr.html b/docs/articles/oppr.html index 1787ff9..68b11ec 100644 --- a/docs/articles/oppr.html +++ b/docs/articles/oppr.html @@ -33,7 +33,7 @@ oppr - 1.0.3 + 1.0.4 @@ -66,1149 +66,976 @@ -
+

Optimal Project Prioritization

- Source: vignettes/oppr.Rmd + Source: vignettes/oppr.Rmd
-
-

-Overview

-

The oppr R package is decision support tool for prioritizing conservation projects. Prioritizations can be developed by maximizing expected feature richness, expected phylogenetic diversity, the number of features that meet persistence targets, or identifying a set of projects that meet persistence targets for minimal cost. Constraints (e.g. lock in specific actions) and feature weights can also be specified to further customize prioritizations. After defining a project prioritization problem, solutions can be obtained using exact alg’orithms, heuristic algorithms, or random processes. In particular, it is recommended to install the ‘Gurobi’ optimizer because it can identify optimal solutions very quickly. Finally, methods are provided for comparing different prioritizations and evaluating their benefits.

-
-
-

-Tutorial

-
-

-Introduction

+
+

Overview +

+

The oppr R package is decision support tool for prioritizing conservation projects. Prioritizations can be developed by maximizing expected feature richness, expected phylogenetic diversity, the number of features that meet persistence targets, or identifying a set of projects that meet persistence targets for minimal cost. Constraints (e.g. lock in specific actions) and feature weights can also be specified to further customize prioritizations. After defining a project prioritization problem, solutions can be obtained using exact algorithms, heuristic algorithms, or random processes. In particular, it is recommended to install the ‘Gurobi’ optimizer because it can identify optimal solutions very quickly. Finally, methods are provided for comparing different prioritizations and evaluating their benefits.

+
+
+

Tutorial +

+
+

Introduction +

Here we will provide a short tutorial showing how the oppr R package can be used to prioritize funding for conservation projects. This package is a general purpose project prioritization decision support tool. It can generate solutions for species-based project prioritization problems (Joseph et al. 2009; Bennett et al. 2014) and priority threat management problems (Carwardine et al. 2018). To develop a project prioritization, this package requires data for (i) conservation projects, (ii) management actions data, and (iii) biodiversity features.

Briefly, biodiversity features are the biological entities that we wish would persist into the future (e.g. threatened populations, native species, eco-systems). These biodiversity features can (and ideally should) include non-threatened species, but should not include threatening processes that we wish to eradicate (e.g. populations of invasive species). Management actions are acts that can be undertaken to enhance biodiversity (e.g. planting native species, reintroducing native species, trapping pest species). Each action should pertain to a specific location (e.g. a national park) or area (e.g. an entire country), and should be associated with a cost estimate. To guide the prioritization, the management actions are grouped into conservation projects (also termed “strategies”). Typically, management actions are grouped into conservation projects based on spatial (e.g. management actions that pertain to the same area), taxonomic (e.g. management actions that pertain to the same pest species or threatened species), or thematic criteria (e.g. management actions that pertain to pest eradication are grouped into a “pest project”, and actions that pertain to habitat restoration are grouped into a “habitat project”). Additionally, some conservation projects can be combinations of other projects (e.g. a “pest and habitat project”). Each conservation project should be associated with (i) a probability of succeeding if it is implemented (also termed “feasibility”), (ii) information about which management actions are associated with it, and (iii) an estimate of how likely each conservation feature affected by the project is to persist into the future if the project is implemented (often derived using expert elicitation). The conservation projects should also include a “baseline project” that represents a “do nothing scenario” which has a 100% chance of succeeding and is associated with an action that costs nothing to implement. This is important because we can’t find a cost-effective solution if we don’t know how much each project improves a species’ chance at persistence. For more background information on project prioritization, please refer to Carwardine et al. (2018).

To start off, we will initialize the random number generator to ensure reproducibility. Next, we will load the oppr R package. And then we will load the ggplot2, tibble, and tidyr R packages to help with data for visualizations and wrangling.

-# set random number generated seed
-set.seed(1000)
-# load oppr package for project prioritization
-library(oppr)
-# load ggplot2 package for plotting
-library(ggplot2)
-# load tibble package for working with tabular data
-library(tibble)
-# load tidyr package for reshaping tabular data
-library(tidyr)
+# set random number generated seed +set.seed(1000) +# load oppr package for project prioritization +library(oppr) +# load ggplot2 package for plotting +library(ggplot2) +# load tibble package for working with tabular data +library(tibble) +# load tidyr package for reshaping tabular data +library(tidyr)
-
# 
-# Attaching package: 'tidyr'
-
+
# 
+# Attaching package: 'tidyr'
+
-
# The following object is masked from 'package:testthat':
-# 
-#     matches
-
+
# The following object is masked from 'package:testthat':
+# 
+#     matches
+
-
-

-Data simulation

+
+

Data simulation +

Now we will simulate a dataset to practice developing project prioritizations. Specifically, we will simulate a dataset for a priority threat management exercise that contains 40 features, 70 projects, and 30 actions.

-# simulate data
-sim_data <- simulate_ptm_data(number_projects = 70, number_actions = 30,
-                              number_features = 40)
-
-# extract project, action, feature data
-projects <- sim_data$projects
-actions <- sim_data$actions
-features <- sim_data$features
-
-# manually set feature weights for teaching purposes
-features$weight <- exp(runif(nrow(features), 1, 15))
-
-# print data
-print(projects) # data for conservation projects
+# simulate data +sim_data <- simulate_ptm_data(number_projects = 70, number_actions = 30, + number_features = 40) + +# extract project, action, feature data +projects <- sim_data$projects +actions <- sim_data$actions +features <- sim_data$features + +# manually set feature weights for teaching purposes +features$weight <- exp(runif(nrow(features), 1, 15)) + +# print data +print(projects) # data for conservation projects
-
# # A tibble: 71 x 73
-#    name     success     F1    F2    F3     F4     F5     F6     F7     F8     F9
-#    <chr>      <dbl>  <dbl> <dbl> <dbl>  <dbl>  <dbl>  <dbl>  <dbl>  <dbl>  <dbl>
-#  1 project…   0.720  0.672    NA    NA NA      0.704 NA     NA      0.523 NA    
-#  2 project…   0.859  0.514    NA    NA  0.832  0.616 NA     NA      0.547  0.687
-#  3 project…   0.724 NA        NA    NA  0.812 NA     NA     NA     NA      0.627
-#  4 project…   0.768  0.505    NA    NA NA     NA      0.530  0.708 NA     NA    
-#  5 project…   0.856  0.539    NA    NA NA     NA      0.844  0.608  0.590 NA    
-#  6 project…   0.891 NA        NA    NA NA     NA      0.563 NA     NA     NA    
-#  7 project…   0.874  0.546    NA    NA NA      0.682  0.576  0.676  0.737 NA    
-#  8 project…   0.932  0.593    NA    NA NA     NA      0.803  0.580  0.666 NA    
-#  9 project…   0.900 NA        NA    NA  0.572  0.547 NA     NA     NA     NA    
-# 10 project…   0.952 NA        NA    NA NA     NA     NA     NA     NA     NA    
-# # … with 61 more rows, and 62 more variables: F10 <dbl>, F11 <dbl>, F12 <dbl>,
-# #   F13 <dbl>, F14 <dbl>, F15 <dbl>, F16 <dbl>, F17 <dbl>, F18 <dbl>,
-# #   F19 <dbl>, F20 <dbl>, F21 <dbl>, F22 <dbl>, F23 <dbl>, F24 <dbl>,
-# #   F25 <dbl>, F26 <dbl>, F27 <dbl>, F28 <dbl>, F29 <dbl>, F30 <dbl>,
-# #   F31 <dbl>, F32 <dbl>, F33 <dbl>, F34 <dbl>, F35 <dbl>, F36 <dbl>,
-# #   F37 <dbl>, F38 <dbl>, F39 <dbl>, F40 <dbl>, action_1 <lgl>, action_2 <lgl>,
-# #   action_3 <lgl>, action_4 <lgl>, action_5 <lgl>, action_6 <lgl>,
-# #   action_7 <lgl>, action_8 <lgl>, action_9 <lgl>, action_10 <lgl>,
-# #   action_11 <lgl>, action_12 <lgl>, action_13 <lgl>, action_14 <lgl>,
-# #   action_15 <lgl>, action_16 <lgl>, action_17 <lgl>, action_18 <lgl>,
-# #   action_19 <lgl>, action_20 <lgl>, action_21 <lgl>, action_22 <lgl>,
-# #   action_23 <lgl>, action_24 <lgl>, action_25 <lgl>, action_26 <lgl>,
-# #   action_27 <lgl>, action_28 <lgl>, action_29 <lgl>, action_30 <lgl>,
-# #   baseline_action <lgl>
-
+
# # A tibble: 71 × 73
+#    name     success     F1    F2    F3     F4     F5     F6     F7     F8     F9
+#    <chr>      <dbl>  <dbl> <dbl> <dbl>  <dbl>  <dbl>  <dbl>  <dbl>  <dbl>  <dbl>
+#  1 project…   0.720  0.672    NA    NA NA      0.704 NA     NA      0.523 NA    
+#  2 project…   0.859  0.514    NA    NA  0.832  0.616 NA     NA      0.547  0.687
+#  3 project…   0.724 NA        NA    NA  0.812 NA     NA     NA     NA      0.627
+#  4 project…   0.768  0.505    NA    NA NA     NA      0.530  0.708 NA     NA    
+#  5 project…   0.856  0.539    NA    NA NA     NA      0.844  0.608  0.590 NA    
+#  6 project…   0.891 NA        NA    NA NA     NA      0.563 NA     NA     NA    
+#  7 project…   0.874  0.546    NA    NA NA      0.682  0.576  0.676  0.737 NA    
+#  8 project…   0.932  0.593    NA    NA NA     NA      0.803  0.580  0.666 NA    
+#  9 project…   0.900 NA        NA    NA  0.572  0.547 NA     NA     NA     NA    
+# 10 project…   0.952 NA        NA    NA NA     NA     NA     NA     NA     NA    
+# # … with 61 more rows, and 62 more variables: F10 <dbl>, F11 <dbl>, F12 <dbl>,
+# #   F13 <dbl>, F14 <dbl>, F15 <dbl>, F16 <dbl>, F17 <dbl>, F18 <dbl>,
+# #   F19 <dbl>, F20 <dbl>, F21 <dbl>, F22 <dbl>, F23 <dbl>, F24 <dbl>,
+# #   F25 <dbl>, F26 <dbl>, F27 <dbl>, F28 <dbl>, F29 <dbl>, F30 <dbl>,
+# #   F31 <dbl>, F32 <dbl>, F33 <dbl>, F34 <dbl>, F35 <dbl>, F36 <dbl>,
+# #   F37 <dbl>, F38 <dbl>, F39 <dbl>, F40 <dbl>, action_1 <lgl>, action_2 <lgl>,
+# #   action_3 <lgl>, action_4 <lgl>, action_5 <lgl>, action_6 <lgl>, …
+
-print(actions)  # data for management actions
+print(actions) # data for management actions
-
# # A tibble: 31 x 4
-#    name       cost locked_in locked_out
-#    <chr>     <dbl> <lgl>     <lgl>     
-#  1 action_1   97.8 FALSE     FALSE     
-#  2 action_2   94.0 FALSE     FALSE     
-#  3 action_3  100.  FALSE     FALSE     
-#  4 action_4  103.  FALSE     FALSE     
-#  5 action_5   96.1 FALSE     FALSE     
-#  6 action_6   98.1 FALSE     FALSE     
-#  7 action_7   97.6 FALSE     FALSE     
-#  8 action_8  104.  FALSE     FALSE     
-#  9 action_9   99.9 FALSE     FALSE     
-# 10 action_10  93.1 FALSE     FALSE     
-# # … with 21 more rows
-
+
# # A tibble: 31 × 4
+#    name       cost locked_in locked_out
+#    <chr>     <dbl> <lgl>     <lgl>     
+#  1 action_1   97.8 FALSE     FALSE     
+#  2 action_2   94.0 FALSE     FALSE     
+#  3 action_3  100.  FALSE     FALSE     
+#  4 action_4  103.  FALSE     FALSE     
+#  5 action_5   96.1 FALSE     FALSE     
+#  6 action_6   98.1 FALSE     FALSE     
+#  7 action_7   97.6 FALSE     FALSE     
+#  8 action_8  104.  FALSE     FALSE     
+#  9 action_9   99.9 FALSE     FALSE     
+# 10 action_10  93.1 FALSE     FALSE     
+# # … with 21 more rows
+
-print(features) # data for biodiversity features
+print(features) # data for biodiversity features
-
# # A tibble: 40 x 2
-#    name     weight
-#    <chr>     <dbl>
-#  1 F1       210.  
-#  2 F2         7.64
-#  3 F3         7.99
-#  4 F4      7732.  
-#  5 F5     34905.  
-#  6 F6         3.31
-#  7 F7      1168.  
-#  8 F8    108301.  
-#  9 F9         3.62
-# 10 F10     6956.  
-# # … with 30 more rows
-
+
# # A tibble: 40 × 2
+#    name     weight
+#    <chr>     <dbl>
+#  1 F1       210.  
+#  2 F2         7.64
+#  3 F3         7.99
+#  4 F4      7732.  
+#  5 F5     34905.  
+#  6 F6         3.31
+#  7 F7      1168.  
+#  8 F8    108301.  
+#  9 F9         3.62
+# 10 F10     6956.  
+# # … with 30 more rows
+
-
-

-Prioritizations with exact algorithms

+
+

Prioritizations with exact algorithms +

Let’s assume that we want to maximize the overall persistence of the conservation features, and that we can only spend $1,000 funding management actions. We will also assume that our decisions involve either funding management actions or not (in other words, our decisions are binary). For the moment, let’s assume that we value the persistence of each feature equally. Given this information, we can generate a project prioritization problem object that matches our specifications.

-# build problem
-p1 <- problem(projects = projects, actions = actions, features = features,
-              "name", "success", "name", "cost", "name") %>%
-      add_max_richness_objective(budget = 1000) %>%
-      add_binary_decisions()
-
-# print problem
-print(p1)
+# build problem +p1 <- problem(projects = projects, actions = actions, features = features, + "name", "success", "name", "cost", "name") %>% + add_max_richness_objective(budget = 1000) %>% + add_binary_decisions() + +# print problem +print(p1)
-
# Project Prioritization Problem
-#   actions          action_1, action_2, action_3, ... (31 actions)
-#   projects         project_1, project_2, project_3, ... (71 projects)
-#   features         F1, F2, F3, ... (40 features)
-#   action costs:    min: 0, max: 113.35036
-#   project success: min: 0.70247, max: 1
-#   objective:       Maximum richness objective [budget (1000)]
-#   targets:         none
-#   weights:         default
-#   decisions        Binary decision 
-#   constraints:     <none>
-#   solver:          default
-
+
# Project Prioritization Problem
+#   actions          action_1, action_2, action_3, ... (31 actions)
+#   projects         project_1, project_2, project_3, ... (71 projects)
+#   features         F1, F2, F3, ... (40 features)
+#   action costs:    min: 0, max: 113.35036
+#   project success: min: 0.70247, max: 1
+#   objective:       Maximum richness objective [budget (1000)]
+#   targets:         none
+#   weights:         default
+#   decisions        Binary decision 
+#   constraints:     <none>
+#   solver:          default
+

After building the problem, we can solve it. Although backwards heuristic algorithms have conventionally been used to solve project prioritization problems (e.g. Joseph et al. 2009; Bennett et al. 2014; Gerber et al. 2018), here we will use exact algorithms to develop a prioritization. Exact algorithms are superior to heuristic algorithms because they can provide guarantees on solution quality (Underhill 1994; Rodrigues & Gaston 2002). In other words, if you specify that you want an optimal solution when using exact algorithms, then you are guaranteed to get an optimal solution. Heuristic algorithms—and even more advanced meta-heuristic algorithms such as simulated annealing that are commonly to guide conservation decision making (Kirkpatrick et al. 1983)—provide no such guarantees and can actually deliver remarkably poor solutions (e.g. Beyer et al. 2016). Later on we will experiment with heuristic algorithms, but for now, we will use exact algorithms. Since we haven’t explicitly stated which solver we would like to use, the oppr R package will identify the best exact algorithm solver currently installed on your system. This is typically the lpSolveAPI R package unless you have manually installed the gurobi R package and the Gurobi optimization suite. Although not shown here, when you try solving the problem you will see information printed to your screen as the solver tries to find an optimal solution. Please do not be alarmed, this is normal behavior and some of the information can actually be useful (e.g. to estimate how long it might take to solve the problem).

-# solve problem
-s1 <- solve(p1)
+# solve problem +s1 <- solve(p1)
-# print solution
-print(s1)
+# print solution +print(s1)
-
# # A tibble: 1 x 146
-#   solution status    obj  cost action_1 action_2 action_3 action_4 action_5
-#      <int> <chr>   <dbl> <dbl>    <dbl>    <dbl>    <dbl>    <dbl>    <dbl>
-# 1        1 OPTIMAL  31.0  993.        1        1        0        0        0
-# # … with 137 more variables: action_6 <dbl>, action_7 <dbl>, action_8 <dbl>,
-# #   action_9 <dbl>, action_10 <dbl>, action_11 <dbl>, action_12 <dbl>,
-# #   action_13 <dbl>, action_14 <dbl>, action_15 <dbl>, action_16 <dbl>,
-# #   action_17 <dbl>, action_18 <dbl>, action_19 <dbl>, action_20 <dbl>,
-# #   action_21 <dbl>, action_22 <dbl>, action_23 <dbl>, action_24 <dbl>,
-# #   action_25 <dbl>, action_26 <dbl>, action_27 <dbl>, action_28 <dbl>,
-# #   action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>,
-# #   project_2 <dbl>, project_3 <dbl>, project_4 <dbl>, project_5 <dbl>,
-# #   project_6 <dbl>, project_7 <dbl>, project_8 <dbl>, project_9 <dbl>,
-# #   project_10 <dbl>, project_11 <dbl>, project_12 <dbl>, project_13 <dbl>,
-# #   project_14 <dbl>, project_15 <dbl>, project_16 <dbl>, project_17 <dbl>,
-# #   project_18 <dbl>, project_19 <dbl>, project_20 <dbl>, project_21 <dbl>,
-# #   project_22 <dbl>, project_23 <dbl>, project_24 <dbl>, project_25 <dbl>,
-# #   project_26 <dbl>, project_27 <dbl>, project_28 <dbl>, project_29 <dbl>,
-# #   project_30 <dbl>, project_31 <dbl>, project_32 <dbl>, project_33 <dbl>,
-# #   project_34 <dbl>, project_35 <dbl>, project_36 <dbl>, project_37 <dbl>,
-# #   project_38 <dbl>, project_39 <dbl>, project_40 <dbl>, project_41 <dbl>,
-# #   project_42 <dbl>, project_43 <dbl>, project_44 <dbl>, project_45 <dbl>,
-# #   project_46 <dbl>, project_47 <dbl>, project_48 <dbl>, project_49 <dbl>,
-# #   project_50 <dbl>, project_51 <dbl>, project_52 <dbl>, project_53 <dbl>,
-# #   project_54 <dbl>, project_55 <dbl>, project_56 <dbl>, project_57 <dbl>,
-# #   project_58 <dbl>, project_59 <dbl>, project_60 <dbl>, project_61 <dbl>,
-# #   project_62 <dbl>, project_63 <dbl>, project_64 <dbl>, project_65 <dbl>,
-# #   project_66 <dbl>, project_67 <dbl>, project_68 <dbl>, project_69 <dbl>,
-# #   project_70 <dbl>, baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, …
-
+
# # A tibble: 1 × 146
+#   solution status    obj  cost action_1 action_2 actio…¹ actio…² actio…³ actio…⁴
+#      <int> <chr>   <dbl> <dbl>    <dbl>    <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+# 1        1 OPTIMAL  31.0  993.        1        1       0       0       0       0
+# # … with 136 more variables: action_7 <dbl>, action_8 <dbl>, action_9 <dbl>,
+# #   action_10 <dbl>, action_11 <dbl>, action_12 <dbl>, action_13 <dbl>,
+# #   action_14 <dbl>, action_15 <dbl>, action_16 <dbl>, action_17 <dbl>,
+# #   action_18 <dbl>, action_19 <dbl>, action_20 <dbl>, action_21 <dbl>,
+# #   action_22 <dbl>, action_23 <dbl>, action_24 <dbl>, action_25 <dbl>,
+# #   action_26 <dbl>, action_27 <dbl>, action_28 <dbl>, action_29 <dbl>,
+# #   action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>, project_2 <dbl>, …
+

The s1 table contains the solution (i.e. a prioritization) and also various statistics associated with the solution. Here, each row corresponds to a different solution. By default only one solution will be returned, and so the table has one row. The "solution" column contains an integer identifier for the solution (this is when multiple solutions are output), the "obj" column contains the objective value (i.e. the expected feature richness in this case), the "cost" column stores the cost of the solution, and the "status" column contains information from the solver about the solution (i.e. it found an optimal solution). Additionally, it contains columns for each action ("action_1", "action_2", "action_3", …, "baseline_action") which indicate their status in the solution. In other words, these columns tell us if each action was prioritized for funding in the solution (i.e. a value of one) or not (i.e. a value of zero). Additionally, it contains columns for each project ("project_1", "project_2", "project_3", …, "baseline_project") that indicate if the project was completely funded or not. Finally, this table contains columns for each feature ("F1, "F2", "F3, …) which indicate the probability that each feature is expected to persist into the future if the solution was implemented (for information on how this is calculated see ?add_max_richness_objective).

Since the text printed to the screen doesn’t show which projects were completely funded, let’s extract this information from the table.

-# extract names of funded projects
-s1_projects <- s1[, c("solution", p1$project_names())] %>%
-               gather(project, status, -solution)
-
-# print project results
-print(s1_projects)
+# extract names of funded projects +s1_projects <- s1[, c("solution", p1$project_names())] %>% + gather(project, status, -solution) + +# print project results +print(s1_projects)
-
# # A tibble: 71 x 3
-#    solution project    status
-#       <int> <chr>       <dbl>
-#  1        1 project_1       0
-#  2        1 project_2       0
-#  3        1 project_3       0
-#  4        1 project_4       0
-#  5        1 project_5       0
-#  6        1 project_6       0
-#  7        1 project_7       0
-#  8        1 project_8       0
-#  9        1 project_9       0
-# 10        1 project_10      0
-# # … with 61 more rows
-
+
# # A tibble: 71 × 3
+#    solution project    status
+#       <int> <chr>       <dbl>
+#  1        1 project_1       0
+#  2        1 project_2       0
+#  3        1 project_3       0
+#  4        1 project_4       0
+#  5        1 project_5       0
+#  6        1 project_6       0
+#  7        1 project_7       0
+#  8        1 project_8       0
+#  9        1 project_9       0
+# 10        1 project_10      0
+# # … with 61 more rows
+
-
-# print names of completely funded projects
-s1_projects$project[s1_projects$status > 0]
+ +# print names of completely funded projects +s1_projects$project[s1_projects$status > 0]
-
# [1] "project_20" "project_23" "project_28" "project_48" "project_69"
-
+
# [1] "project_20" "project_23" "project_28" "project_48" "project_69"
+

We could also calculate cost-effectiveness measures for each of the conservation projects.

-# calculate cost-effectiveness of each project
-p1_pce <- project_cost_effectiveness(p1)
-
-# print output
-print(p1_pce)
+# calculate cost-effectiveness of each project +p1_pce <- project_cost_effectiveness(p1) + +# print output +print(p1_pce)
-
# # A tibble: 71 x 6
-#    project     cost   obj benefit      ce  rank
-#    <chr>      <dbl> <dbl>   <dbl>   <dbl> <dbl>
-#  1 project_1   992.  15.4    4.65 0.00469  63  
-#  2 project_2  2299.  31.1   20.3  0.00885  27  
-#  3 project_3   578.  15.1    4.35 0.00753  57  
-#  4 project_4  1482.  23.5   12.7  0.00859  31  
-#  5 project_5  2292.  30.2   19.5  0.00850  33  
-#  6 project_6  1296.  12.6    1.85 0.00142  69  
-#  7 project_7   785.  15.3    4.52 0.00576  61  
-#  8 project_8  2761.  33.1   22.3  0.00809  44  
-#  9 project_9  1786.  15.7    4.95 0.00277  65  
-# 10 project_10 2977.  34.7   24.0  0.00806  46.5
-# # … with 61 more rows
-
+
# # A tibble: 71 × 6
+#    project     cost   obj benefit      ce  rank
+#    <chr>      <dbl> <dbl>   <dbl>   <dbl> <dbl>
+#  1 project_1   992.  15.4    4.65 0.00469  63  
+#  2 project_2  2299.  31.1   20.3  0.00885  27  
+#  3 project_3   578.  15.1    4.35 0.00753  57  
+#  4 project_4  1482.  23.5   12.7  0.00859  31  
+#  5 project_5  2292.  30.2   19.5  0.00850  33  
+#  6 project_6  1296.  12.6    1.85 0.00142  69  
+#  7 project_7   785.  15.3    4.52 0.00576  61  
+#  8 project_8  2761.  33.1   22.3  0.00809  44  
+#  9 project_9  1786.  15.7    4.95 0.00277  65  
+# 10 project_10 2977.  34.7   24.0  0.00806  46.5
+# # … with 61 more rows
+

The p1_pce table contains the cost-effectiveness of each project. Specifically, the "project" column contains the name of each project. The "cost" column contains the total cost of all the management actions associated with the project. The "obj" column contains the objective value associated with a solution that contains all of the management actions for each project, and also the actions associated with a zero cost. The "benefit" column contains the difference between (i) the objective value associated with each project and also any zero cost actions (as per the "obj" column), and (ii) the objective value associated with the baseline project. The "ce" column contains the cost-effectiveness of each project. For a given project, this is calculated by dividing its benefit by its cost (as per the "benefit" and "cost" columns). The "rank" column contains the rank for each project, with the most cost-effective project having a rank of one.

By combining the project cost-effectiveness table with the project funding table, we can see that many of the projects selected for funding are not actually the most cost-effective projects. This is because simply selecting the most cost-effective projects might double up on the same features and reduce the overall effectiveness of the solution (see Chadés et al. 2015 for more information).

-# print the ranks of the priority projects
-p1_pce$rank[s1_projects$status > 0]
+# print the ranks of the priority projects +p1_pce$rank[s1_projects$status > 0]
-
# [1] 9 2 4 3 1
-
+
# [1] 9 2 4 3 1
+

We could also save these table to our computer (e.g. so we could view them in a spreadsheet program, such as Microsoft Excel).

-# print folder where the file will be saved
-cat(getwd(), "\n")
-
-# save table to file
-write.table(s1, "solutions.csv" , sep = ",", row.names = FALSE)
-write.table(s1_projects, "project_statuses.csv" , sep = ",", row.names = FALSE)
-write.table(p1_pce, "project_ce.csv" , sep = ",", row.names = FALSE)
+# print folder where the file will be saved +cat(getwd(), "\n") + +# save table to file +write.table(s1, "solutions.csv" , sep = ",", row.names = FALSE) +write.table(s1_projects, "project_statuses.csv" , sep = ",", row.names = FALSE) +write.table(p1_pce, "project_ce.csv" , sep = ",", row.names = FALSE)

Since visualizations are an effective way to understand data, let’s create a bar plot to visualize how well this solution would conserve the features. In this plot, each bar corresponds to a different feature, the width of each bar corresponds to its expected probability of persistence, the color of each bar corresponds to the feature’s weight (since we didn’t specify any weights, all bars are the same color). Asterisks denote features that benefit from fully funded projects, and open circles (if any) denote features that do not benefit from fully funded projects but may indirectly benefit from partially funded projects.

-# plot solution
-plot(p1, s1)
+# plot solution +plot(p1, s1)

Overall, we can see that most species have a fairly decent chance at persisting into the future (approx. 77%). But when making this prioritization, we assumed that we valued the persistence of each feature equally. It is often important to account for the fact that certain features are valued more highly than other features when making prioritizations (e.g. for cultural or taxonomic reasons). The features table that we created earlier contains a "weight" column, and features with larger values mean that they are more important. Let’s quickly visualize the feature weight values.

-# print features table
-print(features)
+# print features table +print(features)
-
# # A tibble: 40 x 2
-#    name     weight
-#    <chr>     <dbl>
-#  1 F1       210.  
-#  2 F2         7.64
-#  3 F3         7.99
-#  4 F4      7732.  
-#  5 F5     34905.  
-#  6 F6         3.31
-#  7 F7      1168.  
-#  8 F8    108301.  
-#  9 F9         3.62
-# 10 F10     6956.  
-# # … with 30 more rows
-
+
# # A tibble: 40 × 2
+#    name     weight
+#    <chr>     <dbl>
+#  1 F1       210.  
+#  2 F2         7.64
+#  3 F3         7.99
+#  4 F4      7732.  
+#  5 F5     34905.  
+#  6 F6         3.31
+#  7 F7      1168.  
+#  8 F8    108301.  
+#  9 F9         3.62
+# 10 F10     6956.  
+# # … with 30 more rows
+
-
-# plot histogram of feature weights
-ggplot(data = features, aes(weight)) +
-geom_histogram(bins = 30) +
-scale_x_continuous(labels = scales::comma) +
-xlab("Feature weight") +
-ylab("Frequency")
+ +# plot histogram of feature weights +ggplot(data = features, aes(weight)) + +geom_histogram(bins = 30) + +scale_x_continuous(labels = scales::comma) + +xlab("Feature weight") + +ylab("Frequency")

We can see that most features have a low weighting (less than 1,000), but a few features have very high weightings (greater than 500,000). Let’s make a new problem based on the original problem, add the feature weights to the new problem, and then solve this new problem.

-# build on existing problem and add feature weights
-p2 <- p1 %>%
-      add_feature_weights("weight")
-
-# print problem
-print(p2)
+# build on existing problem and add feature weights +p2 <- p1 %>% + add_feature_weights("weight") + +# print problem +print(p2)
-
# Project Prioritization Problem
-#   actions          action_1, action_2, action_3, ... (31 actions)
-#   projects         project_1, project_2, project_3, ... (71 projects)
-#   features         F1, F2, F3, ... (40 features)
-#   action costs:    min: 0, max: 113.35036
-#   project success: min: 0.70247, max: 1
-#   objective:       Maximum richness objective [budget (1000)]
-#   targets:         none
-#   weights:         min: 3.31044, max: 2432637.83911
-#   decisions        Binary decision 
-#   constraints:     <none>
-#   solver:          default
-
+
# Project Prioritization Problem
+#   actions          action_1, action_2, action_3, ... (31 actions)
+#   projects         project_1, project_2, project_3, ... (71 projects)
+#   features         F1, F2, F3, ... (40 features)
+#   action costs:    min: 0, max: 113.35036
+#   project success: min: 0.70247, max: 1
+#   objective:       Maximum richness objective [budget (1000)]
+#   targets:         none
+#   weights:         min: 3.31044, max: 2432637.83911
+#   decisions        Binary decision 
+#   constraints:     <none>
+#   solver:          default
+
-# solve problem
-s2 <- solve(p2)
+# solve problem +s2 <- solve(p2) 
-# print solution
-print(s2)
+# print solution +print(s2)
-
# # A tibble: 1 x 146
-#   solution status       obj  cost action_1 action_2 action_3 action_4 action_5
-#      <int> <chr>      <dbl> <dbl>    <dbl>    <dbl>    <dbl>    <dbl>    <dbl>
-# 1        1 OPTIMAL 6290606.  980.        0        1        1        0        0
-# # … with 137 more variables: action_6 <dbl>, action_7 <dbl>, action_8 <dbl>,
-# #   action_9 <dbl>, action_10 <dbl>, action_11 <dbl>, action_12 <dbl>,
-# #   action_13 <dbl>, action_14 <dbl>, action_15 <dbl>, action_16 <dbl>,
-# #   action_17 <dbl>, action_18 <dbl>, action_19 <dbl>, action_20 <dbl>,
-# #   action_21 <dbl>, action_22 <dbl>, action_23 <dbl>, action_24 <dbl>,
-# #   action_25 <dbl>, action_26 <dbl>, action_27 <dbl>, action_28 <dbl>,
-# #   action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>,
-# #   project_2 <dbl>, project_3 <dbl>, project_4 <dbl>, project_5 <dbl>,
-# #   project_6 <dbl>, project_7 <dbl>, project_8 <dbl>, project_9 <dbl>,
-# #   project_10 <dbl>, project_11 <dbl>, project_12 <dbl>, project_13 <dbl>,
-# #   project_14 <dbl>, project_15 <dbl>, project_16 <dbl>, project_17 <dbl>,
-# #   project_18 <dbl>, project_19 <dbl>, project_20 <dbl>, project_21 <dbl>,
-# #   project_22 <dbl>, project_23 <dbl>, project_24 <dbl>, project_25 <dbl>,
-# #   project_26 <dbl>, project_27 <dbl>, project_28 <dbl>, project_29 <dbl>,
-# #   project_30 <dbl>, project_31 <dbl>, project_32 <dbl>, project_33 <dbl>,
-# #   project_34 <dbl>, project_35 <dbl>, project_36 <dbl>, project_37 <dbl>,
-# #   project_38 <dbl>, project_39 <dbl>, project_40 <dbl>, project_41 <dbl>,
-# #   project_42 <dbl>, project_43 <dbl>, project_44 <dbl>, project_45 <dbl>,
-# #   project_46 <dbl>, project_47 <dbl>, project_48 <dbl>, project_49 <dbl>,
-# #   project_50 <dbl>, project_51 <dbl>, project_52 <dbl>, project_53 <dbl>,
-# #   project_54 <dbl>, project_55 <dbl>, project_56 <dbl>, project_57 <dbl>,
-# #   project_58 <dbl>, project_59 <dbl>, project_60 <dbl>, project_61 <dbl>,
-# #   project_62 <dbl>, project_63 <dbl>, project_64 <dbl>, project_65 <dbl>,
-# #   project_66 <dbl>, project_67 <dbl>, project_68 <dbl>, project_69 <dbl>,
-# #   project_70 <dbl>, baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, …
-
+
# # A tibble: 1 × 146
+#   solution status      obj  cost actio…¹ actio…² actio…³ actio…⁴ actio…⁵ actio…⁶
+#      <int> <chr>     <dbl> <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+# 1        1 OPTIMAL  6.29e6  987.       0       1       1       0       0       0
+# # … with 136 more variables: action_7 <dbl>, action_8 <dbl>, action_9 <dbl>,
+# #   action_10 <dbl>, action_11 <dbl>, action_12 <dbl>, action_13 <dbl>,
+# #   action_14 <dbl>, action_15 <dbl>, action_16 <dbl>, action_17 <dbl>,
+# #   action_18 <dbl>, action_19 <dbl>, action_20 <dbl>, action_21 <dbl>,
+# #   action_22 <dbl>, action_23 <dbl>, action_24 <dbl>, action_25 <dbl>,
+# #   action_26 <dbl>, action_27 <dbl>, action_28 <dbl>, action_29 <dbl>,
+# #   action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>, project_2 <dbl>, …
+
-# plot solution
-plot(p2, s2)
+# plot solution +plot(p2, s2)

We can also examine how adding feature weights changed our solution.

-# print actions prioritized for funding in first solution
-actions$name[which(as.logical(as.matrix(s1[, action_names(p1)])))]
+# print actions prioritized for funding in first solution +actions$name[which(as.logical(as.matrix(s1[, action_names(p1)])))]
-
#  [1] "action_1"  "action_2"  "action_10" "action_14" "action_21" "action_22"
-#  [7] "action_26" "action_27" "action_28" "action_30"
-
+
#  [1] "action_1"  "action_2"  "action_10" "action_14" "action_21" "action_22"
+#  [7] "action_26" "action_27" "action_28" "action_30"
+
-
-# print actions prioritized for funding in second solution
-actions$name[which(as.logical(as.matrix(s2[, action_names(p2)])))]
+ +# print actions prioritized for funding in second solution +actions$name[which(as.logical(as.matrix(s2[, action_names(p2)])))]
-
#  [1] "action_2"        "action_3"        "action_14"       "action_17"      
-#  [5] "action_19"       "action_22"       "action_27"       "action_28"      
-#  [9] "action_29"       "action_30"       "baseline_action"
-
+
#  [1] "action_2"        "action_3"        "action_14"       "action_17"      
+#  [5] "action_19"       "action_21"       "action_22"       "action_27"      
+#  [9] "action_28"       "action_29"       "baseline_action"
+
-
-# calculate number of actions funded in both solutions
-sum((as.matrix(s1[, action_names(p1)]) == 1) &
-    (as.matrix(s2[, action_names(p2)]) == 1))
+ +# calculate number of actions funded in both solutions +sum((as.matrix(s1[, action_names(p1)]) == 1) & + (as.matrix(s2[, action_names(p2)]) == 1))
-
# [1] 6
-
+
# [1] 6
+

Earlier, we talked about the oppr R package using the default exact algorithm solver. Although you should have the lpSolveAPI solver automatically installed, we strongly recommend installing the gurobi R package and the Gurobi optimization suite. This is because Gurobi can solve optimization problems much faster than any other software currently supported and it can also easily generate multiple solutions. Unfortunately, you will have to install Gurobi manually, but please see the documentation for the solver for instructions (i.e. enter the command ?add_gurobi_solver into the console). If you have Gurobi installed, let’s try using the Gurobi solver to generate multiple solutions. Here, we will manually specify the Gurobi solver and request 1,000 solutions (though we will probably obtain less than 1,000 solutions, so if we actually wanted 1,000 solutions then we would need to specify a much larger number).

-# create new problem, with Gurobi solver added and request multiple solutions
-# note that we set the gap to 0.5 because we are not necessarily interested
-# in the top 1,000 solutions (for more information on why read the Gurobi
-# documentation on solution pools)
-p3 <- p2 %>%
-      add_gurobi_solver(gap = 0.5, number_solution = 1000)
+# create new problem, with Gurobi solver added and request multiple solutions +# note that we set the gap to 0.5 because we are not necessarily interested +# in the top 1,000 solutions (for more information on why read the Gurobi +# documentation on solution pools) +p3 <- p2 %>% + add_gurobi_solver(gap = 0.5, number_solution = 1000) 
-# solve problem
-s3 <- solve(p3)
+# solve problem +s3 <- solve(p3) 
-# print solution
-print(s3)
+# print solution +print(s3)
-
# # A tibble: 63 x 146
-#    solution status       obj  cost action_1 action_2 action_3 action_4 action_5
-#       <int> <chr>      <dbl> <dbl>    <dbl>    <dbl>    <dbl>    <dbl>    <dbl>
-#  1        1 OPTIMAL 6290606.  973.        0        1        1        0        0
-#  2        2 OPTIMAL 6290606.  874.        0        1        1        0        0
-#  3        3 OPTIMAL 6290606.  967.        0        1        1        0        0
-#  4        4 OPTIMAL 6290606.  971.        0        1        1        0        0
-#  5        5 OPTIMAL 6290606.  980.        0        1        1        0        0
-#  6        6 OPTIMAL 6290606.  974.        0        1        1        0        0
-#  7        7 OPTIMAL 6290606.  972.        0        1        1        0        0
-#  8        8 OPTIMAL 6290606.  977.        0        1        1        0        0
-#  9        9 OPTIMAL 6290606.  977.        0        1        1        0        0
-# 10       10 OPTIMAL 6290606.  987.        0        1        1        0        0
-# # … with 53 more rows, and 137 more variables: action_6 <dbl>, action_7 <dbl>,
-# #   action_8 <dbl>, action_9 <dbl>, action_10 <dbl>, action_11 <dbl>,
-# #   action_12 <dbl>, action_13 <dbl>, action_14 <dbl>, action_15 <dbl>,
-# #   action_16 <dbl>, action_17 <dbl>, action_18 <dbl>, action_19 <dbl>,
-# #   action_20 <dbl>, action_21 <dbl>, action_22 <dbl>, action_23 <dbl>,
-# #   action_24 <dbl>, action_25 <dbl>, action_26 <dbl>, action_27 <dbl>,
-# #   action_28 <dbl>, action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>,
-# #   project_1 <dbl>, project_2 <dbl>, project_3 <dbl>, project_4 <dbl>,
-# #   project_5 <dbl>, project_6 <dbl>, project_7 <dbl>, project_8 <dbl>,
-# #   project_9 <dbl>, project_10 <dbl>, project_11 <dbl>, project_12 <dbl>,
-# #   project_13 <dbl>, project_14 <dbl>, project_15 <dbl>, project_16 <dbl>,
-# #   project_17 <dbl>, project_18 <dbl>, project_19 <dbl>, project_20 <dbl>,
-# #   project_21 <dbl>, project_22 <dbl>, project_23 <dbl>, project_24 <dbl>,
-# #   project_25 <dbl>, project_26 <dbl>, project_27 <dbl>, project_28 <dbl>,
-# #   project_29 <dbl>, project_30 <dbl>, project_31 <dbl>, project_32 <dbl>,
-# #   project_33 <dbl>, project_34 <dbl>, project_35 <dbl>, project_36 <dbl>,
-# #   project_37 <dbl>, project_38 <dbl>, project_39 <dbl>, project_40 <dbl>,
-# #   project_41 <dbl>, project_42 <dbl>, project_43 <dbl>, project_44 <dbl>,
-# #   project_45 <dbl>, project_46 <dbl>, project_47 <dbl>, project_48 <dbl>,
-# #   project_49 <dbl>, project_50 <dbl>, project_51 <dbl>, project_52 <dbl>,
-# #   project_53 <dbl>, project_54 <dbl>, project_55 <dbl>, project_56 <dbl>,
-# #   project_57 <dbl>, project_58 <dbl>, project_59 <dbl>, project_60 <dbl>,
-# #   project_61 <dbl>, project_62 <dbl>, project_63 <dbl>, project_64 <dbl>,
-# #   project_65 <dbl>, project_66 <dbl>, project_67 <dbl>, project_68 <dbl>,
-# #   project_69 <dbl>, project_70 <dbl>, baseline_project <dbl>, F1 <dbl>,
-# #   F2 <dbl>, F3 <dbl>, …
-
+
# # A tibble: 85 × 146
+#    solution status     obj  cost actio…¹ actio…² actio…³ actio…⁴ actio…⁵ actio…⁶
+#       <int> <chr>    <dbl> <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#  1        1 OPTIMAL 6.29e6  974.       0       1       1       0       0       0
+#  2        2 OPTIMAL 6.29e6  969.       0       1       1       0       0       0
+#  3        3 OPTIMAL 6.29e6  967.       0       1       1       0       0       0
+#  4        4 OPTIMAL 6.29e6  974.       0       1       1       0       0       0
+#  5        5 OPTIMAL 6.29e6  977.       0       1       1       0       0       0
+#  6        6 OPTIMAL 6.29e6  874.       0       1       1       0       0       0
+#  7        7 OPTIMAL 6.29e6  980.       0       1       1       0       0       0
+#  8        8 OPTIMAL 6.29e6  977.       0       1       1       1       0       0
+#  9        9 OPTIMAL 6.29e6  987.       0       1       1       0       0       0
+# 10       10 OPTIMAL 6.29e6  970.       0       1       1       0       1       0
+# # … with 75 more rows, 136 more variables: action_7 <dbl>, action_8 <dbl>,
+# #   action_9 <dbl>, action_10 <dbl>, action_11 <dbl>, action_12 <dbl>,
+# #   action_13 <dbl>, action_14 <dbl>, action_15 <dbl>, action_16 <dbl>,
+# #   action_17 <dbl>, action_18 <dbl>, action_19 <dbl>, action_20 <dbl>,
+# #   action_21 <dbl>, action_22 <dbl>, action_23 <dbl>, action_24 <dbl>,
+# #   action_25 <dbl>, action_26 <dbl>, action_27 <dbl>, action_28 <dbl>,
+# #   action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>, …
+
-

We obtained 63 solutions. Let’s briefly explore them.

+

We obtained 85 solutions. Let’s briefly explore them.

-# plot histogram of objective values, and add red dashed line to indicate the
-# objective value for the optimal solution
-ggplot(data = s3, aes(obj)) +
-geom_histogram(bins = 10) +
-geom_vline(xintercept = s2$obj, color = "red", linetype = "dashed") +
-scale_x_continuous(labels = scales::comma) +
-xlab("Expected richness (objective function)") +
-ylab("Frequency") +
-theme(plot.margin = unit(c(5.5, 10.5, 5.5, 5.5), "pt"))
+# plot histogram of objective values, and add red dashed line to indicate the +# objective value for the optimal solution +ggplot(data = s3, aes(obj)) + +geom_histogram(bins = 10) + +geom_vline(xintercept = s2$obj, color = "red", linetype = "dashed") + +scale_x_continuous(labels = scales::comma) + +xlab("Expected richness (objective function)") + +ylab("Frequency") + +theme(plot.margin = unit(c(5.5, 10.5, 5.5, 5.5), "pt"))

We can see that some of our solutions performed much better than other solutions. And we can also see that there are several solutions that perform nearly as well as the optimal solution.

-
-

-Assessing action importance

+
+

Assessing action importance +

After obtaining a solution to a project prioritization problem, it is often important to understand which of priority actions are most “important” [or in other words: irreplaceable; Kukkala & Moilanen (2013)]. This is because it may not be possible to implement all actions immediately and simultaneously, and since some conservation projects may be less likely to succeed if their management actions are delayed, it may be useful to provide decision makers with a measure of importance for each priority action. For example, if a pest eradication project is delayed, then the success of the project may diminish as pest populations increase over time. One simple—and potentially inaccurate (but see Carwardine et al. 2007)—approach for assessing the importance of priority actions (i.e. actions selected for funding in a solution) is calculating the “selection frequency” of the actions. Given multiple solutions, this metric involves calculating the average number of times that each priority action is selected (Ball et al. 2009). For illustrative purposes, we shall compute the selection frequency of the solutions we obtained previously (i.e. the s3 object).

-# print the solution object to remind ourselves what it looks like
-print(s3)
+# print the solution object to remind ourselves what it looks like +print(s3)
-
# # A tibble: 63 x 146
-#    solution status       obj  cost action_1 action_2 action_3 action_4 action_5
-#       <int> <chr>      <dbl> <dbl>    <dbl>    <dbl>    <dbl>    <dbl>    <dbl>
-#  1        1 OPTIMAL 6290606.  973.        0        1        1        0        0
-#  2        2 OPTIMAL 6290606.  874.        0        1        1        0        0
-#  3        3 OPTIMAL 6290606.  967.        0        1        1        0        0
-#  4        4 OPTIMAL 6290606.  971.        0        1        1        0        0
-#  5        5 OPTIMAL 6290606.  980.        0        1        1        0        0
-#  6        6 OPTIMAL 6290606.  974.        0        1        1        0        0
-#  7        7 OPTIMAL 6290606.  972.        0        1        1        0        0
-#  8        8 OPTIMAL 6290606.  977.        0        1        1        0        0
-#  9        9 OPTIMAL 6290606.  977.        0        1        1        0        0
-# 10       10 OPTIMAL 6290606.  987.        0        1        1        0        0
-# # … with 53 more rows, and 137 more variables: action_6 <dbl>, action_7 <dbl>,
-# #   action_8 <dbl>, action_9 <dbl>, action_10 <dbl>, action_11 <dbl>,
-# #   action_12 <dbl>, action_13 <dbl>, action_14 <dbl>, action_15 <dbl>,
-# #   action_16 <dbl>, action_17 <dbl>, action_18 <dbl>, action_19 <dbl>,
-# #   action_20 <dbl>, action_21 <dbl>, action_22 <dbl>, action_23 <dbl>,
-# #   action_24 <dbl>, action_25 <dbl>, action_26 <dbl>, action_27 <dbl>,
-# #   action_28 <dbl>, action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>,
-# #   project_1 <dbl>, project_2 <dbl>, project_3 <dbl>, project_4 <dbl>,
-# #   project_5 <dbl>, project_6 <dbl>, project_7 <dbl>, project_8 <dbl>,
-# #   project_9 <dbl>, project_10 <dbl>, project_11 <dbl>, project_12 <dbl>,
-# #   project_13 <dbl>, project_14 <dbl>, project_15 <dbl>, project_16 <dbl>,
-# #   project_17 <dbl>, project_18 <dbl>, project_19 <dbl>, project_20 <dbl>,
-# #   project_21 <dbl>, project_22 <dbl>, project_23 <dbl>, project_24 <dbl>,
-# #   project_25 <dbl>, project_26 <dbl>, project_27 <dbl>, project_28 <dbl>,
-# #   project_29 <dbl>, project_30 <dbl>, project_31 <dbl>, project_32 <dbl>,
-# #   project_33 <dbl>, project_34 <dbl>, project_35 <dbl>, project_36 <dbl>,
-# #   project_37 <dbl>, project_38 <dbl>, project_39 <dbl>, project_40 <dbl>,
-# #   project_41 <dbl>, project_42 <dbl>, project_43 <dbl>, project_44 <dbl>,
-# #   project_45 <dbl>, project_46 <dbl>, project_47 <dbl>, project_48 <dbl>,
-# #   project_49 <dbl>, project_50 <dbl>, project_51 <dbl>, project_52 <dbl>,
-# #   project_53 <dbl>, project_54 <dbl>, project_55 <dbl>, project_56 <dbl>,
-# #   project_57 <dbl>, project_58 <dbl>, project_59 <dbl>, project_60 <dbl>,
-# #   project_61 <dbl>, project_62 <dbl>, project_63 <dbl>, project_64 <dbl>,
-# #   project_65 <dbl>, project_66 <dbl>, project_67 <dbl>, project_68 <dbl>,
-# #   project_69 <dbl>, project_70 <dbl>, baseline_project <dbl>, F1 <dbl>,
-# #   F2 <dbl>, F3 <dbl>, …
-
+
# # A tibble: 85 × 146
+#    solution status     obj  cost actio…¹ actio…² actio…³ actio…⁴ actio…⁵ actio…⁶
+#       <int> <chr>    <dbl> <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#  1        1 OPTIMAL 6.29e6  974.       0       1       1       0       0       0
+#  2        2 OPTIMAL 6.29e6  969.       0       1       1       0       0       0
+#  3        3 OPTIMAL 6.29e6  967.       0       1       1       0       0       0
+#  4        4 OPTIMAL 6.29e6  974.       0       1       1       0       0       0
+#  5        5 OPTIMAL 6.29e6  977.       0       1       1       0       0       0
+#  6        6 OPTIMAL 6.29e6  874.       0       1       1       0       0       0
+#  7        7 OPTIMAL 6.29e6  980.       0       1       1       0       0       0
+#  8        8 OPTIMAL 6.29e6  977.       0       1       1       1       0       0
+#  9        9 OPTIMAL 6.29e6  987.       0       1       1       0       0       0
+# 10       10 OPTIMAL 6.29e6  970.       0       1       1       0       1       0
+# # … with 75 more rows, 136 more variables: action_7 <dbl>, action_8 <dbl>,
+# #   action_9 <dbl>, action_10 <dbl>, action_11 <dbl>, action_12 <dbl>,
+# #   action_13 <dbl>, action_14 <dbl>, action_15 <dbl>, action_16 <dbl>,
+# #   action_17 <dbl>, action_18 <dbl>, action_19 <dbl>, action_20 <dbl>,
+# #   action_21 <dbl>, action_22 <dbl>, action_23 <dbl>, action_24 <dbl>,
+# #   action_25 <dbl>, action_26 <dbl>, action_27 <dbl>, action_28 <dbl>,
+# #   action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>, …
+
-
-# calculate percentage of times each action was selected for
-# funding in the solutions
-actions$sel_freq <- apply(as.matrix(s3[, actions$name]), 2, mean) * 100
-
-# print the actions table with the new column
-print(actions)
+ +# calculate percentage of times each action was selected for +# funding in the solutions +actions$sel_freq <- apply(as.matrix(s3[, actions$name]), 2, mean) * 100 + +# print the actions table with the new column +print(actions)
-
# # A tibble: 31 x 5
-#    name       cost locked_in locked_out sel_freq
-#    <chr>     <dbl> <lgl>     <lgl>         <dbl>
-#  1 action_1   97.8 FALSE     FALSE         11.1 
-#  2 action_2   94.0 FALSE     FALSE         58.7 
-#  3 action_3  100.  FALSE     FALSE         63.5 
-#  4 action_4  103.  FALSE     FALSE          9.52
-#  5 action_5   96.1 FALSE     FALSE          1.59
-#  6 action_6   98.1 FALSE     FALSE          1.59
-#  7 action_7   97.6 FALSE     FALSE         11.1 
-#  8 action_8  104.  FALSE     FALSE         12.7 
-#  9 action_9   99.9 FALSE     FALSE          6.35
-# 10 action_10  93.1 FALSE     FALSE         22.2 
-# # … with 21 more rows
-
+
# # A tibble: 31 × 5
+#    name       cost locked_in locked_out sel_freq
+#    <chr>     <dbl> <lgl>     <lgl>         <dbl>
+#  1 action_1   97.8 FALSE     FALSE         11.8 
+#  2 action_2   94.0 FALSE     FALSE         71.8 
+#  3 action_3  100.  FALSE     FALSE         27.1 
+#  4 action_4  103.  FALSE     FALSE         21.2 
+#  5 action_5   96.1 FALSE     FALSE         17.6 
+#  6 action_6   98.1 FALSE     FALSE          0   
+#  7 action_7   97.6 FALSE     FALSE         11.8 
+#  8 action_8  104.  FALSE     FALSE         11.8 
+#  9 action_9   99.9 FALSE     FALSE          3.53
+# 10 action_10  93.1 FALSE     FALSE         32.9 
+# # … with 21 more rows
+
-
-# print top 10 most important actions based on selection frequency
-head(actions[order(actions$sel_freq, decreasing = TRUE), ], n = 10)
+ +# print top 10 most important actions based on selection frequency +head(actions[order(actions$sel_freq, decreasing = TRUE), ], n = 10)
-
# # A tibble: 10 x 5
-#    name             cost locked_in locked_out sel_freq
-#    <chr>           <dbl> <lgl>     <lgl>         <dbl>
-#  1 baseline_action   0   FALSE     FALSE         100  
-#  2 action_14        99.4 FALSE     FALSE          98.4
-#  3 action_28       102.  FALSE     FALSE          73.0
-#  4 action_19        89.8 FALSE     FALSE          71.4
-#  5 action_27        91.1 FALSE     FALSE          69.8
-#  6 action_17       101.  FALSE     FALSE          66.7
-#  7 action_29       103.  FALSE     FALSE          66.7
-#  8 action_3        100.  FALSE     FALSE          63.5
-#  9 action_2         94.0 FALSE     FALSE          58.7
-# 10 action_22        93.9 FALSE     FALSE          49.2
-
+
# # A tibble: 10 × 5
+#    name             cost locked_in locked_out sel_freq
+#    <chr>           <dbl> <lgl>     <lgl>         <dbl>
+#  1 action_14        99.4 FALSE     FALSE          97.6
+#  2 baseline_action   0   FALSE     FALSE          97.6
+#  3 action_19        89.8 FALSE     FALSE          74.1
+#  4 action_2         94.0 FALSE     FALSE          71.8
+#  5 action_22        93.9 FALSE     FALSE          68.2
+#  6 action_28       102.  FALSE     FALSE          56.5
+#  7 action_27        91.1 FALSE     FALSE          48.2
+#  8 action_29       103.  FALSE     FALSE          41.2
+#  9 action_10        93.1 FALSE     FALSE          32.9
+# 10 action_17       101.  FALSE     FALSE          32.9
+
-
-# plot histogram showing solution frequency
-ggplot(data = actions, aes(sel_freq)) +
-geom_histogram(bins = 30) +
-coord_cartesian(xlim = c(0, 100)) +
-xlab("Selection frequency (%)") +
-ylab("Frequency")
+ +# plot histogram showing solution frequency +ggplot(data = actions, aes(sel_freq)) + +geom_histogram(bins = 30) + +coord_cartesian(xlim = c(0, 100)) + +xlab("Selection frequency (%)") + +ylab("Frequency")

Although selection frequency might seem like an appealing metric, it suffers from an assumption that is unrealistic for most large-scale problems. Specifically, it assumes that our portfolio of solutions is a representative sample of the near-optimal solutions to the problem. And we do not currently have any method to verify this, except by enumerating all possible solutions—which is not feasible for reasonably sized project prioritization exercises. So now we shall examine a superior metric termed the “replacement cost” (Moilanen et al. 2009). Given a set of priority actions and a project prioritization problem, the replacement cost can be calculated for a given priority action by re-solving the problem with the priority action locked out, and calculating the difference between the objective value based on the priority actions and the new objective value with the priority action locked out. So let’s calculate the replacement cost for the priority actions in object s2 using the problem p2.

-# print p2 to remind ourselves about the problem
-print(p2)
+# print p2 to remind ourselves about the problem +print(p2)
-
# Project Prioritization Problem
-#   actions          action_1, action_2, action_3, ... (31 actions)
-#   projects         project_1, project_2, project_3, ... (71 projects)
-#   features         F1, F2, F3, ... (40 features)
-#   action costs:    min: 0, max: 113.35036
-#   project success: min: 0.70247, max: 1
-#   objective:       Maximum richness objective [budget (1000)]
-#   targets:         none
-#   weights:         min: 3.31044, max: 2432637.83911
-#   decisions        Binary decision 
-#   constraints:     <none>
-#   solver:          default
-
+
# Project Prioritization Problem
+#   actions          action_1, action_2, action_3, ... (31 actions)
+#   projects         project_1, project_2, project_3, ... (71 projects)
+#   features         F1, F2, F3, ... (40 features)
+#   action costs:    min: 0, max: 113.35036
+#   project success: min: 0.70247, max: 1
+#   objective:       Maximum richness objective [budget (1000)]
+#   targets:         none
+#   weights:         min: 3.31044, max: 2432637.83911
+#   decisions        Binary decision 
+#   constraints:     <none>
+#   solver:          default
+
-
-# print s2 to remind ourselves about the solution
-print(s2)
+ +# print s2 to remind ourselves about the solution +print(s2)
-
# # A tibble: 1 x 146
-#   solution status       obj  cost action_1 action_2 action_3 action_4 action_5
-#      <int> <chr>      <dbl> <dbl>    <dbl>    <dbl>    <dbl>    <dbl>    <dbl>
-# 1        1 OPTIMAL 6290606.  980.        0        1        1        0        0
-# # … with 137 more variables: action_6 <dbl>, action_7 <dbl>, action_8 <dbl>,
-# #   action_9 <dbl>, action_10 <dbl>, action_11 <dbl>, action_12 <dbl>,
-# #   action_13 <dbl>, action_14 <dbl>, action_15 <dbl>, action_16 <dbl>,
-# #   action_17 <dbl>, action_18 <dbl>, action_19 <dbl>, action_20 <dbl>,
-# #   action_21 <dbl>, action_22 <dbl>, action_23 <dbl>, action_24 <dbl>,
-# #   action_25 <dbl>, action_26 <dbl>, action_27 <dbl>, action_28 <dbl>,
-# #   action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>,
-# #   project_2 <dbl>, project_3 <dbl>, project_4 <dbl>, project_5 <dbl>,
-# #   project_6 <dbl>, project_7 <dbl>, project_8 <dbl>, project_9 <dbl>,
-# #   project_10 <dbl>, project_11 <dbl>, project_12 <dbl>, project_13 <dbl>,
-# #   project_14 <dbl>, project_15 <dbl>, project_16 <dbl>, project_17 <dbl>,
-# #   project_18 <dbl>, project_19 <dbl>, project_20 <dbl>, project_21 <dbl>,
-# #   project_22 <dbl>, project_23 <dbl>, project_24 <dbl>, project_25 <dbl>,
-# #   project_26 <dbl>, project_27 <dbl>, project_28 <dbl>, project_29 <dbl>,
-# #   project_30 <dbl>, project_31 <dbl>, project_32 <dbl>, project_33 <dbl>,
-# #   project_34 <dbl>, project_35 <dbl>, project_36 <dbl>, project_37 <dbl>,
-# #   project_38 <dbl>, project_39 <dbl>, project_40 <dbl>, project_41 <dbl>,
-# #   project_42 <dbl>, project_43 <dbl>, project_44 <dbl>, project_45 <dbl>,
-# #   project_46 <dbl>, project_47 <dbl>, project_48 <dbl>, project_49 <dbl>,
-# #   project_50 <dbl>, project_51 <dbl>, project_52 <dbl>, project_53 <dbl>,
-# #   project_54 <dbl>, project_55 <dbl>, project_56 <dbl>, project_57 <dbl>,
-# #   project_58 <dbl>, project_59 <dbl>, project_60 <dbl>, project_61 <dbl>,
-# #   project_62 <dbl>, project_63 <dbl>, project_64 <dbl>, project_65 <dbl>,
-# #   project_66 <dbl>, project_67 <dbl>, project_68 <dbl>, project_69 <dbl>,
-# #   project_70 <dbl>, baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, …
-
+
# # A tibble: 1 × 146
+#   solution status      obj  cost actio…¹ actio…² actio…³ actio…⁴ actio…⁵ actio…⁶
+#      <int> <chr>     <dbl> <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+# 1        1 OPTIMAL  6.29e6  987.       0       1       1       0       0       0
+# # … with 136 more variables: action_7 <dbl>, action_8 <dbl>, action_9 <dbl>,
+# #   action_10 <dbl>, action_11 <dbl>, action_12 <dbl>, action_13 <dbl>,
+# #   action_14 <dbl>, action_15 <dbl>, action_16 <dbl>, action_17 <dbl>,
+# #   action_18 <dbl>, action_19 <dbl>, action_20 <dbl>, action_21 <dbl>,
+# #   action_22 <dbl>, action_23 <dbl>, action_24 <dbl>, action_25 <dbl>,
+# #   action_26 <dbl>, action_27 <dbl>, action_28 <dbl>, action_29 <dbl>,
+# #   action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>, project_2 <dbl>, …
+
-
-# calculate replacement costs for each priority action selected in s2
-r2 <- replacement_costs(p2, s2)
-
-# print output
-print(r2)
+ +# calculate replacement costs for each priority action selected in s2 +r2 <- replacement_costs(p2, s2) + +# print output +print(r2)
-
# # A tibble: 31 x 4
-#    name       cost      obj rep_cost
-#    <chr>     <dbl>    <dbl>    <dbl>
-#  1 action_1    NA       NA       NA 
-#  2 action_2   988. 6102909.  187698.
-#  3 action_3   993. 6122986.  167620.
-#  4 action_4    NA       NA       NA 
-#  5 action_5    NA       NA       NA 
-#  6 action_6    NA       NA       NA 
-#  7 action_7    NA       NA       NA 
-#  8 action_8    NA       NA       NA 
-#  9 action_9    NA       NA       NA 
-# 10 action_10   NA       NA       NA 
-# # … with 21 more rows
-
+
# # A tibble: 31 × 4
+#    name       cost      obj rep_cost
+#    <chr>     <dbl>    <dbl>    <dbl>
+#  1 action_1    NA       NA       NA 
+#  2 action_2   988. 6102909.  187698.
+#  3 action_3   993. 6122986.  167620.
+#  4 action_4    NA       NA       NA 
+#  5 action_5    NA       NA       NA 
+#  6 action_6    NA       NA       NA 
+#  7 action_7    NA       NA       NA 
+#  8 action_8    NA       NA       NA 
+#  9 action_9    NA       NA       NA 
+# 10 action_10   NA       NA       NA 
+# # … with 21 more rows
+

The r1 table contains the replacement costs for each action and also various statistics associated with the solutions obtained when locking out each action. Here, each row corresponds to a different action. The "action" column contains the name of the actions (as per the actions table used when building the problem), the "cost" column contains the cost of the solutions obtained when each action was locked out, the "obj" column contains the objective value of the solutions when each action was locked out (i.e. the expected feature richness in this case), and the "rep_cost" column contains the replacement costs for the actions. Actions associated with larger replacement cost values are more irreplaceable, actions associated with missing (NA) replacement cost values were not selected for funding in the input solution (i.e. s2), and actions associated with infinite (Inf) replacement cost values are absolutely critical for meeting the constraints (though infinite values should only problems with minimum set objectives and potentially the baseline project).

-# add replacement costs to action table
-actions$rep_cost <- r2$rep_cost
-
-# print actions, ordered by replacement cost
-print(actions[order(actions$rep_cost, decreasing = TRUE), ])
+# add replacement costs to action table +actions$rep_cost <- r2$rep_cost + +# print actions, ordered by replacement cost +print(actions[order(actions$rep_cost, decreasing = TRUE), ])
-
# # A tibble: 31 x 6
-#    name             cost locked_in locked_out sel_freq rep_cost
-#    <chr>           <dbl> <lgl>     <lgl>         <dbl>    <dbl>
-#  1 action_14        99.4 FALSE     FALSE          98.4  345636.
-#  2 action_2         94.0 FALSE     FALSE          58.7  187698.
-#  3 action_22        93.9 FALSE     FALSE          49.2  187698.
-#  4 action_3        100.  FALSE     FALSE          63.5  167620.
-#  5 action_17       101.  FALSE     FALSE          66.7  167620.
-#  6 action_19        89.8 FALSE     FALSE          71.4  167620.
-#  7 action_27        91.1 FALSE     FALSE          69.8  167620.
-#  8 action_28       102.  FALSE     FALSE          73.0  167620.
-#  9 action_29       103.  FALSE     FALSE          66.7  167620.
-# 10 baseline_action   0   FALSE     FALSE         100    167620.
-# # … with 21 more rows
-
+
# # A tibble: 31 × 6
+#    name             cost locked_in locked_out sel_freq rep_cost
+#    <chr>           <dbl> <lgl>     <lgl>         <dbl>    <dbl>
+#  1 action_14        99.4 FALSE     FALSE          97.6  345636.
+#  2 action_2         94.0 FALSE     FALSE          71.8  187698.
+#  3 action_22        93.9 FALSE     FALSE          68.2  187698.
+#  4 action_3        100.  FALSE     FALSE          27.1  167620.
+#  5 action_17       101.  FALSE     FALSE          32.9  167620.
+#  6 action_19        89.8 FALSE     FALSE          74.1  167620.
+#  7 action_27        91.1 FALSE     FALSE          48.2  167620.
+#  8 action_28       102.  FALSE     FALSE          56.5  167620.
+#  9 action_29       103.  FALSE     FALSE          41.2  167620.
+# 10 baseline_action   0   FALSE     FALSE          97.6  167620.
+# # … with 21 more rows
+
-
-# test correlation between selection frequencies and replacement costs
-cor.test(x = actions$sel_freq, y = actions$rep_cost, method = "pearson")
+ +# test correlation between selection frequencies and replacement costs +cor.test(x = actions$sel_freq, y = actions$rep_cost, method = "pearson")
-
# 
-#     Pearson's product-moment correlation
-# 
-# data:  actions$sel_freq and actions$rep_cost
-# t = 3.4433, df = 9, p-value = 0.007352
-# alternative hypothesis: true correlation is not equal to 0
-# 95 percent confidence interval:
-#  0.2813548 0.9322171
-# sample estimates:
-#       cor 
-# 0.7539755
-
+
# 
+#  Pearson's product-moment correlation
+# 
+# data:  actions$sel_freq and actions$rep_cost
+# t = 2.8052, df = 9, p-value = 0.02054
+# alternative hypothesis: true correlation is not equal to 0
+# 95 percent confidence interval:
+#  0.1408131 0.9100231
+# sample estimates:
+#       cor 
+# 0.6829953
+
-
-# plot histogram of replacement costs,
-ggplot(data = actions, aes(rep_cost)) +
-geom_histogram(bins = 30, na.rm = TRUE) +
-scale_x_continuous(labels = scales::comma) +
-xlab("Replacement cost") +
-ylab("Frequency")
+ +# plot histogram of replacement costs, +ggplot(data = actions, aes(rep_cost)) + +geom_histogram(bins = 30, na.rm = TRUE) + +scale_x_continuous(labels = scales::comma) + +xlab("Replacement cost") + +ylab("Frequency")

-
-

-Complementarity in project prioritizations

+
+

Complementarity in project prioritizations +

Broadly speaking, the principle of complementarity is that individual conservation actions should complement each other—in other words, they should not double up on the same biodiversity features—and when implemented together, conservation actions should conserve a comprehensive sample of biodiversity (Vane-Wright et al. 1991; Kukkala & Moilanen 2013). This principle was born from the profound realization that individual reserves need to provide habitat for different species in order to build a reserve network that provides habitat for many different species—even if this means selecting some individual reserves that do not provide habitat for as many species as other potential reserves (Kirkpatrick 1983). In the context of project prioritization, this principle means that resources should be allocated in such a way that avoids doubling up on the same conservation features so that resources can be effectively allocated to as many conservation features as possible (Chadés et al. 2015). For instance, if decision makers consider it acceptable for features to have a 70% chance of persisting into the future, then we should avoid solutions which overly surpass this threshold (e.g. 99%) because we can allocate the limited resources to help other features reach this threshold. Such target thresholds can provide a transparent and effective method for establishing conservation priorities (Carwardine et al. 2009). So, let’s try developing a prioritization with conservation targets. Specifically, we will develop a prioritization that maximizes the number of features that have a 60% chance of persisting, subject to the same $1,000 budget as before.

-# build problem
-p4 <- problem(projects = projects, actions = actions, features = features,
-              "name", "success", "name", "cost", "name") %>%
-      add_max_targets_met_objective(budget = 1000) %>%
-      add_absolute_targets(0.7) %>%
-      add_binary_decisions()
-
-# print problem
-print(p4)
+# build problem +p4 <- problem(projects = projects, actions = actions, features = features, + "name", "success", "name", "cost", "name") %>% + add_max_targets_met_objective(budget = 1000) %>% + add_absolute_targets(0.7) %>% + add_binary_decisions() + +# print problem +print(p4)
-
# Project Prioritization Problem
-#   actions          action_1, action_2, action_3, ... (31 actions)
-#   projects         project_1, project_2, project_3, ... (71 projects)
-#   features         F1, F2, F3, ... (40 features)
-#   action costs:    min: 0, max: 113.35036
-#   project success: min: 0.70247, max: 1
-#   objective:       Maximum targets met objective [budget (1000)]
-#   targets:         Absolute targets [targets (min: 0.7, max: 0.7)]
-#   weights:         default
-#   decisions        Binary decision 
-#   constraints:     <none>
-#   solver:          default
-
+
# Project Prioritization Problem
+#   actions          action_1, action_2, action_3, ... (31 actions)
+#   projects         project_1, project_2, project_3, ... (71 projects)
+#   features         F1, F2, F3, ... (40 features)
+#   action costs:    min: 0, max: 113.35036
+#   project success: min: 0.70247, max: 1
+#   objective:       Maximum targets met objective [budget (1000)]
+#   targets:         Absolute targets [targets (min: 0.7, max: 0.7)]
+#   weights:         default
+#   decisions        Binary decision 
+#   constraints:     <none>
+#   solver:          default
+
-# solve problem
-s4 <- solve(p4)
+# solve problem +s4 <- solve(p4)
-# print solution
-print(s4)
+# print solution +print(s4)
-
# # A tibble: 1 x 146
-#   solution status    obj  cost action_1 action_2 action_3 action_4 action_5
-#      <int> <chr>   <dbl> <dbl>    <dbl>    <dbl>    <dbl>    <dbl>    <dbl>
-# 1        1 OPTIMAL    36  993.        1        1        0        0        0
-# # … with 137 more variables: action_6 <dbl>, action_7 <dbl>, action_8 <dbl>,
-# #   action_9 <dbl>, action_10 <dbl>, action_11 <dbl>, action_12 <dbl>,
-# #   action_13 <dbl>, action_14 <dbl>, action_15 <dbl>, action_16 <dbl>,
-# #   action_17 <dbl>, action_18 <dbl>, action_19 <dbl>, action_20 <dbl>,
-# #   action_21 <dbl>, action_22 <dbl>, action_23 <dbl>, action_24 <dbl>,
-# #   action_25 <dbl>, action_26 <dbl>, action_27 <dbl>, action_28 <dbl>,
-# #   action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>,
-# #   project_2 <dbl>, project_3 <dbl>, project_4 <dbl>, project_5 <dbl>,
-# #   project_6 <dbl>, project_7 <dbl>, project_8 <dbl>, project_9 <dbl>,
-# #   project_10 <dbl>, project_11 <dbl>, project_12 <dbl>, project_13 <dbl>,
-# #   project_14 <dbl>, project_15 <dbl>, project_16 <dbl>, project_17 <dbl>,
-# #   project_18 <dbl>, project_19 <dbl>, project_20 <dbl>, project_21 <dbl>,
-# #   project_22 <dbl>, project_23 <dbl>, project_24 <dbl>, project_25 <dbl>,
-# #   project_26 <dbl>, project_27 <dbl>, project_28 <dbl>, project_29 <dbl>,
-# #   project_30 <dbl>, project_31 <dbl>, project_32 <dbl>, project_33 <dbl>,
-# #   project_34 <dbl>, project_35 <dbl>, project_36 <dbl>, project_37 <dbl>,
-# #   project_38 <dbl>, project_39 <dbl>, project_40 <dbl>, project_41 <dbl>,
-# #   project_42 <dbl>, project_43 <dbl>, project_44 <dbl>, project_45 <dbl>,
-# #   project_46 <dbl>, project_47 <dbl>, project_48 <dbl>, project_49 <dbl>,
-# #   project_50 <dbl>, project_51 <dbl>, project_52 <dbl>, project_53 <dbl>,
-# #   project_54 <dbl>, project_55 <dbl>, project_56 <dbl>, project_57 <dbl>,
-# #   project_58 <dbl>, project_59 <dbl>, project_60 <dbl>, project_61 <dbl>,
-# #   project_62 <dbl>, project_63 <dbl>, project_64 <dbl>, project_65 <dbl>,
-# #   project_66 <dbl>, project_67 <dbl>, project_68 <dbl>, project_69 <dbl>,
-# #   project_70 <dbl>, baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, …
-
+
# # A tibble: 1 × 146
+#   solution status    obj  cost action_1 action_2 actio…¹ actio…² actio…³ actio…⁴
+#      <int> <chr>   <dbl> <dbl>    <dbl>    <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+# 1        1 OPTIMAL    36  993.        1        1       0       0       0       0
+# # … with 136 more variables: action_7 <dbl>, action_8 <dbl>, action_9 <dbl>,
+# #   action_10 <dbl>, action_11 <dbl>, action_12 <dbl>, action_13 <dbl>,
+# #   action_14 <dbl>, action_15 <dbl>, action_16 <dbl>, action_17 <dbl>,
+# #   action_18 <dbl>, action_19 <dbl>, action_20 <dbl>, action_21 <dbl>,
+# #   action_22 <dbl>, action_23 <dbl>, action_24 <dbl>, action_25 <dbl>,
+# #   action_26 <dbl>, action_27 <dbl>, action_28 <dbl>, action_29 <dbl>,
+# #   action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>, project_2 <dbl>, …
+
-
-# plot solution
-plot(p4, s4)
+ +# plot solution +plot(p4, s4)

But how would the number of features which meet the target change if we increased the budget? Or how would the number of features which meet the target change if we increased the target to 85%? These are common questions in project prioritization exercises (e.g. Chadés et al. 2015; Di Fonzo et al. 2016; Martin et al. 2018). So, let’s try solving this problem with 70% and 85% targets under a range of different budgets and plot the relationships.

-# specify budgets, ranging between zero and the total cost of all the budgets,
-# with the total number of different budgets equaling 50
-# (note that we would use a higher number for publications)
-budgets <- seq(0, sum(actions$cost), length.out = 50)
-
-# specify targets
-targets <- c(0.7, 0.85)
-
-# run prioritizations and compile results
-comp_data <- lapply(targets, function(i) {
-  o <- lapply(budgets, function(b) {
-    problem(projects = projects, actions = actions, features = features,
-            "name", "success", "name", "cost", "name") %>%
-    add_max_targets_met_objective(budget = b) %>%
-    add_absolute_targets(i) %>%
-    add_binary_decisions() %>%
-    add_default_solver(verbose = FALSE) %>%
-    solve()
-  })
-  o <- as_tibble(do.call(rbind, o))
-  o$budget <- budgets
-  o$target <- paste0(i * 100, "%")
-  o
-})
-comp_data <- as_tibble(do.call(rbind, comp_data))
-
-# plot the relationship between the number of features that meet the target
-# in a solution and the cost of a solution
-ggplot(comp_data, aes(x = cost, y = obj, color = target)) +
-geom_step() +
-xlab("Solution cost ($)") +
-ylab("Number of features with targets") +
-labs(color = "Target")
+# specify budgets, ranging between zero and the total cost of all the budgets, +# with the total number of different budgets equaling 50 +# (note that we would use a higher number for publications) +budgets <- seq(0, sum(actions$cost), length.out = 50) + +# specify targets +targets <- c(0.7, 0.85) + +# run prioritizations and compile results +comp_data <- lapply(targets, function(i) { + o <- lapply(budgets, function(b) { + problem(projects = projects, actions = actions, features = features, + "name", "success", "name", "cost", "name") %>% + add_max_targets_met_objective(budget = b) %>% + add_absolute_targets(i) %>% + add_binary_decisions() %>% + add_default_solver(verbose = FALSE) %>% + solve() + }) + o <- as_tibble(do.call(rbind, o)) + o$budget <- budgets + o$target <- paste0(i * 100, "%") + o +}) +comp_data <- as_tibble(do.call(rbind, comp_data)) + +# plot the relationship between the number of features that meet the target +# in a solution and the cost of a solution +ggplot(comp_data, aes(x = cost, y = obj, color = target)) + +geom_step() + +xlab("Solution cost ($)") + +ylab("Number of features with targets") + +labs(color = "Target")

We might also be interested in understanding how exactly how much it would cost to implement a set of management actions that would result in all of the features meeting a specific target. Let’s see if we can find out how much it would cost to ensure that every feature has a 99% probability of persistence.

-# build problem
-p5 <- problem(projects = projects, actions = actions, features = features,
-              "name", "success", "name", "cost", "name") %>%
-      add_min_set_objective() %>%
-      add_absolute_targets(0.99) %>%
-      add_binary_decisions()
-
-# print problem
-print(p5)
+# build problem +p5 <- problem(projects = projects, actions = actions, features = features, + "name", "success", "name", "cost", "name") %>% + add_min_set_objective() %>% + add_absolute_targets(0.99) %>% + add_binary_decisions() + +# print problem +print(p5)
-
# Project Prioritization Problem
-#   actions          action_1, action_2, action_3, ... (31 actions)
-#   projects         project_1, project_2, project_3, ... (71 projects)
-#   features         F1, F2, F3, ... (40 features)
-#   action costs:    min: 0, max: 113.35036
-#   project success: min: 0.70247, max: 1
-#   objective:       Minimum set objective 
-#   targets:         Absolute targets [targets (min: 0.99, max: 0.99)]
-#   weights:         default
-#   decisions        Binary decision 
-#   constraints:     <none>
-#   solver:          default
-
+
# Project Prioritization Problem
+#   actions          action_1, action_2, action_3, ... (31 actions)
+#   projects         project_1, project_2, project_3, ... (71 projects)
+#   features         F1, F2, F3, ... (40 features)
+#   action costs:    min: 0, max: 113.35036
+#   project success: min: 0.70247, max: 1
+#   objective:       Minimum set objective 
+#   targets:         Absolute targets [targets (min: 0.99, max: 0.99)]
+#   weights:         default
+#   decisions        Binary decision 
+#   constraints:     <none>
+#   solver:          default
+
-# attempt to solve problem, but this will throw an error
-s5 <- solve(p5)
+# attempt to solve problem, but this will throw an error +s5 <- solve(p5)
-
# Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-# Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-# Optimize a model with 4068 rows, 2942 columns and 10690 nonzeros
-# Model fingerprint: 0xa60a2b7f
-# Variable types: 0 continuous, 2942 integer (2942 binary)
-# Coefficient statistics:
-#   Matrix range     [8e-02, 1e+00]
-#   Objective range  [9e+01, 1e+02]
-#   Bounds range     [1e+00, 1e+00]
-#   RHS range        [1e+00, 1e+00]
-# Presolve time: 0.00s
-# 
-# Explored 0 nodes (0 simplex iterations) in 0.00 seconds
-# Thread count was 1 (of 8 available processors)
-# 
-# Solution count 0
-# 
-# Model is infeasible
-# Best objective -, best bound -, gap -
-
+
# Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+# Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+# Optimize a model with 4068 rows, 2942 columns and 10690 nonzeros
+# Model fingerprint: 0xa60a2b7f
+# Variable types: 0 continuous, 2942 integer (2942 binary)
+# Coefficient statistics:
+#   Matrix range     [8e-02, 1e+00]
+#   Objective range  [9e+01, 1e+02]
+#   Bounds range     [1e+00, 1e+00]
+#   RHS range        [1e+00, 1e+00]
+# Presolve time: 0.00s
+# 
+# Explored 0 nodes (0 simplex iterations) in 0.01 seconds (0.00 work units)
+# Thread count was 1 (of 8 available processors)
+# 
+# Solution count 0
+# 
+# Model is infeasible
+# Best objective -, best bound -, gap -
+
-
# Error in solve(p5): project prioritization problem is infeasible
+
# Error in solve(p5): project prioritization problem is infeasible

We received an error instead of a solution. If we read the error message, then we can see that it is telling us—perhaps rather tersely—that there are no valid solutions to the problem (i.e. the problem is infeasible), because some features simply cannot obtain an 99% probability of persistence given the range of conservation projects that are available. So, let’s see how much it would cost to ensure that every feature has a 60% chance of persistence.

-# build problem
-p6 <- problem(projects = projects, actions = actions, features = features,
-              "name", "success", "name", "cost", "name") %>%
-      add_min_set_objective() %>%
-      add_absolute_targets(0.60) %>%
-      add_binary_decisions()
-
-# print problem
-print(p6)
+# build problem +p6 <- problem(projects = projects, actions = actions, features = features, + "name", "success", "name", "cost", "name") %>% + add_min_set_objective() %>% + add_absolute_targets(0.60) %>% + add_binary_decisions() + +# print problem +print(p6)
-
# Project Prioritization Problem
-#   actions          action_1, action_2, action_3, ... (31 actions)
-#   projects         project_1, project_2, project_3, ... (71 projects)
-#   features         F1, F2, F3, ... (40 features)
-#   action costs:    min: 0, max: 113.35036
-#   project success: min: 0.70247, max: 1
-#   objective:       Minimum set objective 
-#   targets:         Absolute targets [targets (min: 0.6, max: 0.6)]
-#   weights:         default
-#   decisions        Binary decision 
-#   constraints:     <none>
-#   solver:          default
-
+
# Project Prioritization Problem
+#   actions          action_1, action_2, action_3, ... (31 actions)
+#   projects         project_1, project_2, project_3, ... (71 projects)
+#   features         F1, F2, F3, ... (40 features)
+#   action costs:    min: 0, max: 113.35036
+#   project success: min: 0.70247, max: 1
+#   objective:       Minimum set objective 
+#   targets:         Absolute targets [targets (min: 0.6, max: 0.6)]
+#   weights:         default
+#   decisions        Binary decision 
+#   constraints:     <none>
+#   solver:          default
+
-# solve problem
-s6 <- solve(p6)
+# solve problem +s6 <- solve(p6) 
-# print solution
-print(s6)
+# print solution +print(s6)
-
# # A tibble: 1 x 146
-#   solution status    obj  cost action_1 action_2 action_3 action_4 action_5
-#      <int> <chr>   <dbl> <dbl>    <dbl>    <dbl>    <dbl>    <dbl>    <dbl>
-# 1        1 OPTIMAL  972.  972.        0        1        0        0        0
-# # … with 137 more variables: action_6 <dbl>, action_7 <dbl>, action_8 <dbl>,
-# #   action_9 <dbl>, action_10 <dbl>, action_11 <dbl>, action_12 <dbl>,
-# #   action_13 <dbl>, action_14 <dbl>, action_15 <dbl>, action_16 <dbl>,
-# #   action_17 <dbl>, action_18 <dbl>, action_19 <dbl>, action_20 <dbl>,
-# #   action_21 <dbl>, action_22 <dbl>, action_23 <dbl>, action_24 <dbl>,
-# #   action_25 <dbl>, action_26 <dbl>, action_27 <dbl>, action_28 <dbl>,
-# #   action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>,
-# #   project_2 <dbl>, project_3 <dbl>, project_4 <dbl>, project_5 <dbl>,
-# #   project_6 <dbl>, project_7 <dbl>, project_8 <dbl>, project_9 <dbl>,
-# #   project_10 <dbl>, project_11 <dbl>, project_12 <dbl>, project_13 <dbl>,
-# #   project_14 <dbl>, project_15 <dbl>, project_16 <dbl>, project_17 <dbl>,
-# #   project_18 <dbl>, project_19 <dbl>, project_20 <dbl>, project_21 <dbl>,
-# #   project_22 <dbl>, project_23 <dbl>, project_24 <dbl>, project_25 <dbl>,
-# #   project_26 <dbl>, project_27 <dbl>, project_28 <dbl>, project_29 <dbl>,
-# #   project_30 <dbl>, project_31 <dbl>, project_32 <dbl>, project_33 <dbl>,
-# #   project_34 <dbl>, project_35 <dbl>, project_36 <dbl>, project_37 <dbl>,
-# #   project_38 <dbl>, project_39 <dbl>, project_40 <dbl>, project_41 <dbl>,
-# #   project_42 <dbl>, project_43 <dbl>, project_44 <dbl>, project_45 <dbl>,
-# #   project_46 <dbl>, project_47 <dbl>, project_48 <dbl>, project_49 <dbl>,
-# #   project_50 <dbl>, project_51 <dbl>, project_52 <dbl>, project_53 <dbl>,
-# #   project_54 <dbl>, project_55 <dbl>, project_56 <dbl>, project_57 <dbl>,
-# #   project_58 <dbl>, project_59 <dbl>, project_60 <dbl>, project_61 <dbl>,
-# #   project_62 <dbl>, project_63 <dbl>, project_64 <dbl>, project_65 <dbl>,
-# #   project_66 <dbl>, project_67 <dbl>, project_68 <dbl>, project_69 <dbl>,
-# #   project_70 <dbl>, baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, …
-
+
# # A tibble: 1 × 146
+#   solution status    obj  cost action_1 action_2 actio…¹ actio…² actio…³ actio…⁴
+#      <int> <chr>   <dbl> <dbl>    <dbl>    <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+# 1        1 OPTIMAL  972.  972.        0        1       0       0       0       0
+# # … with 136 more variables: action_7 <dbl>, action_8 <dbl>, action_9 <dbl>,
+# #   action_10 <dbl>, action_11 <dbl>, action_12 <dbl>, action_13 <dbl>,
+# #   action_14 <dbl>, action_15 <dbl>, action_16 <dbl>, action_17 <dbl>,
+# #   action_18 <dbl>, action_19 <dbl>, action_20 <dbl>, action_21 <dbl>,
+# #   action_22 <dbl>, action_23 <dbl>, action_24 <dbl>, action_25 <dbl>,
+# #   action_26 <dbl>, action_27 <dbl>, action_28 <dbl>, action_29 <dbl>,
+# #   action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>, project_2 <dbl>, …
+
-# plot solution
-plot(p6, s6)
+# plot solution +plot(p6, s6)

-
-

-Benchmarking conventional algorithms

+
+

Benchmarking conventional algorithms +

Conventionally, heuristic algorithms have been used to develop project prioritizations (e.g. Joseph et al. 2009; Bennett et al. 2014). Although solutions identified using these algorithms often perform better than solutions generated using using random processes [e.g. randomly selecting actions for funding until a budget is met; Joseph et al. (2009)], this is not an especially compelling benchmark. As talked about earlier, heuristic algorithms do not provide any guarantees on solution quality, and so should be avoided where possible (Rodrigues & Gaston 2002). To illustrate the pitfalls of relying on heuristic algorithms, let’s generate a portfolio of solutions using a backwards heuristic algorithm.

-# set budgets for which to create multiple solutions
-budgets <- seq(0, sum(actions$cost), length.out = 100)
-
-# generate solutions using heuristic algorithms
-s7 <- lapply(budgets, function(b) {
-  problem(projects = projects, actions = actions, features = features,
-          "name", "success", "name", "cost", "name") %>%
-  add_max_richness_objective(budget = b) %>%
-  add_feature_weights("weight") %>%
-  add_binary_decisions() %>%
-  add_heuristic_solver(verbose = FALSE) %>%
-  solve()
-})
-s7 <- as_tibble(do.call(rbind, s7))
-s7$budget <- budgets
-
-# print solutions
-print(s7)
+# set budgets for which to create multiple solutions +budgets <- seq(0, sum(actions$cost), length.out = 100) + +# generate solutions using heuristic algorithms +s7 <- lapply(budgets, function(b) { + problem(projects = projects, actions = actions, features = features, + "name", "success", "name", "cost", "name") %>% + add_max_richness_objective(budget = b) %>% + add_feature_weights("weight") %>% + add_binary_decisions() %>% + add_heuristic_solver(verbose = FALSE) %>% + solve() +}) +s7 <- as_tibble(do.call(rbind, s7)) +s7$budget <- budgets + +# print solutions +print(s7)
-
# # A tibble: 100 x 147
-#    solution status      obj  cost action_1 action_2 action_3 action_4 action_5
-#       <int> <chr>     <dbl> <dbl>    <dbl>    <dbl>    <dbl>    <dbl>    <dbl>
-#  1        1 NA     2284593.   0          0        0        0        0        0
-#  2        1 NA     2284593.   0          0        0        0        0        0
-#  3        1 NA     2284593.   0          0        0        0        0        0
-#  4        1 NA     2284593.   0          0        0        0        0        0
-#  5        1 NA     4513353.  99.4        0        0        0        0        0
-#  6        1 NA     4513353.  99.4        0        0        0        0        0
-#  7        1 NA     4513353.  99.4        0        0        0        0        0
-#  8        1 NA     4513353.  99.4        0        0        0        0        0
-#  9        1 NA     4513353.  99.4        0        0        0        0        0
-# 10        1 NA     4513353.  99.4        0        0        0        0        0
-# # … with 90 more rows, and 138 more variables: action_6 <dbl>, action_7 <dbl>,
-# #   action_8 <dbl>, action_9 <dbl>, action_10 <dbl>, action_11 <dbl>,
-# #   action_12 <dbl>, action_13 <dbl>, action_14 <dbl>, action_15 <dbl>,
-# #   action_16 <dbl>, action_17 <dbl>, action_18 <dbl>, action_19 <dbl>,
-# #   action_20 <dbl>, action_21 <dbl>, action_22 <dbl>, action_23 <dbl>,
-# #   action_24 <dbl>, action_25 <dbl>, action_26 <dbl>, action_27 <dbl>,
-# #   action_28 <dbl>, action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>,
-# #   project_1 <dbl>, project_2 <dbl>, project_3 <dbl>, project_4 <dbl>,
-# #   project_5 <dbl>, project_6 <dbl>, project_7 <dbl>, project_8 <dbl>,
-# #   project_9 <dbl>, project_10 <dbl>, project_11 <dbl>, project_12 <dbl>,
-# #   project_13 <dbl>, project_14 <dbl>, project_15 <dbl>, project_16 <dbl>,
-# #   project_17 <dbl>, project_18 <dbl>, project_19 <dbl>, project_20 <dbl>,
-# #   project_21 <dbl>, project_22 <dbl>, project_23 <dbl>, project_24 <dbl>,
-# #   project_25 <dbl>, project_26 <dbl>, project_27 <dbl>, project_28 <dbl>,
-# #   project_29 <dbl>, project_30 <dbl>, project_31 <dbl>, project_32 <dbl>,
-# #   project_33 <dbl>, project_34 <dbl>, project_35 <dbl>, project_36 <dbl>,
-# #   project_37 <dbl>, project_38 <dbl>, project_39 <dbl>, project_40 <dbl>,
-# #   project_41 <dbl>, project_42 <dbl>, project_43 <dbl>, project_44 <dbl>,
-# #   project_45 <dbl>, project_46 <dbl>, project_47 <dbl>, project_48 <dbl>,
-# #   project_49 <dbl>, project_50 <dbl>, project_51 <dbl>, project_52 <dbl>,
-# #   project_53 <dbl>, project_54 <dbl>, project_55 <dbl>, project_56 <dbl>,
-# #   project_57 <dbl>, project_58 <dbl>, project_59 <dbl>, project_60 <dbl>,
-# #   project_61 <dbl>, project_62 <dbl>, project_63 <dbl>, project_64 <dbl>,
-# #   project_65 <dbl>, project_66 <dbl>, project_67 <dbl>, project_68 <dbl>,
-# #   project_69 <dbl>, project_70 <dbl>, baseline_project <dbl>, F1 <dbl>,
-# #   F2 <dbl>, F3 <dbl>, …
-
+
# # A tibble: 100 × 147
+#    solution status     obj  cost actio…¹ actio…² actio…³ actio…⁴ actio…⁵ actio…⁶
+#       <int> <chr>    <dbl> <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#  1        1 NA      2.28e6   0         0       0       0       0       0       0
+#  2        1 NA      2.28e6   0         0       0       0       0       0       0
+#  3        1 NA      2.28e6   0         0       0       0       0       0       0
+#  4        1 NA      2.28e6   0         0       0       0       0       0       0
+#  5        1 NA      4.51e6  99.4       0       0       0       0       0       0
+#  6        1 NA      4.51e6  99.4       0       0       0       0       0       0
+#  7        1 NA      4.51e6  99.4       0       0       0       0       0       0
+#  8        1 NA      4.51e6  99.4       0       0       0       0       0       0
+#  9        1 NA      4.51e6  99.4       0       0       0       0       0       0
+# 10        1 NA      4.51e6  99.4       0       0       0       0       0       0
+# # … with 90 more rows, 137 more variables: action_7 <dbl>, action_8 <dbl>,
+# #   action_9 <dbl>, action_10 <dbl>, action_11 <dbl>, action_12 <dbl>,
+# #   action_13 <dbl>, action_14 <dbl>, action_15 <dbl>, action_16 <dbl>,
+# #   action_17 <dbl>, action_18 <dbl>, action_19 <dbl>, action_20 <dbl>,
+# #   action_21 <dbl>, action_22 <dbl>, action_23 <dbl>, action_24 <dbl>,
+# #   action_25 <dbl>, action_26 <dbl>, action_27 <dbl>, action_28 <dbl>,
+# #   action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>, …
+

Now let’s generate a portfolio of solutions using random processes.

-# generate random solutions under the various budgets and store
-# the objective value of the best and worst solutions
-s8 <- lapply(budgets, function(b) {
-  o <- problem(projects = projects, actions = actions, features = features,
-              "name", "success", "name", "cost", "name") %>%
-       add_max_richness_objective(budget = b) %>%
-       add_feature_weights("weight") %>%
-       add_binary_decisions() %>%
-       add_random_solver(verbose = FALSE, number_solutions = 100) %>%
-       solve()
-  data.frame(budget = b, min_obj = min(o$obj), max_obj = max(o$obj))
-})
-s8 <- as_tibble(do.call(rbind, s8))
-
-# print solutions
-print(s8)
+# generate random solutions under the various budgets and store +# the objective value of the best and worst solutions +s8 <- lapply(budgets, function(b) { + o <- problem(projects = projects, actions = actions, features = features, + "name", "success", "name", "cost", "name") %>% + add_max_richness_objective(budget = b) %>% + add_feature_weights("weight") %>% + add_binary_decisions() %>% + add_random_solver(verbose = FALSE, number_solutions = 100) %>% + solve() + data.frame(budget = b, min_obj = min(o$obj), max_obj = max(o$obj)) +}) +s8 <- as_tibble(do.call(rbind, s8)) + +# print solutions +print(s8)
-
# # A tibble: 100 x 3
-#    budget  min_obj  max_obj
-#     <dbl>    <dbl>    <dbl>
-#  1    0   2284593. 2284593.
-#  2   30.1 2284593. 2284593.
-#  3   60.1 2284593. 2284593.
-#  4   90.2 2284593. 2284593.
-#  5  120.  4513353. 4513353.
-#  6  150.  4513353. 4513353.
-#  7  180.  4513353. 4513353.
-#  8  211.  2284651. 4513353.
-#  9  241.  2284651. 4513353.
-# 10  271.  2284651. 4513353.
-# # … with 90 more rows
-
+
# # A tibble: 100 × 3
+#    budget  min_obj  max_obj
+#     <dbl>    <dbl>    <dbl>
+#  1    0   2284593. 2284593.
+#  2   30.1 2284593. 2284593.
+#  3   60.1 2284593. 2284593.
+#  4   90.2 2284593. 2284593.
+#  5  120.  4513353. 4513353.
+#  6  150.  4513353. 4513353.
+#  7  180.  4513353. 4513353.
+#  8  211.  2284651. 4513353.
+#  9  241.  2284651. 4513353.
+# 10  271.  2284651. 4513353.
+# # … with 90 more rows
+

Now we can visualize how well the solutions identified using the heuristic algorithm compare to solutions generated using random processes. In the plot below, the orange line shows the performance of solutions generated using the heuristic algorithm, and the blue ribbon shows the performance of the best and worst solutions generated using random processes.

-# make plot
-ggplot() +
-geom_ribbon(aes(x = budget, ymin = min_obj, ymax = max_obj), data = s8,
-            color = "#3366FF26", fill = "#3366FF26") +
-geom_step(aes(x = budget, y = obj), data = s7, color = "orange") +
-scale_x_continuous(labels = scales::comma) +
-scale_y_continuous(labels = scales::comma) +
-xlab("Budget available ($)") +
-ylab("Expected richness (objective function)") +
-theme(axis.text.y = element_text(angle = 90, vjust = 1))
+# make plot +ggplot() + +geom_ribbon(aes(x = budget, ymin = min_obj, ymax = max_obj), data = s8, + color = "#3366FF26", fill = "#3366FF26") + +geom_step(aes(x = budget, y = obj), data = s7, color = "orange") + +scale_x_continuous(labels = scales::comma) + +scale_y_continuous(labels = scales::comma) + +xlab("Budget available ($)") + +ylab("Expected richness (objective function)") + +theme(axis.text.y = element_text(angle = 90, vjust = 1))

Here, we can see the that heuristic algorithm generally performs better than funding conservation projects using random processes. We can also see that for some budgets, the heuristic algorithm returns a worse solution (i.e. has a lower objective value) then solutions it found for lower budgets (i.e. where there is a step down in the orange line). Unfortunately, this behavior is normal because heuristic algorithms often deliver suboptimal solutions and the degree of suboptimality often varies depending on the budget. Despite these occasional drops in solution quality, you might be tempted to think that these results show that heuristic algorithms can perform pretty well on balance. But we can do better. Let’s generate a series of solutions using exact algorithms.

-# generate solutions
-s9 <- lapply(budgets, function(b) {
-  problem(projects = projects, actions = actions, features = features,
-          "name", "success", "name", "cost", "name") %>%
-  add_max_richness_objective(budget = b) %>%
-  add_feature_weights("weight") %>%
-  add_binary_decisions() %>%
-  add_default_solver(verbose = FALSE) %>%
-  solve()
-})
-s9 <- as_tibble(do.call(rbind, s9))
-s9$budget <- budgets
-
-# print solutions
-print(s9)
+# generate solutions +s9 <- lapply(budgets, function(b) { + problem(projects = projects, actions = actions, features = features, + "name", "success", "name", "cost", "name") %>% + add_max_richness_objective(budget = b) %>% + add_feature_weights("weight") %>% + add_binary_decisions() %>% + add_default_solver(verbose = FALSE) %>% + solve() +}) +s9 <- as_tibble(do.call(rbind, s9)) +s9$budget <- budgets + +# print solutions +print(s9)
-
# # A tibble: 100 x 147
-#    solution status       obj  cost action_1 action_2 action_3 action_4 action_5
-#       <int> <chr>      <dbl> <dbl>    <dbl>    <dbl>    <dbl>    <dbl>    <dbl>
-#  1        1 OPTIMAL 2284593.   0          0        0        0        0        0
-#  2        1 OPTIMAL 2284593.   0          0        0        0        0        0
-#  3        1 OPTIMAL 2284593.   0          0        0        0        0        0
-#  4        1 OPTIMAL 2284593.   0          0        0        0        0        0
-#  5        1 OPTIMAL 4513353.  99.4        0        0        0        0        0
-#  6        1 OPTIMAL 4513353.  99.4        0        0        0        0        0
-#  7        1 OPTIMAL 4513353.  99.4        0        0        0        0        0
-#  8        1 OPTIMAL 4513353.  99.4        0        0        0        0        0
-#  9        1 OPTIMAL 4513353.  99.4        0        0        0        0        0
-# 10        1 OPTIMAL 4513353.  99.4        0        0        0        0        0
-# # … with 90 more rows, and 138 more variables: action_6 <dbl>, action_7 <dbl>,
-# #   action_8 <dbl>, action_9 <dbl>, action_10 <dbl>, action_11 <dbl>,
-# #   action_12 <dbl>, action_13 <dbl>, action_14 <dbl>, action_15 <dbl>,
-# #   action_16 <dbl>, action_17 <dbl>, action_18 <dbl>, action_19 <dbl>,
-# #   action_20 <dbl>, action_21 <dbl>, action_22 <dbl>, action_23 <dbl>,
-# #   action_24 <dbl>, action_25 <dbl>, action_26 <dbl>, action_27 <dbl>,
-# #   action_28 <dbl>, action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>,
-# #   project_1 <dbl>, project_2 <dbl>, project_3 <dbl>, project_4 <dbl>,
-# #   project_5 <dbl>, project_6 <dbl>, project_7 <dbl>, project_8 <dbl>,
-# #   project_9 <dbl>, project_10 <dbl>, project_11 <dbl>, project_12 <dbl>,
-# #   project_13 <dbl>, project_14 <dbl>, project_15 <dbl>, project_16 <dbl>,
-# #   project_17 <dbl>, project_18 <dbl>, project_19 <dbl>, project_20 <dbl>,
-# #   project_21 <dbl>, project_22 <dbl>, project_23 <dbl>, project_24 <dbl>,
-# #   project_25 <dbl>, project_26 <dbl>, project_27 <dbl>, project_28 <dbl>,
-# #   project_29 <dbl>, project_30 <dbl>, project_31 <dbl>, project_32 <dbl>,
-# #   project_33 <dbl>, project_34 <dbl>, project_35 <dbl>, project_36 <dbl>,
-# #   project_37 <dbl>, project_38 <dbl>, project_39 <dbl>, project_40 <dbl>,
-# #   project_41 <dbl>, project_42 <dbl>, project_43 <dbl>, project_44 <dbl>,
-# #   project_45 <dbl>, project_46 <dbl>, project_47 <dbl>, project_48 <dbl>,
-# #   project_49 <dbl>, project_50 <dbl>, project_51 <dbl>, project_52 <dbl>,
-# #   project_53 <dbl>, project_54 <dbl>, project_55 <dbl>, project_56 <dbl>,
-# #   project_57 <dbl>, project_58 <dbl>, project_59 <dbl>, project_60 <dbl>,
-# #   project_61 <dbl>, project_62 <dbl>, project_63 <dbl>, project_64 <dbl>,
-# #   project_65 <dbl>, project_66 <dbl>, project_67 <dbl>, project_68 <dbl>,
-# #   project_69 <dbl>, project_70 <dbl>, baseline_project <dbl>, F1 <dbl>,
-# #   F2 <dbl>, F3 <dbl>, …
-
+
# # A tibble: 100 × 147
+#    solution status     obj  cost actio…¹ actio…² actio…³ actio…⁴ actio…⁵ actio…⁶
+#       <int> <chr>    <dbl> <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#  1        1 OPTIMAL 2.28e6   0         0       0       0       0       0       0
+#  2        1 OPTIMAL 2.28e6   0         0       0       0       0       0       0
+#  3        1 OPTIMAL 2.28e6   0         0       0       0       0       0       0
+#  4        1 OPTIMAL 2.28e6   0         0       0       0       0       0       0
+#  5        1 OPTIMAL 4.51e6  99.4       0       0       0       0       0       0
+#  6        1 OPTIMAL 4.51e6  99.4       0       0       0       0       0       0
+#  7        1 OPTIMAL 4.51e6  99.4       0       0       0       0       0       0
+#  8        1 OPTIMAL 4.51e6  99.4       0       0       0       0       0       0
+#  9        1 OPTIMAL 4.51e6  99.4       0       0       0       0       0       0
+# 10        1 OPTIMAL 4.51e6  99.4       0       0       0       0       0       0
+# # … with 90 more rows, 137 more variables: action_7 <dbl>, action_8 <dbl>,
+# #   action_9 <dbl>, action_10 <dbl>, action_11 <dbl>, action_12 <dbl>,
+# #   action_13 <dbl>, action_14 <dbl>, action_15 <dbl>, action_16 <dbl>,
+# #   action_17 <dbl>, action_18 <dbl>, action_19 <dbl>, action_20 <dbl>,
+# #   action_21 <dbl>, action_22 <dbl>, action_23 <dbl>, action_24 <dbl>,
+# #   action_25 <dbl>, action_26 <dbl>, action_27 <dbl>, action_28 <dbl>,
+# #   action_29 <dbl>, action_30 <dbl>, baseline_action <dbl>, project_1 <dbl>, …
+

Now let’s redraw the previous graph and add a red line to the plot to represent the solutions generated using the exact algorithm solver.

-# make plot
-ggplot() +
-geom_ribbon(aes(x = budget, ymin = min_obj, ymax = max_obj), data = s8,
-            color = "#3366FF26", fill = "#3366FF26") +
-geom_step(aes(x = budget, y = obj), data = s7, color = "orange") +
-geom_step(aes(x = budget, y = obj), data = s9, color = "red") +
-scale_x_continuous(labels = scales::comma) +
-scale_y_continuous(labels = scales::comma) +
-xlab("Budget available ($)") +
-ylab("Expected richness (objective function)") +
-theme(axis.text.y = element_text(angle = 90, hjust = 0.5, vjust = 1))
+# make plot +ggplot() + +geom_ribbon(aes(x = budget, ymin = min_obj, ymax = max_obj), data = s8, + color = "#3366FF26", fill = "#3366FF26") + +geom_step(aes(x = budget, y = obj), data = s7, color = "orange") + +geom_step(aes(x = budget, y = obj), data = s9, color = "red") + +scale_x_continuous(labels = scales::comma) + +scale_y_continuous(labels = scales::comma) + +xlab("Budget available ($)") + +ylab("Expected richness (objective function)") + +theme(axis.text.y = element_text(angle = 90, hjust = 0.5, vjust = 1))

So, we can see that the exact algorithm solver performs much better than heuristic algorithms—even if heuristic algorithms perform better than random on average.

-
-

-Conclusion

+
+

Conclusion +

Hopefully, this tutorial has been useful. For more information and examples on using any of the functions presented in this tutorial, please refer to this package’s documentation. For instance, you could learn about the mathematical formulations that underpin the objective functions (see ?add_max_richness_objective), how to lock in our lock out certain actions from the solutions (see ?constraints), or how to develop project prioritizations using phylogenies (see ?add_max_phylo_objective). But perhaps one of the best ways to learn how to use a new piece of software is to just try it out. Test it, try breaking it, make mistakes, and learn from them. We would recommend generating project prioritizations using simulated datasets (see ?simulate_ptm_data and ?simulate_ppp_data) and seeing if the solutions line up with what you expect. This way you can quickly verify that the problems you build actually mean what you think they mean. For instance, you can try playing around with the targets and see what effect they have on the solutions, or try playing around with weights and see what effect they have on the solutions.

Finally, if you have any questions about using the oppr R package or suggestions for improving its documentation or functionality (especially this tutorial), please post an issue on this package’s online coding repository (https://github.com/prioritizr/oppr/issues).

-
-

-Citation

+
+

Citation +


 To cite the oppr package in publications, please use:
@@ -1217,8 +1044,8 @@ 

   Optimality in prioritizing conservation projects. Methods in Ecology
   & Evolution, 10: 1655--1663.
 
-  Hanson JO, Schuster R, Strimas-Mackey M, Bennett J (2021) oppr:
-  Optimal Project Prioritization R package version 1.0.3.
+  Hanson JO, Schuster R, Strimas-Mackey M, Bennett J (2022) oppr:
+  Optimal Project Prioritization R package version 1.0.4.
   https://CRAN.R-project.org/package=oppr
 
 To see these entries in BibTeX format, use 'print(<citation>,
@@ -1227,9 +1054,9 @@
-
-

-References

+
+

References +

Ball, I.R., Possingham, H.P. & Watts, M. (2009). Marxan and relatives: Software for spatial conservation prioritisation. Spatial conservation prioritisation: Quantitative methods and computational tools, pp. 185–195. Oxford University Press Oxford. @@ -1301,12 +1128,12 @@

diff --git a/docs/articles/oppr_files/figure-html/unnamed-chunk-12-1.png b/docs/articles/oppr_files/figure-html/unnamed-chunk-12-1.png index 0bab49e..94a29b8 100644 Binary files a/docs/articles/oppr_files/figure-html/unnamed-chunk-12-1.png and b/docs/articles/oppr_files/figure-html/unnamed-chunk-12-1.png differ diff --git a/docs/articles/oppr_files/figure-html/unnamed-chunk-14-1.png b/docs/articles/oppr_files/figure-html/unnamed-chunk-14-1.png index f13082e..8efc3e6 100644 Binary files a/docs/articles/oppr_files/figure-html/unnamed-chunk-14-1.png and b/docs/articles/oppr_files/figure-html/unnamed-chunk-14-1.png differ diff --git a/docs/articles/oppr_files/figure-html/unnamed-chunk-19-1.png b/docs/articles/oppr_files/figure-html/unnamed-chunk-19-1.png index 261db2b..9c6a82b 100644 Binary files a/docs/articles/oppr_files/figure-html/unnamed-chunk-19-1.png and b/docs/articles/oppr_files/figure-html/unnamed-chunk-19-1.png differ diff --git a/docs/articles/oppr_files/figure-html/unnamed-chunk-26-1.png b/docs/articles/oppr_files/figure-html/unnamed-chunk-26-1.png index ea728b0..425cc97 100644 Binary files a/docs/articles/oppr_files/figure-html/unnamed-chunk-26-1.png and b/docs/articles/oppr_files/figure-html/unnamed-chunk-26-1.png differ diff --git a/docs/articles/oppr_files/figure-html/unnamed-chunk-27-1.png b/docs/articles/oppr_files/figure-html/unnamed-chunk-27-1.png index 8786ac9..6486aa4 100644 Binary files a/docs/articles/oppr_files/figure-html/unnamed-chunk-27-1.png and b/docs/articles/oppr_files/figure-html/unnamed-chunk-27-1.png differ diff --git a/docs/articles/oppr_files/figure-html/unnamed-chunk-29-1.png b/docs/articles/oppr_files/figure-html/unnamed-chunk-29-1.png index 96cb6f5..d3ddf76 100644 Binary files a/docs/articles/oppr_files/figure-html/unnamed-chunk-29-1.png and b/docs/articles/oppr_files/figure-html/unnamed-chunk-29-1.png differ diff --git a/docs/articles/oppr_files/figure-html/unnamed-chunk-32-1.png b/docs/articles/oppr_files/figure-html/unnamed-chunk-32-1.png index 7558d2d..9a551a2 100644 Binary files a/docs/articles/oppr_files/figure-html/unnamed-chunk-32-1.png and b/docs/articles/oppr_files/figure-html/unnamed-chunk-32-1.png differ diff --git a/docs/articles/oppr_files/figure-html/unnamed-chunk-33-1.png b/docs/articles/oppr_files/figure-html/unnamed-chunk-33-1.png index 24f1257..2acde50 100644 Binary files a/docs/articles/oppr_files/figure-html/unnamed-chunk-33-1.png and b/docs/articles/oppr_files/figure-html/unnamed-chunk-33-1.png differ diff --git a/docs/articles/oppr_files/figure-html/unnamed-chunk-40-1.png b/docs/articles/oppr_files/figure-html/unnamed-chunk-40-1.png index f94d177..ec6a454 100644 Binary files a/docs/articles/oppr_files/figure-html/unnamed-chunk-40-1.png and b/docs/articles/oppr_files/figure-html/unnamed-chunk-40-1.png differ diff --git a/docs/articles/oppr_files/figure-html/unnamed-chunk-43-1.png b/docs/articles/oppr_files/figure-html/unnamed-chunk-43-1.png index 2d986fb..7b8de51 100644 Binary files a/docs/articles/oppr_files/figure-html/unnamed-chunk-43-1.png and b/docs/articles/oppr_files/figure-html/unnamed-chunk-43-1.png differ diff --git a/docs/articles/oppr_files/figure-html/unnamed-chunk-45-1.png b/docs/articles/oppr_files/figure-html/unnamed-chunk-45-1.png index 7bf5e6f..94800eb 100644 Binary files a/docs/articles/oppr_files/figure-html/unnamed-chunk-45-1.png and b/docs/articles/oppr_files/figure-html/unnamed-chunk-45-1.png differ diff --git a/docs/articles/oppr_files/header-attrs-2.8/header-attrs.js b/docs/articles/oppr_files/header-attrs-2.8/header-attrs.js deleted file mode 100644 index dd57d92..0000000 --- a/docs/articles/oppr_files/header-attrs-2.8/header-attrs.js +++ /dev/null @@ -1,12 +0,0 @@ -// Pandoc 2.9 adds attributes on both header and div. We remove the former (to -// be compatible with the behavior of Pandoc < 2.8). -document.addEventListener('DOMContentLoaded', function(e) { - var hs = document.querySelectorAll("div.section[class*='level'] > :first-child"); - var i, h, a; - for (i = 0; i < hs.length; i++) { - h = hs[i]; - if (!/^h[1-6]$/i.test(h.tagName)) continue; // it should be a header h1-h6 - a = h.attributes; - while (a.length > 0) h.removeAttribute(a[0].name); - } -}); diff --git a/docs/authors.html b/docs/authors.html index c2b67f4..aa13a1a 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -1,75 +1,12 @@ - - - - - - - -Citation and Authors • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Authors and Citation • oppr - - - - - - - - - - - +
-
- -
- -
+
-
-

Citation

- Source: inst/CITATION +
+
+

Authors

+
+ + +
+
+
+

Citation

+ Source: inst/CITATION +
+

Hanson JO, Schuster R, Strimas-Mackey M & Bennett JR (2019) Optimality in prioritizing conservation projects. Methods in Ecology & Evolution, 10: 1655--1663.

@Article{,
   author = {Jeffrey O Hanson and Richard Schuster and Matthew Strimas-Mackey and Joseph Bennett},
@@ -131,63 +87,35 @@ 
Citation

   pages = {1655--1663},
   doi = {10.1111/2041-210X.13264},
 }
-

Hanson JO, Schuster R, Strimas-Mackey M, Bennett J (2021) oppr: Optimal Project Prioritization R package version 1.0.3. https://CRAN.R-project.org/package=oppr

+

Hanson JO, Schuster R, Strimas-Mackey M, Bennett J (2022) oppr: Optimal Project Prioritization R package version 1.0.4. https://CRAN.R-project.org/package=oppr

@Manual{,
   author = {Jeffrey O Hanson and Richard Schuster and Matthew Strimas-Mackey and Joseph Bennett},
   title = {oppr: Optimal Project Prioritization},
-  year = {2021},
-  note = {R package version 1.0.3},
+  year = {2022},
+  note = {R package version 1.0.4},
   url = {https://CRAN.R-project.org/package=oppr},
 }
-
-

Authors

-
- - - -
-
- - - + diff --git a/docs/index.html b/docs/index.html index 634d885..967b6dd 100644 --- a/docs/index.html +++ b/docs/index.html @@ -45,7 +45,7 @@ oppr - 1.0.3 + 1.0.4
@@ -63,7 +63,7 @@
  • - + @@ -80,46 +80,44 @@
    -
    -

    -oppr: Optimal Project Prioritization

    +
    +

    oppr: Optimal Project Prioritization +

    The oppr R package is decision support tool for prioritizing conservation projects. Prioritizations can be developed by maximizing expected feature richness, expected phylogenetic diversity, the number of features that meet persistence targets, or identifying a set of projects that meet persistence targets for minimal cost. Constraints (e.g. lock in specific actions) and feature weights can also be specified to further customize prioritizations. After defining a project prioritization problem, solutions can be obtained using exact algorithms, heuristic algorithms, or random processes. In particular, it is recommended to install the ‘Gurobi’ optimizer because it can identify optimal solutions very quickly. Finally, methods are provided for comparing different prioritizations and evaluating their benefits.

    -
    -

    -Installation

    +
    +

    Installation +

    The latest official version of the oppr R package can be installed from the Comprehensive R Archive Network (CRAN) using the following R code.

    -install.packages("oppr", repos = "https://cran.rstudio.com/")
    +install.packages("oppr", repos = "https://cran.rstudio.com/")

    Alternatively, the latest development version can be installed from GitHub using the following code. Please note that while developmental versions may contain additional features not present in the official version, they may also contain coding errors.

    -if (!require(remotes)) install.packages("remotes")
-remotes::install_github("prioritizr/oppr")
    +if (!require(remotes)) install.packages("remotes") +remotes::install_github("prioritizr/oppr")
    -
    -

    -Citation

    +
    +

    Citation +

    To cite the oppr R package in publications, please use:

    -
    -

    Hanson JO, Schuster R, Strimas-Mackey M & Bennett JR (2019) Optimality in prioritizing conservation projects. Methods in Ecology & Evolution, 10: 1655–1663.

    -
    +

    Hanson JO, Schuster R, Strimas-Mackey M & Bennett JR (2019) Optimality in prioritizing conservation projects. Methods in Ecology & Evolution, 10: 1655–1663.

    You can also use the following R code to determine which version you have installed: packageVersion("oppr")

    -
    -

    -Usage

    +
    +

    Usage +

    Here we will provide a short example showing how the oppr R package can be used to prioritize funding for conservation projects. To start off, we will set the seed for the random number generator to ensure you get the same results as shown here, and load the oppr R package.

    +set.seed(500) +library(oppr)

    Now we will load some data sets that are distributed with the package. First, we will load the sim_features object. This table contains information on the conservation features (e.g. species). Specifically, each row corresponds to a different feature, and each column contains information associated with the features. In this table, the "name" column contains the name of each feature, and the "weight" column denotes the relative importance for each feature.

    -# load data
-data(sim_features)
-
-# print table
-print(sim_features)
    -
    ## # A tibble: 5 x 2
+# load data
+data(sim_features)
+
+# print table
+print(sim_features)
    +
    ## # A tibble: 5 × 2
 ##   name  weight
 ##   <chr>  <dbl>
 ## 1 F1     0.211
@@ -129,12 +127,12 @@ 
    
 ## 5 F5     1.59

    Next, we will load the sim_actions object. This table stores information about the various management actions (i.e. tibble). Each row corresponds to a different action, and each column describes different properties associated with the actions. These actions correspond to specific management actions that have known costs. For example, they may relate to pest eradication activities (e.g. trapping) in sites of conservation importance. In this table, the "name" column contains the name of each action, and the "cost" column denotes the cost of each action. It also contains additional columns for customizing the solutions, but we will ignore them for now. Note that the last action—the "baseline_action"—has a zero cost and is used with the a baseline project (see below).

    -# load data
-data(sim_actions)
-
-# print table
-print(sim_actions)
    -
    ## # A tibble: 6 x 4
+# load data
+data(sim_actions)
+
+# print table
+print(sim_actions)
    +
    ## # A tibble: 6 × 4
 ##   name             cost locked_in locked_out
 ##   <chr>           <dbl> <lgl>     <lgl>     
 ## 1 F1_action        94.4 FALSE     FALSE     
@@ -145,12 +143,12 @@ 
    
 ## 6 baseline_action   0   FALSE     FALSE

    Additionally, we will load the sim_projects object. This table stores information about various conservation projects. Each row corresponds to a different project, and each column describes various properties associated with the projects. These projects correspond to groups of conservation actions. For example, a conservation project may pertain to a set of conservation actions that relate to a single feature or single geographic locality. In this table, the "name" column contains the name of each project, the "success" column denotes the probability of each project succeeding if it is funded, the "F1"–"F5" columns show the probability of each feature is expected to persist if each project is funded (NA values mean that a feature does not benefit from a project), and the "F1_action"–"F5_action" columns indicate which actions are associated with which projects. Note that the last project—the "baseline_project"—is associated with the "baseline_action" action. This project has a zero cost and represents the baseline probability of each feature persisting if no other project is funded. This is important because we can’t find a cost-effective solution if we don’t know how much better each project improves a species’ chance at persistence. Finally, although most projects in this example directly relate to a single feature, you can input projects that directly affect the persistence of multiple features.

    -# load data
-data(sim_projects)
-
-# print table
-print(sim_projects, width = Inf)
    -
    ## # A tibble: 6 x 13
+# load data
+data(sim_projects)
+
+# print table
+print(sim_projects, width = Inf)
    +
    ## # A tibble: 6 × 13
 ##   name             success     F1     F2      F3     F4     F5 F1_action
 ##   <chr>              <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>    
 ## 1 F1_project         0.919  0.791 NA     NA      NA     NA     TRUE     
@@ -169,18 +167,18 @@ 
    
 ## 6 FALSE     FALSE     FALSE     FALSE     TRUE

    After loading the data, we can begin formulating the project prioritization problem. Here our goal is to maximize the overall probability that each feature is expected to persist into the future (i.e. the feature richness), whilst also accounting for the relative importance of each feature and the fact that our resources are limited such that we can only spend at most $400 on funding management actions. Now, let’s build a project prioritization problem object that represents our goal.

    -# build problem
-p <- problem(projects = sim_projects, actions = sim_actions,
-             features =  sim_features, project_name_column = "name",
-             project_success_column = "success", action_name_column = "name",
-             action_cost_column = "cost", feature_name_column = "name") %>%
-     add_max_richness_objective(budget = 400) %>%
-     add_feature_weights(weight = "weight") %>%
-     add_binary_decisions() %>%
-     add_default_solver(verbose = FALSE)
-
-# print problem
-print(p)
    +# build problem +p <- problem(projects = sim_projects, actions = sim_actions, + features = sim_features, project_name_column = "name", + project_success_column = "success", action_name_column = "name", + action_cost_column = "cost", feature_name_column = "name") %>% + add_max_richness_objective(budget = 400) %>% + add_feature_weights(weight = "weight") %>% + add_binary_decisions() %>% + add_default_solver(verbose = FALSE) + +# print problem +print(p)
    ## Project Prioritization Problem
 ##   actions          F1_action, F2_action, F3_action, ... (6 actions)
 ##   projects         F1_project, F2_project, F3_project, ... (6 projects)
@@ -195,12 +193,12 @@ 
    
 ##   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (0)]

    Next, we can solve this problem to obtain a solution. By default, we will obtain the optimal solution to our problem using an exact algorithm solver (e.g. using Gurobi or lpSolveAPI).

    -# solve problem
-s <- solve(p)
    +# solve problem +s <- solve(p)
    -# print solution
-print(s, width = Inf)
    -
    ## # A tibble: 1 x 21
+# print solution
+print(s, width = Inf)
    +
    ## # A tibble: 1 × 21
 ##   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
 ##      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
 ## 1        1 OPTIMAL  1.75  395.         1         1         0         1         1
@@ -212,14 +210,14 @@ 
    
 ## 1                1 0.808 0.865 0.0865 0.688 0.592

    The s table contains the solution and also various statistics associated with the solution. Here, each row corresponds to a different solution. Specifically, the "solution" column contains an identifier for the solution (which may be useful for methods that output multiple solutions), the "obj" column contains the objective value (i.e. the expected feature richness for this problem), the "cost" column stores the cost of the solution, and the "status" column contains information from the solver about the solution. Additionally, it contains columns for each action ("F1_action", "F2_actions", "F3_actions", …, "baseline_action") which indicate if each action was prioritized for funding in the solution. Additionally, it contains columns for each project ("F1_project", "F2_project", "F3_project", …, "baseline_project") that indicate if the project was completely funded or not. Finally, it contains column for each feature ("F1, "F2", "F3, …) which indicate the probability that each feature is expected to persist into the future under each solution (for information on how this is calculated see ?add_max_richness_objective). Since tabular data can be difficult to understand, let’s visualize how well this solution would conserve the features. Note that features which benefit from fully funded projects, excepting the baseline project, are denoted with an asterisk.

    -# visualize solution
-plot(p, s)
    +# visualize solution +plot(p, s)

    This has just been a taster of the oppr R package. For more information, see the package vignette.

    -
    -

    -Getting help

    +
    +

    Getting help +

    If you have any questions about using the oppr R package or suggestions for improving it, please file an issue at the package’s online code repository.

    @@ -229,19 +227,16 @@

    Links

    License

    @@ -249,7 +244,7 @@

    License

    Citation

    @@ -257,13 +252,13 @@

    Citation

    Developers

    @@ -273,7 +268,7 @@

    Dev status

  • lifecycle
  • R-CMD-check-Ubuntu
  • R-CMD-check-Windows
    • -
  • R-CMD-check-Mac-OSX
    • +
  • R-CMD-check-macOS
  • Coverage Status
  • CRAN_Status_Badge
@@ -290,7 +285,7 @@

Dev status

-

Site built with pkgdown 1.6.1.9001.

+

Site built with pkgdown 2.0.6.

diff --git a/docs/news/index.html b/docs/news/index.html index 248457c..23556a0 100644 --- a/docs/news/index.html +++ b/docs/news/index.html @@ -1,75 +1,12 @@ - - - - - - - -Changelog • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Changelog • oppr - - - - - - - - - - - +
-
- -
- -
+

Changelog

- Source: NEWS.md + Source: NEWS.md
-
-

-oppr 1.0.3 (released) Unreleased -

-
    -
  • CRAN release.
    • +
    +

    oppr 1.0.4

    +
    • CRAN release.
      • +
    • Fix compiler warnings raised by CRAN checks.
      • +
    • Remove references to the ggtree package in documentation.
      • +
    • Fix memory issues encountered during installation on CRAN Windows server.
      • +
    • Fix compatibility issues with upcoming version of the Matrix package (version 1.4-2).
      • +
    • Fix broken URLs in package documentation.
      • +
    +
    +

    oppr 1.0.32021-05-11

    +
    • CRAN release.
    • Fix URLs for CRAN.
      • -
    -
    -
    -

    -oppr 1.0.2.5 Unreleased -

    -
      -
    • Update minimum versions for tidytree and ggtree package dependencies. This is because some older versions of tidytree are not compatible with some older versions of ggtree.
      • -
    -
    -
    -

    -oppr 1.0.2.4 Unreleased -

    -
      -
    • Fix missing dependency in DESCRIPTION.
      • -
    -
    -
    -

    -oppr 1.0.2.3 Unreleased -

    -
      -
    • Bug fix: previous versions of the package reported that the gap parameter for the add_rsymphony_solver and add_lpsymphony_solver corresponded to the maximum absolute difference from the optimal objective value. This was an error due to misunderstanding the SYMPHONY documentation. Under previous versions of the package, the gap parameter actually corresponded to a relative optimality gap expressed as a percentage (such thatgap = 10 indicates that solutions must be at least 10% from optimality). We have now fixed this error and the documentation described for the gap parameter is correct. We apologize for any inconvenience this may have caused.
      • +
    +
    +

    oppr 1.0.2.5

    +
    • Update minimum versions for tidytree and ggtree package dependencies. This is because some older versions of tidytree are not compatible with some older versions of ggtree.
    +
    +

    oppr 1.0.2.4

    +
    • Fix missing dependency in DESCRIPTION.
    +
    +

    oppr 1.0.2.3

    +
    • Bug fix: previous versions of the package reported that the gap parameter for the add_rsymphony_solver and add_lpsymphony_solver corresponded to the maximum absolute difference from the optimal objective value. This was an error due to misunderstanding the SYMPHONY documentation. Under previous versions of the package, the gap parameter actually corresponded to a relative optimality gap expressed as a percentage (such thatgap = 10 indicates that solutions must be at least 10% from optimality). We have now fixed this error and the documentation described for the gap parameter is correct. We apologize for any inconvenience this may have caused.
    • Update add_rsymphony_solver and add_lpsymphony_solver functions to have a default time_limit argument set as the maximum machine integer for consistency.
    • Update add_rsymphony_solver, add_lpsymphony_solver, and add_gurobi_solver functions to require logical (TRUE/FALSE) arguments for the first_feasible parameter.
    • Standardize run time calculations across all solvers.
    • Fix compatibility issues between the testthat R package and the gurobi R package in package tests.
      • -
    -
    -
    -

    -oppr 1.0.2.2 Unreleased -

    -
      -
    • Implement GitHub Actions continuous integration (i.e. update tests and README).
      • +
    +
    +

    oppr 1.0.2.2

    +
    • Implement GitHub Actions continuous integration (i.e. update tests and README).
    • Update examples to use \dontrun instead of \donttest per CRAN policies.
      • -
    -
    -
    -

    -oppr 1.0.2.1 Unreleased -

    -
      -
    • Fix “Non-file package-anchored link(s) in documentation object” warnings in R-devel checks.
      • -
    -
    -
    -

    -oppr 1.0.2 (released) 2020-05-20 -

    -
      -
    • CRAN release.
      • -
    -
    -
    -

    -oppr 1.0.1.1 Unreleased -

    - -
    -
    -

    -oppr 1.0.1 (released) 2020-03-11 -

    -
      -
    • CRAN release.
      • -
    -
    -
    -

    -oppr 1.0.0.1 Unreleased -

    -
      -
    • Fix compatibility issues with upcoming tibble (3.0.0) R package.
      • -
    -
    -
    -

    -oppr 1.0.0 (released) 2020-02-07 -

    -
      -
    • CRAN release.
      • -
    -
    -
    -

    -oppr 0.0.4.1 Unreleased -

    -
      -
    • Fix warnings in R-devel CRAN checks related to documentation.
      • +
    +
    +

    oppr 1.0.2.1

    +
    • Fix “Non-file package-anchored link(s) in documentation object” warnings in R-devel checks.
    +
    +

    oppr 1.0.22020-05-20

    +
    • CRAN release.
    +
    +

    oppr 1.0.1.1

    +
    +
    +

    oppr 1.0.12020-03-11

    +
    • CRAN release.
    +
    +

    oppr 1.0.0.1

    +
    • Fix compatibility issues with upcoming tibble (3.0.0) R package.
    +
    +

    oppr 1.0.02020-02-07

    +
    • CRAN release.
    +
    +

    oppr 0.0.4.1

    +
    • Fix warnings in R-devel CRAN checks related to documentation.
    • Add citation for the research article that accompanies this package.
      • -
    -
    -
    -

    -oppr 0.0.4 (released) 2019-08-10 -

    -
      -
    • CRAN release.
      • -
    -
    -
    -

    -oppr 0.0.3.1 Unreleased -

    -
      -
    • Fix typo.
      • +
    +
    +

    oppr 0.0.42019-08-10

    +
    • CRAN release.
    +
    +

    oppr 0.0.3.1

    +
    • Fix typo.
    • Fix broken links to Gurobi academic licenses.
      • -
    -
    -
    -

    -oppr 0.0.3 (released) 2019-04-10 -

    -
      -
    • CRAN release.
      • -
    -
    -
    -

    -oppr 0.0.2.1 Unreleased -

    -
      -
    • Retain debugging symbols to conform with CRAN policies.
      • -
    -
    -
    -

    -oppr 0.0.2 (released) 2019-03-20 -

    -
      -
    • CRAN release.
      • -
    -
    -
    -

    -oppr 0.0.1.1 Unreleased -

    -
      -
    • Fix address sanitizer issues causing CRAN checks to fail.
      • +
    +
    +

    oppr 0.0.32019-04-10

    +
    • CRAN release.
    +
    +

    oppr 0.0.2.1

    +
    • Retain debugging symbols to conform with CRAN policies.
    +
    +

    oppr 0.0.22019-03-20

    +
    • CRAN release.
    +
    +

    oppr 0.0.1.1

    +
    • Fix address sanitizer issues causing CRAN checks to fail.
    • Tests successfully complete when the shiny R package is not installed.
      • -
    -
    -
    -

    -oppr 0.0.1 (released) 2019-03-18 -

    -
      -
    • CRAN release.
      • -
    -
    -
    -

    -oppr 0.0.0.19 Unreleased -

    -
      -
    • Add argument to add_heuristic_solver to skip initial step for removing projects and actions that exceed the budget. While this initial step improves solution quality, it is not conventionally used in project prioritization algorithms and so should be omitted to provide accurate benchmarks.
      • -
    -
    -
    -

    -oppr 0.0.0.18 Unreleased -

    -
      -
    • Reduce precision of extinction probability calculations when formulating a problem with a maximum expected phylogenetic diversity objective (i.e. add_max_phylo_div_objective). Specifically, 1’000 points instead of 10’000 points are now used for piece-wise linear components. It appears that reducing the precision in this manner does not affect the correctness of results, but substantially reduces the time needed to solve problems to optimality in certain situations.
      • -
    -
    -
    -

    -oppr 0.0.0.17 Unreleased -

    -
      -
    • Update add_heuristic_solver algorithm so that cost-effectiveness values are calculated with projects sharing costs (e.g. if two projects share an action that costs $100, then this action contributes $50 to the cost of each project). This update makes the algorithm similar to backwards heuristics conventionally used in prioritizing species recovery projects (i.e. https://github.com/p-robot/ppp; #14).
      • -
    -
    -
    -

    -oppr 0.0.0.16 Unreleased -

    -
      -
    • Fix bug in add_heuristic_solver function introduced in version 0.0.0.15.
      • -
    -
    -
    -

    -oppr 0.0.0.15 Unreleased -

    -
      -
    • Update add_heuristic_solver algorithm so that it removes projects, and not actions, in an iterative fashion. This update (i) makes the algorithm comparable to the backwards heuristics conventionally used in prioritizing species recovery projects (i.e. https://github.com/p-robot/ppp) and (ii) substantially reduces run time (#14).
      • -
    -
    -
    -

    -oppr 0.0.0.14 Unreleased -

    -
      -
    • Fix bugs in add_heuristic_solver and add_random_solver arising from floating point comparison issue. These were causing infeasible solutions to be returned in R version 3.4.4.
      • -
    -
    -
    -

    -oppr 0.0.0.13 Unreleased -

    -
      -
    • Fix bug in project_cost_effectiveness reporting incorrect costs, and cost-effectiveness values.
      • -
    -
    -
    -

    -oppr 0.0.0.12 Unreleased -

    -
      -
    • Assorted documentation tweaks.
      • -
    -
    -
    -

    -oppr 0.0.0.11 Unreleased -

    -
      -
    • Update add_heuristic_solver algorithm so that all actions and projects which exceed the budget are automatically removed prior to the iterative action removal.
      • -
    • Update add_random_solver algorithms so that projects are selected instead of individual actions. This means that solutions from this solver are (i) similar to those in previous project prioritization studies and (ii) more likely to deliver better solutions (#13).
      • -
    -
    -
    -

    -oppr 0.0.0.10 Unreleased -

    -
      -
    • Rename package to oppr since ppr is already on CRAN.
      • +
    +
    +

    oppr 0.0.12019-03-18

    +
    • CRAN release.
    +
    +

    oppr 0.0.0.19

    +
    • Add argument to add_heuristic_solver to skip initial step for removing projects and actions that exceed the budget. While this initial step improves solution quality, it is not conventionally used in project prioritization algorithms and so should be omitted to provide accurate benchmarks.
    +
    +

    oppr 0.0.0.18

    +
    • Reduce precision of extinction probability calculations when formulating a problem with a maximum expected phylogenetic diversity objective (i.e. add_max_phylo_div_objective). Specifically, 1’000 points instead of 10’000 points are now used for piece-wise linear components. It appears that reducing the precision in this manner does not affect the correctness of results, but substantially reduces the time needed to solve problems to optimality in certain situations.
    +
    +

    oppr 0.0.0.17

    +
    • Update add_heuristic_solver algorithm so that cost-effectiveness values are calculated with projects sharing costs (e.g. if two projects share an action that costs $100, then this action contributes $50 to the cost of each project). This update makes the algorithm similar to backwards heuristics conventionally used in prioritizing species recovery projects (i.e. https://github.com/p-robot/ppp; #14).
    +
    +

    oppr 0.0.0.16

    +
    • Fix bug in add_heuristic_solver function introduced in version 0.0.0.15.
    +
    +

    oppr 0.0.0.15

    +
    • Update add_heuristic_solver algorithm so that it removes projects, and not actions, in an iterative fashion. This update (i) makes the algorithm comparable to the backwards heuristics conventionally used in prioritizing species recovery projects (i.e. https://github.com/p-robot/ppp) and (ii) substantially reduces run time (#14).
    +
    +

    oppr 0.0.0.14

    +
    • Fix bugs in add_heuristic_solver and add_random_solver arising from floating point comparison issue. These were causing infeasible solutions to be returned in R version 3.4.4.
    +
    +

    oppr 0.0.0.13

    +
    • Fix bug in project_cost_effectiveness reporting incorrect costs, and cost-effectiveness values.
    +
    +

    oppr 0.0.0.12

    +
    • Assorted documentation tweaks.
    +
    +

    oppr 0.0.0.11

    +
    • Update add_heuristic_solver algorithm so that all actions and projects which exceed the budget are automatically removed prior to the iterative action removal.
      • +
    • Update add_random_solver algorithms so that projects are selected instead of individual actions. This means that solutions from this solver are (i) similar to those in previous project prioritization studies and (ii) more likely to deliver better solutions (#13).
      • +
    +
    +

    oppr 0.0.0.10

    +
    • Rename package to oppr since ppr is already on CRAN.
    • Fix issue with replacement_costs yielding incorrect results for baseline projects when used with SYMPHONY solvers.
      • -
    -
    -
    -

    -oppr 0.0.0.9 Unreleased -

    -
      -
    • Add new project_cost_effectiveness function to calculate the cost-effectiveness for each conservation project in a problem.
      • -
    -
    -
    -

    -oppr 0.0.0.8 Unreleased -

    -
      -
    • Fix typos in documentation (#8).
      • -
    • The solution_statistics function outputs which projects are completely funded in each solution (#9).
      • -
    • Add example for saving tabular data to vignette (#10).
      • -
    • Add examples to vignette for working with the solution output (#11).
      • -
    -
    -
    -

    -oppr 0.0.0.7 Unreleased -

    -
      -
    • Fix annoying “Found more than one class "tbl_df" in cache; using the first, from namespace 'tibble'” text.
      • -
    -
    -
    -

    -oppr 0.0.0.6 Unreleased -

    -
      -
    • Actually fix bug when solving problems with a phylogenetic objective and branches that have a constant probability of persistence (#6).
      • +
    +
    +

    oppr 0.0.0.9

    +
    • Add new project_cost_effectiveness function to calculate the cost-effectiveness for each conservation project in a problem.
    +
    +

    oppr 0.0.0.8

    +
    • Fix typos in documentation (#8).
      • +
    • The solution_statistics function outputs which projects are completely funded in each solution (#9).
      • +
    • Add example for saving tabular data to vignette (#10).
      • +
    • Add examples to vignette for working with the solution output (#11).
      • +
    +
    +

    oppr 0.0.0.7

    +
    • Fix annoying “Found more than one class "tbl_df" in cache; using the first, from namespace 'tibble'” text.
    +
    +

    oppr 0.0.0.6

    +
    • Actually fix bug when solving problems with a phylogenetic objective and branches that have a constant probability of persistence (#6).
    • Fix bug in add_max_phylo_div_objective yielding incorrect solutions when features are ordered differently in the phylogenetic and tabular input data.
    • Fix bug in solution_statistics yielding objective values for phylogenetic problems when features are ordered differently in the phylogenetic and tabular input data.
    • Fix bug when handling phylogenetic data when a species is associated with two tip branches. Although such data probably indicate errors in the phylogenetic data, this functionality could be useful when combining multiple datasets.
      • -
    -
    -
    -

    -oppr 0.0.0.5 Unreleased -

    -
      -
    • Add return_data argument to plot_feature_persistence and plot_phylo_persistence so that plotting data can be obtained for creating custom plots.
      • -
    -
    -
    -

    -oppr 0.0.0.4 Unreleased -

    -
      -
    • Fix bug in add_relative_targets and add_manual_targets (when relative targets supplied) calculations. This result in incorrect calculations.
      • -
    • Fix issue with expected persistence probabilities not accounting for the “do nothing” scenario (#7).
      • -
    -
    -
    -

    -oppr 0.0.0.3 Unreleased -

    -
      -
    • The gurobi solver (i.e. add_gurobi_solver function) now uses NumericFocus=3 to help avoid numerical issues.
      • +
    +
    +

    oppr 0.0.0.5

    +
    • Add return_data argument to plot_feature_persistence and plot_phylo_persistence so that plotting data can be obtained for creating custom plots.
    +
    +

    oppr 0.0.0.4

    +
    • Fix bug in add_relative_targets and add_manual_targets (when relative targets supplied) calculations. This result in incorrect calculations.
      • +
    • Fix issue with expected persistence probabilities not accounting for the “do nothing” scenario (#7).
      • +
    +
    +

    oppr 0.0.0.3

    +
    • The gurobi solver (i.e. add_gurobi_solver function) now uses NumericFocus=3 to help avoid numerical issues.
    • The compile function now throws a warning if problems are likely to have numerical issues.
      • -
    -
    -
    -

    -oppr 0.0.0.2 Unreleased -

    -
      -
    • Fix bug when solving problems with a phylogenetic objective and branches that have a constant probability of persistence (#6). Hindsight shows this attempt did not cover all edge cases.
      • +
    +
    +

    oppr 0.0.0.2

    +
    • Fix bug when solving problems with a phylogenetic objective and branches that have a constant probability of persistence (#6). Hindsight shows this attempt did not cover all edge cases.
    • Add additional data sanity checks to problem. It will now throw descriptive error messages if features are missing baseline probabilities, or are associated with baseline probabilities below 1e-11.
    • Fix unit test for simulate_ptm_data that had a very small chance of failing due to simulating a data set where an action is not associated with any project.
    • Feature columns in simulated data produced using simulate_ppp_data and simulate_ptm_data are now sorted.
      • -
    -
    -
    -

    -oppr 0.0.0.1 Unreleased -

    -
      -
    • Initial commit.
      • -
    -
    +
+
+

oppr 0.0.0.1

+
  • Initial commit.
+
-
- - - + diff --git a/docs/pkgdown.css b/docs/pkgdown.css index 48468ce..80ea5b8 100644 --- a/docs/pkgdown.css +++ b/docs/pkgdown.css @@ -56,8 +56,10 @@ img.icon { float: right; } -img { +/* Ensure in-page images don't run outside their container */ +.contents img { max-width: 100%; + height: auto; } /* Fix bug in bootstrap (only seen in firefox) */ @@ -78,11 +80,10 @@ dd { /* Section anchors ---------------------------------*/ a.anchor { - margin-left: -30px; - display:inline-block; - width: 30px; - height: 30px; - visibility: hidden; + display: none; + margin-left: 5px; + width: 20px; + height: 20px; background-image: url(./link.svg); background-repeat: no-repeat; @@ -90,17 +91,15 @@ a.anchor { background-position: center center; } -.hasAnchor:hover a.anchor { - visibility: visible; -} - -@media (max-width: 767px) { - .hasAnchor:hover a.anchor { - visibility: hidden; - } +h1:hover .anchor, +h2:hover .anchor, +h3:hover .anchor, +h4:hover .anchor, +h5:hover .anchor, +h6:hover .anchor { + display: inline-block; } - /* Fixes for fixed navbar --------------------------*/ .contents h1, .contents h2, .contents h3, .contents h4 { @@ -264,31 +263,26 @@ table { /* Syntax highlighting ---------------------------------------------------- */ -pre { - word-wrap: normal; - word-break: normal; - border: 1px solid #eee; -} - -pre, code { +pre, code, pre code { background-color: #f8f8f8; color: #333; } +pre, pre code { + white-space: pre-wrap; + word-break: break-all; + overflow-wrap: break-word; +} -pre code { - overflow: auto; - word-wrap: normal; - white-space: pre; +pre { + border: 1px solid #eee; } -pre .img { +pre .img, pre .r-plt { margin: 5px 0; } -pre .img img { +pre .img img, pre .r-plt img { background-color: #fff; - display: block; - height: auto; } code a, pre a { @@ -364,3 +358,27 @@ mark { content: ""; } } + +/* Section anchors --------------------------------- + Added in pandoc 2.11: https://github.com/jgm/pandoc-templates/commit/9904bf71 +*/ + +div.csl-bib-body { } +div.csl-entry { + clear: both; +} +.hanging-indent div.csl-entry { + margin-left:2em; + text-indent:-2em; +} +div.csl-left-margin { + min-width:2em; + float:left; +} +div.csl-right-inline { + margin-left:2em; + padding-left:1em; +} +div.csl-indent { + margin-left: 2em; +} diff --git a/docs/pkgdown.js b/docs/pkgdown.js index 7e7048f..6f0eee4 100644 --- a/docs/pkgdown.js +++ b/docs/pkgdown.js @@ -80,7 +80,7 @@ $(document).ready(function() { var copyButton = ""; - $(".examples, div.sourceCode").addClass("hasCopyButton"); + $("div.sourceCode").addClass("hasCopyButton"); // Insert copy buttons: $(copyButton).prependTo(".hasCopyButton"); @@ -91,7 +91,7 @@ // Initialize clipboard: var clipboardBtnCopies = new ClipboardJS('[data-clipboard-copy]', { text: function(trigger) { - return trigger.parentNode.textContent; + return trigger.parentNode.textContent.replace(/\n#>[^\n]*/g, ""); } }); diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml index dc7304e..963e48e 100644 --- a/docs/pkgdown.yml +++ b/docs/pkgdown.yml @@ -1,9 +1,9 @@ pandoc: '2.13' -pkgdown: 1.6.1.9001 -pkgdown_sha: c9e7dde4c5ca066f4a797ff201ead380f702473f +pkgdown: 2.0.6 +pkgdown_sha: ~ articles: oppr: oppr.html -last_built: 2021-05-11T07:05Z +last_built: 2022-09-06T22:14Z urls: reference: https://prioritizr.github.io/oppr/reference article: https://prioritizr.github.io/oppr/articles diff --git a/docs/reference/ArrayParameter-class.html b/docs/reference/ArrayParameter-class.html index 3a0d44d..a825f32 100644 --- a/docs/reference/ArrayParameter-class.html +++ b/docs/reference/ArrayParameter-class.html @@ -1,78 +1,14 @@ - - - - - - - -Array parameter prototype — ArrayParameter-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Array parameter prototype — ArrayParameter-class • oppr - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Array parameter prototype

- Source: R/ArrayParameter-proto.R + Source: R/ArrayParameter-proto.R
@@ -131,41 +60,57 @@

Array parameter prototype

+
+

Fields

+ -

Fields

- +
$id
+

character identifier for parameter.

+ + +
$name
+

character name of parameter.

-
+
$value
+

numeric vector of values.

-
$id

character identifier for parameter.

-
$name

character name of parameter.

+
$label
+

character vector of names for each value.

-
$value

numeric vector of values.

-
$label

character vector of names for each value.

+
$default
+

numeric vector of default values.

-
$default

numeric vector of default values.

-
$length

integer number of values.

+
$length
+

integer number of values.

-
$class

character class of values.

-
$lower_limit

numeric vector specifying the minimum +

$class
+

character class of values.

+ + +
$lower_limit
+

numeric vector specifying the minimum permitted values.

-
$upper_limit

numeric vector specifying the maximum + +

$upper_limit
+

numeric vector specifying the maximum permitted values.

-
$widget

function used to construct a -shiny::shiny() interface for modifying values.

-
+
$widget
+

function used to construct a +shiny::shiny() interface for modifying values.

-

Usage

+
+
+

Usage

@@ -177,77 +122,88 @@

Usage

x$set(tbl)

x$reset()

x$render(...)

-

Arguments

- +
+
+

Arguments

-
-
tbl

data.frame() containing new parameter values with +

tbl
+

data.frame() containing new parameter values with row names indicating the labels and a column called "values" containing the new parameter values.

-
...

arguments passed to function in widget field.

-
+
...
+

arguments passed to function in widget field.

-

Details

+
+
+

Details

-
+
print
+

print the object.

-
print

print the object.

-
show

show the object.

+
show
+

show the object.

-
repr

character representation of object.

-
validate

check if a proposed new set of parameters are valid.

+
repr
+

character representation of object.

-
get

return a base::data.frame() containing the -parameter values.

-
set

update the parameter values using a -base::data.frame().

+
validate
+

check if a proposed new set of parameters are valid.

-
reset

update the parameter values to be the default values.

-
render

create a shiny::shiny() widget to modify +

get
+

return a base::data.frame() containing the parameter values.

-
+
set
+

update the parameter values using a +base::data.frame().

+ + +
reset
+

update the parameter values to be the default values.

+ + +
render
+

create a shiny::shiny() widget to modify +parameter values.

+ -

See also

-

ScalarParameter, Parameter.

+
+
+

See also

+

ScalarParameter, Parameter.

+
+
-
- - - + diff --git a/docs/reference/Collection-class.html b/docs/reference/Collection-class.html index c9f5549..81ae2e3 100644 --- a/docs/reference/Collection-class.html +++ b/docs/reference/Collection-class.html @@ -1,77 +1,13 @@ - - - - - - - -Collection prototype — Collection-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Collection prototype — Collection-class • oppr - - - - - - - - - - - +
-
- -
- -
+

Collection prototype

- Source: R/Collection-proto.R + Source: R/Collection-proto.R

This prototype represents a collection of -ProjectModifier objects.

+ProjectModifier objects.

- -

Fields

- +
+

Fields

-
-
$...

ProjectModifier objects stored +

$...
+

ProjectModifier objects stored in the collection.

-
- -

Usage

+
+
+

Usage

x$print()

@@ -155,86 +83,102 @@

Usage

x$set_parameter(id, value)

x$render_parameter(id)

x$render_all_parameters()

-

Arguments

- +
+
+

Arguments

-
- -
id

id object.

+
id
+

id object.

-
value

any object.

+
value
+

any object.

-
-

Details

+
+
+

Details

-
+
print
+

print the object.

+ -
print

print the object.

+
show
+

show the object.

-
show

show the object.

-
repr

character representation of object.

+
repr
+

character representation of object.

-
ids

character ids for objects inside collection.

-
length

integer number of objects inside collection.

+
ids
+

character ids for objects inside collection.

-
add

add ProjectModifier object.

-
remove

remove an item from the collection.

+
length
+

integer number of objects inside collection.

-
get_parameter

retrieve the value of a parameter in the object + +

add
+

add ProjectModifier object.

+ + +
remove
+

remove an item from the collection.

+ + +
get_parameter
+

retrieve the value of a parameter in the object using an id object.

-
set_parameter

change the value of a parameter in the object + +

set_parameter
+

change the value of a parameter in the object to a new object.

-
render_parameter

generate a shiny widget to modify the + +

render_parameter
+

generate a shiny widget to modify the the value of a parameter (specified by argument id).

-
render_all_parameters

generate a shiny::div() -containing all the parameters" widgets.

+
render_all_parameters
+

generate a shiny::div() +containing all the parameters" widgets.

-
-

See also

-

Constraint.

+
+
+

See also

+

Constraint.

+
+
-
- - - + diff --git a/docs/reference/Constraint-class.html b/docs/reference/Constraint-class.html index 114e1bd..3afe289 100644 --- a/docs/reference/Constraint-class.html +++ b/docs/reference/Constraint-class.html @@ -1,80 +1,16 @@ - - - - - - - -Constraint prototype — Constraint-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Constraint prototype — Constraint-class • oppr - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Constraint prototype

- Source: R/Constraint-proto.R + Source: R/Constraint-proto.R
@@ -130,43 +59,37 @@

Constraint prototype

This prototype is used to represent the constraints used when making a prioritization. This prototype represents a recipe, to actually add constraints to a planning problem, see the help page on -constraints. Only experts should use this class directly. This -prototype inherits from the ProjectModifier.

+constraints. Only experts should use this class directly. This +prototype inherits from the ProjectModifier.

- -

See also

- -

ProjectModifier.

+
+

See also

+

ProjectModifier.

+
+
-

- - - + diff --git a/docs/reference/Decision-class.html b/docs/reference/Decision-class.html index 2931d2a..64849a2 100644 --- a/docs/reference/Decision-class.html +++ b/docs/reference/Decision-class.html @@ -1,81 +1,17 @@ - - - - - - - -Decision prototype — Decision-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Decision prototype — Decision-class • oppr - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Decision prototype

- Source: R/Decision-proto.R + Source: R/Decision-proto.R
@@ -132,43 +61,37 @@

Decision prototype

when prioritizing planning units. This prototype represents a recipe to make a decision, to actually specify the type of decision in a planning problem, see the help page on -decisions. Only experts should use this class directly. -This class inherits from the ProjectModifier.

+decisions. Only experts should use this class directly. +This class inherits from the ProjectModifier.

- -

See also

- -

ProjectModifier.

+
+

See also

+

ProjectModifier.

+
+
-
- - - + diff --git a/docs/reference/MiscParameter-class.html b/docs/reference/MiscParameter-class.html index 0f98026..7fc725f 100644 --- a/docs/reference/MiscParameter-class.html +++ b/docs/reference/MiscParameter-class.html @@ -1,77 +1,13 @@ - - - - - - - -Miscellaneous parameter prototype — MiscParameter-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Miscellaneous parameter prototype — MiscParameter-class • oppr - - - - - - - - - - - +
-
- -
- -
+

Miscellaneous parameter prototype

- Source: R/MiscParameter-proto.R + Source: R/MiscParameter-proto.R
@@ -129,29 +58,35 @@

Miscellaneous parameter prototype

+
+

Fields

+ -

Fields

+
$id
+

character identifier for parameter.

- -
+
$name
+

character name of parameter.

-
$id

character identifier for parameter.

-
$name

character name of parameter.

+
$value
+

tibble::tibble() object.

-
$value

tibble::tibble() object.

-
$validator

list object containing a function that +

$validator
+

list object containing a function that is used to validate changes to the parameter.

-
$widget

list object containing a function used to -construct a shiny interface for modifying values.

-
+
$widget
+

list object containing a function used to +construct a shiny interface for modifying values.

-

Usage

+
+
+

Usage

@@ -162,75 +97,83 @@

Usage

x$set(x)

x$reset()

x$render(...)

-

Arguments

- +
+
+

Arguments

-
- -
x

object used to set a new parameter value.

+
x
+

object used to set a new parameter value.

-
...

arguments passed to $widget.

+
...
+

arguments passed to $widget.

-
-

Details

+
+
+

Details

-
+
print
+

print the object.

-
print

print the object.

-
show

show the object.

+
show
+

show the object.

-
validate

check if a proposed new parameter is valid.

-
get

extract the parameter value.

+
validate
+

check if a proposed new parameter is valid.

-
set

update the parameter value.

-
reset

update the parameter value to be the default value.

+
get
+

extract the parameter value.

+ + +
set
+

update the parameter value.

-
render

create a shiny::shiny() widget to modify -parameter values.

+
reset
+

update the parameter value to be the default value.

+ + +
render
+

create a shiny::shiny() widget to modify +parameter values.

-
-

See also

-

Parameter.

+
+
+

See also

+

Parameter.

+
+
-
- - - + diff --git a/docs/reference/Objective-class.html b/docs/reference/Objective-class.html index 2761324..e82ed92 100644 --- a/docs/reference/Objective-class.html +++ b/docs/reference/Objective-class.html @@ -1,80 +1,16 @@ - - - - - - - -Objective prototype — Objective-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Objective prototype — Objective-class • oppr - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Objective prototype

- Source: R/Objective-proto.R + Source: R/Objective-proto.R

This prototype is used to represent an objective that can be added to a -ProjectProblem object. This prototype +ProjectProblem object. This prototype represents a recipe to make an objective, to actually add an objective to a -planning problem: see objectives. Only experts should use this +planning problem: see objectives. Only experts should use this class directly.

-
+
-
- - - + diff --git a/docs/reference/OptimizationProblem-class.html b/docs/reference/OptimizationProblem-class.html index 0e2726b..85e9e59 100644 --- a/docs/reference/OptimizationProblem-class.html +++ b/docs/reference/OptimizationProblem-class.html @@ -1,78 +1,14 @@ - - - - - - - -Optimization problem class — OptimizationProblem-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Optimization problem class — OptimizationProblem-class • oppr - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Optimization problem class

- Source: R/OptimizationProblem-proto.R + Source: R/OptimizationProblem-proto.R
@@ -131,22 +60,22 @@

Optimization problem class

- -

Fields

- +
+

Fields

-
- -
$ptr

externalptr object.

+
$ptr
+

externalptr object.

-
$data

list object.

+
$data
+

list object.

-
-

Usage

+
+
+

Usage

x$print()

@@ -171,101 +100,137 @@

Usage

x$row_ids()

x$col_ids()

x$get_data()

-

Arguments

+
+
+

Arguments

+ +
ptr
+

externalptr object.

+ + +
+
+

Details

-
-
ptr

externalptr object.

+
print
+

print the object.

-
-

Details

+
show
+

show the object.

- -
+
repr
+

character representation of object.

+ -
print

print the object.

+
ncol
+

integer number of columns (variables) in model matrix.

-
show

show the object.

-
repr

character representation of object.

+
nrow
+

integer number of rows (constraints) in model matrix.

-
ncol

integer number of columns (variables) in model matrix.

-
nrow

integer number of rows (constraints) in model matrix.

+
ncell
+

integer number of cells in model matrix.

-
ncell

integer number of cells in model matrix.

-
modelsense

character model sense.

+
modelsense
+

character model sense.

-
vtype

character vector of variable types.

-
obj

numeric vector containing the linear components of the +

vtype
+

character vector of variable types.

+ + +
obj
+

numeric vector containing the linear components of the objective function.

-
pwlobj

list object containing the piece-wise linear components + +

pwlobj
+

list object containing the piece-wise linear components of the objective function.

-
A

Matrix::dgCMatrix model matrix

-
rhs

numeric vector of right-hand-side constraints.

+
A
+

Matrix::dgCMatrix model matrix

-
sense

character vector of constraint senses.

-
lb

numeric vector of lower bounds for each decision variable.

+
rhs
+

numeric vector of right-hand-side constraints.

-
ub

numeric vector of upper bounds for each decision variable.

-
number_of_projects

integer number of projects in the problem.

+
sense
+

character vector of constraint senses.

-
number_of_actions

integer number of actions in the problem.

-
number_of_features

integer number of features in the problem.

+
lb
+

numeric vector of lower bounds for each decision variable.

-
number_of_branches

integer number of phylogenetic branches in + +

ub
+

numeric vector of upper bounds for each decision variable.

+ + +
number_of_projects
+

integer number of projects in the problem.

+ + +
number_of_actions
+

integer number of actions in the problem.

+ + +
number_of_features
+

integer number of features in the problem.

+ + +
number_of_branches
+

integer number of phylogenetic branches in the problem.

-
col_ids

character names describing each decision variable + +

col_ids
+

character names describing each decision variable (column) in the model matrix.

-
row_ids

character names describing each constraint (row) in + +

row_ids
+

character names describing each constraint (row) in in the model matrix.

-
get_data

list containing additional data.

+
get_data
+

list containing additional data.

-
+
+
+
-
- - - + diff --git a/docs/reference/OptimizationProblem-methods.html b/docs/reference/OptimizationProblem-methods.html index 0b26484..e237bef 100644 --- a/docs/reference/OptimizationProblem-methods.html +++ b/docs/reference/OptimizationProblem-methods.html @@ -1,77 +1,13 @@ - - - - - - - -Optimization problem methods — OptimizationProblem-methods • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Optimization problem methods — OptimizationProblem-methods • oppr - - - - - - - - - - - +
-
- -
- -
+

Optimization problem methods

- Source: R/OptimizationProblem-methods.R + Source: R/OptimizationProblem-methods.R

These functions are used to access data from an -OptimizationProblem object.

+OptimizationProblem object.

- 
nrow(x)
-
-# S4 method for OptimizationProblem
-nrow(x)
-
-ncol(x)
-
-# S4 method for OptimizationProblem
-ncol(x)
-
-ncell(x)
-
-# S4 method for OptimizationProblem
-ncell(x)
-
-modelsense(x)
-
-# S4 method for OptimizationProblem
-modelsense(x)
-
-vtype(x)
-
-# S4 method for OptimizationProblem
-vtype(x)
-
-obj(x)
-
-# S4 method for OptimizationProblem
-obj(x)
-
-pwlobj(x)
-
-# S4 method for OptimizationProblem
-pwlobj(x)
-
-A(x)
-
-# S4 method for OptimizationProblem
-A(x)
-
-rhs(x)
+    

+    
nrow(x)
+
+# S4 method for OptimizationProblem
+nrow(x)
+
+ncol(x)
+
+# S4 method for OptimizationProblem
+ncol(x)
+
+ncell(x)
+
+# S4 method for OptimizationProblem
+ncell(x)
+
+modelsense(x)
+
+# S4 method for OptimizationProblem
+modelsense(x)
+
+vtype(x)
+
+# S4 method for OptimizationProblem
+vtype(x)
+
+obj(x)
+
+# S4 method for OptimizationProblem
+obj(x)
+
+pwlobj(x)
+
+# S4 method for OptimizationProblem
+pwlobj(x)
+
+A(x)
+
+# S4 method for OptimizationProblem
+A(x)
+
+rhs(x)
+
+# S4 method for OptimizationProblem
+rhs(x)
+
+sense(x)
+
+# S4 method for OptimizationProblem
+sense(x)
+
+lb(x)
+
+# S4 method for OptimizationProblem
+lb(x)
+
+ub(x)
+
+# S4 method for OptimizationProblem
+ub(x)
+
+col_ids(x)
+
+# S4 method for OptimizationProblem
+col_ids(x)
+
+row_ids(x)
+
+# S4 method for OptimizationProblem
+row_ids(x)
+
+number_of_branches(x)
+
+# S4 method for OptimizationProblem
+number_of_branches(x)
+
+get_data(x)
+
+# S4 method for OptimizationProblem
+get_data(x)

+    

 
-# S4 method for OptimizationProblem
-rhs(x)
+    

+    
Arguments

+    
x

+
OptimizationProblem object.

 
-sense(x)
+

+    

+    
Value

+    
 
-# S4 method for OptimizationProblem
-sense(x)
+
list, Matrix::dgCMatrix, numeric

 
-lb(x)
 
-# S4 method for OptimizationProblem
-lb(x)
+
vector, numeric vector, or scalar integer depending on the
+method used.

+    

+    

+    
Details

+    
The functions return the following data:

+
nrow

+
integer number of rows (constraints).

 
-ub(x)
 
-# S4 method for OptimizationProblem
-ub(x)
+
ncol

+
integer number of columns (decision variables).

 
-col_ids(x)
 
-# S4 method for OptimizationProblem
-col_ids(x)
+
ncell

+
integer number of cells.

 
-row_ids(x)
 
-# S4 method for OptimizationProblem
-row_ids(x)
+
modelsense

+
character describing if the problem is to be
+maximized ("max") or minimized ("min").

 
-number_of_branches(x)
 
-# S4 method for OptimizationProblem
-number_of_branches(x)
+
vtype

+
character describing the type of each decision variable:
+binary ("B"), semi-continuous ("S"), or continuous
+("C")

 
-get_data(x)
 
-# S4 method for OptimizationProblem
-get_data(x)
+
obj
+

numeric vector defining the linear components of the +objective function.

-

Arguments

- - - - - - -
x

OptimizationProblem object.

-

Value

+
pwlobj
+

list object defining the piece-wise linear components +of the objective function.

-

list, Matrix::dgCMatrix, numeric -vector, numeric vector, or scalar integer depending on the -method used.

-

Details

-

The functions return the following data:

-
+
A
+

Matrix::dgCMatrix matrix object defining the +problem matrix.

-
nrow

integer number of rows (constraints).

-
ncol

integer number of columns (decision variables).

+
rhs
+

numeric vector with right-hand-side linear constraints

-
ncell

integer number of cells.

-
modelsense

character describing if the problem is to be -maximized ("max") or minimized ("min").

+
sense
+

character vector with the senses of the linear +constraints ("<=", ">=", "=").

-
vtype

character describing the type of each decision variable: -binary ("B"), semi-continuous ("S"), or continuous -("C")

-
obj

numeric vector defining the linear components of the -objective function.

+
lb
+

numeric lower bound for each decision variable. Missing data +values (NA) indicate no lower bound for a given variable.

-
pwlobj

list object defining the piece-wise linear components -of the objective function.

-
A

Matrix::dgCMatrix matrix object defining the -problem matrix.

+
ub
+

numeric upper bounds for each decision variable. Missing +data values (NA) indicate no upper bound for a given variable.

-
rhs

numeric vector with right-hand-side linear constraints

-
sense

character vector with the senses of the linear -constraints ("<=", ">=", "=").

+
number_of_projects
+

integer number of projects in the problem.

-
lb

numeric lower bound for each decision variable. Missing data -values (NA) indicate no lower bound for a given variable.

-
ub

numeric upper bounds for each decision variable. Missing -data values (NA) indicate no upper bound for a given variable.

+
number_of_actions
+

integer number of actions in the problem.

-
number_of_projects

integer number of projects in the problem.

-
number_of_actions

integer number of actions in the problem.

+
number_of_features
+

integer number of features in the problem.

-
number_of_features

integer number of features in the problem.

-
number_of_branches

integer number of phylogenetic branches in +

number_of_branches
+

integer number of phylogenetic branches in the problem.

-
+
+
-
- - - + diff --git a/docs/reference/Parameter-class.html b/docs/reference/Parameter-class.html index 795a745..73f0134 100644 --- a/docs/reference/Parameter-class.html +++ b/docs/reference/Parameter-class.html @@ -1,78 +1,14 @@ - - - - - - - -Parameter class — Parameter-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Parameter class — Parameter-class • oppr - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Parameter class

- Source: R/Parameter-proto.R + Source: R/Parameter-proto.R
@@ -131,85 +60,97 @@

Parameter class

+
+

Fields

+ -

Fields

+
$id
+

Id() identifier for parameter.

- -
+
$name
+

character name of parameter.

+ -
$id

Id() identifier for parameter.

+
$value
+

numeric vector of values.

-
$name

character name of parameter.

-
$value

numeric vector of values.

+
$default
+

numeric vector of default values.

-
$default

numeric vector of default values.

-
$class

character name of the class that the values inherit +

$class
+

character name of the class that the values inherit from (e.g. "integer".

-
$lower_limit

numeric vector specifying the minimum + +

$lower_limit
+

numeric vector specifying the minimum permitted value for each element in $value.

-
$upper_limit

numeric vector specifying the maximum + +

$upper_limit
+

numeric vector specifying the maximum permitted value for each element in $value.

-
$widget

function used to construct a -shiny::shiny() interface for modifying values.

-
+
$widget
+

function used to construct a +shiny::shiny() interface for modifying values.

-

Usage

+
+
+

Usage

x$print()

x$show()

x$reset()

-

Details

- +
+
+

Details

-
-
print

print the object.

-
show

show the object.

-
reset

change the parameter values to be the default values.

+
print
+

print the object.

+ +
show
+

show the object.

-
+
reset
+

change the parameter values to be the default values.

-

See also

-

ScalarParameter.

+
+
+

See also

+

ScalarParameter.

+
+
- - - - + diff --git a/docs/reference/Parameters-class.html b/docs/reference/Parameters-class.html index 91745d0..0912aa3 100644 --- a/docs/reference/Parameters-class.html +++ b/docs/reference/Parameters-class.html @@ -1,78 +1,14 @@ - - - - - - - -Parameters class — Parameters-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Parameters class — Parameters-class • oppr - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Parameters class

- Source: R/Parameters-proto.R + Source: R/Parameters-proto.R
-

This class represents a collection of Parameter objects. +

This class represents a collection of Parameter objects. It provides methods for accessing, updating, and rendering the parameters stored inside it.

- -

Fields

- +
+

Fields

-
+
$parameters
+

list object containing +Parameter objects.

-
$parameters

list object containing -Parameter objects.

-
- -

Usage

- +
+
+

Usage

@@ -160,81 +87,97 @@

Usage

x$add(p)

x$render(id)

x$render_all()

-

Arguments

- +
+
+

Arguments

-
-
id

Id() object.

+
id
+

Id() object.

+ -
p

Parameter object.

+
p
+

Parameter object.

-
value

any object.

+
value
+

any object.

-
-

Details

+
+
+

Details

-
+
print
+

print the object.

+ + +
show
+

show the object.

+ + +
repr
+

character representation of object.

-
print

print the object.

-
show

show the object.

+
names
+

return character names of parameters.

-
repr

character representation of object.

-
names

return character names of parameters.

+
ids
+

return character parameter unique identifiers.

-
ids

return character parameter unique identifiers.

-
length

return integer number of parameters in object.

-
get

retrieve the value of a parameter in the object +

length
+

return integer number of parameters in object.

+ +
get
+

retrieve the value of a parameter in the object using an Id object.

-
set

change the value of a parameter in the object + +

set
+

change the value of a parameter in the object to a new object.

-
render

generate a shiny widget to modify the + +

render
+

generate a shiny widget to modify the the value of a parameter (specified by argument Id).

-
render_all

generate a shiny::div() + +

render_all
+

generate a shiny::div() containing all the parameters" widgets.

-
+
+
-
- - - + diff --git a/docs/reference/ProjectModifier-class.html b/docs/reference/ProjectModifier-class.html index 0913204..84698ff 100644 --- a/docs/reference/ProjectModifier-class.html +++ b/docs/reference/ProjectModifier-class.html @@ -1,82 +1,18 @@ - - - - - - - -Conservation problem modifier prototype — ProjectModifier-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Conservation problem modifier prototype — ProjectModifier-class • oppr - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Conservation problem modifier prototype

- Source: R/ProjectModifier-proto.R + Source: R/ProjectModifier-proto.R

This super-prototype is used to represent prototypes that in turn are used to -modify a ProjectProblem object. Specifically, the -Constraint, Decision, -Objective, and Target prototypes +modify a ProjectProblem object. Specifically, the +Constraint, Decision, +Objective, and Target prototypes inherit from this class. Only experts should interact with this class directly because changes to these class will have profound and far reaching effects.

+
+

Fields

+ -

Fields

- +
$name
+

character name of object.

-
+
$parameters
+

list object used to customize the modifier.

-
$name

character name of object.

-
$parameters

list object used to customize the modifier.

+
$data
+

list object with data.

-
$data

list object with data.

-
$compressed_formulation

logical can this constraint be applied +

$compressed_formulation
+

logical can this constraint be applied to the compressed version of the conservation planning problem?. Defaults to TRUE.

-
- -

Usage

+
+
+

Usage

@@ -178,103 +111,128 @@

Usage

x$set_parameter(id, value)

x$render_parameter(id)

x$render_all_parameter()

-

Arguments

- +
+
+

Arguments

-
+
name
+

character name for object

+ + +
value
+

any object

-
name

character name for object

-
value

any object

+
id
+

id or name of parameter

-
id

id or name of parameter

-
cp

ProjectProblem object

+
cp
+

ProjectProblem object

-
op

OptimizationProblem object

+
op
+

OptimizationProblem object

-
-

Details

+
+
+

Details

-
+
print
+

print the object.

-
print

print the object.

-
show

show the object.

+
show
+

show the object.

-
repr

return character representation of the object.

-
get_data

return an object stored in the data field with +

repr
+

return character representation of the object.

+ + +
get_data
+

return an object stored in the data field with the corresponding name. If the object is not present in the data field, a waiver object is returned.

-
set_data

store an object stored in the data field with + +

set_data
+

store an object stored in the data field with the corresponding name. If an object with that name already exists then the object is overwritten.

-
calculate

function used to perform preliminary calculations + +

calculate
+

function used to perform preliminary calculations and store the data so that they can be reused later without performing the same calculations multiple times. Data can be stored in the data slot of the input ProjectModifier or ProjectProblem objects.

-
output

function used to generate an output from the object. -This method is only used for Target objects.

-
apply

function used to apply the modifier to an -OptimizationProblem object. -This is used by Constraint, -Decision, and Objective objects.

+
output
+

function used to generate an output from the object. +This method is only used for Target objects.

+ + +
apply
+

function used to apply the modifier to an +OptimizationProblem object. +This is used by Constraint, +Decision, and Objective objects.

+ -
get_parameter

retrieve the value of a parameter.

+
get_parameter
+

retrieve the value of a parameter.

-
get_all_parameters

generate list containing all the + +

get_all_parameters
+

generate list containing all the parameters.

-
set_parameter

change the value of a parameter to new value.

-
render_parameter

generate a shiny widget to modify the +

set_parameter
+

change the value of a parameter to new value.

+ + +
render_parameter
+

generate a shiny widget to modify the the value of a parameter (specified by argument id).

-
render_all_parameters

generate a shiny::div() + +

render_all_parameters
+

generate a shiny::div() containing all the parameters" widgets.

-
+
+
-
- - - + diff --git a/docs/reference/ProjectProblem-class.html b/docs/reference/ProjectProblem-class.html index 002fa19..44b355a 100644 --- a/docs/reference/ProjectProblem-class.html +++ b/docs/reference/ProjectProblem-class.html @@ -1,76 +1,12 @@ - - - - - - - -Project problem class — ProjectProblem-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Project problem class — ProjectProblem-class • oppr - - - - - - - - - - - +
-
- -
- -
+

Project problem class

- Source: R/ProjectProblem-proto.R + Source: R/ProjectProblem-proto.R
@@ -127,9 +56,8 @@

Project problem class

- -

Description

- +
+

Description

This class is used to represent project prioritization problems. A @@ -164,38 +92,50 @@

This class represents a planning problem, to actually build and then -solve a planning problem, use the problem() function. Only +solve a planning problem, use the problem() function. Only experts should use this class directly.

-

Fields

- +
+
+

Fields

-
+
$data
+

list object containing data.

-
$data

list object containing data.

-
$objective

Objective object used to represent how +

$objective
+

Objective object used to represent how the targets relate to the solution.

-
$decisions

Decision object used to represent the + +

$decisions
+

Decision object used to represent the type of decision made on planning units.

-
$targets

Target object used to represent + +

$targets
+

Target object used to represent representation targets for features.

-
$weights

Weight object used to represent + +

$weights
+

Weight object used to represent feature weights.

-
$constraints

Collection object used to represent -additional constraints that the problem is subject to.

-
$solver

Solver object used to solve the problem.

+
$constraints
+

Collection object used to represent +additional constraints that the problem is subject to.

+ +
$solver
+

Solver object used to solve the problem.

-
-

Usage

+
+
+

Usage

@@ -204,12 +144,12 @@

Usage

x$repr()

x$get_data(name)

x$set_data(name, value)

-

number_of_actions()

-

number_of_projects()

-

number_of_features()

-

action_names()

-

project_names()

-

feature_names()

+

number_of_actions()

+

number_of_projects()

+

number_of_features()

+

action_names()

+

project_names()

+

feature_names()

feature_weights()

feature_phylogeny()

action_costs()

@@ -236,188 +176,281 @@

Usage

x$set_solver_parameter(id, value)

x$render_solver_parameter(id)

x$render_all_solver_parameters()

-

Arguments

- +
+
+

Arguments

-
+
name
+

character name for object.

+ + +
value
+

an object.

+ + +
obj
+

Objective object.

-
name

character name for object.

-
value

an object.

+
wt
+

Weight object.

-
obj

Objective object.

-
wt

Weight object.

+
dec
+

Decision object.

-
dec

Decision object.

-
con

Constraint object.

+
con
+

Constraint object.

-
sol

Solver object.

-
targ

Target object.

+
sol
+

Solver object.

-
wt

Weight object.

-
id

Id object that refers to a specific parameter.

+
targ
+

Target object.

-
value

object that the parameter value should become.

+
wt
+

Weight object.

-
-

Details

+
id
+

Id object that refers to a specific parameter.

+ +
value
+

object that the parameter value should become.

+ + + +
+
+

Details

-
+
print
+

print the object.

+ + +
show
+

show the object.

-
print

print the object.

-
show

show the object.

+
repr
+

return character representation of the object.

-
repr

return character representation of the object.

-
get_data

return an object stored in the data field with +

get_data
+

return an object stored in the data field with the corresponding name. If the object is not present in the data field, a waiver object is returned.

-
set_data

store an object stored in the data field with + +

set_data
+

store an object stored in the data field with the corresponding name. If an object with that name already exists then the object is overwritten.

-
number_of_actions

integer number of actions.

-
number_of_projects

integer number of projects.

+
number_of_actions
+

integer number of actions.

+ + +
number_of_projects
+

integer number of projects.

+ + +
number_of_features
+

integer number of features.

+ -
number_of_features

integer number of features.

+
action_names
+

character names of actions in the problem.

-
action_names

character names of actions in the problem.

-
project_names

character names of projects in the problem.

+
project_names
+

character names of projects in the problem.

-
feature_names

character names of features in the problem.

-
feature_weights

character feature weights.

+
feature_names
+

character names of features in the problem.

-
feature_phylogeny

ape::phylo() phylogenetic tree object.

-
action_costs

numeric costs for each action.

+
feature_weights
+

character feature weights.

-
project_costs

numeric costs for each project.

-
project_success_probabilities

numeric probability that +

feature_phylogeny
+

ape::phylo() phylogenetic tree object.

+ + +
action_costs
+

numeric costs for each action.

+ + +
project_costs
+

numeric costs for each project.

+ + +
project_success_probabilities
+

numeric probability that each project will succeed.

-
pf_matrix

Matrix::dgCMatrix object denoting the enhanced + +

pf_matrix
+

Matrix::dgCMatrix object denoting the enhanced probability that features will persist if different projects are funded.

-
epf_matrix

Matrix::dgCMatrix object denoting the enhanced + +

epf_matrix
+

Matrix::dgCMatrix object denoting the enhanced probability that features is expected to persist if different projects are funded. This is calculated as the pf_matrix multiplied by the project success probabilities.

-
pa_matrix

Matrix::dgCMatrix object indicating which actions are + +

pa_matrix
+

Matrix::dgCMatrix object indicating which actions are associated with which projects.

-
feature_targets

tibble::tibble() with feature targets.

-
add_objective

return a new ProjectProblem +

feature_targets
+

tibble::tibble() with feature targets.

+ + +
add_objective
+

return a new ProjectProblem with the objective added to it.

-
add_decisions

return a new ProjectProblem + +

add_decisions
+

return a new ProjectProblem object with the decision added to it.

-
add_solver

return a new ProjectProblem object + +

add_solver
+

return a new ProjectProblem object with the solver added to it.

-
add_constraint

return a new ProjectProblem + +

add_constraint
+

return a new ProjectProblem object with the constraint added to it.

-
add_targets

return a copy with the targets added to the problem.

-
get_constraint_parameter

get the value of a parameter (specified by +

add_targets
+

return a copy with the targets added to the problem.

+ + +
get_constraint_parameter
+

get the value of a parameter (specified by argument id) used in one of the constraints in the object.

-
set_constraint_parameter

set the value of a parameter (specified by + +

set_constraint_parameter
+

set the value of a parameter (specified by argument id) used in one of the constraints in the object to value.

-
render_constraint_parameter

generate a shiny widget to modify + +

render_constraint_parameter
+

generate a shiny widget to modify the value of a parameter (specified by argument id).

-
render_all_constraint_parameters

generate a shiny div + +

render_all_constraint_parameters
+

generate a shiny div containing all the parameters' widgets.

-
get_objective_parameter

get the value of a parameter (specified by + +

get_objective_parameter
+

get the value of a parameter (specified by argument id) used in the object's objective.

-
set_objective_parameter

set the value of a parameter (specified by + +

set_objective_parameter
+

set the value of a parameter (specified by argument id) used in the object's objective to value.

-
render_objective_parameter

generate a shiny widget to modify + +

render_objective_parameter
+

generate a shiny widget to modify the value of a parameter (specified by argument id).

-
render_all_objective_parameters

generate a shiny div + +

render_all_objective_parameters
+

generate a shiny div containing all the parameters' widgets.

-
get_weight_parameter

get the value of a parameter (specified by + +

get_weight_parameter
+

get the value of a parameter (specified by argument id) used in the object's weights.

-
set_weight_parameter

set the value of a parameter (specified by + +

set_weight_parameter
+

set the value of a parameter (specified by argument id) used in the object's weights to value.

-
render_weight_parameter

generate a shiny widget to modify + +

render_weight_parameter
+

generate a shiny widget to modify the value of a parameter (specified by argument id).

-
render_all_weight_parameters

generate a shiny div + +

render_all_weight_parameters
+

generate a shiny div containing all the parameters' widgets.

-
get_solver_parameter

get the value of a parameter (specified by + +

get_solver_parameter
+

get the value of a parameter (specified by argument id) used in the object's solver.

-
set_solver_parameter

set the value of a parameter (specified by + +

set_solver_parameter
+

set the value of a parameter (specified by argument id) used in the object's solver to value.

-
render_solver_parameter

generate a shiny widget to modify + +

render_solver_parameter
+

generate a shiny widget to modify the value of a parameter (specified by argument id).

-
render_all_solver_parameters

generate a shiny div + +

render_all_solver_parameters
+

generate a shiny div containing all the parameters' widgets.

-
+
+
- - - - + diff --git a/docs/reference/Rplot001.png b/docs/reference/Rplot001.png index 4200210..023c1d3 100644 Binary files a/docs/reference/Rplot001.png and b/docs/reference/Rplot001.png differ diff --git a/docs/reference/Rplot002.png b/docs/reference/Rplot002.png index 856b996..7f3d116 100644 Binary files a/docs/reference/Rplot002.png and b/docs/reference/Rplot002.png differ diff --git a/docs/reference/Rplot003.png b/docs/reference/Rplot003.png index d63d2e3..e04691d 100644 Binary files a/docs/reference/Rplot003.png and b/docs/reference/Rplot003.png differ diff --git a/docs/reference/Rplot004.png b/docs/reference/Rplot004.png index 7a71a28..397cf63 100644 Binary files a/docs/reference/Rplot004.png and b/docs/reference/Rplot004.png differ diff --git a/docs/reference/Rplot005.png b/docs/reference/Rplot005.png index 429ad21..e5a9fd0 100644 Binary files a/docs/reference/Rplot005.png and b/docs/reference/Rplot005.png differ diff --git a/docs/reference/ScalarParameter-class.html b/docs/reference/ScalarParameter-class.html index 8fb37cc..c48b2ce 100644 --- a/docs/reference/ScalarParameter-class.html +++ b/docs/reference/ScalarParameter-class.html @@ -1,77 +1,13 @@ - - - - - - - -Scalar parameter prototype — ScalarParameter-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Scalar parameter prototype — ScalarParameter-class • oppr - - - - - - - - - - - +
-
- -
- -
+

Scalar parameter prototype

- Source: R/ScalarParameter-proto.R + Source: R/ScalarParameter-proto.R
@@ -129,37 +58,49 @@

Scalar parameter prototype

+
+

Fields

+ -

Fields

+
$id
+

character identifier for parameter.

- -
+
$name
+

character name of parameter.

-
$id

character identifier for parameter.

-
$name

character name of parameter.

+
$value
+

numeric scalar value.

-
$value

numeric scalar value.

-
$default

numeric scalar default value.

+
$default
+

numeric scalar default value.

-
$class

character name of the class that $value should + +

$class
+

character name of the class that $value should inherit from (e.g. integer).

-
$lower_limit

numeric scalar value that is the minimum value + +

$lower_limit
+

numeric scalar value that is the minimum value that $value is permitted to be.

-
$upper_limit

numeric scalar value that is the maximum value + +

$upper_limit
+

numeric scalar value that is the maximum value that $value is permitted to be.

-
$widget

function used to construct a -shiny::shiny() interface for modifying values.

-
+
$widget
+

function used to construct a +shiny::shiny() interface for modifying values.

-

Usage

+
+
+

Usage

@@ -170,75 +111,83 @@

Usage

x$set(x)

x$reset()

x$render(...)

-

Arguments

- +
+
+

Arguments

-
- -
x

object used to set a new parameter value.

+
x
+

object used to set a new parameter value.

-
...

arguments passed to $widget.

+
...
+

arguments passed to $widget.

-
-

Details

+
+
+

Details

-
+
print
+

print the object.

-
print

print the object.

-
show

show the object.

+
show
+

show the object.

-
validate

check if a proposed new set of parameters are valid.

-
get

extract the parameter value.

+
validate
+

check if a proposed new set of parameters are valid.

-
set

update the parameter value.

-
reset

update the parameter value to be the default value.

+
get
+

extract the parameter value.

+ + +
set
+

update the parameter value.

-
render

create a shiny::shiny() widget to modify -parameter values.

+
reset
+

update the parameter value to be the default value.

+ + +
render
+

create a shiny::shiny() widget to modify +parameter values.

-
-

See also

-

Parameter, ArrayParameter.

+
+
+

See also

+

Parameter, ArrayParameter.

+
+
- - - - + diff --git a/docs/reference/Solver-class.html b/docs/reference/Solver-class.html index d398e01..e7e0838 100644 --- a/docs/reference/Solver-class.html +++ b/docs/reference/Solver-class.html @@ -1,80 +1,16 @@ - - - - - - - -Solver prototype — Solver-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Solver prototype — Solver-class • oppr - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Solver prototype

- Source: R/Solver-proto.R, R/add_gurobi_solver.R, R/add_heuristic_solver.R, and 4 more + Source: R/Solver-proto.R, R/add_gurobi_solver.R, R/add_heuristic_solver.R, and 4 more
@@ -131,30 +60,32 @@

Solver prototype

optimization problems. This class represents a recipe to create solver and and is only recommended for use by expert users. To customize the method used to solve optimization problems, please see the -help page on solvers.

+help page on solvers.

- -

Fields

- +
+

Fields

-
+
$name
+

character name of solver.

-
$name

character name of solver.

-
$parameters

Parameters object with parameters used to customize +

$parameters
+

Parameters object with parameters used to customize the the solver.

-
$solve

function used to solve a -OptimizationProblem object.

-
+
$solve
+

function used to solve a +OptimizationProblem object.

-

Usage

+
+
+

Usage

@@ -162,65 +93,67 @@

Usage

x$show()

x$repr()

x$solve(op)

-

Arguments

- +
+
+

Arguments

-
- -
x

Solver object.

+
x
+

Solver object.

-
op

OptimizationProblem object.

+
op
+

OptimizationProblem object.

-
-

Details

+
+
+

Details

-
-
print

print the object.

+
print
+

print the object.

-
show

show the object.

-
repr

character representation of object.

+
show
+

show the object.

-
solve

solve an OptimizationProblem using this + +

repr
+

character representation of object.

+ + +
solve
+

solve an OptimizationProblem using this object.

-
+
+
- - - - + diff --git a/docs/reference/Target-class.html b/docs/reference/Target-class.html index b41e812..dec0327 100644 --- a/docs/reference/Target-class.html +++ b/docs/reference/Target-class.html @@ -1,80 +1,16 @@ - - - - - - - -Target prototype — Target-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Target prototype — Target-class • oppr - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Target prototype

- Source: R/Target-proto.R + Source: R/Target-proto.R

This prototype is used to represent the targets used when making a prioritization. This prototype inherits from the -ProjectModifier. This class represents a +ProjectModifier. This class represents a recipe, to actually add targets to a planning problem, see the help page on -targets. Only experts should use this class directly.

+targets. Only experts should use this class directly.

- -

See also

- -

ProjectModifier.

+
+

See also

+

ProjectModifier.

+
+
-
- - - + diff --git a/docs/reference/Weight-class.html b/docs/reference/Weight-class.html index e388230..d56ae0b 100644 --- a/docs/reference/Weight-class.html +++ b/docs/reference/Weight-class.html @@ -1,80 +1,16 @@ - - - - - - - -Weight prototype — Weight-class • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Weight prototype — Weight-class • oppr - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Weight prototype

- Source: R/Weight-proto.R + Source: R/Weight-proto.R

This prototype is used to represent the weights used when making a prioritization. This prototype inherits from the -ProjectModifier. This class represents a +ProjectModifier. This class represents a recipe, to actually add targets to a planning problem, see the help page on -weights. Only experts should use this class directly.

+weights. Only experts should use this class directly.

- -

See also

- -

ProjectModifier.

+
+

See also

+

ProjectModifier.

+
+
-
- - - + diff --git a/docs/reference/action_names.html b/docs/reference/action_names.html index 0e79eaf..b3a9827 100644 --- a/docs/reference/action_names.html +++ b/docs/reference/action_names.html @@ -1,78 +1,12 @@ - - - - - - - -Action names — action_names • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Action names — action_names • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Action names

- Source: R/action_names.R + Source: R/action_names.R
@@ -128,80 +55,80 @@

Action names

Extract the names of the actions in an object.

- 
action_names(x)
-
-# S4 method for ProjectProblem
-action_names(x)
- -

Arguments

- - - - - - -
x

ProjectProblem.

- -

Value

- -

character action names.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with default solver
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions() %>%
-     add_default_solver()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]

-# print action names
-action_names(p)
-
#> [1] "F1_action"       "F2_action"       "F3_action"       "F4_action"      
-#> [5] "F5_action"       "baseline_action"
+
+ 
action_names(x)
+
+# S4 method for ProjectProblem
+action_names(x)
+
+ +
+

Arguments

+
x
+

ProjectProblem.

+ +
+
+

Value

+ + +

character action names.

+
+ +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with default solver
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions() %>%
+     add_default_solver()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]
+
+# print action names
+action_names(p)
+#> [1] "F1_action"       "F2_action"       "F3_action"       "F4_action"      
+#> [5] "F5_action"       "baseline_action"
+
+
+
- - - - + diff --git a/docs/reference/add_absolute_targets-1.png b/docs/reference/add_absolute_targets-1.png index 2b59ba9..16db146 100644 Binary files a/docs/reference/add_absolute_targets-1.png and b/docs/reference/add_absolute_targets-1.png differ diff --git a/docs/reference/add_absolute_targets-2.png b/docs/reference/add_absolute_targets-2.png index 99e4011..5c6b3b6 100644 Binary files a/docs/reference/add_absolute_targets-2.png and b/docs/reference/add_absolute_targets-2.png differ diff --git a/docs/reference/add_absolute_targets-3.png b/docs/reference/add_absolute_targets-3.png index 99e4011..5c6b3b6 100644 Binary files a/docs/reference/add_absolute_targets-3.png and b/docs/reference/add_absolute_targets-3.png differ diff --git a/docs/reference/add_absolute_targets.html b/docs/reference/add_absolute_targets.html index 74d69f7..55ce96f 100644 --- a/docs/reference/add_absolute_targets.html +++ b/docs/reference/add_absolute_targets.html @@ -1,81 +1,15 @@ - - - - - - - -Add absolute targets — add_absolute_targets • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add absolute targets — add_absolute_targets • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add absolute targets

- Source: R/add_absolute_targets.R + Source: R/add_absolute_targets.R
-

Set targets for a project prioritization problem() by +

Set targets for a project prioritization problem() by specifying exactly what probability of persistence is required for each feature. For instance, setting an absolute target of 10% (i.e. 0.1) corresponds to a threshold 10% probability of persisting.

- 
add_absolute_targets(x, targets)
-
-# S4 method for ProjectProblem,numeric
-add_absolute_targets(x, targets)
+    

+    
add_absolute_targets(x, targets)
+
+# S4 method for ProjectProblem,numeric
+add_absolute_targets(x, targets)
+
+# S4 method for ProjectProblem,character
+add_absolute_targets(x, targets)

+    

 
-# S4 method for ProjectProblem,character
-add_absolute_targets(x, targets)
+
+

Arguments

+
x
+

ProjectProblem object.

-

Arguments

- - - - - - - - - - -
x

ProjectProblem object.

targets

Object that specifies the targets for each feature. See the -Details section for more information.

-

Details

+
targets
+

Object that specifies the targets for each feature. See the +Details section for more information.

+
+
+

Details

Targets are used to specify the minimum probability of persistence for each feature in solutions. For minimum set objectives -(i.e. add_min_set_objective(), these targets +(i.e. add_min_set_objective(), these targets specify the minimum probability of persistence required for each species in the solution. And for budget constrained objectives that use targets -(i.e.add_max_targets_met_objective()), these targets +(i.e.add_max_targets_met_objective()), these targets specify the minimum threshold probability of persistence that needs to be achieved to count the benefits for conserving these species. Please note that attempting to solve problems with objectives that require targets without specifying targets will throw an error.

The targets for a problem can be specified in several different ways:

-
- -
numeric

vector of target values for each feature. +

numeric
+

vector of target values for each feature. The order of the target values should correspond to the order of the features in the data used to create the argument to x. Additionally, for convenience, this type of argument can be a single value to assign the same target to each feature.

-
character

specifying the name of column in the -feature data (i.e. the argument to features in the -problem() function) that contains the persistence targets.

- - -
- -

See also

- -

targets.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
 
-# build problem with minimum set objective and targets that require each
-# feature to have a 30% chance of persisting into the future
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_min_set_objective() %>%
-      add_absolute_targets(0.3) %>%
-      add_binary_decisions()
+
character

+
specifying the name of column in the
+feature data (i.e. the argument to features in the
+problem() function) that contains the persistence targets.

 
-# print problem
-print(p1)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Minimum set objective 
-#>   targets:         Absolute targets [targets (min: 0.3, max: 0.3)]
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# build problem with minimum set objective and specify targets that require
-# different levels of persistence for each feature
-p2 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_min_set_objective() %>%
-      add_absolute_targets(c(0.1, 0.2, 0.3, 0.4, 0.5)) %>%
-      add_binary_decisions()
 
-# print problem
-print(p2)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Minimum set objective 
-#>   targets:         Absolute targets [targets (min: 0.1, max: 0.5)]
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# add a column name to the feature data with targets
-sim_features$target <- c(0.1, 0.2, 0.3, 0.4, 0.5)
 
-# build problem with minimum set objective and specify targets using
-# column name in the feature data
-p3 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_min_set_objective() %>%
-      add_absolute_targets("target") %>%
-      add_binary_decisions()
+
+
+

See also

+

targets.

+
-# print problem -print(p3) -
#> Project Prioritization Problem -#> actions F1_action, F2_action, F3_action, ... (6 actions) -#> projects F1_project, F2_project, F3_project, ... (6 projects) -#> features F1, F2, F3, ... (5 features) -#> action costs: min: 0, max: 103.22583 -#> project success: min: 0.81379, max: 1 -#> objective: Minimum set objective -#> targets: Absolute targets [targets (min: 0.1, max: 0.5)] -#> weights: default -#> decisions Binary decision -#> constraints: <none> -#> solver: default
-# \dontrun{ -# solve problems -s1 <- solve(p1) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 46 rows, 42 columns and 92 nonzeros -#> Model fingerprint: 0xde05e947 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+00] -#> Objective range [9e+01, 1e+02] -#> Bounds range [1e+00, 1e+00] -#> RHS range [3e-01, 1e+00] -#> Found heuristic solution: objective 497.7671458 -#> Presolve removed 45 rows and 20 columns -#> Presolve time: 0.00s -#> Presolved: 1 rows, 22 columns, 2 nonzeros -#> Variable types: 0 continuous, 22 integer (22 binary) -#> -#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 497.767 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 4.977671458279e+02, best bound 4.977671458279e+02, gap 0.0000%
s2 <- solve(p2) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 46 rows, 42 columns and 92 nonzeros -#> Model fingerprint: 0x4e7d2c3e -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+00] -#> Objective range [9e+01, 1e+02] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e-01, 1e+00] -#> Found heuristic solution: objective 403.3678534 -#> Presolve removed 31 rows and 14 columns -#> Presolve time: 0.00s -#> Presolved: 15 rows, 28 columns, 30 nonzeros -#> Variable types: 0 continuous, 28 integer (28 binary) -#> Presolved: 15 rows, 28 columns, 30 nonzeros -#> -#> -#> Root relaxation: objective 3.023765e+02, 4 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 302.3764827 302.37648 0.00% - 0s -#> -#> Explored 0 nodes (4 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 302.376 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 3.023764827378e+02, best bound 3.023764827378e+02, gap 0.0000%
s3 <- solve(p3) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 46 rows, 42 columns and 92 nonzeros -#> Model fingerprint: 0x4e7d2c3e -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+00] -#> Objective range [9e+01, 1e+02] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e-01, 1e+00] -#> Found heuristic solution: objective 403.3678534 -#> Presolve removed 31 rows and 14 columns -#> Presolve time: 0.00s -#> Presolved: 15 rows, 28 columns, 30 nonzeros -#> Variable types: 0 continuous, 28 integer (28 binary) -#> Presolved: 15 rows, 28 columns, 30 nonzeros -#> -#> -#> Root relaxation: objective 3.023765e+02, 4 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 302.3764827 302.37648 0.00% - 0s -#> -#> Explored 0 nodes (4 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 302.376 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 3.023764827378e+02, best bound 3.023764827378e+02, gap 0.0000%
-# print solutions -print(s1) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 498. 498. 1 1 1 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
print(s2) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 302. 302. 0 0 1 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
print(s3) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 302. 302. 0 0 1 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solutions -plot(p1, s1) -
plot(p2, s2) -
plot(p3, s3) -
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with minimum set objective and targets that require each
+# feature to have a 30% chance of persisting into the future
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_min_set_objective() %>%
+      add_absolute_targets(0.3) %>%
+      add_binary_decisions()
+
+# print problem
+print(p1)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Minimum set objective 
+#>   targets:         Absolute targets [targets (min: 0.3, max: 0.3)]
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# build problem with minimum set objective and specify targets that require
+# different levels of persistence for each feature
+p2 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_min_set_objective() %>%
+      add_absolute_targets(c(0.1, 0.2, 0.3, 0.4, 0.5)) %>%
+      add_binary_decisions()
+
+# print problem
+print(p2)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Minimum set objective 
+#>   targets:         Absolute targets [targets (min: 0.1, max: 0.5)]
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# add a column name to the feature data with targets
+sim_features$target <- c(0.1, 0.2, 0.3, 0.4, 0.5)
+
+# build problem with minimum set objective and specify targets using
+# column name in the feature data
+p3 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_min_set_objective() %>%
+      add_absolute_targets("target") %>%
+      add_binary_decisions()
+
+# print problem
+print(p3)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Minimum set objective 
+#>   targets:         Absolute targets [targets (min: 0.1, max: 0.5)]
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# \dontrun{
+# solve problems
+s1 <- solve(p1)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 46 rows, 42 columns and 92 nonzeros
+#> Model fingerprint: 0xde05e947
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+00]
+#>   Objective range  [9e+01, 1e+02]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [3e-01, 1e+00]
+#> Found heuristic solution: objective 497.7671458
+#> Presolve removed 45 rows and 20 columns
+#> Presolve time: 0.00s
+#> Presolved: 1 rows, 22 columns, 2 nonzeros
+#> Variable types: 0 continuous, 22 integer (22 binary)
+#> 
+#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 497.767 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 4.977671458279e+02, best bound 4.977671458279e+02, gap 0.0000%
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 46 rows, 42 columns and 92 nonzeros
+#> Model fingerprint: 0x4e7d2c3e
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+00]
+#>   Objective range  [9e+01, 1e+02]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e-01, 1e+00]
+#> Found heuristic solution: objective 403.3678534
+#> Presolve removed 31 rows and 14 columns
+#> Presolve time: 0.00s
+#> Presolved: 15 rows, 28 columns, 30 nonzeros
+#> Variable types: 0 continuous, 28 integer (28 binary)
+#> Root relaxation presolved: 15 rows, 28 columns, 30 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 3.023765e+02, 4 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0     302.3764827  302.37648  0.00%     -    0s
+#> 
+#> Explored 1 nodes (4 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 302.376 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 3.023764827378e+02, best bound 3.023764827378e+02, gap 0.0000%
+s3 <- solve(p3)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 46 rows, 42 columns and 92 nonzeros
+#> Model fingerprint: 0x4e7d2c3e
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+00]
+#>   Objective range  [9e+01, 1e+02]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e-01, 1e+00]
+#> Found heuristic solution: objective 403.3678534
+#> Presolve removed 31 rows and 14 columns
+#> Presolve time: 0.00s
+#> Presolved: 15 rows, 28 columns, 30 nonzeros
+#> Variable types: 0 continuous, 28 integer (28 binary)
+#> Root relaxation presolved: 15 rows, 28 columns, 30 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 3.023765e+02, 4 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0     302.3764827  302.37648  0.00%     -    0s
+#> 
+#> Explored 1 nodes (4 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 302.376 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 3.023764827378e+02, best bound 3.023764827378e+02, gap 0.0000%
+
+# print solutions
+print(s1)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  498.  498.         1       1       1       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+print(s2)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  302.  302.         0       0       1       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+print(s3)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  302.  302.         0       0       1       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solutions
+plot(p1, s1)
+
+plot(p2, s2)
+
+plot(p3, s3)
+
+# }
+
+
+
- - - - + diff --git a/docs/reference/add_binary_decisions-1.png b/docs/reference/add_binary_decisions-1.png index 89a16f5..6c3a587 100644 Binary files a/docs/reference/add_binary_decisions-1.png and b/docs/reference/add_binary_decisions-1.png differ diff --git a/docs/reference/add_binary_decisions.html b/docs/reference/add_binary_decisions.html index 4704a62..b330f29 100644 --- a/docs/reference/add_binary_decisions.html +++ b/docs/reference/add_binary_decisions.html @@ -1,80 +1,14 @@ - - - - - - - -Add binary decisions — add_binary_decisions • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add binary decisions — add_binary_decisions • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add binary decisions

- Source: R/add_binary_decisions.R + Source: R/add_binary_decisions.R
-

Add a binary decision to a project prioritization problem(). +

Add a binary decision to a project prioritization problem(). This is the conventional decision of either prioritizing funding for a management action or not.

- 
add_binary_decisions(x)
+
+ 
add_binary_decisions(x)
+
-

Arguments

- - - - - - -
x

ProjectProblem object.

+
+

Arguments

+
x
+

ProjectProblem object.

-

Value

+
+
+

Value

+ -

ProjectProblem object with the decisions +

ProjectProblem object with the decisions added to it.

-

Details

- +
+
+

Details

Project prioritization problems involve making decisions about how funding will be allocated to management actions. Only a single decision should be added to a ProjectProblem object. If no decision is added to a problem then this decision type will be used by default. Currently, this is the only supported decision type.

-

See also

- -

decisions.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with maximum richness objective, $200 budget, and
-# binary decisions
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions()
+    

+    

+    
See also

+    
decisions.

+    

 
-# print problem
-print(p)
-
#> Project Prioritization Problem -#> actions F1_action, F2_action, F3_action, ... (6 actions) -#> projects F1_project, F2_project, F3_project, ... (6 projects) -#> features F1, F2, F3, ... (5 features) -#> action costs: min: 0, max: 103.22583 -#> project success: min: 0.81379, max: 1 -#> objective: Maximum richness objective [budget (200)] -#> targets: none -#> weights: default -#> decisions Binary decision -#> constraints: <none> -#> solver: default
-# \dontrun{ -# solve problem -s <- solve(p) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0xab0d0209 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [1e+00, 1e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 1.4456093 -#> Presolve removed 16 rows and 12 columns -#> Presolve time: 0.00s -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> Variable types: 0 continuous, 35 integer (35 binary) -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> -#> -#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 2.1903807 2.19038 0.00% - 0s -#> -#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 2.19038 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
-# print solution -print(s) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 2.19 195. 1 1 0 0 0 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solution -plot(p, s) -
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with maximum richness objective, $200 budget, and
+# binary decisions
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# \dontrun{
+# solve problem
+s <- solve(p)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x193cb636
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.19038 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
+
+# print solution
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  2.19  195.         1       1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution
+plot(p, s)
+
+# }
+
+
+
-
- - - + diff --git a/docs/reference/add_default_solver-1.png b/docs/reference/add_default_solver-1.png index 89a16f5..6c3a587 100644 Binary files a/docs/reference/add_default_solver-1.png and b/docs/reference/add_default_solver-1.png differ diff --git a/docs/reference/add_default_solver.html b/docs/reference/add_default_solver.html index 043ce1c..5d96d75 100644 --- a/docs/reference/add_default_solver.html +++ b/docs/reference/add_default_solver.html @@ -1,79 +1,13 @@ - - - - - - - -Add a default solver — add_default_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add a default solver — add_default_solver • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Add a default solver

- Source: R/add_default_solver.R + Source: R/add_default_solver.R

Identify the best solver currently installed on the system and specify that -it should be used to solve a project prioritization problem().

+it should be used to solve a project prioritization problem().

- 
add_default_solver(x, ...)
+
+ 
add_default_solver(x, ...)
+
+ +
+

Arguments

+
x
+

ProjectProblem object.

-

Arguments

- - - - - - - - - - -
x

ProjectProblem object.

...

arguments passed to the solver.

-

Details

+
...
+

arguments passed to the solver.

+
+
+

Details

Ranked from best to worst, the solvers that can be used are: -gurobi, (add_gurobi_solver()), -Rsymphony (add_rsymphony_solver()), lpsymphony -(add_lpsymphony_solver()), and lpSolveAPI -(add_lpsolveapi_solver()). This function does not consider +gurobi, (add_gurobi_solver()), +Rsymphony (add_rsymphony_solver()), lpsymphony +(add_lpsymphony_solver()), and lpSolveAPI +(add_lpsolveapi_solver()). This function does not consider solvers that generate solutions using heuristic algorithms (i.e. -add_heuristic_solver()) or random processes -(i.e. add_random_solver()) because they cannot provide +add_heuristic_solver()) or random processes +(i.e. add_random_solver()) because they cannot provide any guarantees on solution quality.

-

See also

- -

solvers.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with default solver
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions() %>%
-     add_default_solver()
+    

+    

+    
See also

+    
solvers.

+    

 
-# print problem
-print(p)
-
#> Project Prioritization Problem -#> actions F1_action, F2_action, F3_action, ... (6 actions) -#> projects F1_project, F2_project, F3_project, ... (6 projects) -#> features F1, F2, F3, ... (5 features) -#> action costs: min: 0, max: 103.22583 -#> project success: min: 0.81379, max: 1 -#> objective: Maximum richness objective [budget (200)] -#> targets: none -#> weights: default -#> decisions Binary decision -#> constraints: <none> -#> solver: Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]
-# \dontrun{ -# solve problem -s <- solve(p) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0xab0d0209 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [1e+00, 1e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 1.4456093 -#> Presolve removed 16 rows and 12 columns -#> Presolve time: 0.00s -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> Variable types: 0 continuous, 35 integer (35 binary) -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> -#> -#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 2.1903807 2.19038 0.00% - 0s -#> -#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 2.19038 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
-# print solution -print(s) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 2.19 195. 1 1 0 0 0 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solution -plot(p, s) -
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with default solver
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions() %>%
+     add_default_solver()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]
+
+# \dontrun{
+# solve problem
+s <- solve(p)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x193cb636
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.19038 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
+
+# print solution
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  2.19  195.         1       1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution
+plot(p, s)
+
+# }
+
+
+
-
- - - + diff --git a/docs/reference/add_feature_weights-1.png b/docs/reference/add_feature_weights-1.png index 89a16f5..6c3a587 100644 Binary files a/docs/reference/add_feature_weights-1.png and b/docs/reference/add_feature_weights-1.png differ diff --git a/docs/reference/add_feature_weights-2.png b/docs/reference/add_feature_weights-2.png index b6aaf49..4c14674 100644 Binary files a/docs/reference/add_feature_weights-2.png and b/docs/reference/add_feature_weights-2.png differ diff --git a/docs/reference/add_feature_weights-3.png b/docs/reference/add_feature_weights-3.png index b6aaf49..4c14674 100644 Binary files a/docs/reference/add_feature_weights-3.png and b/docs/reference/add_feature_weights-3.png differ diff --git a/docs/reference/add_feature_weights.html b/docs/reference/add_feature_weights.html index b222537..2223361 100644 --- a/docs/reference/add_feature_weights.html +++ b/docs/reference/add_feature_weights.html @@ -1,79 +1,13 @@ - - - - - - - -Add feature weights — add_feature_weights • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add feature weights — add_feature_weights • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Add feature weights

- Source: R/add_feature_weights.R + Source: R/add_feature_weights.R

Set weights for conserving features in a project prioritization -problem().

+problem().

- 
add_feature_weights(x, weights)
-
-# S4 method for ProjectProblem,numeric
-add_feature_weights(x, weights)
+    

+    
add_feature_weights(x, weights)
+
+# S4 method for ProjectProblem,numeric
+add_feature_weights(x, weights)
+
+# S4 method for ProjectProblem,character
+add_feature_weights(x, weights)

+    

 
-# S4 method for ProjectProblem,character
-add_feature_weights(x, weights)
+
+

Arguments

+
x
+

ProjectProblem object.

-

Arguments

- - - - - - - - - - -
x

ProjectProblem object.

weights

Object that specifies the weights for each feature. See the -Details section for more information.

-

Details

+
weights
+

Object that specifies the weights for each feature. See the +Details section for more information.

+
+
+

Details

Weights are used to specify the relative importance for maintaining the persistence of specific features. For budget constrained -problems (e.g. add_max_richness_objective()), these +problems (e.g. add_max_richness_objective()), these weights could be used to specify which features are more important than other features according to evolutionary or cultural metrics. Specifically, @@ -171,256 +97,273 @@

Details Please note that a warning will be thrown if you attempt to solve problems with weights when an objective has been specified that does not use weights. Currently, all objectives---except for the minimum -set objective (i.e. add_min_set_objective())---can use weights.

+set objective (i.e. add_min_set_objective())---can use weights.

The weights for a problem can be specified in several different ways:

-
+
numeric
+

vector of weight values for each feature.

-
numeric

vector of weight values for each feature.

-
character

specifying the name of column in the +

character
+

specifying the name of column in the feature data (i.e. the argument to features in the -problem() function) that contains the weights.

- - -
- -

See also

- -

weights.

+problem() function) that contains the weights.

-

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
 
-# print feature data
-print(sim_features)
-
#> # A tibble: 5 x 2
-#>   name  weight
-#>   <chr>  <dbl>
-#> 1 F1     0.211
-#> 2 F2     0.211
-#> 3 F3     0.221
-#> 4 F4     0.630
-#> 5 F5     1.59 

-# build problem with maximum richness objective, $300 budget, and no weights
-p1 <- problem(sim_projects, sim_actions, sim_features,
-              "name", "success", "name", "cost", "name") %>%
-      add_max_richness_objective(budget = 200) %>%
-      add_binary_decisions()
 
-# print problem
-print(p1)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# build another problem, and specify feature weights using the values in the
-# "weight" column of the sim_features table by specifying the column
-# name "weight"
-p2 <- p1 %>%
-      add_feature_weights("weight")
-
-# print problem
-print(p2)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         min: 0.21136, max: 1.59167
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# build another problem, and specify feature weights using the
-# values in the "weight column of the sim_features table, but
-# actually input the values rather than specifying the column name
-# "weights" column of the sim_features table
-p3 <- p1 %>%
-      add_feature_weights(sim_features$weight)
+

+
+

See also

+

weights.

+
-# print problem -print(p3) -
#> Project Prioritization Problem -#> actions F1_action, F2_action, F3_action, ... (6 actions) -#> projects F1_project, F2_project, F3_project, ... (6 projects) -#> features F1, F2, F3, ... (5 features) -#> action costs: min: 0, max: 103.22583 -#> project success: min: 0.81379, max: 1 -#> objective: Maximum richness objective [budget (200)] -#> targets: none -#> weights: min: 0.21136, max: 1.59167 -#> decisions Binary decision -#> constraints: <none> -#> solver: default
-# \dontrun{ -# solve the problems -s1 <- solve(p1) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0xab0d0209 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [1e+00, 1e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 1.4456093 -#> Presolve removed 16 rows and 12 columns -#> Presolve time: 0.00s -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> Variable types: 0 continuous, 35 integer (35 binary) -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> -#> -#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 2.1903807 2.19038 0.00% - 0s -#> -#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 2.19038 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
s2 <- solve(p2) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0xffde171d -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [2e-01, 2e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 0.6654645 -#> Presolve removed 16 rows and 12 columns -#> Presolve time: 0.00s -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> Variable types: 0 continuous, 35 integer (35 binary) -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> -#> -#> Root relaxation: objective 1.511230e+00, 11 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 1.5112297 1.51123 0.00% - 0s -#> -#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 1.51123 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.511229665304e+00, best bound 1.511229665304e+00, gap 0.0000%
s3 <- solve(p3) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0xffde171d -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [2e-01, 2e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 0.6654645 -#> Presolve removed 16 rows and 12 columns -#> Presolve time: 0.00s -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> Variable types: 0 continuous, 35 integer (35 binary) -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> -#> -#> Root relaxation: objective 1.511230e+00, 11 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 1.5112297 1.51123 0.00% - 0s -#> -#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 1.51123 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.511229665304e+00, best bound 1.511229665304e+00, gap 0.0000%
-# print solutions -print(s1) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 2.19 195. 1 1 0 0 0 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
print(s2) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 1.51 199. 0 0 0 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
print(s3) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 1.51 199. 0 0 0 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solutions -plot(p1, s1) -
plot(p2, s2) -
plot(p3, s3) -
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# print feature data
+print(sim_features)
+#> # A tibble: 5 × 2
+#>   name  weight
+#>   <chr>  <dbl>
+#> 1 F1     0.211
+#> 2 F2     0.211
+#> 3 F3     0.221
+#> 4 F4     0.630
+#> 5 F5     1.59 
+
+# build problem with maximum richness objective, $300 budget, and no weights
+p1 <- problem(sim_projects, sim_actions, sim_features,
+              "name", "success", "name", "cost", "name") %>%
+      add_max_richness_objective(budget = 200) %>%
+      add_binary_decisions()
+
+# print problem
+print(p1)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# build another problem, and specify feature weights using the values in the
+# "weight" column of the sim_features table by specifying the column
+# name "weight"
+p2 <- p1 %>%
+      add_feature_weights("weight")
+
+# print problem
+print(p2)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         min: 0.21136, max: 1.59167
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# build another problem, and specify feature weights using the
+# values in the "weight column of the sim_features table, but
+# actually input the values rather than specifying the column name
+# "weights" column of the sim_features table
+p3 <- p1 %>%
+      add_feature_weights(sim_features$weight)
+
+# print problem
+print(p3)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         min: 0.21136, max: 1.59167
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# \dontrun{
+# solve the problems
+s1 <- solve(p1)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x193cb636
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.19038 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x40fa7344
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [2e-01, 2e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 0.6654645
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.511230e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.5112297    1.51123  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.51123 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.511229665304e+00, best bound 1.511229665304e+00, gap 0.0000%
+s3 <- solve(p3)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x40fa7344
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [2e-01, 2e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 0.6654645
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.511230e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.5112297    1.51123  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.51123 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.511229665304e+00, best bound 1.511229665304e+00, gap 0.0000%
+
+# print solutions
+print(s1)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  2.19  195.         1       1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+print(s2)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  1.51  199.         0       0       0       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+print(s3)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  1.51  199.         0       0       0       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solutions
+plot(p1, s1)
+
+plot(p2, s2)
+
+plot(p3, s3)
+
+# }
+
+
+
- - - - + diff --git a/docs/reference/add_gurobi_solver-1.png b/docs/reference/add_gurobi_solver-1.png index 89a16f5..6c3a587 100644 Binary files a/docs/reference/add_gurobi_solver-1.png and b/docs/reference/add_gurobi_solver-1.png differ diff --git a/docs/reference/add_gurobi_solver.html b/docs/reference/add_gurobi_solver.html index 6a2c141..c829a65 100644 --- a/docs/reference/add_gurobi_solver.html +++ b/docs/reference/add_gurobi_solver.html @@ -1,82 +1,16 @@ - - - - - - - -Add a Gurobi solver — add_gurobi_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add a Gurobi solver — add_gurobi_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add a Gurobi solver

- Source: R/add_gurobi_solver.R + Source: R/add_gurobi_solver.R

Specify that the Gurobi software should be used to solve a -project prioritization problem(). This function can also be +project prioritization problem(). This function can also be used to customize the behavior of the solver. In addition to the Gurobi software suite, it also requires the gurobi package to be installed.

- 
add_gurobi_solver(
-  x,
-  gap = 0,
-  number_solutions = 1,
-  solution_pool_method = 2,
-  time_limit = .Machine$integer.max,
-  presolve = 2,
-  threads = 1,
-  first_feasible = FALSE,
-  verbose = TRUE
-)
- -

Arguments

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
x

ProjectProblem object.

gap

numeric gap to optimality. This gap is relative +

+ 
add_gurobi_solver(
+  x,
+  gap = 0,
+  number_solutions = 1,
+  solution_pool_method = 2,
+  time_limit = .Machine$integer.max,
+  presolve = 2,
+  threads = 1,
+  first_feasible = FALSE,
+  verbose = TRUE
+)
+
+ +
+

Arguments

+
x
+

ProjectProblem object.

+ + +
gap
+

numeric gap to optimality. This gap is relative and expresses the acceptable deviance from the optimal objective. For example, a value of 0.01 will result in the solver stopping when it has found a solution within 1% of optimality. Additionally, a value of 0 will result in the solver stopping when it has found an optimal solution. -The default value is 0.1 (i.e. 10% from optimality).

number_solutions

integer number of solutions desired. +The default value is 0.1 (i.e. 10% from optimality).

+ + +
number_solutions
+

integer number of solutions desired. Defaults to 1. Note that the number of returned solutions can sometimes be less than the argument to number_solutions depending on the argument to solution_pool_method, for example if 100 solutions are requested but only 10 unique solutions exist, then only 10 -solutions will be returned.

solution_pool_method

numeric search method identifier that +solutions will be returned.

+ + +
solution_pool_method
+

numeric search method identifier that determines how multiple solutions should be generated. Available search modes for generating a portfolio of solutions include: 0 recording all solutions identified whilst trying to find @@ -185,51 +112,53 @@

Arg solutions that are of any level of quality (such that the total number of solutions is equal to number_solutions), and 2 finding a specified number of solutions that are nearest to optimality. For more -information, see the Gurobi manual (i.e. https://www.gurobi.com/documentation/8.0/refman/poolsearchmode.html#parameter:PoolSearchMode). Defaults to 2.

time_limit

numeric time limit in seconds to run the optimizer. +information, see the Gurobi manual (i.e. https://www.gurobi.com/documentation/8.0/refman/poolsearchmode.html#parameter:PoolSearchMode). Defaults to 2.

+ + +
time_limit
+

numeric time limit in seconds to run the optimizer. The solver will return the current best solution when this time limit is -exceeded.

presolve

integer number indicating how intensively the +exceeded.

+ + +
presolve
+

integer number indicating how intensively the solver should try to simplify the problem before solving it. The default value of 2 indicates to that the solver should be very aggressive in -trying to simplify the problem.

threads

integer number of threads to use for the +trying to simplify the problem.

+ + +
threads
+

integer number of threads to use for the optimization algorithm. The default value of 1 will result in only -one thread being used.

first_feasible

logical should the first feasible solution be +one thread being used.

+ + +
first_feasible
+

logical should the first feasible solution be be returned? If first_feasible is set to TRUE, the solver will return the first solution it encounters that meets all the constraints, regardless of solution quality. Note that the first feasible solution is not an arbitrary solution, rather it is derived from the relaxed solution, and is therefore often reasonably close to optimality. -Defaults to FALSE.

verbose

logical should information be printed while solving -optimization problems?

- -

Value

- -

ProjectProblem object with the solver added -to it.

-

Details

+Defaults to FALSE.

+ -

Gurobi is a +

verbose
+

logical should information be printed while solving +optimization problems?

+ +
+
+

Value

+ + +

ProjectProblem object with the solver added +to it.

+
+
+

Details

+

Gurobi is a state-of-the-art commercial optimization software with an R package interface. It is by far the fastest of the solvers supported by this package, however, it is also the only solver that is not freely @@ -237,199 +166,208 @@

Details gurobi package is distributed with the Gurobi software suite. This solver uses the gurobi package to solve problems.

To install the gurobi package, the -Gurobi optimization suite will first need to -be installed (see instructions for Linux, -Mac OSX, and -Windows operating systems). Although -Gurobi is a commercial software, academics +Gurobi optimization suite will first need to +be installed (see instructions for Linux, +Mac OSX, and +Windows operating systems). Although +Gurobi is a commercial software, academics can obtain a -special license for no cost. After installing the -Gurobi optimization suite, the gurobi -package can then be installed (see instructions for Linux, -Mac OSX, and -Windows operating systems).

-

See also

- -

solvers.

- -

Examples

- 
# \dontrun{
-# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions()
-
-# build another problem, and specify the Gurobi solver
-p2 <- p1 %>%
-      add_gurobi_solver()
-
-# print problem
-print(p2)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]

-# solve problem
-s2 <- solve(p2)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xab0d0209
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 2.19038 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%

-# print solution
-print(s2)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL  2.19  195.         1         1         0         0         0
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>

-# plot solution
-plot(p2, s2)
-

-# build another problem and obtain multiple solutions
-# note that this problem doesn't have 100 unique solutions so
-# the solver won't return 100 solutions
-p3 <- p1 %>%
-      add_gurobi_solver(number_solutions = 100)
-
-# print problem
-print(p3)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (100), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]

-# solve problem
-s3 <- solve(p3)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xab0d0209
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Found heuristic solution: objective 2.1903807
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#>      0     0          -    0         2.19038    2.19038  0.00%     -    0s
-#> 
-#> Optimal solution found at node 0 - now completing solution pool...
-#> 
-#>     Nodes    |    Current Node    |      Pool Obj. Bounds     |     Work
-#>              |                    |   Worst                   |
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#>      0     0          -    0               -    2.19038      -     -    0s
-#>      0     2          -    0               -    2.19038      -     -    0s
-#> 
-#> Explored 240 nodes (37 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 100: 2.19038 2.19038 2.19038 ... 2.19038
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%

-# print solutions
-print(s3)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL  2.19  195.         1         1         0         0         0
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
# }
-
+special license for no cost. After installing the +Gurobi optimization suite, the gurobi +package can then be installed (see instructions for Linux, +Mac OSX, and +Windows operating systems).

+
+
+

See also

+

solvers.

+
+ +
+

Examples

+ 
# \dontrun{
+# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions()
+
+# build another problem, and specify the Gurobi solver
+p2 <- p1 %>%
+      add_gurobi_solver()
+
+# print problem
+print(p2)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]
+
+# solve problem
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x193cb636
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.19038 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
+
+# print solution
+print(s2)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  2.19  195.         1       1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution
+plot(p2, s2)
+
+
+# build another problem and obtain multiple solutions
+# note that this problem doesn't have 100 unique solutions so
+# the solver won't return 100 solutions
+p3 <- p1 %>%
+      add_gurobi_solver(number_solutions = 100)
+
+# print problem
+print(p3)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (100), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]
+
+# solve problem
+s3 <- solve(p3)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x193cb636
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Found heuristic solution: objective 2.1903807
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#>      0     0          -    0         2.19038    2.19038  0.00%     -    0s
+#> 
+#> Optimal solution found at node 0 - now completing solution pool...
+#> 
+#>     Nodes    |    Current Node    |      Pool Obj. Bounds     |     Work
+#>              |                    |   Worst                   |
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#>      0     0          -    0               -    2.19038      -     -    0s
+#>      0     2          -    0               -    2.19038      -     -    0s
+#> 
+#> Explored 240 nodes (37 simplex iterations) in 0.01 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 100: 2.19038 2.19038 2.19038 ... 2.19038
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
+
+# print solutions
+print(s3)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  2.19  195.         1       1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+# }
+
+
+
- - - - + diff --git a/docs/reference/add_heuristic_solver-1.png b/docs/reference/add_heuristic_solver-1.png index 89a16f5..6c3a587 100644 Binary files a/docs/reference/add_heuristic_solver-1.png and b/docs/reference/add_heuristic_solver-1.png differ diff --git a/docs/reference/add_heuristic_solver.html b/docs/reference/add_heuristic_solver.html index cd0d343..30e995b 100644 --- a/docs/reference/add_heuristic_solver.html +++ b/docs/reference/add_heuristic_solver.html @@ -1,84 +1,18 @@ - - - - - - - -Add a heuristic solver — add_heuristic_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add a heuristic solver — add_heuristic_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add a heuristic solver

- Source: R/add_heuristic_solver.R + Source: R/add_heuristic_solver.R
@@ -135,64 +62,65 @@

Add a heuristic solver

heuristic algorithm (inspired by Cabeza et al. 2004, Korte & Vygen 2000, Probert et al. 2016). Ideally, solutions should be generated using exact algorithm solvers (e.g. -add_rsymphony_solver() or add_gurobi_solver()) +add_rsymphony_solver() or add_gurobi_solver()) because they are guaranteed to identify optimal solutions (Rodrigues & Gaston 2002).

- 
add_heuristic_solver(
-  x,
-  number_solutions = 1,
-  initial_sweep = TRUE,
-  verbose = TRUE
-)
+
+ 
add_heuristic_solver(
+  x,
+  number_solutions = 1,
+  initial_sweep = TRUE,
+  verbose = TRUE
+)
+
+ +
+

Arguments

+
x
+

ProjectProblem object.

-

Arguments

- - - - - - - - - - - - - - - - - - -
x

ProjectProblem object.

number_solutions

integer number of solutions desired. + +

number_solutions
+

integer number of solutions desired. Defaults to 1. Note that the number of returned solutions can sometimes be less than the argument to number_solutions depending on the argument to solution_pool_method, for example if 100 solutions are requested but only 10 unique solutions exist, then only 10 -solutions will be returned.

initial_sweep

logical value indicating if projects and +solutions will be returned.

+ + +
initial_sweep
+

logical value indicating if projects and actions which exceed the budget should be automatically excluded prior to running the backwards heuristic. This step prevents projects which exceed the budget, and so would never be selected in the final solution, from biasing the cost-sharing calculations. However, previous algorithms for project prioritization have not used this step (e.g. Probert et al. 2016). -Defaults to TRUE.

verbose

logical should information be printed while solving -optimization problems?

+Defaults to TRUE.

-

Value

-

ProjectProblem object with the solver added -to it.

-

Details

+
verbose
+

logical should information be printed while solving +optimization problems?

+
+
+

Value

+ + +

ProjectProblem object with the solver added +to it.

+
+
+

Details

The heuristic algorithm used to generate solutions is described below. It is heavily inspired by the cost-sharing backwards heuristic algorithm conventionally used to guide the prioritization of species recovery projects (Probert et al. 2016).

-
    -

  1. All actions and projects are initially selected for funding.

    2. +

    1. All actions and projects are initially selected for funding.

    2. A set of rules are then used to deselect actions and projects based on locked constraints (if any). Specifically, (i) actions which are which are locked out are deselected, and (ii) projects which are @@ -205,10 +133,10 @@

      Details and (iii) actions which are not associated with any project (excepting locked in actions) are also deselected.

    3. If the objective function is to maximize biodiversity subject -to budgetary constraints (e.g. add_max_richness_objective()) +to budgetary constraints (e.g. add_max_richness_objective()) then go to step 5. Otherwise, if the objective is to minimize cost subject to biodiversity constraints (i.e. -add_min_set_objective()) then go to step 7.

      4. +add_min_set_objective()) then go to step 7.

    4. The next step is repeated until (i) the number of desired solutions is obtained, and (ii) the total cost of the remaining actions that are selected for funding is within the budget. After both of @@ -266,10 +194,9 @@

      Details the same \(B_j\) value, the project with the greatest overall cost (including actions which are shared among multiple remaining projects) is deselected.

      5. -
    - -

    References

    - +
+
+

References

Rodrigues AS & Gaston KJ (2002) Optimisation in reserve selection procedures---why not? Biological Conservation, 107, 123--129.

@@ -281,84 +208,87 @@

R Berlin, Germany.

Probert W, Maloney RF, Mellish B, and Joseph L (2016) Project Prioritisation Protocol (PPP). -Formerly available at https://github.com/p-robot -(copy available at https://github.com/jeffreyhanson/ppp).

-

See also

- -

solvers.

- -

Examples

- 
# load ggplot2 package for making plots
-library(ggplot2)
-
-# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with heuristic solver and $200
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions() %>%
-     add_heuristic_solver()
-
-# print problem
-print(p1)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          Heuristic [initial_sweep (1), number_solutions (1), verbose (1)]

-# \dontrun{
-# solve problem
-s1 <- solve(p1)
+Formerly available at https://github.com/p-robot
+(copy available at https://github.com/jeffreyhanson/ppp).

+    

+    

+    
See also

+    
solvers.

+    

 
-# print solution
-print(s1)
-
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 NA 2.19 195. 1 1 0 0 0 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solution -plot(p1, s1) -
# } -
+
+

Examples

+ 
# load ggplot2 package for making plots
+library(ggplot2)
+
+# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with heuristic solver and $200
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions() %>%
+     add_heuristic_solver()
+
+# print problem
+print(p1)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Heuristic [initial_sweep (1), number_solutions (1), verbose (1)]
+
+# \dontrun{
+# solve problem
+s1 <- solve(p1)
+
+# print solution
+print(s1)
+#> # A tibble: 1 × 21
+#>   solution status   obj  cost F1_action F2_act…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>  <dbl> <dbl>     <dbl>    <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 NA      2.19  195.         1        1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution
+plot(p1, s1)
+
+# }
+
+
+
- - - - + diff --git a/docs/reference/add_locked_in_constraints.html b/docs/reference/add_locked_in_constraints.html index 6e408da..e62e701 100644 --- a/docs/reference/add_locked_in_constraints.html +++ b/docs/reference/add_locked_in_constraints.html @@ -1,81 +1,15 @@ - - - - - - - -Add locked in constraints — add_locked_in_constraints • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add locked in constraints — add_locked_in_constraints • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add locked in constraints

- Source: R/add_locked_in_constraints.R + Source: R/add_locked_in_constraints.R
-

Add constraints to a project prioritization problem() to ensure +

Add constraints to a project prioritization problem() to ensure that specific actions are prioritized for funding in the solution. For example, it may be desirable to lock in actions for conserving culturally or taxonomically important species.

- 
add_locked_in_constraints(x, locked_in)
-
-# S4 method for ProjectProblem,numeric
-add_locked_in_constraints(x, locked_in)
+    

+    
add_locked_in_constraints(x, locked_in)
+
+# S4 method for ProjectProblem,numeric
+add_locked_in_constraints(x, locked_in)
+
+# S4 method for ProjectProblem,logical
+add_locked_in_constraints(x, locked_in)
+
+# S4 method for ProjectProblem,character
+add_locked_in_constraints(x, locked_in)

+    

 
-# S4 method for ProjectProblem,logical
-add_locked_in_constraints(x, locked_in)
+    

+    
Arguments

+    
x

+
ProjectProblem object.

 
-# S4 method for ProjectProblem,character
-add_locked_in_constraints(x, locked_in)
-

Arguments

- - - - - - - - - - -
x

ProjectProblem object.

locked_in

Object that determines which planning units that should be -locked in. See the Details section for more information.

+
locked_in
+

Object that determines which planning units that should be +locked in. See the Details section for more information.

-

Value

+
+
+

Value

+ -

ProjectProblem object with the constraints +

ProjectProblem object with the constraints added to it.

-

Details

- +
+
+

Details

The locked actions can be specified in several different ways:

-
- -
integer

vector of indices pertaining to which +

integer
+

vector of indices pertaining to which actions should be locked in the solution (i.e. row numbers of the -actions in the argument to actions in problem()).

+actions in the argument to actions in problem()).

-
logical

vector containing logical + +

logical
+

vector containing logical (i.e. TRUE and/or FALSE values) that indicate which actions should be locked in the solution. These logical values should correspond to each row in the argument to actions -in problem()).

+in problem()).

+ -
character

column name that indicates if actions +

character
+

column name that indicates if actions units should be locked in the solution. This argument should denote a column in the argument to actions -in problem() which contains logical +in problem() which contains logical (i.e. TRUE and/or FALSE values) to indicate which actions should be locked.

-
- -

See also

- -

constraints.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# print action data
-print(sim_actions)
-
#> # A tibble: 6 x 4
-#>   name             cost locked_in locked_out
-#>   <chr>           <dbl> <lgl>     <lgl>     
-#> 1 F1_action        94.4 FALSE     FALSE     
-#> 2 F2_action       101.  FALSE     FALSE     
-#> 3 F3_action       103.  TRUE      FALSE     
-#> 4 F4_action        99.2 FALSE     FALSE     
-#> 5 F5_action        99.9 FALSE     TRUE      
-#> 6 baseline_action   0   FALSE     FALSE     

-# build problem with maximum richness objective and $150 budget
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 150) %>%
-     add_binary_decisions()
 
-# print problem
-print(p1)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (150)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# build another problem, and lock in the 3rd action using numeric inputs
-p2 <- p1 %>%
-      add_locked_in_constraints(c(3))
-
-# print problem
-print(p2)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (150)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <Locked in actions [1 locked units]>
-#>   solver:          default

-# build another problem, and lock in the actions using logical inputs from
-# the sim_actions table
-p3 <- p1 %>%
-      add_locked_in_constraints(sim_actions$locked_in)
-
-# print problem
-print(p3)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (150)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <Locked in actions [1 locked units]>
-#>   solver:          default

-# build another problem, and lock in the actions using the column name
-# "locked_in" in the sim_actions table
-# the sim_actions table
-p4 <- p1 %>%
-      add_locked_in_constraints("locked_in")
+

+    

+    
See also

+    
constraints.

+    

 
-# print problem
-print(p4)
-
#> Project Prioritization Problem -#> actions F1_action, F2_action, F3_action, ... (6 actions) -#> projects F1_project, F2_project, F3_project, ... (6 projects) -#> features F1, F2, F3, ... (5 features) -#> action costs: min: 0, max: 103.22583 -#> project success: min: 0.81379, max: 1 -#> objective: Maximum richness objective [budget (150)] -#> targets: none -#> weights: default -#> decisions Binary decision -#> constraints: <Locked in actions [1 locked units]> -#> solver: default
-# \dontrun{ -# solve problems -s1 <- solve(p1) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0x57c178c1 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [1e+00, 1e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 1.4456093 -#> Presolve removed 16 rows and 12 columns -#> Presolve time: 0.00s -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> Variable types: 0 continuous, 35 integer (35 binary) -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> -#> -#> Root relaxation: objective 1.680145e+00, 11 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 1.6801450 1.68015 0.00% - 0s -#> -#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 1.68015 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.680145013696e+00, best bound 1.680145013696e+00, gap 0.0000%
s2 <- solve(p2) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0xbbb75d04 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [1e+00, 1e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 1.4456093 -#> Presolve removed 42 rows and 41 columns -#> Presolve time: 0.00s -#> Presolved: 5 rows, 6 columns, 10 nonzeros -#> Variable types: 0 continuous, 6 integer (6 binary) -#> -#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 1.44561 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.445609277954e+00, best bound 1.445609277954e+00, gap 0.0000%
s3 <- solve(p3) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0xbbb75d04 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [1e+00, 1e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 1.4456093 -#> Presolve removed 42 rows and 41 columns -#> Presolve time: 0.00s -#> Presolved: 5 rows, 6 columns, 10 nonzeros -#> Variable types: 0 continuous, 6 integer (6 binary) -#> -#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 1.44561 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.445609277954e+00, best bound 1.445609277954e+00, gap 0.0000%
s4 <- solve(p4) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0xbbb75d04 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [1e+00, 1e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 1.4456093 -#> Presolve removed 42 rows and 41 columns -#> Presolve time: 0.00s -#> Presolved: 5 rows, 6 columns, 10 nonzeros -#> Variable types: 0 continuous, 6 integer (6 binary) -#> -#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 1.44561 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.445609277954e+00, best bound 1.445609277954e+00, gap 0.0000%
-# print the actions selected for funding in each of the solutions -print(s1[, sim_actions$name]) -
#> # A tibble: 1 x 6 -#> F1_action F2_action F3_action F4_action F5_action baseline_action -#> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 0 1 0 0 0 1
print(s2[, sim_actions$name]) -
#> # A tibble: 1 x 6 -#> F1_action F2_action F3_action F4_action F5_action baseline_action -#> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 0 0 1 0 0 1
print(s3[, sim_actions$name]) -
#> # A tibble: 1 x 6 -#> F1_action F2_action F3_action F4_action F5_action baseline_action -#> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 0 0 1 0 0 1
print(s4[, sim_actions$name]) -
#> # A tibble: 1 x 6 -#> F1_action F2_action F3_action F4_action F5_action baseline_action -#> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 0 0 1 0 0 1
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# print action data
+print(sim_actions)
+#> # A tibble: 6 × 4
+#>   name             cost locked_in locked_out
+#>   <chr>           <dbl> <lgl>     <lgl>     
+#> 1 F1_action        94.4 FALSE     FALSE     
+#> 2 F2_action       101.  FALSE     FALSE     
+#> 3 F3_action       103.  TRUE      FALSE     
+#> 4 F4_action        99.2 FALSE     FALSE     
+#> 5 F5_action        99.9 FALSE     TRUE      
+#> 6 baseline_action   0   FALSE     FALSE     
+
+# build problem with maximum richness objective and $150 budget
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 150) %>%
+     add_binary_decisions()
+
+# print problem
+print(p1)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (150)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# build another problem, and lock in the 3rd action using numeric inputs
+p2 <- p1 %>%
+      add_locked_in_constraints(c(3))
+
+# print problem
+print(p2)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (150)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <Locked in actions [1 locked units]>
+#>   solver:          default
+
+# build another problem, and lock in the actions using logical inputs from
+# the sim_actions table
+p3 <- p1 %>%
+      add_locked_in_constraints(sim_actions$locked_in)
+
+# print problem
+print(p3)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (150)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <Locked in actions [1 locked units]>
+#>   solver:          default
+
+# build another problem, and lock in the actions using the column name
+# "locked_in" in the sim_actions table
+# the sim_actions table
+p4 <- p1 %>%
+      add_locked_in_constraints("locked_in")
+
+# print problem
+print(p4)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (150)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <Locked in actions [1 locked units]>
+#>   solver:          default
+
+# \dontrun{
+# solve problems
+s1 <- solve(p1)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xf97d9094
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.680145e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.6801450    1.68015  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.68015 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.680145013696e+00, best bound 1.680145013696e+00, gap 0.0000%
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xaace6374
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 42 rows and 41 columns
+#> Presolve time: 0.00s
+#> Presolved: 5 rows, 6 columns, 10 nonzeros
+#> Variable types: 0 continuous, 6 integer (6 binary)
+#> 
+#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.44561 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.445609277954e+00, best bound 1.445609277954e+00, gap 0.0000%
+s3 <- solve(p3)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xaace6374
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 42 rows and 41 columns
+#> Presolve time: 0.00s
+#> Presolved: 5 rows, 6 columns, 10 nonzeros
+#> Variable types: 0 continuous, 6 integer (6 binary)
+#> 
+#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.44561 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.445609277954e+00, best bound 1.445609277954e+00, gap 0.0000%
+s4 <- solve(p4)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xaace6374
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 42 rows and 41 columns
+#> Presolve time: 0.00s
+#> Presolved: 5 rows, 6 columns, 10 nonzeros
+#> Variable types: 0 continuous, 6 integer (6 binary)
+#> 
+#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.44561 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.445609277954e+00, best bound 1.445609277954e+00, gap 0.0000%
+
+# print the actions selected for funding in each of the solutions
+print(s1[, sim_actions$name])
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         0         1         0         0         0               1
+print(s2[, sim_actions$name])
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         0         0         1         0         0               1
+print(s3[, sim_actions$name])
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         0         0         1         0         0               1
+print(s4[, sim_actions$name])
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         0         0         1         0         0               1
+# }
+
+
+
- - - - + diff --git a/docs/reference/add_locked_out_constraints.html b/docs/reference/add_locked_out_constraints.html index e8ab998..f7c889f 100644 --- a/docs/reference/add_locked_out_constraints.html +++ b/docs/reference/add_locked_out_constraints.html @@ -1,81 +1,15 @@ - - - - - - - -Add locked out constraints — add_locked_out_constraints • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add locked out constraints — add_locked_out_constraints • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add locked out constraints

- Source: R/add_locked_out_constraints.R + Source: R/add_locked_out_constraints.R
-

Add constraints to a project prioritization problem() to ensure +

Add constraints to a project prioritization problem() to ensure that specific actions are not prioritized for funding in the solution. For example, it may be desirable to lock out specific actions to examine their importance to the optimal funding scheme.

- 
add_locked_out_constraints(x, locked_out)
-
-# S4 method for ProjectProblem,numeric
-add_locked_out_constraints(x, locked_out)
-
-# S4 method for ProjectProblem,logical
-add_locked_out_constraints(x, locked_out)
-
-# S4 method for ProjectProblem,character
-add_locked_out_constraints(x, locked_out)
- -

Arguments

- - - - - - - - - - -
x

ProjectProblem object.

locked_out

Object that determines which planning units that should be -locked out. See the Details section for more information.

- - -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# update "locked_out" column to lock out action "F2_action"
-sim_actions$locked_out <- c(FALSE, TRUE, FALSE, FALSE, FALSE, FALSE)
-
-# print action data
-print(sim_actions)
-
#> # A tibble: 6 x 4
-#>   name             cost locked_in locked_out
-#>   <chr>           <dbl> <lgl>     <lgl>     
-#> 1 F1_action        94.4 FALSE     FALSE     
-#> 2 F2_action       101.  FALSE     TRUE      
-#> 3 F3_action       103.  TRUE      FALSE     
-#> 4 F4_action        99.2 FALSE     FALSE     
-#> 5 F5_action        99.9 FALSE     FALSE     
-#> 6 baseline_action   0   FALSE     FALSE     

-# build problem with maximum richness objective and $150 budget
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 150) %>%
-     add_binary_decisions()
-
-# print problem
-print(p1)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (150)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# build another problem, and lock out the second action using numeric inputs
-p2 <- p1 %>%
-      add_locked_out_constraints(c(2))
-
-# print problem
-print(p2)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (150)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <Manually locked actions [1 locked units]>
-#>   solver:          default

-# build another problem, and lock out the actions using logical inputs
-# (i.e. TRUE/FALSE values) from the sim_actions table
-p3 <- p1 %>%
-      add_locked_out_constraints(sim_actions$locked_out)
-
-# print problem
-print(p3)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (150)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <Manually locked actions [1 locked units]>
-#>   solver:          default

-# build another problem, and lock out the actions using the column name
-# "locked_out" in the sim_actions table
-# the sim_actions table
-p4 <- p1 %>%
-      add_locked_out_constraints("locked_out")
+    

+    
add_locked_out_constraints(x, locked_out)
+
+# S4 method for ProjectProblem,numeric
+add_locked_out_constraints(x, locked_out)
+
+# S4 method for ProjectProblem,logical
+add_locked_out_constraints(x, locked_out)
+
+# S4 method for ProjectProblem,character
+add_locked_out_constraints(x, locked_out)

+    

 
-# print problem
-print(p4)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (150)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <Manually locked actions [1 locked units]>
-#>   solver:          default

-# \dontrun{
-# solve problems
-s1 <- solve(p1)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0x57c178c1
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 1.680145e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       1.6801450    1.68015  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 1.68015 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 1.680145013696e+00, best bound 1.680145013696e+00, gap 0.0000%
s2 <- solve(p2)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xab53517c
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 22 rows and 19 columns
-#> Presolve time: 0.00s
-#> Presolved: 25 rows, 28 columns, 52 nonzeros
-#> Variable types: 0 continuous, 28 integer (28 binary)
-#> Presolved: 25 rows, 28 columns, 52 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 1.575441e+00, 9 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       1.5754408    1.57544  0.00%     -    0s
-#> 
-#> Explored 0 nodes (9 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 1.57544 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 1.575440809243e+00, best bound 1.575440809243e+00, gap 0.0000%
s3 <- solve(p3)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xab53517c
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 22 rows and 19 columns
-#> Presolve time: 0.00s
-#> Presolved: 25 rows, 28 columns, 52 nonzeros
-#> Variable types: 0 continuous, 28 integer (28 binary)
-#> Presolved: 25 rows, 28 columns, 52 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 1.575441e+00, 9 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       1.5754408    1.57544  0.00%     -    0s
-#> 
-#> Explored 0 nodes (9 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 1.57544 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 1.575440809243e+00, best bound 1.575440809243e+00, gap 0.0000%
s4 <- solve(p4)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xab53517c
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 22 rows and 19 columns
-#> Presolve time: 0.00s
-#> Presolved: 25 rows, 28 columns, 52 nonzeros
-#> Variable types: 0 continuous, 28 integer (28 binary)
-#> Presolved: 25 rows, 28 columns, 52 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 1.575441e+00, 9 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       1.5754408    1.57544  0.00%     -    0s
-#> 
-#> Explored 0 nodes (9 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 1.57544 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 1.575440809243e+00, best bound 1.575440809243e+00, gap 0.0000%

-# print the actions selected for funding in each of the solutions
-print(s1[, sim_actions$name])
-
#> # A tibble: 1 x 6
-#>   F1_action F2_action F3_action F4_action F5_action baseline_action
-#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
-#> 1         0         1         0         0         0               1
print(s2[, sim_actions$name])
-
#> # A tibble: 1 x 6
-#>   F1_action F2_action F3_action F4_action F5_action baseline_action
-#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
-#> 1         1         0         0         0         0               1
print(s3[, sim_actions$name])
-
#> # A tibble: 1 x 6
-#>   F1_action F2_action F3_action F4_action F5_action baseline_action
-#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
-#> 1         1         0         0         0         0               1
print(s4[, sim_actions$name])
-
#> # A tibble: 1 x 6
-#>   F1_action F2_action F3_action F4_action F5_action baseline_action
-#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
-#> 1         1         0         0         0         0               1
# }
-
+
+

Arguments

+
x
+

ProjectProblem object.

+ + +
locked_out
+

Object that determines which planning units that should be +locked out. See the Details section for more information.

+ +
+ +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# update "locked_out" column to lock out action "F2_action"
+sim_actions$locked_out <- c(FALSE, TRUE, FALSE, FALSE, FALSE, FALSE)
+
+# print action data
+print(sim_actions)
+#> # A tibble: 6 × 4
+#>   name             cost locked_in locked_out
+#>   <chr>           <dbl> <lgl>     <lgl>     
+#> 1 F1_action        94.4 FALSE     FALSE     
+#> 2 F2_action       101.  FALSE     TRUE      
+#> 3 F3_action       103.  TRUE      FALSE     
+#> 4 F4_action        99.2 FALSE     FALSE     
+#> 5 F5_action        99.9 FALSE     FALSE     
+#> 6 baseline_action   0   FALSE     FALSE     
+
+# build problem with maximum richness objective and $150 budget
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 150) %>%
+     add_binary_decisions()
+
+# print problem
+print(p1)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (150)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# build another problem, and lock out the second action using numeric inputs
+p2 <- p1 %>%
+      add_locked_out_constraints(c(2))
+
+# print problem
+print(p2)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (150)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <Manually locked actions [1 locked units]>
+#>   solver:          default
+
+# build another problem, and lock out the actions using logical inputs
+# (i.e. TRUE/FALSE values) from the sim_actions table
+p3 <- p1 %>%
+      add_locked_out_constraints(sim_actions$locked_out)
+
+# print problem
+print(p3)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (150)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <Manually locked actions [1 locked units]>
+#>   solver:          default
+
+# build another problem, and lock out the actions using the column name
+# "locked_out" in the sim_actions table
+# the sim_actions table
+p4 <- p1 %>%
+      add_locked_out_constraints("locked_out")
+
+# print problem
+print(p4)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (150)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <Manually locked actions [1 locked units]>
+#>   solver:          default
+
+# \dontrun{
+# solve problems
+s1 <- solve(p1)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xf97d9094
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.680145e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.6801450    1.68015  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.68015 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.680145013696e+00, best bound 1.680145013696e+00, gap 0.0000%
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x80197d20
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 22 rows and 19 columns
+#> Presolve time: 0.00s
+#> Presolved: 25 rows, 28 columns, 52 nonzeros
+#> Variable types: 0 continuous, 28 integer (28 binary)
+#> Root relaxation presolved: 25 rows, 28 columns, 52 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.575441e+00, 9 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.5754408    1.57544  0.00%     -    0s
+#> 
+#> Explored 1 nodes (9 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.57544 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.575440809243e+00, best bound 1.575440809243e+00, gap 0.0000%
+s3 <- solve(p3)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x80197d20
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 22 rows and 19 columns
+#> Presolve time: 0.00s
+#> Presolved: 25 rows, 28 columns, 52 nonzeros
+#> Variable types: 0 continuous, 28 integer (28 binary)
+#> Root relaxation presolved: 25 rows, 28 columns, 52 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.575441e+00, 9 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.5754408    1.57544  0.00%     -    0s
+#> 
+#> Explored 1 nodes (9 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.57544 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.575440809243e+00, best bound 1.575440809243e+00, gap 0.0000%
+s4 <- solve(p4)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x80197d20
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 22 rows and 19 columns
+#> Presolve time: 0.00s
+#> Presolved: 25 rows, 28 columns, 52 nonzeros
+#> Variable types: 0 continuous, 28 integer (28 binary)
+#> Root relaxation presolved: 25 rows, 28 columns, 52 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.575441e+00, 9 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.5754408    1.57544  0.00%     -    0s
+#> 
+#> Explored 1 nodes (9 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.57544 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.575440809243e+00, best bound 1.575440809243e+00, gap 0.0000%
+
+# print the actions selected for funding in each of the solutions
+print(s1[, sim_actions$name])
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         0         1         0         0         0               1
+print(s2[, sim_actions$name])
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         1         0         0         0         0               1
+print(s3[, sim_actions$name])
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         1         0         0         0         0               1
+print(s4[, sim_actions$name])
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         1         0         0         0         0               1
+# }
+
+
+
-
- - - + diff --git a/docs/reference/add_lpsolveapi_solver-1.png b/docs/reference/add_lpsolveapi_solver-1.png index 89a16f5..6c3a587 100644 Binary files a/docs/reference/add_lpsolveapi_solver-1.png and b/docs/reference/add_lpsolveapi_solver-1.png differ diff --git a/docs/reference/add_lpsolveapi_solver.html b/docs/reference/add_lpsolveapi_solver.html index c3b51f1..c983acd 100644 --- a/docs/reference/add_lpsolveapi_solver.html +++ b/docs/reference/add_lpsolveapi_solver.html @@ -1,81 +1,15 @@ - - - - - - - -Add a lp_solve solver with lpSolveAPI — add_lpsolveapi_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add a lp_solve solver with lpSolveAPI — add_lpsolveapi_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add a lp_solve solver with lpSolveAPI

- Source: R/add_lpsolveapi_solver.R + Source: R/add_lpsolveapi_solver.R

Specify that the lp_solve software should be used to solve a -project prioritization problem() using the lpSolveAPI +project prioritization problem() using the lpSolveAPI package. This function can also be used to customize the behavior of the solver. It requires the lpSolveAPI package.

- 
add_lpsolveapi_solver(x, gap = 0, presolve = FALSE, verbose = TRUE)
+
+ 
add_lpsolveapi_solver(x, gap = 0, presolve = FALSE, verbose = TRUE)
+
+ +
+

Arguments

+
x
+

ProjectProblem object.

+ -

Arguments

- - - - - - - - - - - - - - - - - - -
x

ProjectProblem object.

gap

numeric gap to optimality. This gap is relative +

gap
+

numeric gap to optimality. This gap is relative and expresses the acceptable deviance from the optimal objective. For example, a value of 0.01 will result in the solver stopping when it has found a solution within 1% of optimality. Additionally, a value of 0 will result in the solver stopping when it has found an optimal solution. -The default value is 0.1 (i.e. 10% from optimality).

presolve

logical indicating if attempts to should be made +The default value is 0.1 (i.e. 10% from optimality).

+ + +
presolve
+

logical indicating if attempts to should be made to simplify the optimization problem (TRUE) or not (FALSE). -Defaults to TRUE.

verbose

logical should information be printed while solving -optimization problems?

+Defaults to TRUE.

-

Value

-

ProjectProblem object with the solver added -to it.

-

Details

+
verbose
+

logical should information be printed while solving +optimization problems?

-

lp_solve is an +

+
+

Value

+ + +

ProjectProblem object with the solver added +to it.

+
+
+

Details

+

lp_solve is an open-source integer programming solver. Although this solver is the slowest currently supported solver, it is also the only exact algorithm solver that can be installed on all @@ -181,108 +110,112 @@

Details users can try solving small project prioritization problems, without needing to install additional software. When solve moderate or large project prioritization problems, consider using -add_gurobi_solver().

-

See also

- -

solvers.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with lpSolveAPI solver
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions() %>%
-     add_lpsolveapi_solver()
+add_gurobi_solver().

+    

+    

+    
See also

+    
solvers.

+    

 
-# print problem
-print(p)
-
#> Project Prioritization Problem -#> actions F1_action, F2_action, F3_action, ... (6 actions) -#> projects F1_project, F2_project, F3_project, ... (6 projects) -#> features F1, F2, F3, ... (5 features) -#> action costs: min: 0, max: 103.22583 -#> project success: min: 0.81379, max: 1 -#> objective: Maximum richness objective [budget (200)] -#> targets: none -#> weights: default -#> decisions Binary decision -#> constraints: <none> -#> solver: lpSolveAPI [gap (0), presolve (0), verbose (1)]
-# solve problem -s <- solve(p) -
#> -#> Model name: 'project prioritization problem' - run #1 -#> Objective: Maximize(R0) -#> -#> SUBMITTED -#> Model size: 47 constraints, 47 variables, 102 non-zeros. -#> Sets: 0 GUB, 0 SOS. -#> -#> Using DUAL simplex for phase 1 and PRIMAL simplex for phase 2. -#> The primal and dual simplex pricing strategy set to 'Devex'. -#> -#> -#> Relaxed solution 2.21077983146 after 34 iter is B&B base. -#> -#> Feasible solution 1.91490153549 after 43 iter, 8 nodes (gap 9.2%) -#> Improved solution 2.0146497578 after 47 iter, 11 nodes (gap 6.1%) -#> Improved solution 2.19038073724 after 59 iter, 20 nodes (gap 0.6%) -#> -#> Optimal solution 2.19038073724 after 59 iter, 20 nodes (gap 0.6%). -#> -#> Excellent numeric accuracy ||*|| = 1.11022e-16 -#> -#> MEMO: lp_solve version 5.5.2.0 for 64 bit OS, with 64 bit LPSREAL variables. -#> In the total iteration count 59, 16 (27.1%) were bound flips. -#> There were 11 refactorizations, 0 triggered by time and 1 by density. -#> ... on average 3.9 major pivots per refactorization. -#> The largest [LUSOL v2.2.1.0] fact(B) had 104 NZ entries, 1.0x largest basis. -#> The maximum B&B level was 6, 0.1x MIP order, 4 at the optimal solution. -#> The constraint matrix inf-norm is 103.226, with a dynamic range of 1193.9. -#> Time to load data was 0.000 seconds, presolve used 0.000 seconds, -#> ... 0.000 seconds in simplex solver, in total 0.000 seconds.
-# print solution -print(s) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 optima… 2.19 195. 1 1 0 0 0 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solution -plot(p, s) -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with lpSolveAPI solver
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions() %>%
+     add_lpsolveapi_solver()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          lpSolveAPI [gap (0), presolve (0), verbose (1)]
+
+# solve problem
+s <- solve(p)
+#> 
+#> Model name:  'project prioritization problem' - run #1    
+#> Objective:   Maximize(R0)
+#>  
+#> SUBMITTED
+#> Model size:       47 constraints,      47 variables,          102 non-zeros.
+#> Sets:                                   0 GUB,                  0 SOS.
+#>  
+#> Using DUAL simplex for phase 1 and PRIMAL simplex for phase 2.
+#> The primal and dual simplex pricing strategy set to 'Devex'.
+#>  
+#> 
+#> Relaxed solution       2.21077983146 after         34 iter is B&B base.
+#>  
+#> Feasible solution      1.91490153549 after         43 iter,         8 nodes (gap 9.2%)
+#> Improved solution       2.0146497578 after         47 iter,        11 nodes (gap 6.1%)
+#> Improved solution      2.19038073724 after         59 iter,        20 nodes (gap 0.6%)
+#>  
+#> Optimal solution       2.19038073724 after         59 iter,        20 nodes (gap 0.6%).
+#> 
+#> Excellent numeric accuracy ||*|| = 1.11022e-16
+#> 
+#>  MEMO: lp_solve version 5.5.2.0 for 64 bit OS, with 64 bit LPSREAL variables.
+#>       In the total iteration count 59, 16 (27.1%) were bound flips.
+#>       There were 11 refactorizations, 0 triggered by time and 1 by density.
+#>        ... on average 3.9 major pivots per refactorization.
+#>       The largest [LUSOL v2.2.1.0] fact(B) had 104 NZ entries, 1.0x largest basis.
+#>       The maximum B&B level was 6, 0.1x MIP order, 4 at the optimal solution.
+#>       The constraint matrix inf-norm is 103.226, with a dynamic range of 1193.9.
+#>       Time to load data was 0.000 seconds, presolve used 0.000 seconds,
+#>        ... 0.000 seconds in simplex solver, in total 0.000 seconds.
+
+# print solution
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status      obj  cost F1_ac…¹ F2_ac…² F3_ac…³ F4_ac…⁴ F5_ac…⁵ basel…⁶
+#>      <int> <chr>     <dbl> <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 optimal …  2.19  195.       1       1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F1_action, ²​F2_action, ³​F3_action,
+#> #   ⁴​F4_action, ⁵​F5_action, ⁶​baseline_action
+
+# plot solution
+plot(p, s)
+
+
+
+
-
- - - + diff --git a/docs/reference/add_lsymphony_solver-1.png b/docs/reference/add_lsymphony_solver-1.png index 89a16f5..6c3a587 100644 Binary files a/docs/reference/add_lsymphony_solver-1.png and b/docs/reference/add_lsymphony_solver-1.png differ diff --git a/docs/reference/add_lsymphony_solver.html b/docs/reference/add_lsymphony_solver.html index 5e6ff3a..df9e092 100644 --- a/docs/reference/add_lsymphony_solver.html +++ b/docs/reference/add_lsymphony_solver.html @@ -1,81 +1,15 @@ - - - - - - - -Add a SYMPHONY solver with lpsymphony — add_lsymphony_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add a SYMPHONY solver with lpsymphony — add_lsymphony_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add a SYMPHONY solver with lpsymphony

- Source: R/add_lpsymphony_solver.R + Source: R/add_lpsymphony_solver.R

Specify that the SYMPHONY software should be used to solve a -project prioritization problem() using the lpsymphony +project prioritization problem() using the lpsymphony package. This function can also be used to customize the behavior of the solver. It requires the lpsymphony package.

- 
add_lpsymphony_solver(
-  x,
-  gap = 0,
-  time_limit = .Machine$integer.max,
-  first_feasible = FALSE,
-  verbose = TRUE
-)
+
+ 
add_lpsymphony_solver(
+  x,
+  gap = 0,
+  time_limit = .Machine$integer.max,
+  first_feasible = FALSE,
+  verbose = TRUE
+)
+
+ +
+

Arguments

+
x
+

ProjectProblem object.

+ -

Arguments

- - - - - - - - - - - - - - - - - - - - - - -
x

ProjectProblem object.

gap

numeric gap to optimality. This gap is relative +

gap
+

numeric gap to optimality. This gap is relative and expresses the acceptable deviance from the optimal objective. For example, a value of 0.01 will result in the solver stopping when it has found a solution within 1% of optimality. Additionally, a value of 0 will result in the solver stopping when it has found an optimal solution. -The default value is 0.1 (i.e. 10% from optimality).

time_limit

numeric time limit in seconds to run the optimizer. +The default value is 0.1 (i.e. 10% from optimality).

+ + +
time_limit
+

numeric time limit in seconds to run the optimizer. The solver will return the current best solution when this time limit is -exceeded.

first_feasible

logical should the first feasible solution be +exceeded.

+ + +
first_feasible
+

logical should the first feasible solution be be returned? If first_feasible is set to TRUE, the solver will return the first solution it encounters that meets all the constraints, regardless of solution quality. Note that the first feasible solution is not an arbitrary solution, rather it is derived from the relaxed solution, and is therefore often reasonably close to optimality. -Defaults to FALSE.

verbose

logical should information be printed while solving -optimization problems?

+Defaults to FALSE.

-

Value

-

ProjectProblem object with the solver added -to it.

-

Details

+
verbose
+

logical should information be printed while solving +optimization problems?

-

SYMPHONY is an +

+
+

Value

+ + +

ProjectProblem object with the solver added +to it.

+
+
+

Details

+

SYMPHONY is an open-source integer programming solver that is part of the Computational Infrastructure for Operations Research (COIN-OR) project, an initiative to promote development of open-source tools for operations research (a field that includes linear programming). The lpsymphony package is distributed through -Bioconductor. +Bioconductor. This functionality is provided because the lpsymphony package may be easier to install to install on Windows and Mac OSX systems than the Rsymphony package.

-

See also

- -

solvers.

- -

Examples

- 
# \dontrun{
-# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with lpsymphony solver
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions() %>%
-     add_lpsymphony_solver()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          Lpsymphony [first_feasible (0), gap (0), time_limit (2147483647), verbose (1)]

-# solve problem
-s <- solve(p)
+    

+    

+    
See also

+    
solvers.

+    

 
-# print solution
-print(s)
-
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 TM_OPT… 2.19 195. 1 1 0 0 0 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solution -plot(p, s) -
# } -
+
+

Examples

+ 
# \dontrun{
+# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with lpsymphony solver
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions() %>%
+     add_lpsymphony_solver()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Lpsymphony [first_feasible (0), gap (0), time_limit (2147483647), verbose (1)]
+
+# solve problem
+s <- solve(p)
+
+# print solution
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status      obj  cost F1_ac…¹ F2_ac…² F3_ac…³ F4_ac…⁴ F5_ac…⁵ basel…⁶
+#>      <int> <chr>     <dbl> <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 TM_OPTIM…  2.19  195.       1       1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F1_action, ²​F2_action, ³​F3_action,
+#> #   ⁴​F4_action, ⁵​F5_action, ⁶​baseline_action
+
+# plot solution
+plot(p, s)
+
+# }
+
+
+
-
- - - + diff --git a/docs/reference/add_manual_locked_constraints.html b/docs/reference/add_manual_locked_constraints.html index e4c680a..f96d012 100644 --- a/docs/reference/add_manual_locked_constraints.html +++ b/docs/reference/add_manual_locked_constraints.html @@ -1,81 +1,15 @@ - - - - - - - -Add manually specified locked constraints — add_manual_locked_constraints • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add manually specified locked constraints — add_manual_locked_constraints • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add manually specified locked constraints

- Source: R/add_manual_locked_constraints.R + Source: R/add_manual_locked_constraints.R
-

Add constraints to a project prioritization problem() to ensure +

Add constraints to a project prioritization problem() to ensure that solutions fund (or do not fund) specific actions. This function offers -more fine-grained control than the add_locked_in_constraints() -and add_locked_out_constraints() functions.

+more fine-grained control than the add_locked_in_constraints() +and add_locked_out_constraints() functions.

- 
add_manual_locked_constraints(x, locked)
+    

+    
add_manual_locked_constraints(x, locked)
+
+# S4 method for ProjectProblem,data.frame
+add_manual_locked_constraints(x, locked)
+
+# S4 method for ProjectProblem,tbl_df
+add_manual_locked_constraints(x, locked)

+    

 
-# S4 method for ProjectProblem,data.frame
-add_manual_locked_constraints(x, locked)
+    

+    
Arguments

+    
x

+
ProjectProblem object.

 
-# S4 method for ProjectProblem,tbl_df
-add_manual_locked_constraints(x, locked)
-

Arguments

- - - - - - - - - - -
x

ProjectProblem object.

locked

data.frame or tibble::tibble() object. See -the Details section for more information.

+
locked
+

data.frame or tibble::tibble() object. See +the Details section for more information.

-

Value

+
+
+

Value

+ -

ProjectProblem object with the constraints +

ProjectProblem object with the constraints added to it.

-

Details

- +
+
+

Details

The argument to locked must contain the following fields (columns):

-
+
"action"
+

character action name.

-
"action"

character action name.

-
"status"

numeric values indicating if actions should +

"status"
+

numeric values indicating if actions should be funded (with a value of 1) or not (with a value of zero).

-
- -

See also

- -

constraints.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-
-# create data frame with locked statuses
-status <- data.frame(action = sim_actions$name[1:2],
-                     status = c(0, 1))
 
-# print locked statuses
-print(status)
-
#>      action status
-#> 1 F1_action      0
-#> 2 F2_action      1

-# build problem with minimum set objective and targets that require each
-# feature to have a 30% chance of persisting into the future
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_max_richness_objective(budget = 500) %>%
-      add_manual_locked_constraints(status) %>%
-      add_binary_decisions()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (500)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <Manually locked actions [2 locked units]>
-#>   solver:          default

-# \dontrun{
-# solve problem
-s <- solve(p)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0x0d97b4b1
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 5e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 24 rows and 20 columns
-#> Presolve time: 0.00s
-#> Presolved: 23 rows, 27 columns, 46 nonzeros
-#> Variable types: 0 continuous, 27 integer (27 binary)
-#> Presolved: 23 rows, 27 columns, 46 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 2.910246e+00, 7 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       2.9102457    2.91025  0.00%     -    0s
-#> 
-#> Explored 0 nodes (7 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 2.91025 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 2.910245655750e+00, best bound 2.910245655750e+00, gap 0.0000%

-# print solution
-print(s)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL  2.91  403.         0         1         1         1         1
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
# }
+
+
+

See also

+

constraints.

+
-
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+
+# create data frame with locked statuses
+status <- data.frame(action = sim_actions$name[1:2],
+                     status = c(0, 1))
+
+# print locked statuses
+print(status)
+#>      action status
+#> 1 F1_action      0
+#> 2 F2_action      1
+
+# build problem with minimum set objective and targets that require each
+# feature to have a 30% chance of persisting into the future
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_max_richness_objective(budget = 500) %>%
+      add_manual_locked_constraints(status) %>%
+      add_binary_decisions()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (500)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <Manually locked actions [2 locked units]>
+#>   solver:          default
+
+# \dontrun{
+# solve problem
+s <- solve(p)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x54473ab0
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 5e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 24 rows and 20 columns
+#> Presolve time: 0.00s
+#> Presolved: 23 rows, 27 columns, 46 nonzeros
+#> Variable types: 0 continuous, 27 integer (27 binary)
+#> Found heuristic solution: objective 2.0605492
+#> Root relaxation presolved: 23 rows, 27 columns, 46 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.910246e+00, 7 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       2.9102457    2.91025  0.00%     -    0s
+#> 
+#> Explored 1 nodes (7 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.91025 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.910245655750e+00, best bound 2.910245655750e+00, gap 0.0000%
+
+# print solution
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  2.91  403.         0       1       1       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+# }
+
+
+
+
- - - - + diff --git a/docs/reference/add_manual_targets.html b/docs/reference/add_manual_targets.html index c970db2..3e32370 100644 --- a/docs/reference/add_manual_targets.html +++ b/docs/reference/add_manual_targets.html @@ -1,84 +1,18 @@ - - - - - - - -Add manual targets — add_manual_targets • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add manual targets — add_manual_targets • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add manual targets

- Source: R/add_manual_targets.R + Source: R/add_manual_targets.R
-

Set targets for a project prioritization problem() by manually +

Set targets for a project prioritization problem() by manually specifying all the required information for each target. This function is useful because it can be used to customize all aspects of a target. For most cases, targets can be specified using the -add_absolute_targets() and add_relative_targets() +add_absolute_targets() and add_relative_targets() functions. However, this function can be used to mix absolute and relative targets for different features.

- 
add_manual_targets(x, targets)
+    

+    
add_manual_targets(x, targets)
+
+# S4 method for ProjectProblem,data.frame
+add_manual_targets(x, targets)
+
+# S4 method for ProjectProblem,tbl_df
+add_manual_targets(x, targets)

+    

 
-# S4 method for ProjectProblem,data.frame
-add_manual_targets(x, targets)
+    

+    
Arguments

+    
x

+
ProjectProblem object.

 
-# S4 method for ProjectProblem,tbl_df
-add_manual_targets(x, targets)
-

Arguments

- - - - - - - - - - -
x

ProjectProblem object.

targets

data.frame or tibble::tibble() object. See -the Details section for more information.

+
targets
+

data.frame or tibble::tibble() object. See +the Details section for more information.

-

Value

+
+
+

Value

+ -

ProjectProblem object with the targets added +

ProjectProblem object with the targets added to it.

-

Details

- +
+
+

Details

Targets are used to specify the minimum probability of persistence for each feature in solutions. For minimum set objectives -(i.e. add_min_set_objective(), these targets +(i.e. add_min_set_objective(), these targets specify the minimum probability of persistence required for each species in the solution. And for budget constrained objectives that use targets -(i.e. add_max_targets_met_objective()), these targets +(i.e. add_max_targets_met_objective()), these targets specify the minimum threshold probability of persistence that needs to be achieved to count the benefits for conserving these species. Please note that attempting to solve problems with objectives that require targets without specifying targets will throw an error.

The targets argument should contain the following columns:

-
- -
"feature"

character name of features in argument +

"feature"
+

character name of features in argument to x.

-
"type"

character describing the type of target. + +

"type"
+

character describing the type of target. Acceptable values include "absolute" and "relative". -These values correspond to add_absolute_targets(), -and add_relative_targets() respectively.

+These values correspond to add_absolute_targets(), +and add_relative_targets() respectively.

-
"sense"

character sense of the target. The + +

"sense"
+

character sense of the target. The only acceptable value currently supported is: ">=". This field (column) is optional and if it is missing then target senses will default to ">=" values.

-
"target"

numeric target threshold.

- - -
-

See also

+
"target"
+

numeric target threshold.

-

targets.

-

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
 
+

+    

+    
See also

+    
targets.

+    

 
-# create data frame with targets
-targets <- data.frame(feature = sim_features$name,
-                      type = "absolute",
-                      target = 0.1)
-
-# print targets
-print(targets)
-
#> feature type target -#> 1 F1 absolute 0.1 -#> 2 F2 absolute 0.1 -#> 3 F3 absolute 0.1 -#> 4 F4 absolute 0.1 -#> 5 F5 absolute 0.1
-# build problem with minimum set objective and targets that require each -# feature to have a 30% chance of persisting into the future -p <- problem(sim_projects, sim_actions, sim_features, - "name", "success", "name", "cost", "name") %>% - add_min_set_objective() %>% - add_manual_targets(targets) %>% - add_binary_decisions() - -# print problem -print(p) -
#> Project Prioritization Problem -#> actions F1_action, F2_action, F3_action, ... (6 actions) -#> projects F1_project, F2_project, F3_project, ... (6 projects) -#> features F1, F2, F3, ... (5 features) -#> action costs: min: 0, max: 103.22583 -#> project success: min: 0.81379, max: 1 -#> objective: Minimum set objective -#> targets: Absolute targets [targets (min: 0.1, max: 0.1)] -#> weights: default -#> decisions Binary decision -#> constraints: <none> -#> solver: default
-# \dontrun{ -# solve problem -s <- solve(p) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 46 rows, 42 columns and 92 nonzeros -#> Model fingerprint: 0x5a3c452c -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+00] -#> Objective range [9e+01, 1e+02] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e-01, 1e+00] -#> Found heuristic solution: objective 304.1251127 -#> Presolve removed 17 rows and 8 columns -#> Presolve time: 0.00s -#> Presolved: 29 rows, 34 columns, 58 nonzeros -#> Variable types: 0 continuous, 34 integer (34 binary) -#> Presolved: 29 rows, 34 columns, 58 nonzeros -#> -#> -#> Root relaxation: objective 1.032258e+02, 6 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 103.2258290 103.22583 0.00% - 0s -#> -#> Explored 0 nodes (6 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 103.226 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.032258290263e+02, best bound 1.032258290263e+02, gap 0.0000%
-# print solution -print(s) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 103. 103. 0 0 1 0 0 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+
+# create data frame with targets
+targets <- data.frame(feature = sim_features$name,
+                      type = "absolute",
+                      target = 0.1)
+
+# print targets
+print(targets)
+#>   feature     type target
+#> 1      F1 absolute    0.1
+#> 2      F2 absolute    0.1
+#> 3      F3 absolute    0.1
+#> 4      F4 absolute    0.1
+#> 5      F5 absolute    0.1
+
+# build problem with minimum set objective and targets that require each
+# feature to have a 30% chance of persisting into the future
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_min_set_objective() %>%
+      add_manual_targets(targets) %>%
+      add_binary_decisions()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Minimum set objective 
+#>   targets:         Absolute targets [targets (min: 0.1, max: 0.1)]
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# \dontrun{
+# solve problem
+s <- solve(p)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 46 rows, 42 columns and 92 nonzeros
+#> Model fingerprint: 0x5a3c452c
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+00]
+#>   Objective range  [9e+01, 1e+02]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e-01, 1e+00]
+#> Found heuristic solution: objective 304.1251127
+#> Presolve removed 17 rows and 8 columns
+#> Presolve time: 0.00s
+#> Presolved: 29 rows, 34 columns, 58 nonzeros
+#> Variable types: 0 continuous, 34 integer (34 binary)
+#> Root relaxation presolved: 29 rows, 34 columns, 58 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.032258e+02, 6 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0     103.2258290  103.22583  0.00%     -    0s
+#> 
+#> Explored 1 nodes (6 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 103.226 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.032258290263e+02, best bound 1.032258290263e+02, gap 0.0000%
+
+# print solution
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  103.  103.         0       0       1       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+# }
+
+
+
- - - - + diff --git a/docs/reference/add_max_phylo_div_objective-2.png b/docs/reference/add_max_phylo_div_objective-2.png index c4938ab..e222fa2 100644 Binary files a/docs/reference/add_max_phylo_div_objective-2.png and b/docs/reference/add_max_phylo_div_objective-2.png differ diff --git a/docs/reference/add_max_phylo_div_objective-3.png b/docs/reference/add_max_phylo_div_objective-3.png index 1c9de68..ade2b29 100644 Binary files a/docs/reference/add_max_phylo_div_objective-3.png and b/docs/reference/add_max_phylo_div_objective-3.png differ diff --git a/docs/reference/add_max_phylo_div_objective.html b/docs/reference/add_max_phylo_div_objective.html index 6529e3d..58e3988 100644 --- a/docs/reference/add_max_phylo_div_objective.html +++ b/docs/reference/add_max_phylo_div_objective.html @@ -1,81 +1,15 @@ - - - - - - - -Add maximum phylogenetic diversity objective — add_max_phylo_div_objective • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add maximum phylogenetic diversity objective — add_max_phylo_div_objective • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add maximum phylogenetic diversity objective

- Source: R/add_max_phylo_div_objective.R + Source: R/add_max_phylo_div_objective.R
-

Set the objective of a project prioritization problem() to +

Set the objective of a project prioritization problem() to maximize the phylogenetic diversity that is expected to persist into the future, whilst ensuring that the cost of the solution is within a pre-specified budget (Bennett et al. 2014, Faith 2008).

- 
add_max_phylo_div_objective(x, budget, tree)
+
+ 
add_max_phylo_div_objective(x, budget, tree)
+
+ +
+

Arguments

+
x
+

ProjectProblem object.

+ -

Arguments

- - - - - - - - - - - - - - -
x

ProjectProblem object.

budget

numeric budget for funding actions.

tree

ape::phylo() phylogenetic tree describing the +

budget
+

numeric budget for funding actions.

+ + +
tree
+

ape::phylo() phylogenetic tree describing the evolutionary relationships between the features. Note that the argument to tree must contain every feature, and only the -features, present in the argument to x.

+features, present in the argument to x.

-

Value

+
+
+

Value

+ -

ProjectProblem object with the objective +

ProjectProblem object with the objective added to it.

-

Details

- +
+
+

Details

A problem objective is used to specify the overall goal of the project prioritization problem. Here, the maximum phylogenetic diversity objective seeks to find the set @@ -273,8 +202,9 @@

Details extinction probabilities (eqn 1c) with the sum of the log feature extinction probabilities and using piecewise linear approximations (described in Hillier & Price 2005 pp. 390--392) to approximate the exponent of this term.

-

References

- +
+
+

References

Bennett JR, Elliott G, Mellish B, Joseph LN, Tulloch AI, Probert WJ, Di Fonzo MMI, Monks JM, Possingham HP & Maloney R (2014) Balancing phylogenetic diversity @@ -287,159 +217,172 @@

R 22: 1461--1470.

Hillier FS & Price CC (2005) International series in operations research & management science. Springer.

-

See also

- -

objectives.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions, sim_tree)
-
-# plot tree
-plot(sim_tree)
-

-# build problem with maximum phylogenetic diversity objective and $200 budget
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_max_phylo_div_objective(budget = 200, tree = sim_tree) %>%
-      add_binary_decisions()
-
-# \dontrun{
-# solve problem
-s1 <- solve(p1)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 50 rows, 50 columns and 123 nonzeros
-#> Model fingerprint: 0x4b572399
-#> Model has 3 piecewise-linear objective terms
-#> Variable types: 3 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [2e-01, 2e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.7230501
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 37 rows, 2547 columns, 2589 nonzeros
-#> Variable types: 2512 continuous, 35 integer (35 binary)
-#> Presolve removed 3 rows and 3 columns
-#> Presolved: 34 rows, 2544 columns, 2583 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 2.638346e+00, 20 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#>      0     0    2.63835    0    6    1.72305    2.63835  53.1%     -    0s
-#> H    0     0                       1.9924877    2.63835  32.4%     -    0s
-#>      0     2    2.63696    0    6    1.99249    2.63696  32.3%     -    0s
-#> *    1     3               1       2.1724148    2.59317  19.4%   3.0    0s
-#> *    5     3               2       2.5726722    2.57267  0.00%   3.6    0s
-#> 
-#> Explored 6 nodes (38 simplex iterations) in 0.01 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 2.57267 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 2.572672188340e+00, best bound 2.572672188340e+00, gap 0.0000%

-# print solution
-print(s1)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL  2.57  194.         1         0         0         0         1
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>

-# plot solution
-plot(p1, s1)
-

-# build another problem that includes feature weights
-p2 <- p1 %>%
-      add_feature_weights("weight")
+    

+    

+    
See also

+    
objectives.

+    

 
-# solve problem with feature weights
-s2 <- solve(p2)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 50 rows, 50 columns and 123 nonzeros -#> Model fingerprint: 0xd55461e2 -#> Model has 3 piecewise-linear objective terms -#> Variable types: 3 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [4e-01, 3e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 2.3885146 -#> Presolve removed 16 rows and 12 columns -#> Presolve time: 0.00s -#> Presolved: 37 rows, 2547 columns, 2589 nonzeros -#> Variable types: 2512 continuous, 35 integer (35 binary) -#> Presolve removed 3 rows and 3 columns -#> Presolved: 34 rows, 2544 columns, 2583 nonzeros -#> -#> -#> Root relaxation: objective 4.074411e+00, 20 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> 0 0 4.07441 0 6 2.38851 4.07441 70.6% - 0s -#> H 0 0 4.0567449 4.07441 0.44% - 0s -#> -#> Explored 0 nodes (20 simplex iterations) in 0.02 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 4.05674 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 4.056744940702e+00, best bound 4.056744940702e+00, gap 0.0000%
-# print solution based on feature weights -print(s2) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 4.06 199. 0 0 0 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solution based on feature weights -plot(p2, s2) -
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions, sim_tree)
+
+# plot tree
+plot(sim_tree)
+
+
+# build problem with maximum phylogenetic diversity objective and $200 budget
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_max_phylo_div_objective(budget = 200, tree = sim_tree) %>%
+      add_binary_decisions()
+
+# \dontrun{
+# solve problem
+s1 <- solve(p1)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 50 rows, 50 columns and 123 nonzeros
+#> Model fingerprint: 0x3d5512d7
+#> Model has 3 piecewise-linear objective terms
+#> Variable types: 3 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [2e-01, 2e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#>   PWLObj x range   [6e-01, 5e+00]
+#>   PWLObj obj range [5e-03, 1e+00]
+#> Found heuristic solution: objective 1.7230501
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 37 rows, 2547 columns, 2589 nonzeros
+#> Variable types: 2512 continuous, 35 integer (35 binary)
+#> Root relaxation presolve removed 3 rows and 3 columns
+#> Root relaxation presolved: 34 rows, 2544 columns, 2583 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.638346e+00, 24 iterations, 0.01 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#>      0     0    2.63835    0    6    1.72305    2.63835  53.1%     -    0s
+#> H    0     0                       1.9924877    2.63835  32.4%     -    0s
+#> H    0     0                       2.1724148    2.63835  21.4%     -    0s
+#> H    0     0                       2.5726722    2.63835  2.55%     -    0s
+#>      0     2    2.63696    0    6    2.57267    2.63696  2.50%     -    0s
+#> 
+#> Explored 3 nodes (28 simplex iterations) in 0.06 seconds (0.02 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.57267 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.572672188340e+00, best bound 2.572672188340e+00, gap 0.0000%
+
+# print solution
+print(s1)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  2.57  194.         1       0       0       0       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution
+plot(p1, s1)
+
+
+# build another problem that includes feature weights
+p2 <- p1 %>%
+      add_feature_weights("weight")
+
+# solve problem with feature weights
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 50 rows, 50 columns and 123 nonzeros
+#> Model fingerprint: 0x5feb5267
+#> Model has 3 piecewise-linear objective terms
+#> Variable types: 3 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [4e-01, 3e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#>   PWLObj x range   [6e-01, 5e+00]
+#>   PWLObj obj range [5e-03, 1e+00]
+#> Found heuristic solution: objective 2.3885146
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 37 rows, 2547 columns, 2589 nonzeros
+#> Variable types: 2512 continuous, 35 integer (35 binary)
+#> Root relaxation presolve removed 3 rows and 3 columns
+#> Root relaxation presolved: 34 rows, 2544 columns, 2583 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 4.074411e+00, 25 iterations, 0.01 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#>      0     0    4.07441    0    6    2.38851    4.07441  70.6%     -    0s
+#> H    0     0                       4.0567449    4.07441  0.44%     -    0s
+#> 
+#> Explored 1 nodes (25 simplex iterations) in 0.07 seconds (0.03 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 4.05674 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 4.056744940702e+00, best bound 4.056744940718e+00, gap 0.0000%
+
+# print solution based on feature weights
+print(s2)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  4.06  199.         0       0       0       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution based on feature weights
+plot(p2, s2)
+
+# }
+
+
+
-
- - - + diff --git a/docs/reference/add_max_richness_objective-1.png b/docs/reference/add_max_richness_objective-1.png index 89a16f5..6c3a587 100644 Binary files a/docs/reference/add_max_richness_objective-1.png and b/docs/reference/add_max_richness_objective-1.png differ diff --git a/docs/reference/add_max_richness_objective-2.png b/docs/reference/add_max_richness_objective-2.png index b6aaf49..4c14674 100644 Binary files a/docs/reference/add_max_richness_objective-2.png and b/docs/reference/add_max_richness_objective-2.png differ diff --git a/docs/reference/add_max_richness_objective.html b/docs/reference/add_max_richness_objective.html index 48c74c4..bb47dad 100644 --- a/docs/reference/add_max_richness_objective.html +++ b/docs/reference/add_max_richness_objective.html @@ -1,84 +1,18 @@ - - - - - - - -Add maximum richness objective — add_max_richness_objective • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add maximum richness objective — add_max_richness_objective • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add maximum richness objective

- Source: R/add_max_richness_objective.R + Source: R/add_max_richness_objective.R
-

Set the objective of a project prioritization problem() to +

Set the objective of a project prioritization problem() to maximize the total number of features that are expected to persist, whilst ensuring that the cost of the solution is within a pre-specified budget (Joseph, Maloney & Possingham 2009). This objective is conceptually similar to maximizing species richness in a study area. Furthermore, weights can also be used to specify the relative importance of conserving specific -features (see add_feature_weights()).

+features (see add_feature_weights()).

- 
add_max_richness_objective(x, budget)
+
+ 
add_max_richness_objective(x, budget)
+
-

Arguments

- - - - - - - - - - -
x

ProjectProblem object.

budget

numeric budget for funding actions.

+
+

Arguments

+
x
+

ProjectProblem object.

-

Value

-

ProjectProblem object with the objective -added to it.

-

Details

+
budget
+

numeric budget for funding actions.

+ +
+
+

Value

+ +

ProjectProblem object with the objective +added to it.

+
+
+

Details

A problem objective is used to specify the overall goal of the project prioritization problem. Here, the maximum richness objective seeks to find the set of actions that @@ -242,154 +171,163 @@

Details (\(E_f\)) are bounded between zero and one. Constraints (eqns 1h) ensure that the action funding (\(X_i\)), project funding (\(Y_j\)), and project allocation (\(Z_{fj}\)) variables are binary.

-

References

- +
+
+

References

Joseph LN, Maloney RF & Possingham HP (2009) Optimal allocation of resources among threatened species: A project prioritization protocol. Conservation Biology, 23, 328--338.

-

See also

- -

objectives.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with maximum richness objective and $300 budget
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions()
-
-# \dontrun{
-# solve problem
-s1 <- solve(p1)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xab0d0209
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 2.19038 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%

-# print solution
-print(s1)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL  2.19  195.         1         1         0         0         0
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>

-# plot solution
-plot(p1, s1)
-
# }
-
-# build another problem that includes feature weights
-p2 <- p1 %>%
-     add_feature_weights("weight")
+    

+    

+    
See also

+    
objectives.

+    

 
-# \dontrun{
-# solve problem with feature weights
-s2 <- solve(p2)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0xffde171d -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [2e-01, 2e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 0.6654645 -#> Presolve removed 16 rows and 12 columns -#> Presolve time: 0.00s -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> Variable types: 0 continuous, 35 integer (35 binary) -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> -#> -#> Root relaxation: objective 1.511230e+00, 11 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 1.5112297 1.51123 0.00% - 0s -#> -#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 1.51123 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.511229665304e+00, best bound 1.511229665304e+00, gap 0.0000%
-# print solution based on feature weights -print(s2) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 1.51 199. 0 0 0 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solution based on feature weights -plot(p2, s2) -
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with maximum richness objective and $300 budget
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions()
+
+# \dontrun{
+# solve problem
+s1 <- solve(p1)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x193cb636
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.19038 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
+
+# print solution
+print(s1)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  2.19  195.         1       1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution
+plot(p1, s1)
+
+# }
+
+# build another problem that includes feature weights
+p2 <- p1 %>%
+     add_feature_weights("weight")
+
+# \dontrun{
+# solve problem with feature weights
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x40fa7344
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [2e-01, 2e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 0.6654645
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.511230e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.5112297    1.51123  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.51123 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.511229665304e+00, best bound 1.511229665304e+00, gap 0.0000%
+
+# print solution based on feature weights
+print(s2)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  1.51  199.         0       0       0       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution based on feature weights
+plot(p2, s2)
+
+# }
+
+
+
-
- - - + diff --git a/docs/reference/add_max_targets_met_objective-1.png b/docs/reference/add_max_targets_met_objective-1.png index 9f015ac..0f9c8a7 100644 Binary files a/docs/reference/add_max_targets_met_objective-1.png and b/docs/reference/add_max_targets_met_objective-1.png differ diff --git a/docs/reference/add_max_targets_met_objective-2.png b/docs/reference/add_max_targets_met_objective-2.png index 62a7e2f..16aaca2 100644 Binary files a/docs/reference/add_max_targets_met_objective-2.png and b/docs/reference/add_max_targets_met_objective-2.png differ diff --git a/docs/reference/add_max_targets_met_objective.html b/docs/reference/add_max_targets_met_objective.html index ce2e18e..aafa2c7 100644 --- a/docs/reference/add_max_targets_met_objective.html +++ b/docs/reference/add_max_targets_met_objective.html @@ -1,46 +1,5 @@ - - - - - - - -Add maximum targets met objective — add_max_targets_met_objective • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add maximum targets met objective — add_max_targets_met_objective • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add maximum targets met objective

- Source: R/add_max_targets_met_objective.R + Source: R/add_max_targets_met_objective.R
-

Set the objective of a project prioritization problem() to +

Set the objective of a project prioritization problem() to maximize the total number of persistence targets met for the features, whilst ensuring that the cost of the solution is within a pre-specified budget (Chades et al. 2015). In some project prioritization exercises, @@ -155,30 +82,32 @@

Add maximum targets met objective

secures a 95% chance of persistence will accrue the same benefit as a solution which secures a 50% chance of persistence). Furthermore, weights can also be used to specify the relative importance of meeting targets -for specific features (see add_feature_weights()).

+for specific features (see add_feature_weights()).

- 
add_max_targets_met_objective(x, budget)
+
+ 
add_max_targets_met_objective(x, budget)
+
-

Arguments

- - - - - - - - - - -
x

ProjectProblem object.

budget

numeric budget for funding actions.

+
+

Arguments

+
x
+

ProjectProblem object.

-

Value

-

ProjectProblem object with the objective -added to it.

-

Details

+
budget
+

numeric budget for funding actions.

+ +
+
+

Value

+ +

ProjectProblem object with the objective +added to it.

+
+
+

Details

A problem objective is used to specify the overall goal of the project prioritization problem. Here, the maximum targets met objective seeks to find the set of actions @@ -268,174 +197,183 @@

Details (\(E_f\)) are bounded between zero and one. Constraints (eqns 1i) ensure that the target met (\(G_f\)), action funding (\(X_i\)), project funding (\(Y_j\)), and project allocation (\(Z_{fj}\)) variables are binary.

-

References

- +
+
+

References

Chades I, Nicol S, van Leeuwen S, Walters B, Firn J, Reeson A, Martin TG & Carwardine J (2015) Benefits of integrating complementarity into priority threat management. Conservation Biology, 29, 525--536.

-

See also

- -

objectives.

- -

Examples

- 
# load the ggplot2 R package to customize plot
-library(ggplot2)
-
-# load data
-data(sim_projects, sim_features, sim_actions)
-
-# manually adjust feature weights
-sim_features$weight <- c(8, 2, 6, 3, 1)
-
-# build problem with maximum targets met objective, a $200 budget,
-# targets that require each feature to have a 20% chance of persisting into
-# the future, and zero cost actions locked in
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_max_targets_met_objective(budget = 200) %>%
-      add_absolute_targets(0.2) %>%
-      add_locked_in_constraints(which(sim_actions$cost < 1e-5)) %>%
-      add_binary_decisions()
-
-# \dontrun{
-# solve problem
-s1 <- solve(p1)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0x79c9aabe
-#> Variable types: 0 continuous, 47 integer (47 binary)
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 3.0000000
-#> Presolve removed 14 rows and 7 columns
-#> Presolve time: 0.00s
-#> Presolved: 33 rows, 40 columns, 69 nonzeros
-#> Variable types: 0 continuous, 40 integer (40 binary)
-#> Presolved: 33 rows, 40 columns, 69 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 4.961414e+00, 7 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#>      0     0    4.96141    0    4    3.00000    4.96141  65.4%     -    0s
-#> H    0     0                       4.0000000    4.96141  24.0%     -    0s
-#>      0     0    4.96141    0    4    4.00000    4.96141  24.0%     -    0s
-#> 
-#> Explored 0 nodes (7 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 4 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 4.000000000000e+00, best bound 4.000000000000e+00, gap 0.0000%

-# print solution
-print(s1)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL     4  99.9         0         0         0         0         1
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>

-# plot solution, and add a dashed line to indicate the feature targets
-# we can see the three features meet the targets under the baseline
-# scenario, and the project for F5 was prioritized for funding
-# so that its probability of persistence meets the target
-plot(p1, s1) +
-geom_hline(yintercept = 0.2, linetype = "dashed")
-
# }
-
-# build another problem that includes feature weights
-p2 <- p1 %>%
-      add_feature_weights("weight")
+    

+    

+    
See also

+    
objectives.

+    

 
-# \dontrun{
-# solve problem
-s2 <- solve(p2)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0x534550d5 -#> Variable types: 0 continuous, 47 integer (47 binary) -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [1e+00, 8e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 13.0000000 -#> Presolve removed 14 rows and 7 columns -#> Presolve time: 0.00s -#> Presolved: 33 rows, 40 columns, 69 nonzeros -#> Variable types: 0 continuous, 40 integer (40 binary) -#> Presolved: 33 rows, 40 columns, 69 nonzeros -#> -#> -#> Root relaxation: objective 1.996013e+01, 7 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> 0 0 19.96013 0 4 13.00000 19.96013 53.5% - 0s -#> H 0 0 19.0000000 19.96013 5.05% - 0s -#> 0 0 19.96013 0 4 19.00000 19.96013 5.05% - 0s -#> -#> Explored 0 nodes (7 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 19 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.900000000000e+01, best bound 1.900000000000e+01, gap 0.0000%
-# print solution -print(s2) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 19 103. 0 0 1 0 0 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solution, and add a dashed line to indicate the feature targets -# we can see that adding weights to the problem has changed the solution -# specifically, the projects for the feature F3 is now funded -# to enhance its probability of persistence -plot(p2, s2) + -geom_hline(yintercept = 0.2, linetype = "dashed") -
# } -
+
+

Examples

+ 
# load the ggplot2 R package to customize plot
+library(ggplot2)
+
+# load data
+data(sim_projects, sim_features, sim_actions)
+
+# manually adjust feature weights
+sim_features$weight <- c(8, 2, 6, 3, 1)
+
+# build problem with maximum targets met objective, a $200 budget,
+# targets that require each feature to have a 20% chance of persisting into
+# the future, and zero cost actions locked in
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_max_targets_met_objective(budget = 200) %>%
+      add_absolute_targets(0.2) %>%
+      add_locked_in_constraints(which(sim_actions$cost < 1e-5)) %>%
+      add_binary_decisions()
+
+# \dontrun{
+# solve problem
+s1 <- solve(p1)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x00731be5
+#> Variable types: 0 continuous, 47 integer (47 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 3.0000000
+#> Presolve removed 14 rows and 7 columns
+#> Presolve time: 0.00s
+#> Presolved: 33 rows, 40 columns, 69 nonzeros
+#> Variable types: 0 continuous, 40 integer (40 binary)
+#> Root relaxation presolved: 33 rows, 40 columns, 69 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 4.961414e+00, 7 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#>      0     0    4.96141    0    4    3.00000    4.96141  65.4%     -    0s
+#> H    0     0                       4.0000000    4.96141  24.0%     -    0s
+#>      0     0    4.96141    0    4    4.00000    4.96141  24.0%     -    0s
+#> 
+#> Explored 1 nodes (7 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 4 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 4.000000000000e+00, best bound 4.000000000000e+00, gap 0.0000%
+
+# print solution
+print(s1)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL     4  99.9         0       0       0       0       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution, and add a dashed line to indicate the feature targets
+# we can see the three features meet the targets under the baseline
+# scenario, and the project for F5 was prioritized for funding
+# so that its probability of persistence meets the target
+plot(p1, s1) +
+geom_hline(yintercept = 0.2, linetype = "dashed")
+
+# }
+
+# build another problem that includes feature weights
+p2 <- p1 %>%
+      add_feature_weights("weight")
+
+# \dontrun{
+# solve problem
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x2cfdc744
+#> Variable types: 0 continuous, 47 integer (47 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 8e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 13.0000000
+#> Presolve removed 14 rows and 7 columns
+#> Presolve time: 0.00s
+#> Presolved: 33 rows, 40 columns, 69 nonzeros
+#> Variable types: 0 continuous, 40 integer (40 binary)
+#> Root relaxation presolved: 33 rows, 40 columns, 69 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.996013e+01, 7 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#>      0     0   19.96013    0    4   13.00000   19.96013  53.5%     -    0s
+#> H    0     0                      19.0000000   19.96013  5.05%     -    0s
+#>      0     0   19.96013    0    4   19.00000   19.96013  5.05%     -    0s
+#> 
+#> Explored 1 nodes (7 simplex iterations) in 0.01 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 19 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.900000000000e+01, best bound 1.900000000000e+01, gap 0.0000%
+
+# print solution
+print(s2)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL    19  103.         0       0       1       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution, and add a dashed line to indicate the feature targets
+# we can see that adding weights to the problem has changed the solution
+# specifically, the projects for the feature F3 is now funded
+# to enhance its probability of persistence
+plot(p2, s2) +
+geom_hline(yintercept = 0.2, linetype = "dashed")
+
+# }
+
+
+
-
- - - + diff --git a/docs/reference/add_min_set_objective-1.png b/docs/reference/add_min_set_objective-1.png index 260a895..f56a224 100644 Binary files a/docs/reference/add_min_set_objective-1.png and b/docs/reference/add_min_set_objective-1.png differ diff --git a/docs/reference/add_min_set_objective.html b/docs/reference/add_min_set_objective.html index 3f336d5..582e7d6 100644 --- a/docs/reference/add_min_set_objective.html +++ b/docs/reference/add_min_set_objective.html @@ -1,81 +1,15 @@ - - - - - - - -Add minimum set objective — add_min_set_objective • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add minimum set objective — add_min_set_objective • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add minimum set objective

- Source: R/add_min_set_objective.R + Source: R/add_min_set_objective.R
-

Set the objective of a project prioritization problem() to +

Set the objective of a project prioritization problem() to minimize the cost of the solution whilst ensuring that all targets are met. This objective is conceptually similar to that used in Marxan (Ball, Possingham & Watts 2009).

- 
add_min_set_objective(x)
+
+ 
add_min_set_objective(x)
+
-

Arguments

- - - - - - -
x

ProjectProblem object.

+
+

Arguments

+
x
+

ProjectProblem object.

-

Value

+
+
+

Value

+ -

ProjectProblem object with the objective +

ProjectProblem object with the objective added to it.

-

Details

- +
+
+

Details

A problem objective is used to specify the overall goal of the project prioritization problem. Here, the minimum set objective seeks to find the set of actions that @@ -231,98 +160,102 @@

Details (\(E_f\)) are bounded between zero and one. Constraints (eqns 1h) ensure that the action funding (\(X_i\)), project funding (\(Y_j\)), and project allocation (\(Z_{fj}\)) variables are binary.

-

References

- +
+
+

References

Ball IR, Possingham HP & Watts M (2009) Marxan and relatives: software for spatial conservation prioritisation. Spatial conservation prioritisation: Quantitative methods and computational tools, 185-195.

-

See also

- -

objectives, targets.

- -

Examples

- 
# load the ggplot2 R package to customize plot
-library(ggplot2)
-
-# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with minimum set objective and targets that require each
-# feature to have a 30% chance of persisting into the future
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_min_set_objective() %>%
-      add_absolute_targets(0.3) %>%
-      add_binary_decisions()
+    

+    

+    
See also

+    
objectives, targets.

+    

 
-# \dontrun{
-# solve problem
-s <- solve(p)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 46 rows, 42 columns and 92 nonzeros -#> Model fingerprint: 0xde05e947 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+00] -#> Objective range [9e+01, 1e+02] -#> Bounds range [1e+00, 1e+00] -#> RHS range [3e-01, 1e+00] -#> Found heuristic solution: objective 497.7671458 -#> Presolve removed 45 rows and 20 columns -#> Presolve time: 0.00s -#> Presolved: 1 rows, 22 columns, 2 nonzeros -#> Variable types: 0 continuous, 22 integer (22 binary) -#> -#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 497.767 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 4.977671458279e+02, best bound 4.977671458279e+02, gap 0.0000%
-# print solution -print(s) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 498. 498. 1 1 1 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solution, and add a dashed line to indicate the feature targets -plot(p, s) + -geom_hline(yintercept = 0.3, linetype = "dashed") -
# } -
+
+

Examples

+ 
# load the ggplot2 R package to customize plot
+library(ggplot2)
+
+# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with minimum set objective and targets that require each
+# feature to have a 30% chance of persisting into the future
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_min_set_objective() %>%
+      add_absolute_targets(0.3) %>%
+      add_binary_decisions()
+
+# \dontrun{
+# solve problem
+s <- solve(p)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 46 rows, 42 columns and 92 nonzeros
+#> Model fingerprint: 0xde05e947
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+00]
+#>   Objective range  [9e+01, 1e+02]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [3e-01, 1e+00]
+#> Found heuristic solution: objective 497.7671458
+#> Presolve removed 45 rows and 20 columns
+#> Presolve time: 0.00s
+#> Presolved: 1 rows, 22 columns, 2 nonzeros
+#> Variable types: 0 continuous, 22 integer (22 binary)
+#> 
+#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 497.767 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 4.977671458279e+02, best bound 4.977671458279e+02, gap 0.0000%
+
+# print solution
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  498.  498.         1       1       1       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution, and add a dashed line to indicate the feature targets
+plot(p, s) +
+geom_hline(yintercept = 0.3, linetype = "dashed")
+
+# }
+
+
+
-
- - - + diff --git a/docs/reference/add_random_solver-1.png b/docs/reference/add_random_solver-1.png index 74894d6..1f672af 100644 Binary files a/docs/reference/add_random_solver-1.png and b/docs/reference/add_random_solver-1.png differ diff --git a/docs/reference/add_random_solver-2.png b/docs/reference/add_random_solver-2.png index 54aeffd..a797b2d 100644 Binary files a/docs/reference/add_random_solver-2.png and b/docs/reference/add_random_solver-2.png differ diff --git a/docs/reference/add_random_solver-3.png b/docs/reference/add_random_solver-3.png index 29aa6e1..9b5973b 100644 Binary files a/docs/reference/add_random_solver-3.png and b/docs/reference/add_random_solver-3.png differ diff --git a/docs/reference/add_random_solver.html b/docs/reference/add_random_solver.html index 518f65b..e788f62 100644 --- a/docs/reference/add_random_solver.html +++ b/docs/reference/add_random_solver.html @@ -1,81 +1,15 @@ - - - - - - - -Add a random solver — add_random_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add a random solver — add_random_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add a random solver

- Source: R/add_random_solver.R + Source: R/add_random_solver.R
@@ -134,44 +61,45 @@

Add a random solver

the effectiveness of solutions.

- 
add_random_solver(x, number_solutions = 1, verbose = TRUE)
+
+ 
add_random_solver(x, number_solutions = 1, verbose = TRUE)
+
-

Arguments

- - - - - - - - - - - - - - -
x

ProjectProblem object.

number_solutions

integer number of solutions desired. +

+

Arguments

+
x
+

ProjectProblem object.

+ + +
number_solutions
+

integer number of solutions desired. Defaults to 1. Note that the number of returned solutions can sometimes be less than the argument to number_solutions depending on the argument to solution_pool_method, for example if 100 solutions are requested but only 10 unique solutions exist, then only 10 -solutions will be returned.

verbose

logical should information be printed while solving -optimization problems?

+solutions will be returned.

-

Value

-

ProjectProblem object with the solver added -to it.

-

Details

+
verbose
+

logical should information be printed while solving +optimization problems?

+
+
+

Value

+ + +

ProjectProblem object with the solver added +to it.

+
+
+

Details

The algorithm used to randomly generate solutions depends on the the objective specified for the project prioritization -problem().

+problem().

For objectives which maximize benefit subject to budgetary constraints -(e.g. add_max_richness_objective()):

-
    -

  1. All locked in and zero-cost actions are initially +(e.g. add_max_richness_objective()):

    +

    1. All locked in and zero-cost actions are initially selected for funding (excepting actions which are locked out).

    2. A project---and all of its associated actions---is randomly selected for funding (excepting projects associated with locked out actions, @@ -180,12 +108,9 @@

      Details

    3. The previous step is repeated until no more projects can be selected for funding without the total cost of the prioritized actions exceeding the budget.

      4. -

    - -

    For objectives which minimize cost subject to biodiversity constraints -(i.e. add_min_set_objective():

    -
      -

    1. All locked in and zero-cost actions are initially +

    For objectives which minimize cost subject to biodiversity constraints +(i.e. add_min_set_objective():

    +

    1. All locked in and zero-cost actions are initially selected for funding (excepting actions which are locked out).

    2. A project---and all of its associated actions---is randomly selected for funding (excepting projects associated with locked out actions, @@ -193,144 +118,148 @@

      Details to the existing set of selected actions).

    3. The previous step is repeated until all of the persistence targets are met.

      4. -
    - -

    See also

    - -

    solvers.

    - -

    Examples

    - 
    # load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with random solver, and generate 100 random solutions
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions() %>%
-     add_random_solver(number_solutions = 100)
-
-# print problem
-print(p1)
-
    #> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          Random [number_solutions (100), verbose (1)]
    
-# solve problem
-s1 <- solve(p1)
-
-# print solutions
-print(s1)
-
    #> # A tibble: 100 x 21
-#>    solution status   obj  cost F1_action F2_action F3_action F4_action F5_action
-#>       <int> <chr>  <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#>  1        1 NA      1.99  194.         1         0         0         0         1
-#>  2        2 NA      2.01  194.         1         0         0         1         0
-#>  3        3 NA      1.96  198.         1         0         1         0         0
-#>  4        4 NA      1.96  198.         1         0         1         0         0
-#>  5        5 NA      1.91  199.         0         0         0         1         1
-#>  6        6 NA      1.99  194.         1         0         0         0         1
-#>  7        7 NA      1.96  198.         1         0         1         0         0
-#>  8        8 NA      1.96  198.         1         0         1         0         0
-#>  9        9 NA      1.96  198.         1         0         1         0         0
-#> 10       10 NA      2.19  195.         1         1         0         0         0
-#> # … with 90 more rows, and 12 more variables: baseline_action <dbl>,
-#> #   F1_project <dbl>, F2_project <dbl>, F3_project <dbl>, F4_project <dbl>,
-#> #   F5_project <dbl>, baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>,
-#> #   F4 <dbl>, F5 <dbl>
    
-# plot first random solution
-plot(p1, s1)
-
    
-# plot histogram of the objective values for the random solutions
-hist(s1$obj, xlab = "Expected richness", xlim = c(0, 2.5),
-     main = "Histogram of random solutions")
-
    
-# since the objective values don't tell us much about the quality of the
-# solutions, we can find the optimal solution and calculate how different
-# each of the random solutions is from optimality
-
-# \dontrun{
-# find the optimal objective value using an exact algorithms solver
-s2 <- p1 %>%
-      add_default_solver() %>%
-      solve()
-
    #> Warning: overwriting previously defined solver
    #> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xab0d0209
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 2.19038 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
    
-# create new column in s1 with percent difference from optimality
-s1$optimality_diff <- ((s2$obj - s1$obj) / s1$obj) * 100
+
+
+

See also

+

solvers.

+
-# plot histogram showing the quality of the random solutions -# higher numbers indicate worse solutions -hist(s1$optimality_diff, xlab = "Difference from optimality (%)", - main = "Histogram of random solutions", xlim = c(0, 50)) -
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with random solver, and generate 100 random solutions
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions() %>%
+     add_random_solver(number_solutions = 100)
+
+# print problem
+print(p1)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Random [number_solutions (100), verbose (1)]
+
+# solve problem
+s1 <- solve(p1)
+
+# print solutions
+print(s1)
+#> # A tibble: 100 × 21
+#>    solution status   obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>       <int> <chr>  <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#>  1        1 NA      1.91  199.         0       0       0       1       1       1
+#>  2        2 NA      1.96  198.         1       0       1       0       0       1
+#>  3        3 NA      2.01  194.         1       0       0       1       0       1
+#>  4        4 NA      2.19  195.         1       1       0       0       0       1
+#>  5        5 NA      1.91  199.         0       0       0       1       1       1
+#>  6        6 NA      2.01  194.         1       0       0       1       0       1
+#>  7        7 NA      2.19  195.         1       1       0       0       0       1
+#>  8        8 NA      2.19  195.         1       1       0       0       0       1
+#>  9        9 NA      1.99  194.         1       0       0       0       1       1
+#> 10       10 NA      1.96  198.         1       0       1       0       0       1
+#> # … with 90 more rows, 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot first random solution
+plot(p1, s1)
+
+
+# plot histogram of the objective values for the random solutions
+hist(s1$obj, xlab = "Expected richness", xlim = c(0, 2.5),
+     main = "Histogram of random solutions")
+
+
+# since the objective values don't tell us much about the quality of the
+# solutions, we can find the optimal solution and calculate how different
+# each of the random solutions is from optimality
+
+# \dontrun{
+# find the optimal objective value using an exact algorithms solver
+s2 <- p1 %>%
+      add_default_solver() %>%
+      solve()
+#> Warning: overwriting previously defined solver
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x193cb636
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.19038 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
+
+# create new column in s1 with percent difference from optimality
+s1$optimality_diff <- ((s2$obj - s1$obj) / s1$obj) * 100
+
+# plot histogram showing the quality of the random solutions
+# higher numbers indicate worse solutions
+hist(s1$optimality_diff, xlab = "Difference from optimality (%)",
+     main = "Histogram of random solutions", xlim = c(0, 50))
+
+# }
+
+
+ - - - - + diff --git a/docs/reference/add_relative_targets-1.png b/docs/reference/add_relative_targets-1.png index 2b59ba9..16db146 100644 Binary files a/docs/reference/add_relative_targets-1.png and b/docs/reference/add_relative_targets-1.png differ diff --git a/docs/reference/add_relative_targets-2.png b/docs/reference/add_relative_targets-2.png index a01ecbd..4e34133 100644 Binary files a/docs/reference/add_relative_targets-2.png and b/docs/reference/add_relative_targets-2.png differ diff --git a/docs/reference/add_relative_targets-3.png b/docs/reference/add_relative_targets-3.png index a01ecbd..4e34133 100644 Binary files a/docs/reference/add_relative_targets-3.png and b/docs/reference/add_relative_targets-3.png differ diff --git a/docs/reference/add_relative_targets.html b/docs/reference/add_relative_targets.html index 49d7210..cfa59ea 100644 --- a/docs/reference/add_relative_targets.html +++ b/docs/reference/add_relative_targets.html @@ -1,83 +1,17 @@ - - - - - - - -Add relative targets — add_relative_targets • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add relative targets — add_relative_targets • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add relative targets

- Source: R/add_relative_targets.R + Source: R/add_relative_targets.R
-

Set targets for a project prioritization problem() as a proportion +

Set targets for a project prioritization problem() as a proportion (between 0 and 1) of the maximum probability of persistence associated with the best project for feature. For instance, if the best project for a feature has an 80% probability of persisting, @@ -138,262 +65,277 @@

Add relative targets

threshold probability of persisting.

- 
add_relative_targets(x, targets)
-
-# S4 method for ProjectProblem,numeric
-add_relative_targets(x, targets)
+    

+    
add_relative_targets(x, targets)
+
+# S4 method for ProjectProblem,numeric
+add_relative_targets(x, targets)
+
+# S4 method for ProjectProblem,character
+add_relative_targets(x, targets)

+    

 
-# S4 method for ProjectProblem,character
-add_relative_targets(x, targets)
+
+

Arguments

+
x
+

ProjectProblem object.

-

Arguments

- - - - - - - - - - -
x

ProjectProblem object.

targets

Object that specifies the targets for each feature. See the -Details section for more information.

-

Details

+
targets
+

Object that specifies the targets for each feature. See the +Details section for more information.

+
+
+

Details

Targets are used to specify the minimum probability of persistence for each feature in solutions. For minimum set objectives -(i.e. add_min_set_objective(), these targets +(i.e. add_min_set_objective(), these targets specify the minimum probability of persistence required for each species in the solution. And for budget constrained objectives that use targets -(i.e.add_max_targets_met_objective()), these targets +(i.e.add_max_targets_met_objective()), these targets specify the minimum threshold probability of persistence that needs to be achieved to count the benefits for conserving these species. Please note that attempting to solve problems with objectives that require targets without specifying targets will throw an error.

The targets for a problem can be specified in several different ways:

-
- -
numeric

vector of target values for each feature. +

numeric
+

vector of target values for each feature. The order of the target values should correspond to the order of the features in the data used to create the argument to x. Additionally, for convenience, this type of argument can be a single value to assign the same target to each feature.

-
character

specifying the name of column in the -feature data (i.e. the argument to features in the -problem() function) that contains the persistence targets.

- - -
- -

See also

- -

targets.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
 
-# build problem with minimum set objective and targets that require each
-# feature to have a level of persistence that is greater than or equal to
-# 70% of the best project for conserving it
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_min_set_objective() %>%
-      add_relative_targets(0.7) %>%
-      add_binary_decisions()
+
character

+
specifying the name of column in the
+feature data (i.e. the argument to features in the
+problem() function) that contains the persistence targets.

 
-# print problem
-print(p1)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Minimum set objective 
-#>   targets:         Relative targets [targets (min: 0.7, max: 0.7)]
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# build problem with minimum set objective and specify targets that require
-# different levels of persistence for each feature
-p2 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_min_set_objective() %>%
-      add_relative_targets(c(0.2, 0.3, 0.4, 0.5, 0.6)) %>%
-      add_binary_decisions()
 
-# print problem
-print(p2)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Minimum set objective 
-#>   targets:         Relative targets [targets (min: 0.2, max: 0.6)]
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# add a column name to the feature data with targets
-sim_features$target <- c(0.2, 0.3, 0.4, 0.5, 0.6)
 
-# build problem with minimum set objective and specify targets using
-# column name in the feature data
-p3 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_min_set_objective() %>%
-      add_relative_targets("target") %>%
-      add_binary_decisions()
+
+
+

See also

+

targets.

+
-# \dontrun{ -# print problem -print(p3) -
#> Project Prioritization Problem -#> actions F1_action, F2_action, F3_action, ... (6 actions) -#> projects F1_project, F2_project, F3_project, ... (6 projects) -#> features F1, F2, F3, ... (5 features) -#> action costs: min: 0, max: 103.22583 -#> project success: min: 0.81379, max: 1 -#> objective: Minimum set objective -#> targets: Relative targets [targets (min: 0.2, max: 0.6)] -#> weights: default -#> decisions Binary decision -#> constraints: <none> -#> solver: default
-# solve problems -s1 <- solve(p1) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 46 rows, 42 columns and 92 nonzeros -#> Model fingerprint: 0xe339eeda -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+00] -#> Objective range [9e+01, 1e+02] -#> Bounds range [1e+00, 1e+00] -#> RHS range [3e-01, 1e+00] -#> Found heuristic solution: objective 497.7671458 -#> Presolve removed 45 rows and 20 columns -#> Presolve time: 0.00s -#> Presolved: 1 rows, 22 columns, 2 nonzeros -#> Variable types: 0 continuous, 22 integer (22 binary) -#> -#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 497.767 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 4.977671458279e+02, best bound 4.977671458279e+02, gap 0.0000%
s2 <- solve(p2) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 46 rows, 42 columns and 92 nonzeros -#> Model fingerprint: 0xe4091247 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+00] -#> Objective range [9e+01, 1e+02] -#> Bounds range [1e+00, 1e+00] -#> RHS range [2e-01, 1e+00] -#> Found heuristic solution: objective 403.3678534 -#> Presolve removed 38 rows and 17 columns -#> Presolve time: 0.00s -#> Presolved: 8 rows, 25 columns, 16 nonzeros -#> Variable types: 0 continuous, 25 integer (25 binary) -#> -#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 403.368 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 4.033678533759e+02, best bound 4.033678533759e+02, gap 0.0000%
s3 <- solve(p3) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 46 rows, 42 columns and 92 nonzeros -#> Model fingerprint: 0xe4091247 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+00] -#> Objective range [9e+01, 1e+02] -#> Bounds range [1e+00, 1e+00] -#> RHS range [2e-01, 1e+00] -#> Found heuristic solution: objective 403.3678534 -#> Presolve removed 38 rows and 17 columns -#> Presolve time: 0.00s -#> Presolved: 8 rows, 25 columns, 16 nonzeros -#> Variable types: 0 continuous, 25 integer (25 binary) -#> -#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 403.368 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 4.033678533759e+02, best bound 4.033678533759e+02, gap 0.0000%
-# print solutions -print(s1) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 498. 498. 1 1 1 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
print(s2) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 403. 403. 0 1 1 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
print(s3) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 403. 403. 0 1 1 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solutions -plot(p1, s1) -
plot(p2, s2) -
plot(p3, s3) -
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with minimum set objective and targets that require each
+# feature to have a level of persistence that is greater than or equal to
+# 70% of the best project for conserving it
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_min_set_objective() %>%
+      add_relative_targets(0.7) %>%
+      add_binary_decisions()
+
+# print problem
+print(p1)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Minimum set objective 
+#>   targets:         Relative targets [targets (min: 0.7, max: 0.7)]
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# build problem with minimum set objective and specify targets that require
+# different levels of persistence for each feature
+p2 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_min_set_objective() %>%
+      add_relative_targets(c(0.2, 0.3, 0.4, 0.5, 0.6)) %>%
+      add_binary_decisions()
+
+# print problem
+print(p2)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Minimum set objective 
+#>   targets:         Relative targets [targets (min: 0.2, max: 0.6)]
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# add a column name to the feature data with targets
+sim_features$target <- c(0.2, 0.3, 0.4, 0.5, 0.6)
+
+# build problem with minimum set objective and specify targets using
+# column name in the feature data
+p3 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_min_set_objective() %>%
+      add_relative_targets("target") %>%
+      add_binary_decisions()
+
+# \dontrun{
+# print problem
+print(p3)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Minimum set objective 
+#>   targets:         Relative targets [targets (min: 0.2, max: 0.6)]
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# solve problems
+s1 <- solve(p1)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 46 rows, 42 columns and 92 nonzeros
+#> Model fingerprint: 0xe339eeda
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+00]
+#>   Objective range  [9e+01, 1e+02]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [3e-01, 1e+00]
+#> Found heuristic solution: objective 497.7671458
+#> Presolve removed 45 rows and 20 columns
+#> Presolve time: 0.00s
+#> Presolved: 1 rows, 22 columns, 2 nonzeros
+#> Variable types: 0 continuous, 22 integer (22 binary)
+#> 
+#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 497.767 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 4.977671458279e+02, best bound 4.977671458279e+02, gap 0.0000%
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 46 rows, 42 columns and 92 nonzeros
+#> Model fingerprint: 0xe4091247
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+00]
+#>   Objective range  [9e+01, 1e+02]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [2e-01, 1e+00]
+#> Found heuristic solution: objective 403.3678534
+#> Presolve removed 38 rows and 17 columns
+#> Presolve time: 0.00s
+#> Presolved: 8 rows, 25 columns, 16 nonzeros
+#> Variable types: 0 continuous, 25 integer (25 binary)
+#> 
+#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 403.368 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 4.033678533759e+02, best bound 4.033678533759e+02, gap 0.0000%
+s3 <- solve(p3)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 46 rows, 42 columns and 92 nonzeros
+#> Model fingerprint: 0xe4091247
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+00]
+#>   Objective range  [9e+01, 1e+02]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [2e-01, 1e+00]
+#> Found heuristic solution: objective 403.3678534
+#> Presolve removed 38 rows and 17 columns
+#> Presolve time: 0.00s
+#> Presolved: 8 rows, 25 columns, 16 nonzeros
+#> Variable types: 0 continuous, 25 integer (25 binary)
+#> 
+#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 403.368 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 4.033678533759e+02, best bound 4.033678533759e+02, gap 0.0000%
+
+# print solutions
+print(s1)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  498.  498.         1       1       1       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+print(s2)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  403.  403.         0       1       1       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+print(s3)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  403.  403.         0       1       1       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solutions
+plot(p1, s1)
+
+plot(p2, s2)
+
+plot(p3, s3)
+
+# }
+
+
+
- - - - + diff --git a/docs/reference/add_rsymphony_solver-1.png b/docs/reference/add_rsymphony_solver-1.png index 89a16f5..6c3a587 100644 Binary files a/docs/reference/add_rsymphony_solver-1.png and b/docs/reference/add_rsymphony_solver-1.png differ diff --git a/docs/reference/add_rsymphony_solver.html b/docs/reference/add_rsymphony_solver.html index db6854c..8561f94 100644 --- a/docs/reference/add_rsymphony_solver.html +++ b/docs/reference/add_rsymphony_solver.html @@ -1,81 +1,15 @@ - - - - - - - -Add a SYMPHONY solver with Rsymphony — add_rsymphony_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Add a SYMPHONY solver with Rsymphony — add_rsymphony_solver • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Add a SYMPHONY solver with Rsymphony

- Source: R/add_rsymphony_solver.R + Source: R/add_rsymphony_solver.R

Specify that the SYMPHONY software should be used to solve a -project prioritization problem() using the Rsymphony +project prioritization problem() using the Rsymphony package. This function can also be used to customize the behavior of the solver. It requires the Rsymphony package.

- 
add_rsymphony_solver(
-  x,
-  gap = 0,
-  time_limit = .Machine$integer.max,
-  first_feasible = FALSE,
-  verbose = TRUE
-)
+
+ 
add_rsymphony_solver(
+  x,
+  gap = 0,
+  time_limit = .Machine$integer.max,
+  first_feasible = FALSE,
+  verbose = TRUE
+)
+
+ +
+

Arguments

+
x
+

ProjectProblem object.

+ -

Arguments

- - - - - - - - - - - - - - - - - - - - - - -
x

ProjectProblem object.

gap

numeric gap to optimality. This gap is relative +

gap
+

numeric gap to optimality. This gap is relative and expresses the acceptable deviance from the optimal objective. For example, a value of 0.01 will result in the solver stopping when it has found a solution within 1% of optimality. Additionally, a value of 0 will result in the solver stopping when it has found an optimal solution. -The default value is 0.1 (i.e. 10% from optimality).

time_limit

numeric time limit in seconds to run the optimizer. +The default value is 0.1 (i.e. 10% from optimality).

+ + +
time_limit
+

numeric time limit in seconds to run the optimizer. The solver will return the current best solution when this time limit is -exceeded.

first_feasible

logical should the first feasible solution be +exceeded.

+ + +
first_feasible
+

logical should the first feasible solution be be returned? If first_feasible is set to TRUE, the solver will return the first solution it encounters that meets all the constraints, regardless of solution quality. Note that the first feasible solution is not an arbitrary solution, rather it is derived from the relaxed solution, and is therefore often reasonably close to optimality. -Defaults to FALSE.

verbose

logical should information be printed while solving -optimization problems?

+Defaults to FALSE.

-

Value

-

ProjectProblem object with the solver added -to it.

-

Details

+
verbose
+

logical should information be printed while solving +optimization problems?

-

SYMPHONY is an +

+
+

Value

+ + +

ProjectProblem object with the solver added +to it.

+
+
+

Details

+

SYMPHONY is an open-source integer programming solver that is part of the Computational Infrastructure for Operations Research (COIN-OR) project, an initiative to promote development of open-source tools for operations research (a field that includes linear programming). The Rsymphony package provides an interface to COIN-OR and is available on CRAN. This solver uses the Rsymphony package to solve problems.

-

See also

- -

solvers.

- -

Examples

- 
# \dontrun{
-# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with Rsymphony solver
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions() %>%
-     add_rsymphony_solver()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          Rsymphony [first_feasible (0), gap (0), time_limit (2147483647), verbose (1)]

-# solve problem
-s <- solve(p)
+    

+    

+    
See also

+    
solvers.

+    

 
-# print solution
-print(s)
-
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 TM_OPT… 2.19 195. 1 1 0 0 0 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solution -plot(p, s) -
# } -
+
+

Examples

+ 
# \dontrun{
+# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with Rsymphony solver
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions() %>%
+     add_rsymphony_solver()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Rsymphony [first_feasible (0), gap (0), time_limit (2147483647), verbose (1)]
+
+# solve problem
+s <- solve(p)
+
+# print solution
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status      obj  cost F1_ac…¹ F2_ac…² F3_ac…³ F4_ac…⁴ F5_ac…⁵ basel…⁶
+#>      <int> <chr>     <dbl> <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 TM_OPTIM…  2.19  195.       1       1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F1_action, ²​F2_action, ³​F3_action,
+#> #   ⁴​F4_action, ⁵​F5_action, ⁶​baseline_action
+
+# plot solution
+plot(p, s)
+
+# }
+
+
+
-
- - - + diff --git a/docs/reference/array_parameters.html b/docs/reference/array_parameters.html index 72adf4b..b528145 100644 --- a/docs/reference/array_parameters.html +++ b/docs/reference/array_parameters.html @@ -1,79 +1,13 @@ - - - - - - - -Array parameters — array_parameters • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Array parameters — array_parameters • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Array parameters

- Source: R/parameters.R + Source: R/parameters.R
@@ -130,185 +57,208 @@

Array parameters

to create a parameter with conflicting settings then an error will be thrown.

- 
proportion_parameter_array(name, value, label)
-
-binary_parameter_array(name, value, label)
-
-integer_parameter_array(
-  name,
-  value,
-  label,
-  lower_limit = rep(as.integer(-.Machine$integer.max), length(value)),
-  upper_limit = rep(as.integer(.Machine$integer.max), length(value))
-)
-
-numeric_parameter_array(
-  name,
-  value,
-  label,
-  lower_limit = rep(.Machine$double.xmin, length(value)),
-  upper_limit = rep(.Machine$double.xmax, length(value))
-)
- -

Arguments

- - - - - - - - - - - - - - - - - - - - - - -
name

character name of parameter.

value

vector of values.

label

character vector of labels for each value.

lower_limit

vector of values denoting the minimum acceptable -value for each element in value. Defaults to the -smallest possible number on the system.

upper_limit

vector of values denoting the maximum acceptable +

+ 
proportion_parameter_array(name, value, label)
+
+binary_parameter_array(name, value, label)
+
+integer_parameter_array(
+  name,
+  value,
+  label,
+  lower_limit = rep(as.integer(-.Machine$integer.max), length(value)),
+  upper_limit = rep(as.integer(.Machine$integer.max), length(value))
+)
+
+numeric_parameter_array(
+  name,
+  value,
+  label,
+  lower_limit = rep(.Machine$double.xmin, length(value)),
+  upper_limit = rep(.Machine$double.xmax, length(value))
+)
+
+ +
+

Arguments

+
name
+

character name of parameter.

+ + +
value
+

vector of values.

+ + +
label
+

character vector of labels for each value.

+ + +
lower_limit
+

vector of values denoting the minimum acceptable value for each element in value. Defaults to the -largest possible number on the system.

+smallest possible number on the system.

-

Value

-

ArrayParameter object.

-

Details

+
upper_limit
+

vector of values denoting the maximum acceptable +value for each element in value. Defaults to the +largest possible number on the system.

-

Below is a list of parameter generating functions and a brief -description of each.

+
+
+

Value

+ -
proportion_parameter_array

a parameter that consists of multiple +

ArrayParameter object.

+
+
+

Details

+

Below is a list of parameter generating functions and a brief +description of each.

proportion_parameter_array
+

a parameter that consists of multiple numeric values that are between zero and one.

-
binary_parameter_array

a parameter that consists of multiple + +

binary_parameter_array
+

a parameter that consists of multiple integer values that are either zero or one.

-
integer_parameter_array

a parameter that consists of multiple + +

integer_parameter_array
+

a parameter that consists of multiple integer values.

-
numeric_parameter_array

a parameter that consists of multiple + +

numeric_parameter_array
+

a parameter that consists of multiple numeric values.

-
- - -

Examples

- 
# proportion parameter array
-p1 <- proportion_parameter_array('prop_array', c(0.1, 0.2, 0.3),
-                                 letters[1:3])
-print(p1) # print it
-
#> prop_array (min: 0.1, max: 0.3)
p1$get() # get value
-
#>   value
-#> a   0.1
-#> b   0.2
-#> c   0.3
p1$id # get id
-
#> id: 4c535118-abcd-445f-bd5f-ecf5cc8776cf
invalid <- data.frame(value = 1:3, row.names=letters[1:3]) # invalid values
-p1$validate(invalid) # check invalid input is invalid
-valid <- data.frame(value = c(0.4, 0.5, 0.6), row.names=letters[1:3]) # valid
-p1$validate(valid) # check valid input is valid
-p1$set(valid) # change value to valid input
-print(p1)
-
#> prop_array (min: 0.4, max: 0.6)

-# binary parameter array
-p2 <- binary_parameter_array('bin_array', c(0L, 1L, 0L), letters[1:3])
-print(p2) # print it
-
#> bin_array (min: 0, max: 1)
p2$get() # get value
-
#>   value
-#> a     0
-#> b     1
-#> c     0
p2$id # get id
-
#> id: 5ac5d056-dacf-42c3-9fa5-56233408d5ea
invalid <- data.frame(value = 1:3, row.names=letters[1:3]) # invalid values
-p2$validate(invalid) # check invalid input is invalid
-valid <- data.frame(value = c(0L, 0L, 0L), row.names=letters[1:3]) # valid
-p2$validate(valid) # check valid input is valid
-p2$set(valid) # change value to valid input
-print(p2)
-
#> bin_array (min: 0, max: 0)

-# integer parameter array
-p3 <- integer_parameter_array('int_array', c(1:3), letters[1:3])
-print(p3) # print it
-
#> int_array (min: 1, max: 3)
p3$get() # get value
-
#>   value
-#> a     1
-#> b     2
-#> c     3
p3$id # get id
-
#> id: 717a2b55-a812-44db-85d1-3b818a41b1fc
invalid <- data.frame(value = rnorm(3), row.names=letters[1:3]) # invalid
-p3$validate(invalid) # check invalid input is invalid
-valid <- data.frame(value = 5:7, row.names=letters[1:3]) # valid
-p3$validate(valid) # check valid input is valid
-p3$set(valid) # change value to valid input
-print(p3)
-
#> int_array (min: 5, max: 7)

-# numeric parameter array
-p4 <- numeric_parameter_array('dbl_array', c(0.1, 4, -5), letters[1:3])
-print(p4) # print it
-
#> dbl_array (min: -5, max: 4)
p4$get() # get value
-
#>   value
-#> a   0.1
-#> b   4.0
-#> c  -5.0
p4$id # get id
-
#> id: 6411ca83-643f-4df7-aee0-9982cb0562ca
invalid <- data.frame(value = c(NA, 1, 2), row.names=letters[1:3]) # invalid
-p4$validate(invalid) # check invalid input is invalid
-valid <- data.frame(value = c(1, 2, 3), row.names=letters[1:3]) # valid
-p4$validate(valid) # check valid input is valid
-p4$set(valid) # change value to valid input
-print(p4)
-
#> dbl_array (min: 1, max: 3)

-# numeric parameter array with lower bounds
-p5 <- numeric_parameter_array('b_dbl_array', c(0.1, 4, -5), letters[1:3],
-                              lower_limit=c(0, 1, 2))
-print(p5) # print it
-
#> b_dbl_array (min: -5, max: 4)
p5$get() # get value
-
#>   value
-#> a   0.1
-#> b   4.0
-#> c  -5.0
p5$id# get id
-
#> id: 5e28e224-d11a-48b9-b158-cf2ee4b260cf
invalid <- data.frame(value = c(-1, 5, 5), row.names=letters[1:3]) # invalid
-p5$validate(invalid) # check invalid input is invalid
-valid <- data.frame(value = c(0, 1, 2), row.names=letters[1:3]) # valid
-p5$validate(valid) # check valid input is valid
-p5$set(valid) # change value to valid input
-print(p5)
-
#> b_dbl_array (min: 0, max: 2)

-
+ +
+ +
+

Examples

+ 
# proportion parameter array
+p1 <- proportion_parameter_array('prop_array', c(0.1, 0.2, 0.3),
+                                 letters[1:3])
+print(p1) # print it
+#> prop_array (min: 0.1, max: 0.3)
+p1$get() # get value
+#>   value
+#> a   0.1
+#> b   0.2
+#> c   0.3
+p1$id # get id
+#> id: 94c06762-698e-4c26-a201-e37189f99391
+invalid <- data.frame(value = 1:3, row.names=letters[1:3]) # invalid values
+p1$validate(invalid) # check invalid input is invalid
+valid <- data.frame(value = c(0.4, 0.5, 0.6), row.names=letters[1:3]) # valid
+p1$validate(valid) # check valid input is valid
+p1$set(valid) # change value to valid input
+print(p1)
+#> prop_array (min: 0.4, max: 0.6)
+
+# binary parameter array
+p2 <- binary_parameter_array('bin_array', c(0L, 1L, 0L), letters[1:3])
+print(p2) # print it
+#> bin_array (min: 0, max: 1)
+p2$get() # get value
+#>   value
+#> a     0
+#> b     1
+#> c     0
+p2$id # get id
+#> id: e9387d8e-0fe0-4709-a990-e569f2988a52
+invalid <- data.frame(value = 1:3, row.names=letters[1:3]) # invalid values
+p2$validate(invalid) # check invalid input is invalid
+valid <- data.frame(value = c(0L, 0L, 0L), row.names=letters[1:3]) # valid
+p2$validate(valid) # check valid input is valid
+p2$set(valid) # change value to valid input
+print(p2)
+#> bin_array (min: 0, max: 0)
+
+# integer parameter array
+p3 <- integer_parameter_array('int_array', c(1:3), letters[1:3])
+print(p3) # print it
+#> int_array (min: 1, max: 3)
+p3$get() # get value
+#>   value
+#> a     1
+#> b     2
+#> c     3
+p3$id # get id
+#> id: 0bef8045-0690-442d-b6db-71b622cc69a9
+invalid <- data.frame(value = rnorm(3), row.names=letters[1:3]) # invalid
+p3$validate(invalid) # check invalid input is invalid
+valid <- data.frame(value = 5:7, row.names=letters[1:3]) # valid
+p3$validate(valid) # check valid input is valid
+p3$set(valid) # change value to valid input
+print(p3)
+#> int_array (min: 5, max: 7)
+
+# numeric parameter array
+p4 <- numeric_parameter_array('dbl_array', c(0.1, 4, -5), letters[1:3])
+print(p4) # print it
+#> dbl_array (min: -5, max: 4)
+p4$get() # get value
+#>   value
+#> a   0.1
+#> b   4.0
+#> c  -5.0
+p4$id # get id
+#> id: 92da33ac-6abd-42b9-8669-d2cfb5c5da1a
+invalid <- data.frame(value = c(NA, 1, 2), row.names=letters[1:3]) # invalid
+p4$validate(invalid) # check invalid input is invalid
+valid <- data.frame(value = c(1, 2, 3), row.names=letters[1:3]) # valid
+p4$validate(valid) # check valid input is valid
+p4$set(valid) # change value to valid input
+print(p4)
+#> dbl_array (min: 1, max: 3)
+
+# numeric parameter array with lower bounds
+p5 <- numeric_parameter_array('b_dbl_array', c(0.1, 4, -5), letters[1:3],
+                              lower_limit=c(0, 1, 2))
+print(p5) # print it
+#> b_dbl_array (min: -5, max: 4)
+p5$get() # get value
+#>   value
+#> a   0.1
+#> b   4.0
+#> c  -5.0
+p5$id# get id
+#> id: 245965ee-0bf5-41a4-8fd5-4519cb8bfe61
+invalid <- data.frame(value = c(-1, 5, 5), row.names=letters[1:3]) # invalid
+p5$validate(invalid) # check invalid input is invalid
+valid <- data.frame(value = c(0, 1, 2), row.names=letters[1:3]) # valid
+p5$validate(valid) # check valid input is valid
+p5$set(valid) # change value to valid input
+print(p5)
+#> b_dbl_array (min: 0, max: 2)
+
+
+
+
- - - - + diff --git a/docs/reference/as.html b/docs/reference/as.html index 32dcc8e..9db5862 100644 --- a/docs/reference/as.html +++ b/docs/reference/as.html @@ -1,76 +1,12 @@ - - - - - - - -Coerce object to another object — as.Id • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Coerce object to another object — as.Id • oppr - - - - - - - - - - - +
-
- -
- -
+

Coerce object to another object

- Source: R/Id.R, R/misc.R + Source: R/Id.R, R/misc.R
@@ -126,58 +55,54 @@

Coerce object to another object

Coerce an object.

- 
as.Id(x, ...)
+    

+    
as.Id(x, ...)
+
+# S3 method for character
+as.Id(x, ...)
+
+# S3 method for Parameters
+as.list(x, ...)

+    

 
-# S3 method for character
-as.Id(x, ...)
+    

+    
Arguments

+    
x

+
Object.

 
-# S3 method for Parameters
-as.list(x, ...)
-

Arguments

- - - - - - - - - - -
x

Object.

...

unused arguments.

+
...
+

unused arguments.

-

Value

+
+
+

Value

+ -

An Object.

+

An Object.

+
+
- - - - + diff --git a/docs/reference/as.list.html b/docs/reference/as.list.html index 395b34d..e222d56 100644 --- a/docs/reference/as.list.html +++ b/docs/reference/as.list.html @@ -1,76 +1,12 @@ - - - - - - - -Convert OptimizationProblem to list — as.list.OptimizationProblem • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Convert OptimizationProblem to list — as.list.OptimizationProblem • oppr - - - - - - - - - - - +
-
- -
- -
+

Convert OptimizationProblem to list

- Source: R/OptimizationProblem-methods.R + Source: R/OptimizationProblem-methods.R
@@ -126,53 +55,49 @@

Convert OptimizationProblem to list

Convert OptimizationProblem to list

- 
# S3 method for OptimizationProblem
-as.list(x, ...)
+
+ 
# S3 method for OptimizationProblem
+as.list(x, ...)
+
-

Arguments

- - - - - - - - - - -
x

OptimizationProblem object.

...

not used.

+
+

Arguments

+
x
+

OptimizationProblem object.

-

Value

-

list() object.

+
...
+

not used.

+ +
+
+

Value

+ + +

list() object.

+
+
- - - - + diff --git a/docs/reference/branch_matrix-1.png b/docs/reference/branch_matrix-1.png index 363c332..170c709 100644 Binary files a/docs/reference/branch_matrix-1.png and b/docs/reference/branch_matrix-1.png differ diff --git a/docs/reference/branch_matrix.html b/docs/reference/branch_matrix.html index b82eb75..3ab244b 100644 --- a/docs/reference/branch_matrix.html +++ b/docs/reference/branch_matrix.html @@ -1,85 +1,19 @@ - - - - - - - -Branch matrix — branch_matrix • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Branch matrix — branch_matrix • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Branch matrix

- Source: R/branch_matrix.R + Source: R/branch_matrix.R
@@ -142,82 +69,81 @@

Branch matrix

history each species has experienced.

- 
branch_matrix(x, ...)
-
-# S3 method for default
-branch_matrix(x, ...)
-
-# S3 method for phylo
-branch_matrix(x, assert_validity = TRUE, ...)
- -

Arguments

- - - - - - - - - - - - - - -
x

ape::phylo() tree object.

...

not used.

assert_validity

logical value (i.e. TRUE or FALSE -indicating if the argument to x should be checked for validity. -Defaults to TRUE.

+
+ 
branch_matrix(x, ...)
+
+# S3 method for default
+branch_matrix(x, ...)
+
+# S3 method for phylo
+branch_matrix(x, assert_validity = TRUE, ...)
+
-

Value

+
+

Arguments

+
x
+

ape::phylo() tree object.

-

Matrix::dgCMatrix sparse matrix object. Each row -corresponds to a different species. Each column corresponds to a different -branch. Species that inherit from a given branch are indicated with a one.

-

Examples

- 
# load Matrix package to plot matrices
-library(Matrix)
+
...

+
not used.

 
-# load data
-data(sim_tree)
 
-# generate species by branch matrix
-m <- branch_matrix(sim_tree)
+
assert_validity

+
logical value (i.e. TRUE or FALSE
+indicating if the argument to x should be checked for validity.
+Defaults to TRUE.

 
-# plot data
-par(mfrow = c(1,2))
-plot(sim_tree, main = "phylogeny")
-image(m, main = "branch matrix")
+
+
+

Value

+ -
+

Matrix::dgCMatrix sparse matrix object. Each row +corresponds to a different species. Each column corresponds to a different +branch. Species that inherit from a given branch are indicated with a one.

+
+ +
+

Examples

+ 
# load Matrix package to plot matrices
+library(Matrix)
+
+# load data
+data(sim_tree)
+
+# generate species by branch matrix
+m <- branch_matrix(sim_tree)
+
+# plot data
+par(mfrow = c(1,2))
+plot(sim_tree, main = "phylogeny")
+image(m, main = "branch matrix")
+
+
+
+
+
- - - - + diff --git a/docs/reference/compile.html b/docs/reference/compile.html index fe32f4e..14606ec 100644 --- a/docs/reference/compile.html +++ b/docs/reference/compile.html @@ -1,79 +1,13 @@ - - - - - - - -Compile a problem — compile • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Compile a problem — compile • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Compile a problem

- Source: R/compile.R + Source: R/compile.R
-

Compile a project prioritization problem() into a general +

Compile a project prioritization problem() into a general purpose format for optimization.

- 
compile(x, ...)
+    

+    
compile(x, ...)
+
+# S3 method for ProjectProblem
+compile(x, ...)

+    

 
-# S3 method for ProjectProblem
-compile(x, ...)
+
+

Arguments

+
x
+

ProjectProblem object.

-

Arguments

- - - - - - - - - - -
x

ProjectProblem object.

...

not used.

-

Value

+
...
+

not used.

-

OptimizationProblem object.

-

Details

+
+
+

Value

+ +

OptimizationProblem object.

+
+
+

Details

This function might be useful for those interested in understanding -how their project prioritization problem() is expressed +how their project prioritization problem() is expressed as a mathematical problem. However, if the problem just needs to -be solved, then the solve() function should be used instead.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with maximum richness objective, $200 budget, and
-# binary decisions
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# compile problem
-o <- compile(p)
-
-# print compiled problem
-print(o)
-
#> optimization problem
-#>   objective:    linear
-#>   model sense: max
-#>   dimensions:  47, 47, 103 (nrow, ncol, ncell)
-#>   variables:   42 (B), 5 (S)
+be solved, then the solve() function should be used instead.

+
+ +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with maximum richness objective, $200 budget, and
+# binary decisions
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# compile problem
+o <- compile(p)
+
+# print compiled problem
+print(o)
+#> optimization problem
+#>   objective:    linear
+#>   model sense: max
+#>   dimensions:  47, 47, 103 (nrow, ncol, ncell)
+#>   variables:   42 (B), 5 (S)
+
+
+
-
- - - + diff --git a/docs/reference/constraints.html b/docs/reference/constraints.html index b944c3c..1f26973 100644 --- a/docs/reference/constraints.html +++ b/docs/reference/constraints.html @@ -1,79 +1,13 @@ - - - - - - - -Project prioritization problem constraints — constraints • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Project prioritization problem constraints — constraints • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Project prioritization problem constraints

- Source: R/constraints.R + Source: R/constraints.R
-

A constraint can be added to a project prioritization problem() +

A constraint can be added to a project prioritization problem() to ensure that solutions exhibit a specific characteristic.

- -

Details

- +
+

Details

The following constraints can be added to a project prioritization -problem():

-
- -
add_locked_in_constraints()

Add constraints to ensure +problem():

+
add_locked_in_constraints()
+

Add constraints to ensure that certain actions are prioritized for funding.

-
add_locked_out_constraints()

Add constraints to ensure -that certain actions are not prioritized for funding.

- - -
- -

See also

- -

decisions, objectives, -problem(), solvers, targets, -weights.

-

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
+
add_locked_out_constraints()

+
Add constraints to ensure
+that certain actions are not prioritized for funding.

 
-# build problem with maximum richness objective and $150 budget
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 150) %>%
-     add_binary_decisions()
 
-# print problem
-print(p1)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (150)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# build another problem, and lock in the third action
-p2 <- p1 %>%
-      add_locked_in_constraints(c(3))
 
-# print problem
-print(p2)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (150)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <Locked in actions [1 locked units]>
-#>   solver:          default

-# build another problem, and lock out the second action
-p3 <- p1 %>%
-      add_locked_out_constraints(c(2))
+
+ -# print problem -print(p3) -
#> Project Prioritization Problem -#> actions F1_action, F2_action, F3_action, ... (6 actions) -#> projects F1_project, F2_project, F3_project, ... (6 projects) -#> features F1, F2, F3, ... (5 features) -#> action costs: min: 0, max: 103.22583 -#> project success: min: 0.81379, max: 1 -#> objective: Maximum richness objective [budget (150)] -#> targets: none -#> weights: default -#> decisions Binary decision -#> constraints: <Manually locked actions [1 locked units]> -#> solver: default
-# \dontrun{ -# solve problems -s1 <- solve(p1) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0x57c178c1 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [1e+00, 1e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 1.4456093 -#> Presolve removed 16 rows and 12 columns -#> Presolve time: 0.00s -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> Variable types: 0 continuous, 35 integer (35 binary) -#> Presolved: 31 rows, 35 columns, 65 nonzeros -#> -#> -#> Root relaxation: objective 1.680145e+00, 11 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 1.6801450 1.68015 0.00% - 0s -#> -#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 1.68015 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.680145013696e+00, best bound 1.680145013696e+00, gap 0.0000%
s2 <- solve(p2) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0xbbb75d04 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [1e+00, 1e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 1.4456093 -#> Presolve removed 42 rows and 41 columns -#> Presolve time: 0.00s -#> Presolved: 5 rows, 6 columns, 10 nonzeros -#> Variable types: 0 continuous, 6 integer (6 binary) -#> -#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 1.44561 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.445609277954e+00, best bound 1.445609277954e+00, gap 0.0000%
s3 <- solve(p3) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0xab53517c -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [1e+00, 1e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 2e+02] -#> Found heuristic solution: objective 1.4456093 -#> Presolve removed 22 rows and 19 columns -#> Presolve time: 0.00s -#> Presolved: 25 rows, 28 columns, 52 nonzeros -#> Variable types: 0 continuous, 28 integer (28 binary) -#> Presolved: 25 rows, 28 columns, 52 nonzeros -#> -#> -#> Root relaxation: objective 1.575441e+00, 9 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 1.5754408 1.57544 0.00% - 0s -#> -#> Explored 0 nodes (9 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 1.57544 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.575440809243e+00, best bound 1.575440809243e+00, gap 0.0000%
-# print the actions selected for funding in each of the solutions -print(s1[, sim_actions$name]) -
#> # A tibble: 1 x 6 -#> F1_action F2_action F3_action F4_action F5_action baseline_action -#> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 0 1 0 0 0 1
print(s2[, sim_actions$name]) -
#> # A tibble: 1 x 6 -#> F1_action F2_action F3_action F4_action F5_action baseline_action -#> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 0 0 1 0 0 1
print(s3[, sim_actions$name]) -
#> # A tibble: 1 x 6 -#> F1_action F2_action F3_action F4_action F5_action baseline_action -#> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 0 0 0 0 1
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with maximum richness objective and $150 budget
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 150) %>%
+     add_binary_decisions()
+
+# print problem
+print(p1)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (150)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# build another problem, and lock in the third action
+p2 <- p1 %>%
+      add_locked_in_constraints(c(3))
+
+# print problem
+print(p2)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (150)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <Locked in actions [1 locked units]>
+#>   solver:          default
+
+# build another problem, and lock out the second action
+p3 <- p1 %>%
+      add_locked_out_constraints(c(2))
+
+# print problem
+print(p3)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (150)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <Manually locked actions [1 locked units]>
+#>   solver:          default
+
+# \dontrun{
+# solve problems
+s1 <- solve(p1)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xf97d9094
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.680145e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.6801450    1.68015  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.68015 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.680145013696e+00, best bound 1.680145013696e+00, gap 0.0000%
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xaace6374
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 42 rows and 41 columns
+#> Presolve time: 0.00s
+#> Presolved: 5 rows, 6 columns, 10 nonzeros
+#> Variable types: 0 continuous, 6 integer (6 binary)
+#> 
+#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.44561 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.445609277954e+00, best bound 1.445609277954e+00, gap 0.0000%
+s3 <- solve(p3)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x80197d20
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 22 rows and 19 columns
+#> Presolve time: 0.00s
+#> Presolved: 25 rows, 28 columns, 52 nonzeros
+#> Variable types: 0 continuous, 28 integer (28 binary)
+#> Root relaxation presolved: 25 rows, 28 columns, 52 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.575441e+00, 9 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.5754408    1.57544  0.00%     -    0s
+#> 
+#> Explored 1 nodes (9 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.57544 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.575440809243e+00, best bound 1.575440809243e+00, gap 0.0000%
+
+# print the actions selected for funding in each of the solutions
+print(s1[, sim_actions$name])
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         0         1         0         0         0               1
+print(s2[, sim_actions$name])
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         0         0         1         0         0               1
+print(s3[, sim_actions$name])
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         1         0         0         0         0               1
+# }
+
+
+
- - - - + diff --git a/docs/reference/decisions-1.png b/docs/reference/decisions-1.png index 89a16f5..6c3a587 100644 Binary files a/docs/reference/decisions-1.png and b/docs/reference/decisions-1.png differ diff --git a/docs/reference/decisions.html b/docs/reference/decisions.html index 4093165..0b2e839 100644 --- a/docs/reference/decisions.html +++ b/docs/reference/decisions.html @@ -1,79 +1,13 @@ - - - - - - - -Specify the type of decisions — decisions • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Specify the type of decisions — decisions • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Specify the type of decisions

- Source: R/decisions.R + Source: R/decisions.R
@@ -131,125 +58,126 @@

Specify the type of decisions

- -

Details

- +
+

Details

Please note that only one type of decision is currently supported:

-
- -
add_binary_decisions()

This is the conventional type of decision where management actions are +

add_binary_decisions()
+

This is the conventional type of decision where management actions are either prioritized for funding or not.

-
- -

See also

- -

constraints, objectives, -problem(), solvers, targets, -weights.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with maximum richness objective, $200 budget, and
-# binary decisions
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# \dontrun{
-# solve problem
-s <- solve(p)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xab0d0209
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 2.19038 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%

-# print solution
-print(s)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL  2.19  195.         1         1         0         0         0
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>

-# plot solution
-plot(p, s)
-
# }
-
+ +
+ + +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with maximum richness objective, $200 budget, and
+# binary decisions
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# \dontrun{
+# solve problem
+s <- solve(p)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x193cb636
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.19038 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
+
+# print solution
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  2.19  195.         1       1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution
+plot(p, s)
+
+# }
+
+
+
- - - - + diff --git a/docs/reference/feature_names.html b/docs/reference/feature_names.html index 4d19118..c16b7e0 100644 --- a/docs/reference/feature_names.html +++ b/docs/reference/feature_names.html @@ -1,78 +1,12 @@ - - - - - - - -Feature names — feature_names • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Feature names — feature_names • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Feature names

- Source: R/feature_names.R + Source: R/feature_names.R
@@ -128,79 +55,79 @@

Feature names

Extract the names of the features in an object.

- 
feature_names(x)
-
-# S4 method for ProjectProblem
-feature_names(x)
- -

Arguments

- - - - - - -
x

ProjectProblem.

- -

Value

- -

character feature names.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with default solver
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions() %>%
-     add_default_solver()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]

-# print feature names
-feature_names(p)
-
#> [1] "F1" "F2" "F3" "F4" "F5"
+
+ 
feature_names(x)
+
+# S4 method for ProjectProblem
+feature_names(x)
+
+ +
+

Arguments

+
x
+

ProjectProblem.

+ +
+
+

Value

+ + +

character feature names.

+
+ +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with default solver
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions() %>%
+     add_default_solver()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]
+
+# print feature names
+feature_names(p)
+#> [1] "F1" "F2" "F3" "F4" "F5"
+
+
+
- - - - + diff --git a/docs/reference/figures/README-readme-plot-1.png b/docs/reference/figures/README-readme-plot-1.png index 11b705e..cc5edc7 100644 Binary files a/docs/reference/figures/README-readme-plot-1.png and b/docs/reference/figures/README-readme-plot-1.png differ diff --git a/docs/reference/index.html b/docs/reference/index.html index a323ddc..dd9686a 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -1,75 +1,12 @@ - - - - - - - -Function reference • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Function reference • oppr - - - - - - - - - - - +
-
- -
- -
+

Reference

- - - - - - - - - - -
-

Summary

-

Summary of the package

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+

Summary

+

Summary of the package

+

oppr

oppr: Optimal Project Prioritization

-

Data

-

Simulated datasets and data simulation functions

+
+

Data

+

Simulated datasets and data simulation functions

+

sim_actions sim_projects sim_features sim_tree

Simulated data

+

simulate_ppp_data()

Simulate data for the 'Project Prioritization Protocol'

+

simulate_ptm_data()

Simulate data for 'Priority threat management'

-

Create and solve problems

-

Functions for creating new problems and solving them

+
+

Create and solve problems

+

Functions for creating new problems and solving them

+

problem()

Project prioritization problem

+

solve(<OptimizationProblem>,<Solver>) solve(<ProjectProblem>,<missing>)

Solve

-

Evaluate solutions

-

Functions for evaluating and visualizing solutions to a problem

+
+

Evaluate solutions

+

Functions for evaluating and visualizing solutions to a problem

+

plot(<ProjectProblem>)

Plot a solution to a project prioritization problem

+

plot_feature_persistence()

Plot a bar plot to visualize a project prioritization

+

plot_phylo_persistence()

Plot a phylogram to visualize a project prioritization

+

solution_statistics()

Solution statistics

+

replacement_costs()

Replacement cost

+

project_cost_effectiveness()

Project cost effectiveness

-

Objectives

-

Functions for adding an objective to a problem

+
+

Objectives

+

Functions for adding an objective to a problem

+

objectives

Problem objective

+

add_max_phylo_div_objective()

Add maximum phylogenetic diversity objective

+

add_max_richness_objective()

Add maximum richness objective

+

add_max_targets_met_objective()

Add maximum targets met objective

+

add_min_set_objective()

Add minimum set objective

-

Weights

-

Functions for adding weights to a problem

+
+

Weights

+

Functions for adding weights to a problem

+

weights

Weights

+

add_feature_weights()

Add feature weights

-

Targets

-

Functions for adding targets to a problem

+
+

Targets

+

Functions for adding targets to a problem

+

targets

Targets

+

add_absolute_targets()

Add absolute targets

+

add_manual_targets()

Add manual targets

+

add_relative_targets()

Add relative targets

-

Constraints

-

Functions for adding constraints to a problem

+
+

Constraints

+

Functions for adding constraints to a problem

+

constraints

Project prioritization problem constraints

+

add_locked_in_constraints()

Add locked in constraints

+

add_locked_out_constraints()

Add locked out constraints

+

add_manual_locked_constraints()

Add manually specified locked constraints

-

Decisions

-

Functions for specifying the type of decisions in a problem

+
+

Decisions

+

Functions for specifying the type of decisions in a problem

+

decisions

Specify the type of decisions

+

add_binary_decisions()

Add binary decisions

-

Solvers

-

Functions for specifying how a problem should be solved

+
+

Solvers

+

Functions for specifying how a problem should be solved

+

solvers

Problem solvers

+

add_default_solver()

Add a default solver

+

add_gurobi_solver()

Add a Gurobi solver

+

add_heuristic_solver()

Add a heuristic solver

+

add_lpsolveapi_solver()

Add a lp_solve solver with lpSolveAPI

+

add_lpsymphony_solver()

Add a SYMPHONY solver with lpsymphony

+

add_random_solver()

Add a random solver

+

add_rsymphony_solver()

Add a SYMPHONY solver with Rsymphony

-

Problem manipulation functions

-

Functions for extracting information from problems

+
+

Problem manipulation functions

+

Functions for extracting information from problems

+

feature_names()

Feature names

+

action_names()

Action names

+

project_names()

Project names

+

number_of_features()

Number of features

+

number_of_actions()

Number of actions

+

number_of_projects()

Number of projects

-

Miscellaneous functions

-

Assorted functions distributed with the package

+
+

Miscellaneous functions

+

Assorted functions distributed with the package

+

print(<ProjectProblem>) print(<ProjectModifier>) print(<Id>) print(<Id>) print(<OptimizationProblem>) print(<ScalarParameter>) print(<ArrayParameter>) print(<Solver>)

Print

+

show(<ProjectModifier>) show(<ProjectProblem>) show(<Id>) show(<OptimizationProblem>) show(<Parameter>) show(<Solver>)

Show

-

%>%

+
+

%>% pipe

Pipe operator

-

%T>%

+
+

%T>% tee

Tee operator

+

is.Id() is.Waiver()

Is it?

+

as.Id() as.list(<Parameters>)

Coerce object to another object

+

compile()

Compile a problem

+

branch_matrix()

Branch matrix

-

Class definitions and methods

-

These pages document the package’s internal data structures and functions for manipulating them—they contain information that is really only useful when adding new functionality to the package

+
+

Class definitions and methods

+

These pages document the package’s internal data structures and functions for manipulating them—they contain information that is really only useful when adding new functionality to the package

+

new_id()

Identifier

+

new_waiver()

Waiver

+

pproto()

Create a new pproto object

+

new_optimization_problem()

Optimization problem

+

as.list(<OptimizationProblem>)

Convert OptimizationProblem to list

-

ArrayParameter-class

+
+

ArrayParameter-class ArrayParameter

Array parameter prototype

-

Collection-class

+
+

Collection-class Collection

Collection prototype

-

Constraint-class

+
+

Constraint-class Constraint

Constraint prototype

-

Decision-class

+
+

Decision-class Decision

Decision prototype

-

MiscParameter-class

+
+

MiscParameter-class MiscParameter

Miscellaneous parameter prototype

-

Objective-class

+
+

Objective-class Objective

Objective prototype

-

OptimizationProblem-class

+
+

OptimizationProblem-class OptimizationProblem

Optimization problem class

-

Parameter-class

+
+

Parameter-class Parameter

Parameter class

-

Parameters-class

+
+

Parameters-class Parameters

Parameters class

-

ProjectModifier-class

+
+

ProjectModifier-class ProjectModifier

Conservation problem modifier prototype

-

ProjectProblem-class

+
+

ProjectProblem-class ProjectProblem

Project problem class

-

ScalarParameter-class

+
+

ScalarParameter-class ScalarParameter

Scalar parameter prototype

-

Solver-class

+
+

Solver-class Solver GurobiSolver-class HeuristicSolver-class LpsolveapiSolver-class LpsymphonySolver-class RandomSolver-class RsymphonySolver-class

Solver prototype

-

Target-class

+
+

Target-class Target

Target prototype

-

Weight-class

+
+

Weight-class Weight

Weight prototype

+

nrow() ncol() ncell() modelsense() vtype() obj() pwlobj() A() rhs() sense() lb() ub() col_ids() row_ids() number_of_branches() get_data()

Optimization problem methods

+

nrow(<tbl_df>) ncol(<tbl_df>) as.list(<tbl_df>)

Manipulate tibbles

-

Parameter definitions

-

These pages document the package’s internal data structures for representing different types of variables—they contain information that is really only useful when adding new functionality to the package

+
+

Parameter definitions

+

These pages document the package’s internal data structures for representing different types of variables—they contain information that is really only useful when adding new functionality to the package

+

proportion_parameter_array() binary_parameter_array() integer_parameter_array() numeric_parameter_array()

Array parameters

+

numeric_matrix_parameter() binary_matrix_parameter()

Matrix parameters

+

misc_parameter()

Miscellaneous parameter

+

proportion_parameter() binary_parameter() integer_parameter() numeric_parameter()

Scalar parameters

+

parameters()

Parameters

- +
+
-
- - - + diff --git a/docs/reference/is.html b/docs/reference/is.html index 040cc41..a5e5a45 100644 --- a/docs/reference/is.html +++ b/docs/reference/is.html @@ -1,76 +1,12 @@ - - - - - - - -Is it? — is.Id • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Is it? — is.Id • oppr - - - - - - - - - - - +
-
- -
- -
+

Is it?

- Source: R/Id.R, R/misc.R + Source: R/Id.R, R/misc.R
@@ -126,50 +55,46 @@

Is it?

Test if an object inherits from a class.

- 
is.Id(x)
-
-is.Waiver(x)
+
+ 
is.Id(x)
+
+is.Waiver(x)
+
-

Arguments

- - - - - - -
x

Object.

+
+

Arguments

+
x
+

Object.

-

Value

+
+
+

Value

+ -

logical indicating if it inherits from the class.

+

logical indicating if it inherits from the class.

+
+
- - - - + diff --git a/docs/reference/matrix_parameters.html b/docs/reference/matrix_parameters.html index 5f05b59..0e4ad5a 100644 --- a/docs/reference/matrix_parameters.html +++ b/docs/reference/matrix_parameters.html @@ -1,78 +1,12 @@ - - - - - - - -Matrix parameters — matrix_parameters • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Matrix parameters — matrix_parameters • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Matrix parameters

- Source: R/parameters.R + Source: R/parameters.R
@@ -128,122 +55,130 @@

Matrix parameters

Create a parameter that represents a matrix object.

- 
numeric_matrix_parameter(
-  name,
-  value,
-  lower_limit = .Machine$double.xmin,
-  upper_limit = .Machine$double.xmax,
-  symmetric = FALSE
-)
-
-binary_matrix_parameter(name, value, symmetric = FALSE)
- -

Arguments

- - - - - - - - - - - - - - - - - - - - - - -
name

character name of parameter.

value

matrix object.

lower_limit

numeric values denoting the minimum acceptable +

+ 
numeric_matrix_parameter(
+  name,
+  value,
+  lower_limit = .Machine$double.xmin,
+  upper_limit = .Machine$double.xmax,
+  symmetric = FALSE
+)
+
+binary_matrix_parameter(name, value, symmetric = FALSE)
+
+ +
+

Arguments

+
name
+

character name of parameter.

+ + +
value
+

matrix object.

+ + +
lower_limit
+

numeric values denoting the minimum acceptable value in the matrix. Defaults to the smallest possible number on the -system.

upper_limit

numeric values denoting the maximum acceptable +system.

+ + +
upper_limit
+

numeric values denoting the maximum acceptable value in the matrix. Defaults to the smallest possible number on the -system.

symmetric

logical must the must be matrix be symmetric? -Defaults to FALSE.

- -

Value

- -

MiscParameter object.

- -

Examples

- 
# create matrix
-m <- matrix(runif(9), ncol = 3)
-colnames(m) <- letters[1:3]
-rownames(m) <- letters[1:3]
-
-# create a numeric matrix parameter
-p1 <- numeric_matrix_parameter("m", m)
-print(p1) # print it
-
#> <environment: 0x55de5b5a4120>
-#> attr(,"class")
-#> [1] "MiscParameter" "MiscParameter" "Parameter"     "pproto"       
-#> [5] "proto"         "environment"  
p1$get() # get value
-
#>            a         b         c
-#> a 0.21314931 0.9447748 0.2882372
-#> b 0.21031074 0.2449280 0.8753579
-#> c 0.03952069 0.7811226 0.2957501
p1$id # get id
-
#> id: 851242fb-2a96-417e-89d4-e81e539b2b08
p1$validate(m[, -1]) # check if parameter can be updated
-
#> [1] FALSE
-#> attr(,"msg")
-#> [1] "ncol(m) not equal to ncol(value)"
p1$set(m + 1) # set parameter to new values
-p1$print() # print it again
-
#> [1] "m"

-# create a binary matrix parameter
-m <- matrix(round(runif(9)), ncol = 3)
-colnames(m) <- letters[1:3]
-rownames(m) <- letters[1:3]
-
-# create a binary matrix parameter
-p2 <- binary_matrix_parameter("m", m)
-print(p2) # print it
-
#> <environment: 0x55de4f605b60>
-#> attr(,"class")
-#> [1] "MiscParameter" "MiscParameter" "Parameter"     "pproto"       
-#> [5] "proto"         "environment"  
p2$get() # get value
-
#>   a b c
-#> a 1 1 0
-#> b 1 1 0
-#> c 1 0 1
p2$id # get id
-
#> id: c5bda0bb-13c7-4793-9f00-02dde447d77b
p2$validate(m[, -1]) # check if parameter can be updated
-
#> [1] FALSE
-#> attr(,"msg")
-#> [1] "ncol(m) not equal to ncol(value)"
p2$set(m + 1) # set parameter to new values
-p2$print() # print it again
-
#> [1] "m"
+system.

+ + +
symmetric
+

logical must the must be matrix be symmetric? +Defaults to FALSE.

+ +
+
+

Value

+ + +

MiscParameter object.

+
+ +
+

Examples

+ 
# create matrix
+m <- matrix(runif(9), ncol = 3)
+colnames(m) <- letters[1:3]
+rownames(m) <- letters[1:3]
+
+# create a numeric matrix parameter
+p1 <- numeric_matrix_parameter("m", m)
+print(p1) # print it
+#> <environment: 0x556a1b7c63e0>
+#> attr(,"class")
+#> [1] "MiscParameter" "MiscParameter" "Parameter"     "pproto"       
+#> [5] "proto"         "environment"  
+p1$get() # get value
+#>           a          b         c
+#> a 0.3714649 0.21764370 0.3577770
+#> b 0.5189460 0.05271852 0.3794181
+#> c 0.8149471 0.97241605 0.1247372
+p1$id # get id
+#> id: f91439b7-76b8-4492-9766-f0e19d6e1451
+p1$validate(m[, -1]) # check if parameter can be updated
+#> [1] FALSE
+#> attr(,"msg")
+#> [1] "ncol(m) not equal to ncol(value)"
+p1$set(m + 1) # set parameter to new values
+p1$print() # print it again
+#> [1] "m"
+
+# create a binary matrix parameter
+m <- matrix(round(runif(9)), ncol = 3)
+colnames(m) <- letters[1:3]
+rownames(m) <- letters[1:3]
+
+# create a binary matrix parameter
+p2 <- binary_matrix_parameter("m", m)
+print(p2) # print it
+#> <environment: 0x556a1aa979b0>
+#> attr(,"class")
+#> [1] "MiscParameter" "MiscParameter" "Parameter"     "pproto"       
+#> [5] "proto"         "environment"  
+p2$get() # get value
+#>   a b c
+#> a 1 0 1
+#> b 0 0 1
+#> c 0 0 0
+p2$id # get id
+#> id: 254cfd68-73d1-4ccd-8fc3-0d323205ee46
+p2$validate(m[, -1]) # check if parameter can be updated
+#> [1] FALSE
+#> attr(,"msg")
+#> [1] "ncol(m) not equal to ncol(value)"
+p2$set(m + 1) # set parameter to new values
+p2$print() # print it again
+#> [1] "m"
+
+
+
- - - - + diff --git a/docs/reference/misc_parameter.html b/docs/reference/misc_parameter.html index 79db730..28316ba 100644 --- a/docs/reference/misc_parameter.html +++ b/docs/reference/misc_parameter.html @@ -1,78 +1,12 @@ - - - - - - - -Miscellaneous parameter — misc_parameter • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Miscellaneous parameter — misc_parameter • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Miscellaneous parameter

- Source: R/parameters.R + Source: R/parameters.R
@@ -128,404 +55,413 @@

Miscellaneous parameter

Create a parameter that consists of a miscellaneous object.

- 
misc_parameter(name, value, validator, widget)
+
+ 
misc_parameter(name, value, validator, widget)
+
+ +
+

Arguments

+
name
+

character name of parameter.

-

Arguments

- - - - - - - - - - - - - - - - - - -
name

character name of parameter.

value

object.

validator

function to validate changes to the parameter. This + +

value
+

object.

+ + +
validator
+

function to validate changes to the parameter. This function must have a single argument and return either TRUE or FALSE depending on if the argument is valid candidate for the -parameter.

widget

function to render a shiny widget. This function -should must have a single argument that accepts a valid object and return -a shiny.tag or shiny.tag.list object.

+parameter.

-

Value

-

MiscParameter object.

+
widget
+

function to render a shiny widget. This function +should must have a single argument that accepts a valid object and return +a shiny.tag or shiny.tag.list object.

-

Examples

- 
# load data
-data(iris, mtcars)
+
+
+

Value

+ -# create table parameter can that can be updated to any other object -p1 <- misc_parameter("tbl", iris, - function(x) TRUE, - function(id, x) structure(id, .Class = "shiny.tag")) -print(p1) # print it -
#> <environment: 0x55de5ce0eb50> -#> attr(,"class") -#> [1] "MiscParameter" "MiscParameter" "Parameter" "pproto" -#> [5] "proto" "environment"
p1$get() # get value -
#> Sepal.Length Sepal.Width Petal.Length Petal.Width Species -#> 1 5.1 3.5 1.4 0.2 setosa -#> 2 4.9 3.0 1.4 0.2 setosa -#> 3 4.7 3.2 1.3 0.2 setosa -#> 4 4.6 3.1 1.5 0.2 setosa -#> 5 5.0 3.6 1.4 0.2 setosa -#> 6 5.4 3.9 1.7 0.4 setosa -#> 7 4.6 3.4 1.4 0.3 setosa -#> 8 5.0 3.4 1.5 0.2 setosa -#> 9 4.4 2.9 1.4 0.2 setosa -#> 10 4.9 3.1 1.5 0.1 setosa -#> 11 5.4 3.7 1.5 0.2 setosa -#> 12 4.8 3.4 1.6 0.2 setosa -#> 13 4.8 3.0 1.4 0.1 setosa -#> 14 4.3 3.0 1.1 0.1 setosa -#> 15 5.8 4.0 1.2 0.2 setosa -#> 16 5.7 4.4 1.5 0.4 setosa -#> 17 5.4 3.9 1.3 0.4 setosa -#> 18 5.1 3.5 1.4 0.3 setosa -#> 19 5.7 3.8 1.7 0.3 setosa -#> 20 5.1 3.8 1.5 0.3 setosa -#> 21 5.4 3.4 1.7 0.2 setosa -#> 22 5.1 3.7 1.5 0.4 setosa -#> 23 4.6 3.6 1.0 0.2 setosa -#> 24 5.1 3.3 1.7 0.5 setosa -#> 25 4.8 3.4 1.9 0.2 setosa -#> 26 5.0 3.0 1.6 0.2 setosa -#> 27 5.0 3.4 1.6 0.4 setosa -#> 28 5.2 3.5 1.5 0.2 setosa -#> 29 5.2 3.4 1.4 0.2 setosa -#> 30 4.7 3.2 1.6 0.2 setosa -#> 31 4.8 3.1 1.6 0.2 setosa -#> 32 5.4 3.4 1.5 0.4 setosa -#> 33 5.2 4.1 1.5 0.1 setosa -#> 34 5.5 4.2 1.4 0.2 setosa -#> 35 4.9 3.1 1.5 0.2 setosa -#> 36 5.0 3.2 1.2 0.2 setosa -#> 37 5.5 3.5 1.3 0.2 setosa -#> 38 4.9 3.6 1.4 0.1 setosa -#> 39 4.4 3.0 1.3 0.2 setosa -#> 40 5.1 3.4 1.5 0.2 setosa -#> 41 5.0 3.5 1.3 0.3 setosa -#> 42 4.5 2.3 1.3 0.3 setosa -#> 43 4.4 3.2 1.3 0.2 setosa -#> 44 5.0 3.5 1.6 0.6 setosa -#> 45 5.1 3.8 1.9 0.4 setosa -#> 46 4.8 3.0 1.4 0.3 setosa -#> 47 5.1 3.8 1.6 0.2 setosa -#> 48 4.6 3.2 1.4 0.2 setosa -#> 49 5.3 3.7 1.5 0.2 setosa -#> 50 5.0 3.3 1.4 0.2 setosa -#> 51 7.0 3.2 4.7 1.4 versicolor -#> 52 6.4 3.2 4.5 1.5 versicolor -#> 53 6.9 3.1 4.9 1.5 versicolor -#> 54 5.5 2.3 4.0 1.3 versicolor -#> 55 6.5 2.8 4.6 1.5 versicolor -#> 56 5.7 2.8 4.5 1.3 versicolor -#> 57 6.3 3.3 4.7 1.6 versicolor -#> 58 4.9 2.4 3.3 1.0 versicolor -#> 59 6.6 2.9 4.6 1.3 versicolor -#> 60 5.2 2.7 3.9 1.4 versicolor -#> 61 5.0 2.0 3.5 1.0 versicolor -#> 62 5.9 3.0 4.2 1.5 versicolor -#> 63 6.0 2.2 4.0 1.0 versicolor -#> 64 6.1 2.9 4.7 1.4 versicolor -#> 65 5.6 2.9 3.6 1.3 versicolor -#> 66 6.7 3.1 4.4 1.4 versicolor -#> 67 5.6 3.0 4.5 1.5 versicolor -#> 68 5.8 2.7 4.1 1.0 versicolor -#> 69 6.2 2.2 4.5 1.5 versicolor -#> 70 5.6 2.5 3.9 1.1 versicolor -#> 71 5.9 3.2 4.8 1.8 versicolor -#> 72 6.1 2.8 4.0 1.3 versicolor -#> 73 6.3 2.5 4.9 1.5 versicolor -#> 74 6.1 2.8 4.7 1.2 versicolor -#> 75 6.4 2.9 4.3 1.3 versicolor -#> 76 6.6 3.0 4.4 1.4 versicolor -#> 77 6.8 2.8 4.8 1.4 versicolor -#> 78 6.7 3.0 5.0 1.7 versicolor -#> 79 6.0 2.9 4.5 1.5 versicolor -#> 80 5.7 2.6 3.5 1.0 versicolor -#> 81 5.5 2.4 3.8 1.1 versicolor -#> 82 5.5 2.4 3.7 1.0 versicolor -#> 83 5.8 2.7 3.9 1.2 versicolor -#> 84 6.0 2.7 5.1 1.6 versicolor -#> 85 5.4 3.0 4.5 1.5 versicolor -#> 86 6.0 3.4 4.5 1.6 versicolor -#> 87 6.7 3.1 4.7 1.5 versicolor -#> 88 6.3 2.3 4.4 1.3 versicolor -#> 89 5.6 3.0 4.1 1.3 versicolor -#> 90 5.5 2.5 4.0 1.3 versicolor -#> 91 5.5 2.6 4.4 1.2 versicolor -#> 92 6.1 3.0 4.6 1.4 versicolor -#> 93 5.8 2.6 4.0 1.2 versicolor -#> 94 5.0 2.3 3.3 1.0 versicolor -#> 95 5.6 2.7 4.2 1.3 versicolor -#> 96 5.7 3.0 4.2 1.2 versicolor -#> 97 5.7 2.9 4.2 1.3 versicolor -#> 98 6.2 2.9 4.3 1.3 versicolor -#> 99 5.1 2.5 3.0 1.1 versicolor -#> 100 5.7 2.8 4.1 1.3 versicolor -#> 101 6.3 3.3 6.0 2.5 virginica -#> 102 5.8 2.7 5.1 1.9 virginica -#> 103 7.1 3.0 5.9 2.1 virginica -#> 104 6.3 2.9 5.6 1.8 virginica -#> 105 6.5 3.0 5.8 2.2 virginica -#> 106 7.6 3.0 6.6 2.1 virginica -#> 107 4.9 2.5 4.5 1.7 virginica -#> 108 7.3 2.9 6.3 1.8 virginica -#> 109 6.7 2.5 5.8 1.8 virginica -#> 110 7.2 3.6 6.1 2.5 virginica -#> 111 6.5 3.2 5.1 2.0 virginica -#> 112 6.4 2.7 5.3 1.9 virginica -#> 113 6.8 3.0 5.5 2.1 virginica -#> 114 5.7 2.5 5.0 2.0 virginica -#> 115 5.8 2.8 5.1 2.4 virginica -#> 116 6.4 3.2 5.3 2.3 virginica -#> 117 6.5 3.0 5.5 1.8 virginica -#> 118 7.7 3.8 6.7 2.2 virginica -#> 119 7.7 2.6 6.9 2.3 virginica -#> 120 6.0 2.2 5.0 1.5 virginica -#> 121 6.9 3.2 5.7 2.3 virginica -#> 122 5.6 2.8 4.9 2.0 virginica -#> 123 7.7 2.8 6.7 2.0 virginica -#> 124 6.3 2.7 4.9 1.8 virginica -#> 125 6.7 3.3 5.7 2.1 virginica -#> 126 7.2 3.2 6.0 1.8 virginica -#> 127 6.2 2.8 4.8 1.8 virginica -#> 128 6.1 3.0 4.9 1.8 virginica -#> 129 6.4 2.8 5.6 2.1 virginica -#> 130 7.2 3.0 5.8 1.6 virginica -#> 131 7.4 2.8 6.1 1.9 virginica -#> 132 7.9 3.8 6.4 2.0 virginica -#> 133 6.4 2.8 5.6 2.2 virginica -#> 134 6.3 2.8 5.1 1.5 virginica -#> 135 6.1 2.6 5.6 1.4 virginica -#> 136 7.7 3.0 6.1 2.3 virginica -#> 137 6.3 3.4 5.6 2.4 virginica -#> 138 6.4 3.1 5.5 1.8 virginica -#> 139 6.0 3.0 4.8 1.8 virginica -#> 140 6.9 3.1 5.4 2.1 virginica -#> 141 6.7 3.1 5.6 2.4 virginica -#> 142 6.9 3.1 5.1 2.3 virginica -#> 143 5.8 2.7 5.1 1.9 virginica -#> 144 6.8 3.2 5.9 2.3 virginica -#> 145 6.7 3.3 5.7 2.5 virginica -#> 146 6.7 3.0 5.2 2.3 virginica -#> 147 6.3 2.5 5.0 1.9 virginica -#> 148 6.5 3.0 5.2 2.0 virginica -#> 149 6.2 3.4 5.4 2.3 virginica -#> 150 5.9 3.0 5.1 1.8 virginica
p1$id # get id -
#> id: 9c0b32d3-fee9-4c92-af8d-58251a27b927
p1$validate(mtcars) # check if parameter can be updated -
#> [1] TRUE
p1$set(mtcars) # set parameter to mtcars -p1$print() # print it again -
#> [1] "tbl"
-# create table parameter with validation function that requires -# all values in the first column to be less then 200 and that the -# parameter have the same column names as the iris data set -p2 <- misc_parameter("tbl2", iris, - function(x) all(names(x) %in% names(iris)) && - all(x[[1]] < 200), - function(id, x) structure(id, .Class = "shiny.tag")) -print(p2) # print it -
#> <environment: 0x55de4d19a3c0> -#> attr(,"class") -#> [1] "MiscParameter" "MiscParameter" "Parameter" "pproto" -#> [5] "proto" "environment"
p2$get() # get value -
#> Sepal.Length Sepal.Width Petal.Length Petal.Width Species -#> 1 5.1 3.5 1.4 0.2 setosa -#> 2 4.9 3.0 1.4 0.2 setosa -#> 3 4.7 3.2 1.3 0.2 setosa -#> 4 4.6 3.1 1.5 0.2 setosa -#> 5 5.0 3.6 1.4 0.2 setosa -#> 6 5.4 3.9 1.7 0.4 setosa -#> 7 4.6 3.4 1.4 0.3 setosa -#> 8 5.0 3.4 1.5 0.2 setosa -#> 9 4.4 2.9 1.4 0.2 setosa -#> 10 4.9 3.1 1.5 0.1 setosa -#> 11 5.4 3.7 1.5 0.2 setosa -#> 12 4.8 3.4 1.6 0.2 setosa -#> 13 4.8 3.0 1.4 0.1 setosa -#> 14 4.3 3.0 1.1 0.1 setosa -#> 15 5.8 4.0 1.2 0.2 setosa -#> 16 5.7 4.4 1.5 0.4 setosa -#> 17 5.4 3.9 1.3 0.4 setosa -#> 18 5.1 3.5 1.4 0.3 setosa -#> 19 5.7 3.8 1.7 0.3 setosa -#> 20 5.1 3.8 1.5 0.3 setosa -#> 21 5.4 3.4 1.7 0.2 setosa -#> 22 5.1 3.7 1.5 0.4 setosa -#> 23 4.6 3.6 1.0 0.2 setosa -#> 24 5.1 3.3 1.7 0.5 setosa -#> 25 4.8 3.4 1.9 0.2 setosa -#> 26 5.0 3.0 1.6 0.2 setosa -#> 27 5.0 3.4 1.6 0.4 setosa -#> 28 5.2 3.5 1.5 0.2 setosa -#> 29 5.2 3.4 1.4 0.2 setosa -#> 30 4.7 3.2 1.6 0.2 setosa -#> 31 4.8 3.1 1.6 0.2 setosa -#> 32 5.4 3.4 1.5 0.4 setosa -#> 33 5.2 4.1 1.5 0.1 setosa -#> 34 5.5 4.2 1.4 0.2 setosa -#> 35 4.9 3.1 1.5 0.2 setosa -#> 36 5.0 3.2 1.2 0.2 setosa -#> 37 5.5 3.5 1.3 0.2 setosa -#> 38 4.9 3.6 1.4 0.1 setosa -#> 39 4.4 3.0 1.3 0.2 setosa -#> 40 5.1 3.4 1.5 0.2 setosa -#> 41 5.0 3.5 1.3 0.3 setosa -#> 42 4.5 2.3 1.3 0.3 setosa -#> 43 4.4 3.2 1.3 0.2 setosa -#> 44 5.0 3.5 1.6 0.6 setosa -#> 45 5.1 3.8 1.9 0.4 setosa -#> 46 4.8 3.0 1.4 0.3 setosa -#> 47 5.1 3.8 1.6 0.2 setosa -#> 48 4.6 3.2 1.4 0.2 setosa -#> 49 5.3 3.7 1.5 0.2 setosa -#> 50 5.0 3.3 1.4 0.2 setosa -#> 51 7.0 3.2 4.7 1.4 versicolor -#> 52 6.4 3.2 4.5 1.5 versicolor -#> 53 6.9 3.1 4.9 1.5 versicolor -#> 54 5.5 2.3 4.0 1.3 versicolor -#> 55 6.5 2.8 4.6 1.5 versicolor -#> 56 5.7 2.8 4.5 1.3 versicolor -#> 57 6.3 3.3 4.7 1.6 versicolor -#> 58 4.9 2.4 3.3 1.0 versicolor -#> 59 6.6 2.9 4.6 1.3 versicolor -#> 60 5.2 2.7 3.9 1.4 versicolor -#> 61 5.0 2.0 3.5 1.0 versicolor -#> 62 5.9 3.0 4.2 1.5 versicolor -#> 63 6.0 2.2 4.0 1.0 versicolor -#> 64 6.1 2.9 4.7 1.4 versicolor -#> 65 5.6 2.9 3.6 1.3 versicolor -#> 66 6.7 3.1 4.4 1.4 versicolor -#> 67 5.6 3.0 4.5 1.5 versicolor -#> 68 5.8 2.7 4.1 1.0 versicolor -#> 69 6.2 2.2 4.5 1.5 versicolor -#> 70 5.6 2.5 3.9 1.1 versicolor -#> 71 5.9 3.2 4.8 1.8 versicolor -#> 72 6.1 2.8 4.0 1.3 versicolor -#> 73 6.3 2.5 4.9 1.5 versicolor -#> 74 6.1 2.8 4.7 1.2 versicolor -#> 75 6.4 2.9 4.3 1.3 versicolor -#> 76 6.6 3.0 4.4 1.4 versicolor -#> 77 6.8 2.8 4.8 1.4 versicolor -#> 78 6.7 3.0 5.0 1.7 versicolor -#> 79 6.0 2.9 4.5 1.5 versicolor -#> 80 5.7 2.6 3.5 1.0 versicolor -#> 81 5.5 2.4 3.8 1.1 versicolor -#> 82 5.5 2.4 3.7 1.0 versicolor -#> 83 5.8 2.7 3.9 1.2 versicolor -#> 84 6.0 2.7 5.1 1.6 versicolor -#> 85 5.4 3.0 4.5 1.5 versicolor -#> 86 6.0 3.4 4.5 1.6 versicolor -#> 87 6.7 3.1 4.7 1.5 versicolor -#> 88 6.3 2.3 4.4 1.3 versicolor -#> 89 5.6 3.0 4.1 1.3 versicolor -#> 90 5.5 2.5 4.0 1.3 versicolor -#> 91 5.5 2.6 4.4 1.2 versicolor -#> 92 6.1 3.0 4.6 1.4 versicolor -#> 93 5.8 2.6 4.0 1.2 versicolor -#> 94 5.0 2.3 3.3 1.0 versicolor -#> 95 5.6 2.7 4.2 1.3 versicolor -#> 96 5.7 3.0 4.2 1.2 versicolor -#> 97 5.7 2.9 4.2 1.3 versicolor -#> 98 6.2 2.9 4.3 1.3 versicolor -#> 99 5.1 2.5 3.0 1.1 versicolor -#> 100 5.7 2.8 4.1 1.3 versicolor -#> 101 6.3 3.3 6.0 2.5 virginica -#> 102 5.8 2.7 5.1 1.9 virginica -#> 103 7.1 3.0 5.9 2.1 virginica -#> 104 6.3 2.9 5.6 1.8 virginica -#> 105 6.5 3.0 5.8 2.2 virginica -#> 106 7.6 3.0 6.6 2.1 virginica -#> 107 4.9 2.5 4.5 1.7 virginica -#> 108 7.3 2.9 6.3 1.8 virginica -#> 109 6.7 2.5 5.8 1.8 virginica -#> 110 7.2 3.6 6.1 2.5 virginica -#> 111 6.5 3.2 5.1 2.0 virginica -#> 112 6.4 2.7 5.3 1.9 virginica -#> 113 6.8 3.0 5.5 2.1 virginica -#> 114 5.7 2.5 5.0 2.0 virginica -#> 115 5.8 2.8 5.1 2.4 virginica -#> 116 6.4 3.2 5.3 2.3 virginica -#> 117 6.5 3.0 5.5 1.8 virginica -#> 118 7.7 3.8 6.7 2.2 virginica -#> 119 7.7 2.6 6.9 2.3 virginica -#> 120 6.0 2.2 5.0 1.5 virginica -#> 121 6.9 3.2 5.7 2.3 virginica -#> 122 5.6 2.8 4.9 2.0 virginica -#> 123 7.7 2.8 6.7 2.0 virginica -#> 124 6.3 2.7 4.9 1.8 virginica -#> 125 6.7 3.3 5.7 2.1 virginica -#> 126 7.2 3.2 6.0 1.8 virginica -#> 127 6.2 2.8 4.8 1.8 virginica -#> 128 6.1 3.0 4.9 1.8 virginica -#> 129 6.4 2.8 5.6 2.1 virginica -#> 130 7.2 3.0 5.8 1.6 virginica -#> 131 7.4 2.8 6.1 1.9 virginica -#> 132 7.9 3.8 6.4 2.0 virginica -#> 133 6.4 2.8 5.6 2.2 virginica -#> 134 6.3 2.8 5.1 1.5 virginica -#> 135 6.1 2.6 5.6 1.4 virginica -#> 136 7.7 3.0 6.1 2.3 virginica -#> 137 6.3 3.4 5.6 2.4 virginica -#> 138 6.4 3.1 5.5 1.8 virginica -#> 139 6.0 3.0 4.8 1.8 virginica -#> 140 6.9 3.1 5.4 2.1 virginica -#> 141 6.7 3.1 5.6 2.4 virginica -#> 142 6.9 3.1 5.1 2.3 virginica -#> 143 5.8 2.7 5.1 1.9 virginica -#> 144 6.8 3.2 5.9 2.3 virginica -#> 145 6.7 3.3 5.7 2.5 virginica -#> 146 6.7 3.0 5.2 2.3 virginica -#> 147 6.3 2.5 5.0 1.9 virginica -#> 148 6.5 3.0 5.2 2.0 virginica -#> 149 6.2 3.4 5.4 2.3 virginica -#> 150 5.9 3.0 5.1 1.8 virginica
p2$id # get id -
#> id: 4fd534e2-37a4-439c-aa1e-dbf9f48a145d
p2$validate(mtcars) # check if parameter can be updated -
#> [1] FALSE
iris2 <- iris; iris2[1,1] <- 300 # create updated iris data set -p2$validate(iris2) # check if parameter can be updated -
#> [1] FALSE
iris3 <- iris; iris2[1,1] <- 100 # create updated iris data set -p2$set(iris3) # set parameter to iris3 -p2$print() # print it again -
#> [1] "tbl2"
-
+

MiscParameter object.

+
+ +
+

Examples

+ 
# load data
+data(iris, mtcars)
+
+# create table parameter can that can be updated to any other object
+p1 <- misc_parameter("tbl", iris,
+                     function(x) TRUE,
+                     function(id, x) structure(id, .Class = "shiny.tag"))
+print(p1) # print it
+#> <environment: 0x556a1f2b1d20>
+#> attr(,"class")
+#> [1] "MiscParameter" "MiscParameter" "Parameter"     "pproto"       
+#> [5] "proto"         "environment"  
+p1$get() # get value
+#>     Sepal.Length Sepal.Width Petal.Length Petal.Width    Species
+#> 1            5.1         3.5          1.4         0.2     setosa
+#> 2            4.9         3.0          1.4         0.2     setosa
+#> 3            4.7         3.2          1.3         0.2     setosa
+#> 4            4.6         3.1          1.5         0.2     setosa
+#> 5            5.0         3.6          1.4         0.2     setosa
+#> 6            5.4         3.9          1.7         0.4     setosa
+#> 7            4.6         3.4          1.4         0.3     setosa
+#> 8            5.0         3.4          1.5         0.2     setosa
+#> 9            4.4         2.9          1.4         0.2     setosa
+#> 10           4.9         3.1          1.5         0.1     setosa
+#> 11           5.4         3.7          1.5         0.2     setosa
+#> 12           4.8         3.4          1.6         0.2     setosa
+#> 13           4.8         3.0          1.4         0.1     setosa
+#> 14           4.3         3.0          1.1         0.1     setosa
+#> 15           5.8         4.0          1.2         0.2     setosa
+#> 16           5.7         4.4          1.5         0.4     setosa
+#> 17           5.4         3.9          1.3         0.4     setosa
+#> 18           5.1         3.5          1.4         0.3     setosa
+#> 19           5.7         3.8          1.7         0.3     setosa
+#> 20           5.1         3.8          1.5         0.3     setosa
+#> 21           5.4         3.4          1.7         0.2     setosa
+#> 22           5.1         3.7          1.5         0.4     setosa
+#> 23           4.6         3.6          1.0         0.2     setosa
+#> 24           5.1         3.3          1.7         0.5     setosa
+#> 25           4.8         3.4          1.9         0.2     setosa
+#> 26           5.0         3.0          1.6         0.2     setosa
+#> 27           5.0         3.4          1.6         0.4     setosa
+#> 28           5.2         3.5          1.5         0.2     setosa
+#> 29           5.2         3.4          1.4         0.2     setosa
+#> 30           4.7         3.2          1.6         0.2     setosa
+#> 31           4.8         3.1          1.6         0.2     setosa
+#> 32           5.4         3.4          1.5         0.4     setosa
+#> 33           5.2         4.1          1.5         0.1     setosa
+#> 34           5.5         4.2          1.4         0.2     setosa
+#> 35           4.9         3.1          1.5         0.2     setosa
+#> 36           5.0         3.2          1.2         0.2     setosa
+#> 37           5.5         3.5          1.3         0.2     setosa
+#> 38           4.9         3.6          1.4         0.1     setosa
+#> 39           4.4         3.0          1.3         0.2     setosa
+#> 40           5.1         3.4          1.5         0.2     setosa
+#> 41           5.0         3.5          1.3         0.3     setosa
+#> 42           4.5         2.3          1.3         0.3     setosa
+#> 43           4.4         3.2          1.3         0.2     setosa
+#> 44           5.0         3.5          1.6         0.6     setosa
+#> 45           5.1         3.8          1.9         0.4     setosa
+#> 46           4.8         3.0          1.4         0.3     setosa
+#> 47           5.1         3.8          1.6         0.2     setosa
+#> 48           4.6         3.2          1.4         0.2     setosa
+#> 49           5.3         3.7          1.5         0.2     setosa
+#> 50           5.0         3.3          1.4         0.2     setosa
+#> 51           7.0         3.2          4.7         1.4 versicolor
+#> 52           6.4         3.2          4.5         1.5 versicolor
+#> 53           6.9         3.1          4.9         1.5 versicolor
+#> 54           5.5         2.3          4.0         1.3 versicolor
+#> 55           6.5         2.8          4.6         1.5 versicolor
+#> 56           5.7         2.8          4.5         1.3 versicolor
+#> 57           6.3         3.3          4.7         1.6 versicolor
+#> 58           4.9         2.4          3.3         1.0 versicolor
+#> 59           6.6         2.9          4.6         1.3 versicolor
+#> 60           5.2         2.7          3.9         1.4 versicolor
+#> 61           5.0         2.0          3.5         1.0 versicolor
+#> 62           5.9         3.0          4.2         1.5 versicolor
+#> 63           6.0         2.2          4.0         1.0 versicolor
+#> 64           6.1         2.9          4.7         1.4 versicolor
+#> 65           5.6         2.9          3.6         1.3 versicolor
+#> 66           6.7         3.1          4.4         1.4 versicolor
+#> 67           5.6         3.0          4.5         1.5 versicolor
+#> 68           5.8         2.7          4.1         1.0 versicolor
+#> 69           6.2         2.2          4.5         1.5 versicolor
+#> 70           5.6         2.5          3.9         1.1 versicolor
+#> 71           5.9         3.2          4.8         1.8 versicolor
+#> 72           6.1         2.8          4.0         1.3 versicolor
+#> 73           6.3         2.5          4.9         1.5 versicolor
+#> 74           6.1         2.8          4.7         1.2 versicolor
+#> 75           6.4         2.9          4.3         1.3 versicolor
+#> 76           6.6         3.0          4.4         1.4 versicolor
+#> 77           6.8         2.8          4.8         1.4 versicolor
+#> 78           6.7         3.0          5.0         1.7 versicolor
+#> 79           6.0         2.9          4.5         1.5 versicolor
+#> 80           5.7         2.6          3.5         1.0 versicolor
+#> 81           5.5         2.4          3.8         1.1 versicolor
+#> 82           5.5         2.4          3.7         1.0 versicolor
+#> 83           5.8         2.7          3.9         1.2 versicolor
+#> 84           6.0         2.7          5.1         1.6 versicolor
+#> 85           5.4         3.0          4.5         1.5 versicolor
+#> 86           6.0         3.4          4.5         1.6 versicolor
+#> 87           6.7         3.1          4.7         1.5 versicolor
+#> 88           6.3         2.3          4.4         1.3 versicolor
+#> 89           5.6         3.0          4.1         1.3 versicolor
+#> 90           5.5         2.5          4.0         1.3 versicolor
+#> 91           5.5         2.6          4.4         1.2 versicolor
+#> 92           6.1         3.0          4.6         1.4 versicolor
+#> 93           5.8         2.6          4.0         1.2 versicolor
+#> 94           5.0         2.3          3.3         1.0 versicolor
+#> 95           5.6         2.7          4.2         1.3 versicolor
+#> 96           5.7         3.0          4.2         1.2 versicolor
+#> 97           5.7         2.9          4.2         1.3 versicolor
+#> 98           6.2         2.9          4.3         1.3 versicolor
+#> 99           5.1         2.5          3.0         1.1 versicolor
+#> 100          5.7         2.8          4.1         1.3 versicolor
+#> 101          6.3         3.3          6.0         2.5  virginica
+#> 102          5.8         2.7          5.1         1.9  virginica
+#> 103          7.1         3.0          5.9         2.1  virginica
+#> 104          6.3         2.9          5.6         1.8  virginica
+#> 105          6.5         3.0          5.8         2.2  virginica
+#> 106          7.6         3.0          6.6         2.1  virginica
+#> 107          4.9         2.5          4.5         1.7  virginica
+#> 108          7.3         2.9          6.3         1.8  virginica
+#> 109          6.7         2.5          5.8         1.8  virginica
+#> 110          7.2         3.6          6.1         2.5  virginica
+#> 111          6.5         3.2          5.1         2.0  virginica
+#> 112          6.4         2.7          5.3         1.9  virginica
+#> 113          6.8         3.0          5.5         2.1  virginica
+#> 114          5.7         2.5          5.0         2.0  virginica
+#> 115          5.8         2.8          5.1         2.4  virginica
+#> 116          6.4         3.2          5.3         2.3  virginica
+#> 117          6.5         3.0          5.5         1.8  virginica
+#> 118          7.7         3.8          6.7         2.2  virginica
+#> 119          7.7         2.6          6.9         2.3  virginica
+#> 120          6.0         2.2          5.0         1.5  virginica
+#> 121          6.9         3.2          5.7         2.3  virginica
+#> 122          5.6         2.8          4.9         2.0  virginica
+#> 123          7.7         2.8          6.7         2.0  virginica
+#> 124          6.3         2.7          4.9         1.8  virginica
+#> 125          6.7         3.3          5.7         2.1  virginica
+#> 126          7.2         3.2          6.0         1.8  virginica
+#> 127          6.2         2.8          4.8         1.8  virginica
+#> 128          6.1         3.0          4.9         1.8  virginica
+#> 129          6.4         2.8          5.6         2.1  virginica
+#> 130          7.2         3.0          5.8         1.6  virginica
+#> 131          7.4         2.8          6.1         1.9  virginica
+#> 132          7.9         3.8          6.4         2.0  virginica
+#> 133          6.4         2.8          5.6         2.2  virginica
+#> 134          6.3         2.8          5.1         1.5  virginica
+#> 135          6.1         2.6          5.6         1.4  virginica
+#> 136          7.7         3.0          6.1         2.3  virginica
+#> 137          6.3         3.4          5.6         2.4  virginica
+#> 138          6.4         3.1          5.5         1.8  virginica
+#> 139          6.0         3.0          4.8         1.8  virginica
+#> 140          6.9         3.1          5.4         2.1  virginica
+#> 141          6.7         3.1          5.6         2.4  virginica
+#> 142          6.9         3.1          5.1         2.3  virginica
+#> 143          5.8         2.7          5.1         1.9  virginica
+#> 144          6.8         3.2          5.9         2.3  virginica
+#> 145          6.7         3.3          5.7         2.5  virginica
+#> 146          6.7         3.0          5.2         2.3  virginica
+#> 147          6.3         2.5          5.0         1.9  virginica
+#> 148          6.5         3.0          5.2         2.0  virginica
+#> 149          6.2         3.4          5.4         2.3  virginica
+#> 150          5.9         3.0          5.1         1.8  virginica
+p1$id # get id
+#> id: 186a5ebe-11b6-4645-a682-399bcf7f8cf4
+p1$validate(mtcars) # check if parameter can be updated
+#> [1] TRUE
+p1$set(mtcars) # set parameter to mtcars
+p1$print() # print it again
+#> [1] "tbl"
+
+# create table parameter with validation function that requires
+# all values in the first column to be less then 200 and that the
+# parameter have the same column names as the iris data set
+p2 <- misc_parameter("tbl2", iris,
+                     function(x) all(names(x) %in% names(iris)) &&
+                                 all(x[[1]] < 200),
+                     function(id, x) structure(id, .Class = "shiny.tag"))
+print(p2) # print it
+#> <environment: 0x556a227c5068>
+#> attr(,"class")
+#> [1] "MiscParameter" "MiscParameter" "Parameter"     "pproto"       
+#> [5] "proto"         "environment"  
+p2$get() # get value
+#>     Sepal.Length Sepal.Width Petal.Length Petal.Width    Species
+#> 1            5.1         3.5          1.4         0.2     setosa
+#> 2            4.9         3.0          1.4         0.2     setosa
+#> 3            4.7         3.2          1.3         0.2     setosa
+#> 4            4.6         3.1          1.5         0.2     setosa
+#> 5            5.0         3.6          1.4         0.2     setosa
+#> 6            5.4         3.9          1.7         0.4     setosa
+#> 7            4.6         3.4          1.4         0.3     setosa
+#> 8            5.0         3.4          1.5         0.2     setosa
+#> 9            4.4         2.9          1.4         0.2     setosa
+#> 10           4.9         3.1          1.5         0.1     setosa
+#> 11           5.4         3.7          1.5         0.2     setosa
+#> 12           4.8         3.4          1.6         0.2     setosa
+#> 13           4.8         3.0          1.4         0.1     setosa
+#> 14           4.3         3.0          1.1         0.1     setosa
+#> 15           5.8         4.0          1.2         0.2     setosa
+#> 16           5.7         4.4          1.5         0.4     setosa
+#> 17           5.4         3.9          1.3         0.4     setosa
+#> 18           5.1         3.5          1.4         0.3     setosa
+#> 19           5.7         3.8          1.7         0.3     setosa
+#> 20           5.1         3.8          1.5         0.3     setosa
+#> 21           5.4         3.4          1.7         0.2     setosa
+#> 22           5.1         3.7          1.5         0.4     setosa
+#> 23           4.6         3.6          1.0         0.2     setosa
+#> 24           5.1         3.3          1.7         0.5     setosa
+#> 25           4.8         3.4          1.9         0.2     setosa
+#> 26           5.0         3.0          1.6         0.2     setosa
+#> 27           5.0         3.4          1.6         0.4     setosa
+#> 28           5.2         3.5          1.5         0.2     setosa
+#> 29           5.2         3.4          1.4         0.2     setosa
+#> 30           4.7         3.2          1.6         0.2     setosa
+#> 31           4.8         3.1          1.6         0.2     setosa
+#> 32           5.4         3.4          1.5         0.4     setosa
+#> 33           5.2         4.1          1.5         0.1     setosa
+#> 34           5.5         4.2          1.4         0.2     setosa
+#> 35           4.9         3.1          1.5         0.2     setosa
+#> 36           5.0         3.2          1.2         0.2     setosa
+#> 37           5.5         3.5          1.3         0.2     setosa
+#> 38           4.9         3.6          1.4         0.1     setosa
+#> 39           4.4         3.0          1.3         0.2     setosa
+#> 40           5.1         3.4          1.5         0.2     setosa
+#> 41           5.0         3.5          1.3         0.3     setosa
+#> 42           4.5         2.3          1.3         0.3     setosa
+#> 43           4.4         3.2          1.3         0.2     setosa
+#> 44           5.0         3.5          1.6         0.6     setosa
+#> 45           5.1         3.8          1.9         0.4     setosa
+#> 46           4.8         3.0          1.4         0.3     setosa
+#> 47           5.1         3.8          1.6         0.2     setosa
+#> 48           4.6         3.2          1.4         0.2     setosa
+#> 49           5.3         3.7          1.5         0.2     setosa
+#> 50           5.0         3.3          1.4         0.2     setosa
+#> 51           7.0         3.2          4.7         1.4 versicolor
+#> 52           6.4         3.2          4.5         1.5 versicolor
+#> 53           6.9         3.1          4.9         1.5 versicolor
+#> 54           5.5         2.3          4.0         1.3 versicolor
+#> 55           6.5         2.8          4.6         1.5 versicolor
+#> 56           5.7         2.8          4.5         1.3 versicolor
+#> 57           6.3         3.3          4.7         1.6 versicolor
+#> 58           4.9         2.4          3.3         1.0 versicolor
+#> 59           6.6         2.9          4.6         1.3 versicolor
+#> 60           5.2         2.7          3.9         1.4 versicolor
+#> 61           5.0         2.0          3.5         1.0 versicolor
+#> 62           5.9         3.0          4.2         1.5 versicolor
+#> 63           6.0         2.2          4.0         1.0 versicolor
+#> 64           6.1         2.9          4.7         1.4 versicolor
+#> 65           5.6         2.9          3.6         1.3 versicolor
+#> 66           6.7         3.1          4.4         1.4 versicolor
+#> 67           5.6         3.0          4.5         1.5 versicolor
+#> 68           5.8         2.7          4.1         1.0 versicolor
+#> 69           6.2         2.2          4.5         1.5 versicolor
+#> 70           5.6         2.5          3.9         1.1 versicolor
+#> 71           5.9         3.2          4.8         1.8 versicolor
+#> 72           6.1         2.8          4.0         1.3 versicolor
+#> 73           6.3         2.5          4.9         1.5 versicolor
+#> 74           6.1         2.8          4.7         1.2 versicolor
+#> 75           6.4         2.9          4.3         1.3 versicolor
+#> 76           6.6         3.0          4.4         1.4 versicolor
+#> 77           6.8         2.8          4.8         1.4 versicolor
+#> 78           6.7         3.0          5.0         1.7 versicolor
+#> 79           6.0         2.9          4.5         1.5 versicolor
+#> 80           5.7         2.6          3.5         1.0 versicolor
+#> 81           5.5         2.4          3.8         1.1 versicolor
+#> 82           5.5         2.4          3.7         1.0 versicolor
+#> 83           5.8         2.7          3.9         1.2 versicolor
+#> 84           6.0         2.7          5.1         1.6 versicolor
+#> 85           5.4         3.0          4.5         1.5 versicolor
+#> 86           6.0         3.4          4.5         1.6 versicolor
+#> 87           6.7         3.1          4.7         1.5 versicolor
+#> 88           6.3         2.3          4.4         1.3 versicolor
+#> 89           5.6         3.0          4.1         1.3 versicolor
+#> 90           5.5         2.5          4.0         1.3 versicolor
+#> 91           5.5         2.6          4.4         1.2 versicolor
+#> 92           6.1         3.0          4.6         1.4 versicolor
+#> 93           5.8         2.6          4.0         1.2 versicolor
+#> 94           5.0         2.3          3.3         1.0 versicolor
+#> 95           5.6         2.7          4.2         1.3 versicolor
+#> 96           5.7         3.0          4.2         1.2 versicolor
+#> 97           5.7         2.9          4.2         1.3 versicolor
+#> 98           6.2         2.9          4.3         1.3 versicolor
+#> 99           5.1         2.5          3.0         1.1 versicolor
+#> 100          5.7         2.8          4.1         1.3 versicolor
+#> 101          6.3         3.3          6.0         2.5  virginica
+#> 102          5.8         2.7          5.1         1.9  virginica
+#> 103          7.1         3.0          5.9         2.1  virginica
+#> 104          6.3         2.9          5.6         1.8  virginica
+#> 105          6.5         3.0          5.8         2.2  virginica
+#> 106          7.6         3.0          6.6         2.1  virginica
+#> 107          4.9         2.5          4.5         1.7  virginica
+#> 108          7.3         2.9          6.3         1.8  virginica
+#> 109          6.7         2.5          5.8         1.8  virginica
+#> 110          7.2         3.6          6.1         2.5  virginica
+#> 111          6.5         3.2          5.1         2.0  virginica
+#> 112          6.4         2.7          5.3         1.9  virginica
+#> 113          6.8         3.0          5.5         2.1  virginica
+#> 114          5.7         2.5          5.0         2.0  virginica
+#> 115          5.8         2.8          5.1         2.4  virginica
+#> 116          6.4         3.2          5.3         2.3  virginica
+#> 117          6.5         3.0          5.5         1.8  virginica
+#> 118          7.7         3.8          6.7         2.2  virginica
+#> 119          7.7         2.6          6.9         2.3  virginica
+#> 120          6.0         2.2          5.0         1.5  virginica
+#> 121          6.9         3.2          5.7         2.3  virginica
+#> 122          5.6         2.8          4.9         2.0  virginica
+#> 123          7.7         2.8          6.7         2.0  virginica
+#> 124          6.3         2.7          4.9         1.8  virginica
+#> 125          6.7         3.3          5.7         2.1  virginica
+#> 126          7.2         3.2          6.0         1.8  virginica
+#> 127          6.2         2.8          4.8         1.8  virginica
+#> 128          6.1         3.0          4.9         1.8  virginica
+#> 129          6.4         2.8          5.6         2.1  virginica
+#> 130          7.2         3.0          5.8         1.6  virginica
+#> 131          7.4         2.8          6.1         1.9  virginica
+#> 132          7.9         3.8          6.4         2.0  virginica
+#> 133          6.4         2.8          5.6         2.2  virginica
+#> 134          6.3         2.8          5.1         1.5  virginica
+#> 135          6.1         2.6          5.6         1.4  virginica
+#> 136          7.7         3.0          6.1         2.3  virginica
+#> 137          6.3         3.4          5.6         2.4  virginica
+#> 138          6.4         3.1          5.5         1.8  virginica
+#> 139          6.0         3.0          4.8         1.8  virginica
+#> 140          6.9         3.1          5.4         2.1  virginica
+#> 141          6.7         3.1          5.6         2.4  virginica
+#> 142          6.9         3.1          5.1         2.3  virginica
+#> 143          5.8         2.7          5.1         1.9  virginica
+#> 144          6.8         3.2          5.9         2.3  virginica
+#> 145          6.7         3.3          5.7         2.5  virginica
+#> 146          6.7         3.0          5.2         2.3  virginica
+#> 147          6.3         2.5          5.0         1.9  virginica
+#> 148          6.5         3.0          5.2         2.0  virginica
+#> 149          6.2         3.4          5.4         2.3  virginica
+#> 150          5.9         3.0          5.1         1.8  virginica
+p2$id # get id
+#> id: 1f26bfc8-ed3c-4480-83e7-2af9b8900836
+p2$validate(mtcars) # check if parameter can be updated
+#> [1] FALSE
+iris2 <- iris; iris2[1,1] <- 300 # create updated iris data set
+p2$validate(iris2) # check if parameter can be updated
+#> [1] FALSE
+iris3 <- iris; iris2[1,1] <- 100 # create updated iris data set
+p2$set(iris3) # set parameter to iris3
+p2$print() # print it again
+#> [1] "tbl2"
+
+
+
+
- - - - + diff --git a/docs/reference/new_id.html b/docs/reference/new_id.html index 22167e5..b033351 100644 --- a/docs/reference/new_id.html +++ b/docs/reference/new_id.html @@ -1,78 +1,12 @@ - - - - - - - -Identifier — new_id • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Identifier — new_id • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Identifier

- Source: R/Id.R + Source: R/Id.R
@@ -128,60 +55,65 @@

Identifier

Generate a new unique identifier.

- 
new_id()
- - -

Value

- -

Id object.

-

Details

- -

Identifiers are made using the uuid::UUIDgenerate().

-

See also

+
+ 
new_id()
+
-

uuid::UUIDgenerate().

+
+

Value

+ -

Examples

- 
# create new id
-i <- new_id()
+
Id object.

+    

+    

+    
Details

+    
Identifiers are made using the uuid::UUIDgenerate().

+    

+    

+    
See also

+    
uuid::UUIDgenerate().

+    

 
-# print id
-print(i)
-
#> id: ebf951f3-0393-43d3-a27d-308d191b2418
-# convert to character -as.character(i) -
#> [1] "ebf951f3-0393-43d3-a27d-308d191b2418"
-# check if it is an Id object -is.Id(i) -
#> [1] TRUE
-
+
+

Examples

+ 
# create new id
+i <- new_id()
+
+# print id
+print(i)
+#> id: 4fd55b80-f1e8-48ab-8aa1-bd6c3264288d
+
+# convert to character
+as.character(i)
+#> [1] "4fd55b80-f1e8-48ab-8aa1-bd6c3264288d"
+
+# check if it is an Id object
+is.Id(i)
+#> [1] TRUE
+
+
+
+
- - - - + diff --git a/docs/reference/new_optimization_problem.html b/docs/reference/new_optimization_problem.html index 7c0775a..ab93b23 100644 --- a/docs/reference/new_optimization_problem.html +++ b/docs/reference/new_optimization_problem.html @@ -1,78 +1,12 @@ - - - - - - - -Optimization problem — new_optimization_problem • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Optimization problem — new_optimization_problem • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Optimization problem

- Source: R/new_optimization_problem.R + Source: R/new_optimization_problem.R
-

Generate a new empty OptimizationProblem object.

+

Generate a new empty OptimizationProblem object.

- 
new_optimization_problem()
- - -

Value

- -

OptimizationProblem object.

-

See also

+
+ 
new_optimization_problem()
+
-

OptimizationProblem-methods()

+
+

Value

+ -

Examples

- 
# create empty OptimizationProblem object
-x <- new_optimization_problem()
+
OptimizationProblem object.

+    

+    
 
-# print new object
-print(x)
-
#> optimization problem (empty)
+
+

Examples

+ 
# create empty OptimizationProblem object
+x <- new_optimization_problem()
+
+# print new object
+print(x)
+#> optimization problem (empty)
+
+
+
-
- - - + diff --git a/docs/reference/new_waiver.html b/docs/reference/new_waiver.html index 4caa1a0..d81a0c6 100644 --- a/docs/reference/new_waiver.html +++ b/docs/reference/new_waiver.html @@ -1,78 +1,12 @@ - - - - - - - -Waiver — new_waiver • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Waiver — new_waiver • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Waiver

- Source: R/waiver.R + Source: R/waiver.R
@@ -128,60 +55,63 @@

Waiver

Create a waiver object.

- 
new_waiver()
- - -

Value

+
+ 
new_waiver()
+
-

object of class Waiver.

-

Details

+
+

Value

+ +

object of class Waiver.

+
+
+

Details

This object is used to represent that the user has not manually specified a setting, and so defaults should be used. By explicitly using a new_waiver(), this means that NULL objects can be a valid setting. The use of a "waiver" object was inspired by the ggplot2 package.

+
-

Examples

- 
# create new waiver object
-w <- new_waiver()
-
-# print object
-print(w)
-
#> list()
-#> attr(,"class")
-#> [1] "Waiver"

-# is it a waiver object?
-is.Waiver(w)
-
#> [1] TRUE

-
+
+

Examples

+ 
# create new waiver object
+w <- new_waiver()
+
+# print object
+print(w)
+#> list()
+#> attr(,"class")
+#> [1] "Waiver"
+
+# is it a waiver object?
+is.Waiver(w)
+#> [1] TRUE
+
+
+
+
- - - - + diff --git a/docs/reference/number_of_actions.html b/docs/reference/number_of_actions.html index 751bba6..caa9bd9 100644 --- a/docs/reference/number_of_actions.html +++ b/docs/reference/number_of_actions.html @@ -1,78 +1,12 @@ - - - - - - - -Number of actions — number_of_actions • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Number of actions — number_of_actions • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Number of actions

- Source: R/number_of_actions.R + Source: R/number_of_actions.R
@@ -128,83 +55,83 @@

Number of actions

Extract the number of actions in an object.

- 
number_of_actions(x)
-
-# S4 method for ProjectProblem
-number_of_actions(x)
-
-# S4 method for OptimizationProblem
-number_of_actions(x)
- -

Arguments

- - - - - - -
x

ProjectProblem or -OptimizationProblem object.

- -

Value

- -

integer number of actions.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with default solver
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions() %>%
-     add_default_solver()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]

-# print number of actions
-number_of_actions(p)
-
#> [1] 6
+
+ 
number_of_actions(x)
+
+# S4 method for ProjectProblem
+number_of_actions(x)
+
+# S4 method for OptimizationProblem
+number_of_actions(x)
+
+ +
+

Arguments

+
x
+

ProjectProblem or +OptimizationProblem object.

+ +
+
+

Value

+ + +

integer number of actions.

+
+ +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with default solver
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions() %>%
+     add_default_solver()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]
+
+# print number of actions
+number_of_actions(p)
+#> [1] 6
+
+
+
- - - - + diff --git a/docs/reference/number_of_features.html b/docs/reference/number_of_features.html index e71c2c7..f983dcf 100644 --- a/docs/reference/number_of_features.html +++ b/docs/reference/number_of_features.html @@ -1,78 +1,12 @@ - - - - - - - -Number of features — number_of_features • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Number of features — number_of_features • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Number of features

- Source: R/number_of_features.R + Source: R/number_of_features.R
@@ -128,83 +55,83 @@

Number of features

Extract the number of features in an object.

- 
number_of_features(x)
-
-# S4 method for ProjectProblem
-number_of_features(x)
-
-# S4 method for OptimizationProblem
-number_of_features(x)
- -

Arguments

- - - - - - -
x

ProjectProblem or -OptimizationProblem object.

- -

Value

- -

integer number of features.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with default solver
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions() %>%
-     add_default_solver()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]

-# print number of features
-number_of_features(p)
-
#> [1] 5
+
+ 
number_of_features(x)
+
+# S4 method for ProjectProblem
+number_of_features(x)
+
+# S4 method for OptimizationProblem
+number_of_features(x)
+
+ +
+

Arguments

+
x
+

ProjectProblem or +OptimizationProblem object.

+ +
+
+

Value

+ + +

integer number of features.

+
+ +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with default solver
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions() %>%
+     add_default_solver()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]
+
+# print number of features
+number_of_features(p)
+#> [1] 5
+
+
+
- - - - + diff --git a/docs/reference/number_of_projects.html b/docs/reference/number_of_projects.html index 8888f7e..ae1554a 100644 --- a/docs/reference/number_of_projects.html +++ b/docs/reference/number_of_projects.html @@ -1,78 +1,12 @@ - - - - - - - -Number of projects — number_of_projects • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Number of projects — number_of_projects • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Number of projects

- Source: R/number_of_projects.R + Source: R/number_of_projects.R
@@ -128,83 +55,83 @@

Number of projects

Extract the number of projects in an object.

- 
number_of_projects(x)
-
-# S4 method for ProjectProblem
-number_of_projects(x)
-
-# S4 method for OptimizationProblem
-number_of_projects(x)
- -

Arguments

- - - - - - -
x

ProjectProblem or -OptimizationProblem object.

- -

Value

- -

integer number of projects.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with default solver
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions() %>%
-     add_default_solver()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]

-# print number of projects
-number_of_projects(p)
-
#> [1] 6
+
+ 
number_of_projects(x)
+
+# S4 method for ProjectProblem
+number_of_projects(x)
+
+# S4 method for OptimizationProblem
+number_of_projects(x)
+
+ +
+

Arguments

+
x
+

ProjectProblem or +OptimizationProblem object.

+ +
+
+

Value

+ + +

integer number of projects.

+
+ +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with default solver
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions() %>%
+     add_default_solver()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]
+
+# print number of projects
+number_of_projects(p)
+#> [1] 6
+
+
+
- - - - + diff --git a/docs/reference/objectives-1.png b/docs/reference/objectives-1.png index 89a16f5..6c3a587 100644 Binary files a/docs/reference/objectives-1.png and b/docs/reference/objectives-1.png differ diff --git a/docs/reference/objectives-2.png b/docs/reference/objectives-2.png index c4938ab..e222fa2 100644 Binary files a/docs/reference/objectives-2.png and b/docs/reference/objectives-2.png differ diff --git a/docs/reference/objectives-3.png b/docs/reference/objectives-3.png index 89a16f5..6c3a587 100644 Binary files a/docs/reference/objectives-3.png and b/docs/reference/objectives-3.png differ diff --git a/docs/reference/objectives-4.png b/docs/reference/objectives-4.png index 2b59ba9..16db146 100644 Binary files a/docs/reference/objectives-4.png and b/docs/reference/objectives-4.png differ diff --git a/docs/reference/objectives.html b/docs/reference/objectives.html index 46f765e..afc17e2 100644 --- a/docs/reference/objectives.html +++ b/docs/reference/objectives.html @@ -1,46 +1,5 @@ - - - - - - - -Problem objective — objectives • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Problem objective — objectives • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Problem objective

- Source: R/objectives.R + Source: R/objectives.R

An objective is used to specify the overall goal of a project prioritization -problem(). All project prioritization problems involve +problem(). All project prioritization problems involve minimizing or maximizing some kind of objective. For instance, the decision maker may require a funding scheme that maximizes the total number of species that are expected to persist into the future whilst ensuring that @@ -145,40 +72,44 @@

Problem objective

Alternatively, the planner may require a solution that ensures that each species meets a target level of persistence whilst minimizing the cost of the funded actions. A project prioritization -problem() must have a specified objective before it can +problem() must have a specified objective before it can be solved, and attempting to solve a problem which does not have a specified objective will throw an error.

- -

Details

- +
+

Details

The following objectives can be added to a conservation planning -problem():

-
- -
add_max_richness_objective()

Maximize the total number of features that are expected to persist, +problem():

+
add_max_richness_objective()
+

Maximize the total number of features that are expected to persist, whilst ensuring that the cost of the solution is within a pre-specified budget (Joseph, Maloney & Possingham 2009).

-
add_max_targets_met_objective()

Maximize the total number of persistence targets met for the features, + +

add_max_targets_met_objective()
+

Maximize the total number of persistence targets met for the features, whilst ensuring that the cost of the solution is within a pre-specified budget (Chades et al. 2015).

-
add_max_phylo_div_objective()

Maximize the phylogenetic diversity that is expected to persist into the + +

add_max_phylo_div_objective()
+

Maximize the phylogenetic diversity that is expected to persist into the future, whilst ensuring that the cost of the solution is within a pre-specified budget (Bennett et al. 2014, Faith 2008).

-
add_min_set_objective()

Minimize the cost of the solution whilst ensuring that all targets are + +

add_min_set_objective()
+

Minimize the cost of the solution whilst ensuring that all targets are met. This objective is conceptually similar to that used in Marxan (Ball, Possingham & Watts 2009).

-
- -

References

+
+
+

References

Ball IR, Possingham HP & Watts M (2009) Marxan and relatives: software for spatial conservation prioritisation. Spatial conservation prioritisation: Quantitative methods and @@ -199,261 +130,281 @@

R

Joseph LN, Maloney RF & Possingham HP (2009) Optimal allocation of resources among threatened species: A project prioritization protocol. Conservation Biology, 23, 328--338.

-

See also

- -

constraints, decisions, -problem(), solvers, targets, -weights.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions, sim_tree)
-
-# build problem with maximum richness objective and $200 budget
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions()
-
-# \dontrun{
-# solve problem
-s1 <- solve(p1)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xab0d0209
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 2.19038 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%

-# print solution
-print(s1)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL  2.19  195.         1         1         0         0         0
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>

-# plot solution
-plot(p1, s1)
-
# }
-
-# build problem with maximum phylogenetic diversity objective and $200 budget
-p2 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_phylo_div_objective(budget = 200, tree = sim_tree) %>%
-     add_binary_decisions()
-
-# \dontrun{
-# solve problem
-s2 <- solve(p2)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 50 rows, 50 columns and 123 nonzeros
-#> Model fingerprint: 0x4b572399
-#> Model has 3 piecewise-linear objective terms
-#> Variable types: 3 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [2e-01, 2e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.7230501
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 37 rows, 2547 columns, 2589 nonzeros
-#> Variable types: 2512 continuous, 35 integer (35 binary)
-#> Presolve removed 3 rows and 3 columns
-#> Presolved: 34 rows, 2544 columns, 2583 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 2.638346e+00, 20 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#>      0     0    2.63835    0    6    1.72305    2.63835  53.1%     -    0s
-#> H    0     0                       1.9924877    2.63835  32.4%     -    0s
-#>      0     2    2.63696    0    6    1.99249    2.63696  32.3%     -    0s
-#> *    1     3               1       2.1724148    2.59317  19.4%   3.0    0s
-#> *    5     3               2       2.5726722    2.57267  0.00%   3.6    0s
-#> 
-#> Explored 6 nodes (38 simplex iterations) in 0.01 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 2.57267 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 2.572672188340e+00, best bound 2.572672188340e+00, gap 0.0000%

-# print solution
-print(s2)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL  2.57  194.         1         0         0         0         1
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>

-# plot solution
-plot(p2, s2)
-
# }
-# build problem with maximum targets met objective, $200 budget, and
-# 40% persistence targets
-p3 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_targets_met_objective(budget = 200) %>%
-     add_absolute_targets(0.4) %>%
-     add_binary_decisions()
-
-# \dontrun{
-# solve problem
-s3 <- solve(p3)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0x1c3a1930
-#> Variable types: 0 continuous, 47 integer (47 binary)
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 2.0000000
-#> Presolve removed 11 rows and 7 columns
-#> Presolve time: 0.00s
-#> Presolved: 36 rows, 40 columns, 75 nonzeros
-#> Variable types: 0 continuous, 40 integer (40 binary)
-#> Presolved: 36 rows, 40 columns, 75 nonzeros
-#> 
-#> 
-#> Root relaxation: cutoff, 17 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#>      0     0     cutoff    0         2.00000    2.00000  0.00%     -    0s
-#> 
-#> Explored 0 nodes (17 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 2 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 2.000000000000e+00, best bound 2.000000000000e+00, gap 0.0000%

-# print solution
-print(s3)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL     2  195.         1         1         0         0         0
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>

-# plot solution
-plot(p3, s3)
-
# }
-
-# build problem with minimum set objective, $200 budget, and 40%
-# persistence targets
-p4 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_min_set_objective() %>%
-     add_absolute_targets(0.4) %>%
-     add_binary_decisions()
+    

+    
 
-# \dontrun{
-# solve problem
-s4 <- solve(p4)
-

#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 46 rows, 42 columns and 92 nonzeros -#> Model fingerprint: 0x9cba05f4 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+00] -#> Objective range [9e+01, 1e+02] -#> Bounds range [1e+00, 1e+00] -#> RHS range [4e-01, 1e+00] -#> Found heuristic solution: objective 497.7671458 -#> Presolve removed 45 rows and 20 columns -#> Presolve time: 0.00s -#> Presolved: 1 rows, 22 columns, 2 nonzeros -#> Variable types: 0 continuous, 22 integer (22 binary) -#> -#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 497.767 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 4.977671458279e+02, best bound 4.977671458279e+02, gap 0.0000%
-# print solution -print(s4) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 498. 498. 1 1 1 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solution -plot(p4, s4) -
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions, sim_tree)
+
+# build problem with maximum richness objective and $200 budget
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions()
+
+# \dontrun{
+# solve problem
+s1 <- solve(p1)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x193cb636
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.19038 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
+
+# print solution
+print(s1)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  2.19  195.         1       1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution
+plot(p1, s1)
+
+# }
+
+# build problem with maximum phylogenetic diversity objective and $200 budget
+p2 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_phylo_div_objective(budget = 200, tree = sim_tree) %>%
+     add_binary_decisions()
+
+# \dontrun{
+# solve problem
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 50 rows, 50 columns and 123 nonzeros
+#> Model fingerprint: 0x3d5512d7
+#> Model has 3 piecewise-linear objective terms
+#> Variable types: 3 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [2e-01, 2e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#>   PWLObj x range   [6e-01, 5e+00]
+#>   PWLObj obj range [5e-03, 1e+00]
+#> Found heuristic solution: objective 1.7230501
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 37 rows, 2547 columns, 2589 nonzeros
+#> Variable types: 2512 continuous, 35 integer (35 binary)
+#> Root relaxation presolve removed 3 rows and 3 columns
+#> Root relaxation presolved: 34 rows, 2544 columns, 2583 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.638346e+00, 24 iterations, 0.01 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#>      0     0    2.63835    0    6    1.72305    2.63835  53.1%     -    0s
+#> H    0     0                       1.9924877    2.63835  32.4%     -    0s
+#> H    0     0                       2.1724148    2.63835  21.4%     -    0s
+#> H    0     0                       2.5726722    2.63835  2.55%     -    0s
+#>      0     2    2.63696    0    6    2.57267    2.63696  2.50%     -    0s
+#> 
+#> Explored 3 nodes (28 simplex iterations) in 0.07 seconds (0.02 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.57267 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.572672188340e+00, best bound 2.572672188340e+00, gap 0.0000%
+
+# print solution
+print(s2)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  2.57  194.         1       0       0       0       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution
+plot(p2, s2)
+
+# }
+# build problem with maximum targets met objective, $200 budget, and
+# 40% persistence targets
+p3 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_targets_met_objective(budget = 200) %>%
+     add_absolute_targets(0.4) %>%
+     add_binary_decisions()
+
+# \dontrun{
+# solve problem
+s3 <- solve(p3)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xec4d8189
+#> Variable types: 0 continuous, 47 integer (47 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 2.0000000
+#> Presolve removed 11 rows and 7 columns
+#> Presolve time: 0.00s
+#> Presolved: 36 rows, 40 columns, 75 nonzeros
+#> Variable types: 0 continuous, 40 integer (40 binary)
+#> Root relaxation presolved: 36 rows, 40 columns, 75 nonzeros
+#> 
+#> 
+#> Root relaxation: cutoff, 17 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#>      0     0     cutoff    0         2.00000    2.00000  0.00%     -    0s
+#> 
+#> Explored 1 nodes (17 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.000000000000e+00, best bound 2.000000000000e+00, gap 0.0000%
+
+# print solution
+print(s3)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL     2  195.         1       1       0       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution
+plot(p3, s3)
+
+# }
+
+# build problem with minimum set objective, $200 budget, and 40%
+# persistence targets
+p4 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_min_set_objective() %>%
+     add_absolute_targets(0.4) %>%
+     add_binary_decisions()
+
+# \dontrun{
+# solve problem
+s4 <- solve(p4)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 46 rows, 42 columns and 92 nonzeros
+#> Model fingerprint: 0x9cba05f4
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+00]
+#>   Objective range  [9e+01, 1e+02]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [4e-01, 1e+00]
+#> Found heuristic solution: objective 497.7671458
+#> Presolve removed 45 rows and 20 columns
+#> Presolve time: 0.00s
+#> Presolved: 1 rows, 22 columns, 2 nonzeros
+#> Variable types: 0 continuous, 22 integer (22 binary)
+#> 
+#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 497.767 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 4.977671458279e+02, best bound 4.977671458279e+02, gap 0.0000%
+
+# print solution
+print(s4)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  498.  498.         1       1       1       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution
+plot(p4, s4)
+
+# }
+
+
+
-
- - - + diff --git a/docs/reference/oppr-1.png b/docs/reference/oppr-1.png index 793caec..52202a1 100644 Binary files a/docs/reference/oppr-1.png and b/docs/reference/oppr-1.png differ diff --git a/docs/reference/oppr.html b/docs/reference/oppr.html index fbb7343..6b4f1b2 100644 --- a/docs/reference/oppr.html +++ b/docs/reference/oppr.html @@ -1,46 +1,5 @@ - - - - - - - -oppr: Optimal Project Prioritization — oppr • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -oppr: Optimal Project Prioritization — oppr • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

oppr: Optimal Project Prioritization

- Source: R/package.R + Source: R/package.R
@@ -150,192 +77,201 @@

oppr: Optimal Project Prioritization

problem, solutions can be obtained using exact algorithms, heuristic algorithms, or random processes. In particular, it is recommended to install the 'Gurobi' optimizer (available from -https://www.gurobi.com) +https://www.gurobi.com) because it can identify optimal solutions very quickly. Finally, methods are provided for comparing different prioritizations and evaluating their benefits.

- -

Installation

- +
+

Installation

-

To make the most of this package, the ggtree and -gurobi R packages will need to be installed. -Since the ggtree package is exclusively available -at Bioconductor---and is not available on -The Comprehensive R Archive Network---please +

To make the most of this package, the ggtree and +gurobi R packages will need to be installed. +Since the ggtree package is exclusively available +at Bioconductor---and is not available on +The Comprehensive R Archive Network---please execute the following command to install it: source("https://bioconductor.org/biocLite.R");biocLite("ggtree"). If the installation process fails, please consult the -package's online documentation. To install the gurobi package, the -Gurobi optimization suite will first need to -be installed (see instructions for Linux, -Mac OSX, and -Windows operating systems). Although -Gurobi is a commercial software, academics +package's online documentation. To install the gurobi package, the +Gurobi optimization suite will first need to +be installed (see instructions for Linux, +Mac OSX, and +Windows operating systems). Although +Gurobi is a commercial software, academics can obtain a -special license for no cost. After installing the -Gurobi optimization suite, the gurobi -package can then be installed (see instructions for Linux, -Mac OSX, and -Windows operating systems).

-

See also

- -

Please refer to the package vignette for more information and worked +special license for no cost. After installing the +Gurobi optimization suite, the gurobi +package can then be installed (see instructions for Linux, +Mac OSX, and +Windows operating systems).

+
+
+

See also

+

Please refer to the package vignette for more information and worked examples. This can be accessed using the code -vignette("oppr").

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# print project data
-print(sim_projects)
-
#> # A tibble: 6 x 13
-#>   name           success     F1     F2      F3     F4     F5 F1_action F2_action
-#>   <chr>            <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>     <lgl>    
-#> 1 F1_project       0.919  0.791 NA     NA      NA     NA     TRUE      FALSE    
-#> 2 F2_project       0.923 NA      0.888 NA      NA     NA     FALSE     TRUE     
-#> 3 F3_project       0.829 NA     NA      0.502  NA     NA     FALSE     FALSE    
-#> 4 F4_project       0.848 NA     NA     NA       0.690 NA     FALSE     FALSE    
-#> 5 F5_project       0.814 NA     NA     NA      NA      0.617 FALSE     FALSE    
-#> 6 baseline_proj…   1      0.298  0.250  0.0865  0.249  0.182 FALSE     FALSE    
-#> # … with 4 more variables: F3_action <lgl>, F4_action <lgl>, F5_action <lgl>,
-#> #   baseline_action <lgl>

-# print action data
-print(sim_features)
-
#> # A tibble: 5 x 2
-#>   name  weight
-#>   <chr>  <dbl>
-#> 1 F1     0.211
-#> 2 F2     0.211
-#> 3 F3     0.221
-#> 4 F4     0.630
-#> 5 F5     1.59 

-# print feature data
-print(sim_actions)
-
#> # A tibble: 6 x 4
-#>   name             cost locked_in locked_out
-#>   <chr>           <dbl> <lgl>     <lgl>     
-#> 1 F1_action        94.4 FALSE     FALSE     
-#> 2 F2_action       101.  FALSE     FALSE     
-#> 3 F3_action       103.  TRUE      FALSE     
-#> 4 F4_action        99.2 FALSE     FALSE     
-#> 5 F5_action        99.9 FALSE     TRUE      
-#> 6 baseline_action   0   FALSE     FALSE     

-# build problem
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 400) %>%
-     add_feature_weights("weight") %>%
-     add_binary_decisions()
+vignette("oppr").

+
-# print problem -print(p) -
#> Project Prioritization Problem -#> actions F1_action, F2_action, F3_action, ... (6 actions) -#> projects F1_project, F2_project, F3_project, ... (6 projects) -#> features F1, F2, F3, ... (5 features) -#> action costs: min: 0, max: 103.22583 -#> project success: min: 0.81379, max: 1 -#> objective: Maximum richness objective [budget (400)] -#> targets: none -#> weights: min: 0.21136, max: 1.59167 -#> decisions Binary decision -#> constraints: <none> -#> solver: default
-# \dontrun{ -# solve problem -s <- solve(p) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 47 rows, 47 columns and 102 nonzeros -#> Model fingerprint: 0xa2bba4dd -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Semi-Variable types: 5 continuous, 0 integer -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+02] -#> Objective range [2e-01, 2e+00] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e+00, 4e+02] -#> Found heuristic solution: objective 0.6654645 -#> Presolve removed 16 rows and 12 columns -#> Presolve time: 0.00s -#> Presolved: 31 rows, 35 columns, 64 nonzeros -#> Variable types: 0 continuous, 35 integer (35 binary) -#> Presolved: 31 rows, 35 columns, 64 nonzeros -#> -#> -#> Root relaxation: objective 1.749045e+00, 11 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 1.7490448 1.74904 0.00% - 0s -#> -#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 1.74904 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 1.749044775334e+00, best bound 1.749044775334e+00, gap 0.0000%
-# print output -print(s) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 1.75 395. 1 1 0 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# print which actions are funded in the solution -s[, sim_actions$name, drop = FALSE] -
#> # A tibble: 1 x 6 -#> F1_action F2_action F3_action F4_action F5_action baseline_action -#> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 1 0 1 1 1
-# print the expected probability of persistence for each feature -# if the solution were implemented -s[, sim_features$name, drop = FALSE] -
#> # A tibble: 1 x 5 -#> F1 F2 F3 F4 F5 -#> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 0.808 0.865 0.0865 0.688 0.592
-# visualize solution -plot(p, s) -
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# print project data
+print(sim_projects)
+#> # A tibble: 6 × 13
+#>   name       success     F1     F2      F3     F4     F5 F1_ac…¹ F2_ac…² F3_ac…³
+#>   <chr>        <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>   <lgl>   <lgl>  
+#> 1 F1_project   0.919  0.791 NA     NA      NA     NA     TRUE    FALSE   FALSE  
+#> 2 F2_project   0.923 NA      0.888 NA      NA     NA     FALSE   TRUE    FALSE  
+#> 3 F3_project   0.829 NA     NA      0.502  NA     NA     FALSE   FALSE   TRUE   
+#> 4 F4_project   0.848 NA     NA     NA       0.690 NA     FALSE   FALSE   FALSE  
+#> 5 F5_project   0.814 NA     NA     NA      NA      0.617 FALSE   FALSE   FALSE  
+#> 6 baseline_…   1      0.298  0.250  0.0865  0.249  0.182 FALSE   FALSE   FALSE  
+#> # … with 3 more variables: F4_action <lgl>, F5_action <lgl>,
+#> #   baseline_action <lgl>, and abbreviated variable names ¹​F1_action,
+#> #   ²​F2_action, ³​F3_action
+
+# print action data
+print(sim_features)
+#> # A tibble: 5 × 2
+#>   name  weight
+#>   <chr>  <dbl>
+#> 1 F1     0.211
+#> 2 F2     0.211
+#> 3 F3     0.221
+#> 4 F4     0.630
+#> 5 F5     1.59 
+
+# print feature data
+print(sim_actions)
+#> # A tibble: 6 × 4
+#>   name             cost locked_in locked_out
+#>   <chr>           <dbl> <lgl>     <lgl>     
+#> 1 F1_action        94.4 FALSE     FALSE     
+#> 2 F2_action       101.  FALSE     FALSE     
+#> 3 F3_action       103.  TRUE      FALSE     
+#> 4 F4_action        99.2 FALSE     FALSE     
+#> 5 F5_action        99.9 FALSE     TRUE      
+#> 6 baseline_action   0   FALSE     FALSE     
+
+# build problem
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 400) %>%
+     add_feature_weights("weight") %>%
+     add_binary_decisions()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (400)]
+#>   targets:         none
+#>   weights:         min: 0.21136, max: 1.59167
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# \dontrun{
+# solve problem
+s <- solve(p)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xa33f6587
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [2e-01, 2e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 4e+02]
+#> Found heuristic solution: objective 0.6654645
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 64 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 64 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.749045e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.7490448    1.74904  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.74904 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.749044775334e+00, best bound 1.749044775334e+00, gap 0.0000%
+
+# print output
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  1.75  395.         1       1       0       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# print which actions are funded in the solution
+s[, sim_actions$name, drop = FALSE]
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         1         1         0         1         1               1
+
+# print the expected probability of persistence for each feature
+# if the solution were implemented
+s[, sim_features$name, drop = FALSE]
+#> # A tibble: 1 × 5
+#>      F1    F2     F3    F4    F5
+#>   <dbl> <dbl>  <dbl> <dbl> <dbl>
+#> 1 0.808 0.865 0.0865 0.688 0.592
+
+# visualize solution
+plot(p, s)
+
+# }
+
+
+
- - - - + diff --git a/docs/reference/parameters.html b/docs/reference/parameters.html index 2f2167e..ed16f20 100644 --- a/docs/reference/parameters.html +++ b/docs/reference/parameters.html @@ -1,78 +1,12 @@ - - - - - - - -Parameters — parameters • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Parameters — parameters • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Parameters

- Source: R/parameters.R + Source: R/parameters.R
@@ -128,66 +55,68 @@

Parameters

Create a new collection of Parameter objects.

- 
parameters(...)
- -

Arguments

- - - - - - -
...

Parameter objects.

- -

Value

- -

Parameters object.

-

See also

- -

array_parameters(), scalar_parameters().

- -

Examples

- 
# create two Parameter objects
-p1 <- binary_parameter("parameter one", 1)
-print(p1)
-
#> parameter one (1)

-p2 <- numeric_parameter("parameter two", 5)
-print(p2)
-
#> parameter two (5)

-# store Parameter objects in a Parameters object
-p <- parameters(p1, p2)
-print(p)
-
#> <environment: 0x55de4cbc0b48>
-#> attr(,"class")
-#> [1] "Parameters"  "pproto"      "proto"       "environment"

-
+
+ 
parameters(...)
+
+ +
+

Arguments

+
...
+

Parameter objects.

+ +
+
+

Value

+ + +

Parameters object.

+
+ + +
+

Examples

+ 
# create two Parameter objects
+p1 <- binary_parameter("parameter one", 1)
+print(p1)
+#> parameter one (1)
+
+p2 <- numeric_parameter("parameter two", 5)
+print(p2)
+#> parameter two (5)
+
+# store Parameter objects in a Parameters object
+p <- parameters(p1, p2)
+print(p)
+#> <environment: 0x556a22161588>
+#> attr(,"class")
+#> [1] "Parameters"  "pproto"      "proto"       "environment"
+
+
+
+
- - - - + diff --git a/docs/reference/pipe.html b/docs/reference/pipe.html index d2a090b..3966dcf 100644 --- a/docs/reference/pipe.html +++ b/docs/reference/pipe.html @@ -1,79 +1,13 @@ - - - - - - - -Pipe operator — %>% • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Pipe operator — %>% • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Pipe operator

- Source: R/magrittr-operators.R + Source: R/magrittr-operators.R
@@ -131,61 +58,57 @@

Pipe operator

-

Arguments

- - - - - - -
lhs, rhs

An object and a function.

- -

See also

- -

magrittr::%>%(), tee().

+
+

Arguments

+
lhs, rhs
+

An object and a function.

-

Examples

- 
# set seed for reproducibility
-set.seed(500)
-
-# generate 100 random numbers and calculate the mean
-mean(runif(100))
-
#> [1] 0.473179

-# reset the seed
-set.seed(500)
+
+
+

See also

+

magrittr::%>%(), tee().

+
-# repeat the previous procedure but use the pipe operator instead of nesting -# function calls inside each other. -runif(100) %>% mean() -
#> [1] 0.473179
-
+
+

Examples

+ 
# set seed for reproducibility
+set.seed(500)
+
+# generate 100 random numbers and calculate the mean
+mean(runif(100))
+#> [1] 0.473179
+
+# reset the seed
+set.seed(500)
+
+# repeat the previous procedure but use the pipe operator instead of nesting
+# function calls inside each other.
+runif(100) %>% mean()
+#> [1] 0.473179
+
+
+
+
- - - - + diff --git a/docs/reference/plot.ProjectProblem-1.png b/docs/reference/plot.ProjectProblem-1.png index 793caec..52202a1 100644 Binary files a/docs/reference/plot.ProjectProblem-1.png and b/docs/reference/plot.ProjectProblem-1.png differ diff --git a/docs/reference/plot.ProjectProblem-2.png b/docs/reference/plot.ProjectProblem-2.png index b6d4d82..a916e02 100644 Binary files a/docs/reference/plot.ProjectProblem-2.png and b/docs/reference/plot.ProjectProblem-2.png differ diff --git a/docs/reference/plot.ProjectProblem.html b/docs/reference/plot.ProjectProblem.html index 8b46281..d47818e 100644 --- a/docs/reference/plot.ProjectProblem.html +++ b/docs/reference/plot.ProjectProblem.html @@ -1,79 +1,13 @@ - - - - - - - -Plot a solution to a project prioritization problem — plot.ProjectProblem • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Plot a solution to a project prioritization problem — plot.ProjectProblem • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Plot a solution to a project prioritization problem

- Source: R/plot.R + Source: R/plot.R

Create a plot to visualize how well a solution to a project prioritization -problem() will maintain biodiversity.

+problem() will maintain biodiversity.

+
+ +
+ 
# S3 method for ProjectProblem
+plot(x, solution, n = 1, symbol_hjust = 0.007, return_data = FALSE, ...)
- 
# S3 method for ProjectProblem
-plot(x, solution, n = 1, symbol_hjust = 0.007, return_data = FALSE, ...)
+
+

Arguments

+
x
+

project prioritization problem().

-

Arguments

- - - - - - - - - - - - - - - - - - - - - - - - - - -
x

project prioritization problem().

solution

base::data.frame() or -tibble::tibble() table containing the solutions. Here, + +

solution
+

base::data.frame() or +tibble::tibble() table containing the solutions. Here, rows correspond to different solutions and columns correspond to different actions. Each column in the argument to solution should be named according to a different action in x. Cell values indicate if an action is funded in a given solution or not, and should be either zero or one. Arguments to solution can -contain additional columns, and they will be ignored.

n

integer solution number to visualize. +contain additional columns, and they will be ignored.

+ + +
n
+

integer solution number to visualize. Since each row in the argument to solutions corresponds to a different solution, this argument should correspond to a row in -the argument to solutions. Defaults to 1.

symbol_hjust

numeric horizontal adjustment parameter to +the argument to solutions. Defaults to 1.

+ + +
symbol_hjust
+

numeric horizontal adjustment parameter to manually align the asterisks and dashes in the plot. Defaults to 0.007. Increasing this parameter will shift the symbols further right. Please note that this parameter may require some tweaking -to produce visually appealing publication quality plots.

return_data

logical should the underlying data used to create -the plot be returned instead of the plot? Defaults to FALSE.

...

not used.

+to produce visually appealing publication quality plots.

+ + +
return_data
+

logical should the underlying data used to create +the plot be returned instead of the plot? Defaults to FALSE.

-

Value

-

A ggplot() object.

-

Details

+
...
+

not used.

+
+
+

Value

+ + +

A ggplot() object.

+
+
+

Details

The type of plot that this function creates depends on the problem objective. If the problem objective contains phylogenetic data, then this function plots a phylogenetic tree where each branch @@ -196,139 +125,143 @@

Details projects---because they are associated with partially funded projects that have non-zero costs and share actions with at least one funded project---are depicted with an open circle symbol.

-

See also

- -

This function is essentially a wrapper for -plot_feature_persistence() and -plot_phylo_persistence(), so refer to the documentation +

+
+

See also

+

This function is essentially a wrapper for +plot_feature_persistence() and +plot_phylo_persistence(), so refer to the documentation for these functions for more information.

+
-

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem without phylogenetic data
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_max_richness_objective(budget = 400) %>%
-      add_feature_weights("weight") %>%
-      add_binary_decisions()
-
-# \dontrun{
-# solve problem without phylogenetic data
-s1 <- solve(p1)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xa2bba4dd
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [2e-01, 2e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 4e+02]
-#> Found heuristic solution: objective 0.6654645
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 64 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 64 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 1.749045e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       1.7490448    1.74904  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 1.74904 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 1.749044775334e+00, best bound 1.749044775334e+00, gap 0.0000%

-# visualize solution without phylogenetic data
-plot(p1, s1)
-
# }
-
-# build problem with phylogenetic data
-p2 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_max_phylo_div_objective(budget = 400, sim_tree) %>%
-      add_binary_decisions()
-
-# \dontrun{
-# solve problem with phylogenetic data
-s2 <- solve(p2)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 50 rows, 50 columns and 123 nonzeros
-#> Model fingerprint: 0x02cbd8bd
-#> Model has 3 piecewise-linear objective terms
-#> Variable types: 3 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [2e-01, 2e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 4e+02]
-#> Found heuristic solution: objective 1.7230501
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 37 rows, 3035 columns, 3076 nonzeros
-#> Variable types: 3000 continuous, 35 integer (35 binary)
-#> Presolve removed 3 rows and 3 columns
-#> Presolved: 34 rows, 3032 columns, 3070 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 3.112324e+00, 17 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       3.1123243    3.11232  0.00%     -    0s
-#> 
-#> Explored 0 nodes (17 simplex iterations) in 0.01 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 3.11232 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 3.112324258740e+00, best bound 3.112324258740e+00, gap 0.0000%

-# visualize solution with phylogenetic data
-plot(p2, s2)
-
# }
-
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem without phylogenetic data
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_max_richness_objective(budget = 400) %>%
+      add_feature_weights("weight") %>%
+      add_binary_decisions()
+
+# \dontrun{
+# solve problem without phylogenetic data
+s1 <- solve(p1)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xa33f6587
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [2e-01, 2e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 4e+02]
+#> Found heuristic solution: objective 0.6654645
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 64 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 64 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.749045e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.7490448    1.74904  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.74904 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.749044775334e+00, best bound 1.749044775334e+00, gap 0.0000%
+
+# visualize solution without phylogenetic data
+plot(p1, s1)
+
+# }
+
+# build problem with phylogenetic data
+p2 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_max_phylo_div_objective(budget = 400, sim_tree) %>%
+      add_binary_decisions()
+
+# \dontrun{
+# solve problem with phylogenetic data
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 50 rows, 50 columns and 123 nonzeros
+#> Model fingerprint: 0xb7356220
+#> Model has 3 piecewise-linear objective terms
+#> Variable types: 3 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [2e-01, 2e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 4e+02]
+#>   PWLObj x range   [6e-01, 5e+00]
+#>   PWLObj obj range [5e-03, 1e+00]
+#> Found heuristic solution: objective 1.7230501
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 37 rows, 3035 columns, 3076 nonzeros
+#> Variable types: 3000 continuous, 35 integer (35 binary)
+#> Root relaxation presolve removed 3 rows and 3 columns
+#> Root relaxation presolved: 34 rows, 3032 columns, 3070 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 3.112324e+00, 17 iterations, 0.01 seconds (0.01 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       3.1123243    3.11232  0.00%     -    0s
+#> 
+#> Explored 1 nodes (17 simplex iterations) in 0.02 seconds (0.01 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 3.11232 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 3.112324258740e+00, best bound 3.112324258740e+00, gap 0.0000%
+
+# visualize solution with phylogenetic data
+plot(p2, s2)
+
+# }
+
+
+
-
- - - + diff --git a/docs/reference/plot_feature_persistence-1.png b/docs/reference/plot_feature_persistence-1.png index 793caec..52202a1 100644 Binary files a/docs/reference/plot_feature_persistence-1.png and b/docs/reference/plot_feature_persistence-1.png differ diff --git a/docs/reference/plot_feature_persistence-2.png b/docs/reference/plot_feature_persistence-2.png index b69fd44..0d4a702 100644 Binary files a/docs/reference/plot_feature_persistence-2.png and b/docs/reference/plot_feature_persistence-2.png differ diff --git a/docs/reference/plot_feature_persistence-3.png b/docs/reference/plot_feature_persistence-3.png index ff21090..c54f762 100644 Binary files a/docs/reference/plot_feature_persistence-3.png and b/docs/reference/plot_feature_persistence-3.png differ diff --git a/docs/reference/plot_feature_persistence.html b/docs/reference/plot_feature_persistence.html index d1c83cf..b92595c 100644 --- a/docs/reference/plot_feature_persistence.html +++ b/docs/reference/plot_feature_persistence.html @@ -1,79 +1,13 @@ - - - - - - - -Plot a bar plot to visualize a project prioritization — plot_feature_persistence • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Plot a bar plot to visualize a project prioritization — plot_feature_persistence • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Plot a bar plot to visualize a project prioritization

- Source: R/plot_feature_persistence.R + Source: R/plot_feature_persistence.R

Create a bar plot to visualize how likely features are to persist into -the future under a solution to a project prioritization problem().

+the future under a solution to a project prioritization problem().

+
+ +
+ 
plot_feature_persistence(
+  x,
+  solution,
+  n = 1,
+  symbol_hjust = 0.007,
+  return_data = FALSE
+)
- 
plot_feature_persistence(
-  x,
-  solution,
-  n = 1,
-  symbol_hjust = 0.007,
-  return_data = FALSE
-)
+
+

Arguments

+
x
+

project prioritization problem().

+ -

Arguments

- - - - - - - - - - - - - - - - - - - - - - -
x

project prioritization problem().

solution

base::data.frame() or -tibble::tibble() table containing the solutions. Here, +

solution
+

base::data.frame() or +tibble::tibble() table containing the solutions. Here, rows correspond to different solutions and columns correspond to different actions. Each column in the argument to solution should be named according to a different action in x. Cell values indicate if an action is funded in a given solution or not, and should be either zero or one. Arguments to solution can -contain additional columns, and they will be ignored.

n

integer solution number to visualize. +contain additional columns, and they will be ignored.

+ + +
n
+

integer solution number to visualize. Since each row in the argument to solutions corresponds to a different solution, this argument should correspond to a row in -the argument to solutions. Defaults to 1.

symbol_hjust

numeric horizontal adjustment parameter to +the argument to solutions. Defaults to 1.

+ + +
symbol_hjust
+

numeric horizontal adjustment parameter to manually align the asterisks and dashes in the plot. Defaults to 0.007. Increasing this parameter will shift the symbols further right. Please note that this parameter may require some tweaking -to produce visually appealing publication quality plots.

return_data

logical should the underlying data used to create -the plot be returned instead of the plot? Defaults to FALSE.

+to produce visually appealing publication quality plots.

-

Value

-

A ggplot() object, or a -tibble::tbl_df() object if return_data is -TRUE.

-

Details

+
return_data
+

logical should the underlying data used to create +the plot be returned instead of the plot? Defaults to FALSE.

+
+
+

Value

+ + +

A ggplot() object, or a +tibble::tbl_df() object if return_data is +TRUE.

+
+
+

Details

In this plot, each bar corresponds to a different feature. The length of each bar indicates the probability that a given feature will persist into the future, and the color of each bar indicates @@ -195,79 +124,80 @@

Details projects---because they are associated with partially funded projects that have non-zero costs and share actions with at least one completely funded project---are depicted with an open circle symbol.

+

-

Examples

- 
# set seed for reproducibility
-set.seed(500)
-
-# load the ggplot2 R package to customize plots
-library(ggplot2)
-
-# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_max_richness_objective(budget = 400) %>%
-      add_feature_weights("weight") %>%
-      add_binary_decisions() %>%
-      add_heuristic_solver(n = 10)
-
-# \dontrun{
-# solve problem
-s <- solve(p)
-
-# plot the first solution
-plot(p, s)
-

-# plot the second solution
-plot(p, s, n = 2)
-

-# since this function returns a ggplot2 plot object, we can customize the
-# appearance of the plot using standard ggplot2 commands!
-# for example, we can add a title
-plot(p, s) + ggtitle("solution")
-

-# we can also obtain the raw plotting data using return_data=TRUE
-plot_data <- plot(p, s, return_data = TRUE)
-print(plot_data)
-
#> # A tibble: 5 x 4
-#>   name    prob weight status
-#>   <fct>  <dbl>  <dbl> <chr> 
-#> 1 F5    0.592   1.59  Funded
-#> 2 F4    0.688   0.630 Funded
-#> 3 F3    0.0865  0.221 NA    
-#> 4 F2    0.865   0.211 Funded
-#> 5 F1    0.808   0.211 Funded
# }
-
+
+

Examples

+ 
# set seed for reproducibility
+set.seed(500)
+
+# load the ggplot2 R package to customize plots
+library(ggplot2)
+
+# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_max_richness_objective(budget = 400) %>%
+      add_feature_weights("weight") %>%
+      add_binary_decisions() %>%
+      add_heuristic_solver(n = 10)
+
+# \dontrun{
+# solve problem
+s <- solve(p)
+
+# plot the first solution
+plot(p, s)
+
+
+# plot the second solution
+plot(p, s, n = 2)
+
+
+# since this function returns a ggplot2 plot object, we can customize the
+# appearance of the plot using standard ggplot2 commands!
+# for example, we can add a title
+plot(p, s) + ggtitle("solution")
+
+
+# we can also obtain the raw plotting data using return_data=TRUE
+plot_data <- plot(p, s, return_data = TRUE)
+print(plot_data)
+#> # A tibble: 5 × 4
+#>   name    prob weight status
+#>   <fct>  <dbl>  <dbl> <chr> 
+#> 1 F5    0.592   1.59  Funded
+#> 2 F4    0.688   0.630 Funded
+#> 3 F3    0.0865  0.221 NA    
+#> 4 F2    0.865   0.211 Funded
+#> 5 F1    0.808   0.211 Funded
+# }
+
+
+
-
- - - + diff --git a/docs/reference/plot_phylo_persistence-1.png b/docs/reference/plot_phylo_persistence-1.png index b6d4d82..a916e02 100644 Binary files a/docs/reference/plot_phylo_persistence-1.png and b/docs/reference/plot_phylo_persistence-1.png differ diff --git a/docs/reference/plot_phylo_persistence-2.png b/docs/reference/plot_phylo_persistence-2.png index f9f8d03..82316ed 100644 Binary files a/docs/reference/plot_phylo_persistence-2.png and b/docs/reference/plot_phylo_persistence-2.png differ diff --git a/docs/reference/plot_phylo_persistence-3.png b/docs/reference/plot_phylo_persistence-3.png index 523db42..c448378 100644 Binary files a/docs/reference/plot_phylo_persistence-3.png and b/docs/reference/plot_phylo_persistence-3.png differ diff --git a/docs/reference/plot_phylo_persistence-4.png b/docs/reference/plot_phylo_persistence-4.png index 0d17bea..089fe1e 100644 Binary files a/docs/reference/plot_phylo_persistence-4.png and b/docs/reference/plot_phylo_persistence-4.png differ diff --git a/docs/reference/plot_phylo_persistence-5.png b/docs/reference/plot_phylo_persistence-5.png index 4e9a28a..d85b7db 100644 Binary files a/docs/reference/plot_phylo_persistence-5.png and b/docs/reference/plot_phylo_persistence-5.png differ diff --git a/docs/reference/plot_phylo_persistence.html b/docs/reference/plot_phylo_persistence.html index a163e20..3b915b9 100644 --- a/docs/reference/plot_phylo_persistence.html +++ b/docs/reference/plot_phylo_persistence.html @@ -1,80 +1,14 @@ - - - - - - - -Plot a phylogram to visualize a project prioritization — plot_phylo_persistence • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Plot a phylogram to visualize a project prioritization — plot_phylo_persistence • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Plot a phylogram to visualize a project prioritization

- Source: R/plot_phylo_persistence.R + Source: R/plot_phylo_persistence.R

Create a plot showing a phylogenetic tree (i.e. a "phylogram") to visualize the probability that phylogenetic branches are expected to persist -into the future under a solution to a project prioritization problem().

+into the future under a solution to a project prioritization problem().

+
+ +
+ 
plot_phylo_persistence(
+  x,
+  solution,
+  n = 1,
+  symbol_hjust = 0.007,
+  return_data = FALSE
+)
- 
plot_phylo_persistence(
-  x,
-  solution,
-  n = 1,
-  symbol_hjust = 0.007,
-  return_data = FALSE
-)
+
+

Arguments

+
x
+

project prioritization problem().

-

Arguments

- - - - - - - - - - - - - - - - - - - - - - -
x

project prioritization problem().

solution

base::data.frame() or -tibble::tibble() table containing the solutions. Here, + +

solution
+

base::data.frame() or +tibble::tibble() table containing the solutions. Here, rows correspond to different solutions and columns correspond to different actions. Each column in the argument to solution should be named according to a different action in x. Cell values indicate if an action is funded in a given solution or not, and should be either zero or one. Arguments to solution can -contain additional columns, and they will be ignored.

n

integer solution number to visualize. +contain additional columns, and they will be ignored.

+ + +
n
+

integer solution number to visualize. Since each row in the argument to solutions corresponds to a different solution, this argument should correspond to a row in -the argument to solutions. Defaults to 1.

symbol_hjust

numeric horizontal adjustment parameter to +the argument to solutions. Defaults to 1.

+ + +
symbol_hjust
+

numeric horizontal adjustment parameter to manually align the asterisks and dashes in the plot. Defaults to 0.007. Increasing this parameter will shift the symbols further right. Please note that this parameter may require some tweaking -to produce visually appealing publication quality plots.

return_data

logical should the underlying data used to create -the plot be returned instead of the plot? Defaults to FALSE.

+to produce visually appealing publication quality plots.

-

Value

-

A ggtree::ggtree() object, or a -tidytree::treedata() object if return_data is -TRUE.

-

Details

+
return_data
+

logical should the underlying data used to create +the plot be returned instead of the plot? Defaults to FALSE.

+ +
+
+

Value

+ +

A ggtree::ggtree() object, or a +tidytree::treedata() object if return_data is +TRUE.

+
+
+

Details

This function requires the ggtree (Yu et al. 2017). Since this package is distributed exclusively -through Bioconductor, and is not +through Bioconductor, and is not available on the -Comprehensive R Archive Network, -please execute the following command to install it: -source("https://bioconductor.org/biocLite.R");biocLite("ggtree"). -If the installation process fails, please consult the package's online documentation.

+Comprehensive R Archive Network, +please execute the following commands to install it:

+

if (!require(remotes)) install.packages("remotes")
+remotes::install_bioc("ggtree")

+

If the installation process fails, please consult the package's +online documentation.

In this plot, each phylogenetic branch is colored according to probability that it is expected to persist into the future (see Faith 2008). Features that directly benefit from at least a single @@ -203,8 +134,9 @@

Details projects---because they are associated with partially funded projects that have non-zero costs and share actions with at least one completely funded project---are depicted with an open circle symbol.

-

References

- +
+
+

References

Faith DP (2008) Threatened species and the potential loss of phylogenetic diversity: conservation scenarios based on estimated extinction probabilities and phylogenetic risk analysis. Conservation Biology, @@ -213,108 +145,130 @@

R R package for visualization and annotation of phylogenetic trees with their covariates and other associated data. Methods in Ecology and Evolution, 8: 28--36.

+

-

Examples

- 
# set seed for reproducibility
-set.seed(500)
-
-# load the ggplot2 R package to customize plots
-library(ggplot2)
-
-data(sim_projects, sim_features, sim_actions)
-
-# build problem
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_phylo_div_objective(budget = 400, sim_tree) %>%
-     add_binary_decisions() %>%
-     add_heuristic_solver(number_solutions = 10)
-
-# \dontrun{
-# solve problem
-s <- solve(p)
-
-# plot the first solution
-plot(p, s)
-

-# plot the second solution
-plot(p, s, n = 2)
-

-# since this function returns a ggplot2 plot object, we can customize the
-# appearance of the plot using standard ggplot2 commands!
-# for example, we can add a title
-plot(p, s) + ggtitle("solution")
-

-# we could also also set the minimum and maximum values in the color ramp to
-# correspond to those in the data, rather than being capped at 0 and 1
-plot(p, s) +
-scale_color_gradientn(name = "Probability of\npersistence",
-                      colors = viridisLite::inferno(150, begin = 0,
-                                                    end = 0.9,
-                                                    direction = -1)) +
-ggtitle("solution")
-
#> Scale for 'colour' is already present. Adding another scale for 'colour',
-#> which will replace the existing scale.

-# we could also change the color ramp
-plot(p, s) +
-scale_color_gradient(name = "Probability of\npersistence",
-                     low = "red", high = "black") +
-ggtitle("solution")
-
#> Scale for 'colour' is already present. Adding another scale for 'colour',
-#> which will replace the existing scale.

-# we could even hide the legend if desired
-plot(p, s) +
-scale_color_gradient(name = "Probability of\npersistence",
-                     low = "red", high = "black") +
-theme(legend.position = "hide") +
-ggtitle("solution")
-
#> Scale for 'colour' is already present. Adding another scale for 'colour',
-#> which will replace the existing scale.

-# we can also obtain the raw plotting data using return_data=TRUE
-plot_data <- plot(p, s, return_data = TRUE)
-print(plot_data)
-
#> 'treedata' S4 object'.
-#> 
-#> ...@ phylo: 
-#> Phylogenetic tree with 5 tips and 4 internal nodes.
-#> 
-#> Tip labels:
-#>      F1,    F2,    F3,    F4,    F5
-#> Node labels:
-#>      NA,    NA,    NA,    NA
-#> 
-#> Rooted; includes branch lengths.
-#> 
-#> with the following features available:
-#> 	'status',	'prob'.
# }
-
+
+

Examples

+ 
# set seed for reproducibility
+set.seed(500)
+
+# load the ggplot2 R package to customize plots
+library(ggplot2)
+
+data(sim_projects, sim_features, sim_actions)
+
+# build problem
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_phylo_div_objective(budget = 400, sim_tree) %>%
+     add_binary_decisions() %>%
+     add_heuristic_solver(number_solutions = 10)
+
+# \dontrun{
+# solve problem
+s <- solve(p)
+
+# plot the first solution
+plot(p, s)
+
+
+# plot the second solution
+plot(p, s, n = 2)
+
+
+# since this function returns a ggplot2 plot object, we can customize the
+# appearance of the plot using standard ggplot2 commands!
+# for example, we can add a title
+plot(p, s) + ggtitle("solution")
+
+
+# we could also also set the minimum and maximum values in the color ramp to
+# correspond to those in the data, rather than being capped at 0 and 1
+plot(p, s) +
+scale_color_gradientn(name = "Probability of\npersistence",
+                      colors = viridisLite::inferno(150, begin = 0,
+                                                    end = 0.9,
+                                                    direction = -1)) +
+ggtitle("solution")
+#> Scale for 'colour' is already present. Adding another scale for 'colour',
+#> which will replace the existing scale.
+
+
+# we could also change the color ramp
+plot(p, s) +
+scale_color_gradient(name = "Probability of\npersistence",
+                     low = "red", high = "black") +
+ggtitle("solution")
+#> Scale for 'colour' is already present. Adding another scale for 'colour',
+#> which will replace the existing scale.
+
+
+# we could even hide the legend if desired
+plot(p, s) +
+scale_color_gradient(name = "Probability of\npersistence",
+                     low = "red", high = "black") +
+theme(legend.position = "hide") +
+ggtitle("solution")
+#> Scale for 'colour' is already present. Adding another scale for 'colour',
+#> which will replace the existing scale.
+
+
+# we can also obtain the raw plotting data using return_data=TRUE
+plot_data <- plot(p, s, return_data = TRUE)
+print(plot_data)
+#> 'treedata' S4 object'.
+#> 
+#> ...@ phylo:
+#> 
+#> Phylogenetic tree with 5 tips and 4 internal nodes.
+#> 
+#> Tip labels:
+#>      F1,    F2,    F3,    F4,    F5
+#> Node labels:
+#>      NA,    NA,    NA,    NA
+#> 
+#> Rooted; includes branch lengths.
+#> 
+#> with the following features available:
+#>   'status', 'prob'.
+#> 
+#> # The associated data tibble abstraction: 9 × 5
+#> # The 'node', 'label' and 'isTip' are from the phylo tree.
+#>    node label   isTip status    prob
+#>   <int> <chr>   <lgl> <chr>    <dbl>
+#> 1     1 "   F1" TRUE  Funded  0.808 
+#> 2     2 "   F2" TRUE  Funded  0.865 
+#> 3     3 "   F3" TRUE  NA      0.0865
+#> 4     4 "   F4" TRUE  Funded  0.688 
+#> 5     5 "   F5" TRUE  Funded  0.592 
+#> 6     6 "   NA" FALSE NA     NA     
+#> 7     7 "   NA" FALSE NA      0.993 
+#> 8     8 "   NA" FALSE NA      0.976 
+#> 9     9 "   NA" FALSE NA      0.974 
+# }
+
+
+
-
- - - + diff --git a/docs/reference/pproto.html b/docs/reference/pproto.html index 5085679..ee22e48 100644 --- a/docs/reference/pproto.html +++ b/docs/reference/pproto.html @@ -1,79 +1,13 @@ - - - - - - - -Create a new pproto object — pproto • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Create a new pproto object — pproto • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Create a new pproto object

- Source: R/pproto.R + Source: R/pproto.R
@@ -130,78 +57,77 @@

Create a new pproto object

from the ggproto system used in the ggplot2 package.

- 
pproto(`_class` = NULL, `_inherit` = NULL, ...)
+
+ 
pproto(`_class` = NULL, `_inherit` = NULL, ...)
+
-

Arguments

- - - - - - - - - - - - - - -
_class

Class name to assign to the object. This is stored as the class +

+

Arguments

+
_class
+

Class name to assign to the object. This is stored as the class attribute of the object. This is optional: if NULL (the default), -no class name will be added to the object.

_inherit

pproto object to inherit from. If NULL, don"t -inherit from any object.

...

A list of members to add to the new pproto object.

- - -

Examples

- 
Adder <- pproto("Adder",
-  x = 0,
-  add = function(self, n) {
-    self$x <- self$x + n
-    self$x
-  }
-)
-
-Adder$add(10)
-
#> [1] 10
Adder$add(10)
-
#> [1] 20

-Abacus <- pproto("Abacus", Adder,
-  subtract = function(self, n) {
-    self$x <- self$x - n
-    self$x
-  }
-)
-Abacus$add(10)
-
#> [1] 30
Abacus$subtract(10)
-
#> [1] 20

-
+no class name will be added to the object.

+ + +
_inherit
+

pproto object to inherit from. If NULL, don"t +inherit from any object.

+ + +
...
+

A list of members to add to the new pproto object.

+ +
+ +
+

Examples

+ 
Adder <- pproto("Adder",
+  x = 0,
+  add = function(self, n) {
+    self$x <- self$x + n
+    self$x
+  }
+)
+
+Adder$add(10)
+#> [1] 10
+Adder$add(10)
+#> [1] 20
+
+Abacus <- pproto("Abacus", Adder,
+  subtract = function(self, n) {
+    self$x <- self$x - n
+    self$x
+  }
+)
+Abacus$add(10)
+#> [1] 30
+Abacus$subtract(10)
+#> [1] 20
+
+
+
+
- - - - + diff --git a/docs/reference/print.html b/docs/reference/print.html index a9aa26c..c04e5f8 100644 --- a/docs/reference/print.html +++ b/docs/reference/print.html @@ -1,78 +1,12 @@ - - - - - - - -Print — print • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Print — print • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Print

- Source: R/print.R + Source: R/print.R
@@ -128,81 +55,81 @@

Print

Display information about an object.

- 
# S3 method for ProjectProblem
-print(x, ...)
-
-# S3 method for ProjectModifier
-print(x, ...)
-
-# S3 method for Id
-print(x, ...)
-
-# S4 method for Id
-print(x)
-
-# S3 method for OptimizationProblem
-print(x, ...)
-
-# S3 method for ScalarParameter
-print(x, ...)
-
-# S3 method for ArrayParameter
-print(x, ...)
+    

+    
# S3 method for ProjectProblem
+print(x, ...)
+
+# S3 method for ProjectModifier
+print(x, ...)
+
+# S3 method for Id
+print(x, ...)
+
+# S4 method for Id
+print(x)
+
+# S3 method for OptimizationProblem
+print(x, ...)
+
+# S3 method for ScalarParameter
+print(x, ...)
+
+# S3 method for ArrayParameter
+print(x, ...)
+
+# S3 method for Solver
+print(x, ...)

+    

 
-# S3 method for Solver
-print(x, ...)
+
+

Arguments

+
x
+

Any object.

-

Arguments

- - - - - - - - - - -
x

Any object.

...

not used.

-

Value

+
...
+

not used.

-

None.

-

See also

+
+
+

Value

+ -

base::print().

+

None.

+
+
+

See also

+

base::print().

+
-

Examples

- 
a <- 1:4
-print(a)
-
#> [1] 1 2 3 4
+
+

Examples

+ 
a <- 1:4
+print(a)
+#> [1] 1 2 3 4
+
+
+
- - - - + diff --git a/docs/reference/problem-1.png b/docs/reference/problem-1.png index 793caec..52202a1 100644 Binary files a/docs/reference/problem-1.png and b/docs/reference/problem-1.png differ diff --git a/docs/reference/problem.html b/docs/reference/problem.html index aa8055b..05d39cf 100644 --- a/docs/reference/problem.html +++ b/docs/reference/problem.html @@ -1,46 +1,5 @@ - - - - - - - -Project prioritization problem — problem • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Project prioritization problem — problem • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Project prioritization problem

- Source: R/problem.R + Source: R/problem.R
@@ -138,31 +65,31 @@

Project prioritization problem

the management actions, and the features that need to be conserved (e.g. species, ecosystems). After constructing this ProjectProblem-class object, -it can be customized using objectives, targets, -weights, constraints, decisions and -solvers. After building the problem, the -solve() function can be used to identify solutions.

+it can be customized using objectives, targets, +weights, constraints, decisions and +solvers. After building the problem, the +solve() function can be used to identify solutions.

+
+ +
+ 
problem(
+  projects,
+  actions,
+  features,
+  project_name_column,
+  project_success_column,
+  action_name_column,
+  action_cost_column,
+  feature_name_column,
+  adjust_for_baseline = TRUE
+)
- 
problem(
-  projects,
-  actions,
-  features,
-  project_name_column,
-  project_success_column,
-  action_name_column,
-  action_cost_column,
-  feature_name_column,
-  adjust_for_baseline = TRUE
-)
- -

Arguments

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
projects

base::data.frame() or -tibble::tibble() table containing project data. Here, each row +

+

Arguments

+
projects
+

base::data.frame() or +tibble::tibble() table containing project data. Here, each row should correspond to a different project and columns should contain data that correspond to each project. This object should contain data that denote (i) @@ -181,17 +108,17 @@

Arg given the funded projects in a solution, the combined benefits of multiple projects can be encoded by creating additional projects that represent "combined projects". For instance, a habitat restoration project might -cost \$100 and mean that a feature has a 40% chance of persisting, and -a pest eradication project might cost \$50 and mean that a feature has a +cost $100 and mean that a feature has a 40% chance of persisting, and +a pest eradication project might cost $50 and mean that a feature has a 60% chance of persisting. Due to non-linear effects, funding both of these projects might mean that a species has a 90% chance of persistence. This can be accounted for by creating a third project, representing the -funding of both projects, which costs \$150 and provides a 90% chance -of persistence.

actions

base::data.frame() or tibble::tibble() +funding of both projects, which costs $150 and provides a 90% chance +of persistence.

+ + +
actions
+

base::data.frame() or tibble::tibble() table containing the action data. Here, each row should correspond to a different action and columns should contain data that correspond to each action. At a minimum, this object should contain data that denote (i) @@ -199,75 +126,77 @@

Arg action_name_column), (ii) the cost of each action (specified in the argument to action_cost_column). Optionally, it may also contain data that indicate actions should be (iii) locked in or (iv) locked -out (see add_locked_in_constraints() and -add_locked_out_constraints()). It should also contain a -zero-cost baseline action that is associated with the baseline project.

features

base::data.frame() or -tibble::tibble() +out (see add_locked_in_constraints() and +add_locked_out_constraints()). It should also contain a +zero-cost baseline action that is associated with the baseline project.

+ + +
features
+

base::data.frame() or +tibble::tibble() table containing the feature data. Here, each row should correspond to a different feature and columns should contain data that correspond to each feature. At a minimum, this object should contain data that denote (i) the name of each feature (specified in the argument to feature_name_column). Optionally, it may also contain (ii) the -weight for each feature or (iii) persistence targets for each feature.

project_name_column

character name of column that contains +weight for each feature or (iii) persistence targets for each feature.

+ + +
project_name_column
+

character name of column that contains the name for each conservation project. This argument corresponds to the projects table. Note that the project names must not contain any -duplicates or missing values.

project_success_column

character name of column that +duplicates or missing values.

+ + +
project_success_column
+

character name of column that indicates the probability that each project will succeed. This argument corresponds to the argument to projects table. This column must have numeric values which range between zero and one. No missing values -are permitted.

action_name_column

character name of column that contains +are permitted.

+ + +
action_name_column
+

character name of column that contains the name for each management action. This argument corresponds to the actions table. Note that the project names must not contain any -duplicates or missing values.

action_cost_column

character name of column that +duplicates or missing values.

+ + +
action_cost_column
+

character name of column that indicates the cost for funding each action. This argument corresponds to the argument to actions table. This column must have numeric values which are equal to or greater than zero. No missing -values are permitted.

feature_name_column

character name of the column that contains +values are permitted.

+ + +
feature_name_column
+

character name of the column that contains the name for each feature. This argument corresponds to the feature table. Note that the feature names must not contain any -duplicates or missing values.

adjust_for_baseline

logical should the probability of +duplicates or missing values.

+ + +
adjust_for_baseline
+

logical should the probability of features persisting when projects are funded be adjusted to account for the probability of features persisting under the baseline "do nothing" scenario in the event that the funded projects fail to succeed? This should always be TRUE, except when funding a project means that the baseline "do nothing" scenario does not apply if a funded -project fails. Defaults to TRUE.

+project fails. Defaults to TRUE.

-

Value

- -

A new ProjectProblem object.

-

Details

+
+
+

Value

+ +

A new ProjectProblem object.

+
+
+

Details

A project prioritization problem has actions, projects, and features. Features are the biological entities that need to be conserved (e.g. species, populations, ecosystems). Actions are @@ -300,162 +229,172 @@

Details constraints impose limits such as the total budget available for funding management actions. For more information on the mathematical formulations used in this package, please refer to the manual entries for -the available objectives (listed in objectives).

-

See also

- -

constraints, decisions, -objectives, solvers, targets, -weights, solution_statistics(), -plot.ProjectProblem().

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# print project data
-print(sim_projects)
-
#> # A tibble: 6 x 13
-#>   name           success     F1     F2      F3     F4     F5 F1_action F2_action
-#>   <chr>            <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>     <lgl>    
-#> 1 F1_project       0.919  0.791 NA     NA      NA     NA     TRUE      FALSE    
-#> 2 F2_project       0.923 NA      0.888 NA      NA     NA     FALSE     TRUE     
-#> 3 F3_project       0.829 NA     NA      0.502  NA     NA     FALSE     FALSE    
-#> 4 F4_project       0.848 NA     NA     NA       0.690 NA     FALSE     FALSE    
-#> 5 F5_project       0.814 NA     NA     NA      NA      0.617 FALSE     FALSE    
-#> 6 baseline_proj…   1      0.298  0.250  0.0865  0.249  0.182 FALSE     FALSE    
-#> # … with 4 more variables: F3_action <lgl>, F4_action <lgl>, F5_action <lgl>,
-#> #   baseline_action <lgl>

-# print action data
-print(sim_features)
-
#> # A tibble: 5 x 2
-#>   name  weight
-#>   <chr>  <dbl>
-#> 1 F1     0.211
-#> 2 F2     0.211
-#> 3 F3     0.221
-#> 4 F4     0.630
-#> 5 F5     1.59 

-# print feature data
-print(sim_actions)
-
#> # A tibble: 6 x 4
-#>   name             cost locked_in locked_out
-#>   <chr>           <dbl> <lgl>     <lgl>     
-#> 1 F1_action        94.4 FALSE     FALSE     
-#> 2 F2_action       101.  FALSE     FALSE     
-#> 3 F3_action       103.  TRUE      FALSE     
-#> 4 F4_action        99.2 FALSE     FALSE     
-#> 5 F5_action        99.9 FALSE     TRUE      
-#> 6 baseline_action   0   FALSE     FALSE     

-# build problem
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 400) %>%
-     add_feature_weights("weight") %>%
-     add_binary_decisions()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (400)]
-#>   targets:         none
-#>   weights:         min: 0.21136, max: 1.59167
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# \dontrun{
-# solve problem
-s <- solve(p)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xa2bba4dd
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [2e-01, 2e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 4e+02]
-#> Found heuristic solution: objective 0.6654645
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 64 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 64 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 1.749045e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       1.7490448    1.74904  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 1.74904 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 1.749044775334e+00, best bound 1.749044775334e+00, gap 0.0000%

-# print output
-print(s)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL  1.75  395.         1         1         0         1         1
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>

-# print which actions are funded in the solution
-s[, sim_actions$name, drop = FALSE]
-
#> # A tibble: 1 x 6
-#>   F1_action F2_action F3_action F4_action F5_action baseline_action
-#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
-#> 1         1         1         0         1         1               1

-# print the expected probability of persistence for each feature
-# if the solution were implemented
-s[, sim_features$name, drop = FALSE]
-
#> # A tibble: 1 x 5
-#>      F1    F2     F3    F4    F5
-#>   <dbl> <dbl>  <dbl> <dbl> <dbl>
-#> 1 0.808 0.865 0.0865 0.688 0.592

-# visualize solution
-plot(p, s)
-
# }
-
+the available objectives (listed in objectives).

+
+ + +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# print project data
+print(sim_projects)
+#> # A tibble: 6 × 13
+#>   name       success     F1     F2      F3     F4     F5 F1_ac…¹ F2_ac…² F3_ac…³
+#>   <chr>        <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>   <lgl>   <lgl>  
+#> 1 F1_project   0.919  0.791 NA     NA      NA     NA     TRUE    FALSE   FALSE  
+#> 2 F2_project   0.923 NA      0.888 NA      NA     NA     FALSE   TRUE    FALSE  
+#> 3 F3_project   0.829 NA     NA      0.502  NA     NA     FALSE   FALSE   TRUE   
+#> 4 F4_project   0.848 NA     NA     NA       0.690 NA     FALSE   FALSE   FALSE  
+#> 5 F5_project   0.814 NA     NA     NA      NA      0.617 FALSE   FALSE   FALSE  
+#> 6 baseline_…   1      0.298  0.250  0.0865  0.249  0.182 FALSE   FALSE   FALSE  
+#> # … with 3 more variables: F4_action <lgl>, F5_action <lgl>,
+#> #   baseline_action <lgl>, and abbreviated variable names ¹​F1_action,
+#> #   ²​F2_action, ³​F3_action
+
+# print action data
+print(sim_features)
+#> # A tibble: 5 × 2
+#>   name  weight
+#>   <chr>  <dbl>
+#> 1 F1     0.211
+#> 2 F2     0.211
+#> 3 F3     0.221
+#> 4 F4     0.630
+#> 5 F5     1.59 
+
+# print feature data
+print(sim_actions)
+#> # A tibble: 6 × 4
+#>   name             cost locked_in locked_out
+#>   <chr>           <dbl> <lgl>     <lgl>     
+#> 1 F1_action        94.4 FALSE     FALSE     
+#> 2 F2_action       101.  FALSE     FALSE     
+#> 3 F3_action       103.  TRUE      FALSE     
+#> 4 F4_action        99.2 FALSE     FALSE     
+#> 5 F5_action        99.9 FALSE     TRUE      
+#> 6 baseline_action   0   FALSE     FALSE     
+
+# build problem
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 400) %>%
+     add_feature_weights("weight") %>%
+     add_binary_decisions()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (400)]
+#>   targets:         none
+#>   weights:         min: 0.21136, max: 1.59167
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# \dontrun{
+# solve problem
+s <- solve(p)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xa33f6587
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [2e-01, 2e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 4e+02]
+#> Found heuristic solution: objective 0.6654645
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 64 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 64 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.749045e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.7490448    1.74904  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.74904 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.749044775334e+00, best bound 1.749044775334e+00, gap 0.0000%
+
+# print output
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  1.75  395.         1       1       0       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# print which actions are funded in the solution
+s[, sim_actions$name, drop = FALSE]
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         1         1         0         1         1               1
+
+# print the expected probability of persistence for each feature
+# if the solution were implemented
+s[, sim_features$name, drop = FALSE]
+#> # A tibble: 1 × 5
+#>      F1    F2     F3    F4    F5
+#>   <dbl> <dbl>  <dbl> <dbl> <dbl>
+#> 1 0.808 0.865 0.0865 0.688 0.592
+
+# visualize solution
+plot(p, s)
+
+# }
+
+
+
- - - - + diff --git a/docs/reference/project_cost_effectiveness-1.png b/docs/reference/project_cost_effectiveness-1.png index 3b47214..7905310 100644 Binary files a/docs/reference/project_cost_effectiveness-1.png and b/docs/reference/project_cost_effectiveness-1.png differ diff --git a/docs/reference/project_cost_effectiveness.html b/docs/reference/project_cost_effectiveness.html index cf63eb6..c1958c8 100644 --- a/docs/reference/project_cost_effectiveness.html +++ b/docs/reference/project_cost_effectiveness.html @@ -1,80 +1,14 @@ - - - - - - - -Project cost effectiveness — project_cost_effectiveness • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Project cost effectiveness — project_cost_effectiveness • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Project cost effectiveness

- Source: R/project_cost_effectiveness.R + Source: R/project_cost_effectiveness.R

Calculate the individual cost-effectiveness of each conservation project -in a project prioritization problem() +in a project prioritization problem() (Joseph, Maloney & Possingham 2009).

- 
project_cost_effectiveness(x)
+
+ 
project_cost_effectiveness(x)
+
-

Arguments

- - - - - - -
x

project prioritization problem().

+
+

Arguments

+
x
+

project prioritization problem().

-

Value

+
+
+

Value

+ -

A tibble::tibble() table containing the following +

A tibble::tibble() table containing the following columns:

-
-
"project"

character name of each project

-
"cost"

numeric cost of each project.

+
"project"
+

character name of each project

+ + +
"cost"
+

numeric cost of each project.

-
"benefit"

numeric benefit for each project. For a + +

"benefit"
+

numeric benefit for each project. For a given project, this is calculated as the difference between (i) the objective value for a solution containing all of the management actions associated with the project and all zero cost actions, and (ii) the objective value for a solution containing the baseline project.

-
"ce"

numeric cost-effectiveness of each project. + +

"ce"
+

numeric cost-effectiveness of each project. For a given project, this is calculated as the difference between the the benefit for the project and the benefit for the baseline project, divided by the cost of the project. Note that the baseline project will have a NaN value because it has a zero cost.

-
"rank"

numeric rank for each project according to + +

"rank"
+

numeric rank for each project according to is cost-effectiveness value. The project with a rank of one is the most cost-effective project. Ties are accommodated using averages.

-
- -

Details

+
+
+

Details

Note that project cost-effectiveness cannot be calculated for problems with minimum set objectives because the objective function for these problems is to minimize cost and not maximize some measure of biodiversity persistence.

-

References

- +
+
+

References

Joseph LN, Maloney RF & Possingham HP (2009) Optimal allocation of resources among threatened species: A project prioritization protocol. Conservation Biology, 23, 328--338.

-

See also

- -

solution_statistics(), replacement_costs().

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# print project data
-print(sim_projects)
-
#> # A tibble: 6 x 13
-#>   name           success     F1     F2      F3     F4     F5 F1_action F2_action
-#>   <chr>            <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>     <lgl>    
-#> 1 F1_project       0.919  0.791 NA     NA      NA     NA     TRUE      FALSE    
-#> 2 F2_project       0.923 NA      0.888 NA      NA     NA     FALSE     TRUE     
-#> 3 F3_project       0.829 NA     NA      0.502  NA     NA     FALSE     FALSE    
-#> 4 F4_project       0.848 NA     NA     NA       0.690 NA     FALSE     FALSE    
-#> 5 F5_project       0.814 NA     NA     NA      NA      0.617 FALSE     FALSE    
-#> 6 baseline_proj…   1      0.298  0.250  0.0865  0.249  0.182 FALSE     FALSE    
-#> # … with 4 more variables: F3_action <lgl>, F4_action <lgl>, F5_action <lgl>,
-#> #   baseline_action <lgl>

-# print action data
-print(sim_features)
-
#> # A tibble: 5 x 2
-#>   name  weight
-#>   <chr>  <dbl>
-#> 1 F1     0.211
-#> 2 F2     0.211
-#> 3 F3     0.221
-#> 4 F4     0.630
-#> 5 F5     1.59 

-# print feature data
-print(sim_actions)
-
#> # A tibble: 6 x 4
-#>   name             cost locked_in locked_out
-#>   <chr>           <dbl> <lgl>     <lgl>     
-#> 1 F1_action        94.4 FALSE     FALSE     
-#> 2 F2_action       101.  FALSE     FALSE     
-#> 3 F3_action       103.  TRUE      FALSE     
-#> 4 F4_action        99.2 FALSE     FALSE     
-#> 5 F5_action        99.9 FALSE     TRUE      
-#> 6 baseline_action   0   FALSE     FALSE     

-# build problem
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 400) %>%
-     add_feature_weights("weight") %>%
-     add_binary_decisions()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (400)]
-#>   targets:         none
-#>   weights:         min: 0.21136, max: 1.59167
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# calculate cost-effectiveness of each project
-pce <- project_cost_effectiveness(p)
-
-# print project costs, benefits, and cost-effectiveness values
-print(pce)
-
#> # A tibble: 6 x 6
-#>   project           cost   obj benefit         ce  rank
-#>   <chr>            <dbl> <dbl>   <dbl>      <dbl> <dbl>
-#> 1 F1_project        94.4 0.689  0.108    0.00114      4
-#> 2 F2_project       101.  0.711  0.130    0.00129      3
-#> 3 F3_project       103.  0.665  0.0841   0.000815     5
-#> 4 F4_project        99.2 0.858  0.277    0.00279      2
-#> 5 F5_project        99.9 1.23   0.653    0.00654      1
-#> 6 baseline_project   0   0.581  0      NaN            6

-# plot histogram of cost-effectiveness values
-hist(pce$ce, xlab = "Cost effectiveness", main = "")
-
+
+ + +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# print project data
+print(sim_projects)
+#> # A tibble: 6 × 13
+#>   name       success     F1     F2      F3     F4     F5 F1_ac…¹ F2_ac…² F3_ac…³
+#>   <chr>        <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>   <lgl>   <lgl>  
+#> 1 F1_project   0.919  0.791 NA     NA      NA     NA     TRUE    FALSE   FALSE  
+#> 2 F2_project   0.923 NA      0.888 NA      NA     NA     FALSE   TRUE    FALSE  
+#> 3 F3_project   0.829 NA     NA      0.502  NA     NA     FALSE   FALSE   TRUE   
+#> 4 F4_project   0.848 NA     NA     NA       0.690 NA     FALSE   FALSE   FALSE  
+#> 5 F5_project   0.814 NA     NA     NA      NA      0.617 FALSE   FALSE   FALSE  
+#> 6 baseline_…   1      0.298  0.250  0.0865  0.249  0.182 FALSE   FALSE   FALSE  
+#> # … with 3 more variables: F4_action <lgl>, F5_action <lgl>,
+#> #   baseline_action <lgl>, and abbreviated variable names ¹​F1_action,
+#> #   ²​F2_action, ³​F3_action
+
+# print action data
+print(sim_features)
+#> # A tibble: 5 × 2
+#>   name  weight
+#>   <chr>  <dbl>
+#> 1 F1     0.211
+#> 2 F2     0.211
+#> 3 F3     0.221
+#> 4 F4     0.630
+#> 5 F5     1.59 
+
+# print feature data
+print(sim_actions)
+#> # A tibble: 6 × 4
+#>   name             cost locked_in locked_out
+#>   <chr>           <dbl> <lgl>     <lgl>     
+#> 1 F1_action        94.4 FALSE     FALSE     
+#> 2 F2_action       101.  FALSE     FALSE     
+#> 3 F3_action       103.  TRUE      FALSE     
+#> 4 F4_action        99.2 FALSE     FALSE     
+#> 5 F5_action        99.9 FALSE     TRUE      
+#> 6 baseline_action   0   FALSE     FALSE     
+
+# build problem
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 400) %>%
+     add_feature_weights("weight") %>%
+     add_binary_decisions()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (400)]
+#>   targets:         none
+#>   weights:         min: 0.21136, max: 1.59167
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# calculate cost-effectiveness of each project
+pce <- project_cost_effectiveness(p)
+
+# print project costs, benefits, and cost-effectiveness values
+print(pce)
+#> # A tibble: 6 × 6
+#>   project           cost   obj benefit         ce  rank
+#>   <chr>            <dbl> <dbl>   <dbl>      <dbl> <dbl>
+#> 1 F1_project        94.4 0.689  0.108    0.00114      4
+#> 2 F2_project       101.  0.711  0.130    0.00129      3
+#> 3 F3_project       103.  0.665  0.0841   0.000815     5
+#> 4 F4_project        99.2 0.858  0.277    0.00279      2
+#> 5 F5_project        99.9 1.23   0.653    0.00654      1
+#> 6 baseline_project   0   0.581  0      NaN            6
+
+# plot histogram of cost-effectiveness values
+hist(pce$ce, xlab = "Cost effectiveness", main = "")
+
+
+
+
-
- - - + diff --git a/docs/reference/project_names.html b/docs/reference/project_names.html index 750b76e..dc58ebf 100644 --- a/docs/reference/project_names.html +++ b/docs/reference/project_names.html @@ -1,78 +1,12 @@ - - - - - - - -Project names — project_names • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Project names — project_names • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Project names

- Source: R/project_names.R + Source: R/project_names.R
@@ -128,80 +55,80 @@

Project names

Extract the names of the projects in an object.

- 
project_names(x)
-
-# S4 method for ProjectProblem
-project_names(x)
- -

Arguments

- - - - - - -
x

ProjectProblem.

- -

Value

- -

character project names.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with default solver
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions() %>%
-     add_default_solver()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (200)]
-#>   targets:         none
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]

-# print project names
-project_names(p)
-
#> [1] "F1_project"       "F2_project"       "F3_project"       "F4_project"      
-#> [5] "F5_project"       "baseline_project"
+
+ 
project_names(x)
+
+# S4 method for ProjectProblem
+project_names(x)
+
+ +
+

Arguments

+
x
+

ProjectProblem.

+ +
+
+

Value

+ + +

character project names.

+
+ +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with default solver
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions() %>%
+     add_default_solver()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (200)]
+#>   targets:         none
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          Gurobi [first_feasible (0), gap (0), number_solutions (1), presolve (2), solution_pool_method (2), threads (1), time_limit (2147483647), time_limit (2147483647), verbose (1)]
+
+# print project names
+project_names(p)
+#> [1] "F1_project"       "F2_project"       "F3_project"       "F4_project"      
+#> [5] "F5_project"       "baseline_project"
+
+
+
- - - - + diff --git a/docs/reference/replacement_costs-1.png b/docs/reference/replacement_costs-1.png index 1616093..5246dc0 100644 Binary files a/docs/reference/replacement_costs-1.png and b/docs/reference/replacement_costs-1.png differ diff --git a/docs/reference/replacement_costs.html b/docs/reference/replacement_costs.html index 55cf382..ae3f7ed 100644 --- a/docs/reference/replacement_costs.html +++ b/docs/reference/replacement_costs.html @@ -1,82 +1,16 @@ - - - - - - - -Replacement cost — replacement_costs • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Replacement cost — replacement_costs • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Replacement cost

- Source: R/replacement_costs.R + Source: R/replacement_costs.R

Calculate the replacement cost for priority actions in a project -prioritization problem() (Moilanen et al. 2009). Actions associated -with larger replacement cost values are more irreplaceabe, and may +prioritization problem() (Moilanen et al. 2009). Actions associated +with larger replacement cost values are more irreplaceable, and may need to be implemented sooner than actions with lower replacement cost values.

- 
replacement_costs(x, solution, n = 1)
- -

Arguments

- - - - - - - - - - - - - - -
x

project prioritization problem().

solution

base::data.frame() or -tibble::tibble() table containing the solutions. Here, +

+ 
replacement_costs(x, solution, n = 1)
+
+ +
+

Arguments

+
x
+

project prioritization problem().

+ + +
solution
+

base::data.frame() or +tibble::tibble() table containing the solutions. Here, rows correspond to different solutions and columns correspond to different actions. Each column in the argument to solution should be named according to a different action in x. Cell values indicate if an action is funded in a given solution or not, and should be either zero or one. Arguments to solution can -contain additional columns, and they will be ignored.

n

integer solution number to calculate replacement cost values. +contain additional columns, and they will be ignored.

+ + +
n
+

integer solution number to calculate replacement cost values. Since each row in the argument to solutions corresponds to a different solution, this argument should correspond to a row in -the argument to solutions. Defaults to 1.

+the argument to solutions. Defaults to 1.

-

Value

+
+
+

Value

+ -

A tibble::tibble() table containing the following +

A tibble::tibble() table containing the following columns:

-
-
"action"

character name of each action.

-
"cost"

numeric cost of each solution when each +

"action"
+

character name of each action.

+ + +
"cost"
+

numeric cost of each solution when each action is locked out.

-
"obj"

numeric objective value of each solution when + +

"obj"
+

numeric objective value of each solution when each action is locked out. This is calculated using the objective function defined for the argument to x.

-
"rep_cost"

numeric replacement cost for each + +

"rep_cost"
+

numeric replacement cost for each action. Greater values indicate greater irreplaceability. Missing (NA) values are assigned to actions which are not selected for funding in the specified solution, infinite (Inf) values are @@ -189,10 +124,10 @@

Value

the specified solution exist.

-
- -

Details

+
+
+

Details

Replacement cost values are calculated for each priority action specified in the solution. Missing (NA) values are assigned to actions which are not selected for funding in the specified solution. @@ -202,124 +137,129 @@

Details optimal solution to the argument to x with the given action locked out, (iii) calculating the difference between the two objective values, (iv) the problem has an objective which aims to minimize -the objective value (only add_min_set_objective(), then +the objective value (only add_min_set_objective(), then the resulting value is multiplied by minus one so that larger values always indicate actions with greater irreplaceability. Please note this function can take a long time to complete for large problems since it involves re-solving the problem for every action selected for funding.

-

References

- +
+
+

References

Moilanen A, Arponen A, Stokland JN & Cabeza M (2009) Assessing replacement cost of conservation areas: how does habitat loss influence priorities? Biological Conservation, 142, 575--585.

-

See also

- -

solution_statistics(), -project_cost_effectiveness().

- -

Examples

- 
# \dontrun{
-# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with maximum richness objective and $400 budget
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 400) %>%
-     add_feature_weights("weight") %>%
-     add_binary_decisions()
-
-# solve problem
-s <- solve(p)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xa2bba4dd
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [2e-01, 2e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 4e+02]
-#> Found heuristic solution: objective 0.6654645
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 64 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 64 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 1.749045e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       1.7490448    1.74904  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 1.74904 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 1.749044775334e+00, best bound 1.749044775334e+00, gap 0.0000%

-# print solution
-print(s)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL  1.75  395.         1         1         0         1         1
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>

-# calculate replacement cost values
-r <- replacement_costs(p, s)
-
-# print output
-print(r)
-
#> # A tibble: 6 x 4
-#>   name             cost    obj  rep_cost
-#>   <chr>           <dbl>  <dbl>     <dbl>
-#> 1 F1_action        300.   1.64    0.108 
-#> 2 F2_action        397.   1.70    0.0458
-#> 3 F3_action         NA   NA      NA     
-#> 4 F4_action        399.   1.56    0.192 
-#> 5 F5_action        398.   1.18    0.569 
-#> 6 baseline_action  Inf  Inf    -Inf     

-# plot histogram of replacement costs,
-# with this objective, greater values indicate greater irreplaceability
-hist(r$rep_cost, xlab = "Replacement cost", main = "")
-
# }
-
+
+ + +
+

Examples

+ 
# \dontrun{
+# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with maximum richness objective and $400 budget
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 400) %>%
+     add_feature_weights("weight") %>%
+     add_binary_decisions()
+
+# solve problem
+s <- solve(p)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xa33f6587
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [2e-01, 2e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 4e+02]
+#> Found heuristic solution: objective 0.6654645
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 64 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 64 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.749045e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.7490448    1.74904  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.74904 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.749044775334e+00, best bound 1.749044775334e+00, gap 0.0000%
+
+# print solution
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  1.75  395.         1       1       0       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# calculate replacement cost values
+r <- replacement_costs(p, s)
+
+# print output
+print(r)
+#> # A tibble: 6 × 4
+#>   name             cost    obj  rep_cost
+#>   <chr>           <dbl>  <dbl>     <dbl>
+#> 1 F1_action        300.   1.64    0.108 
+#> 2 F2_action        397.   1.70    0.0458
+#> 3 F3_action         NA   NA      NA     
+#> 4 F4_action        399.   1.56    0.192 
+#> 5 F5_action        398.   1.18    0.569 
+#> 6 baseline_action  Inf  Inf    -Inf     
+
+# plot histogram of replacement costs,
+# with this objective, greater values indicate greater irreplaceability
+hist(r$rep_cost, xlab = "Replacement cost", main = "")
+
+# }
+
+
+
- - - - + diff --git a/docs/reference/scalar_parameters.html b/docs/reference/scalar_parameters.html index 06fde52..ab4f870 100644 --- a/docs/reference/scalar_parameters.html +++ b/docs/reference/scalar_parameters.html @@ -1,82 +1,16 @@ - - - - - - - -Scalar parameters — scalar_parameters • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Scalar parameters — scalar_parameters • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Scalar parameters

- Source: R/parameters.R + Source: R/parameters.R

These functions are used to create parameters that consist of a single number. Parameters have a name, a value, a defined range of acceptable -values, a default value, a class, and a shiny::shiny() widget for +values, a default value, a class, and a shiny::shiny() widget for modifying them. If values are supplied to a parameter that are unacceptable then an error is thrown.

- 
proportion_parameter(name, value)
-
-binary_parameter(name, value)
-
-integer_parameter(
-  name,
-  value,
-  lower_limit = as.integer(-.Machine$integer.max),
-  upper_limit = as.integer(.Machine$integer.max)
-)
-
-numeric_parameter(
-  name,
-  value,
-  lower_limit = .Machine$double.xmin,
-  upper_limit = .Machine$double.xmax
-)
- -

Arguments

- - - - - - - - - - - - - - - - - - -
name

character name of parameter.

value

integer or double value depending on the -parameter.

lower_limit

integer or double value representing +

+ 
proportion_parameter(name, value)
+
+binary_parameter(name, value)
+
+integer_parameter(
+  name,
+  value,
+  lower_limit = as.integer(-.Machine$integer.max),
+  upper_limit = as.integer(.Machine$integer.max)
+)
+
+numeric_parameter(
+  name,
+  value,
+  lower_limit = .Machine$double.xmin,
+  upper_limit = .Machine$double.xmax
+)
+
+ +
+

Arguments

+
name
+

character name of parameter.

+ + +
value
+

integer or double value depending on the +parameter.

+ + +
lower_limit
+

integer or double value representing the smallest acceptable value for value. Defaults to -the smallest possible number on the system.

upper_limit

integer or double value representing -the largest acceptable value for value. Defaults to -the largest possible number on the system.

+the smallest possible number on the system.

+ -

Value

+
upper_limit
+

integer or double value representing +the largest acceptable value for value. Defaults to +the largest possible number on the system.

-

ScalarParameter object.

-

Details

+
+
+

Value

+ +

ScalarParameter object.

+
+
+

Details

Below is a list of parameter generating functions and a brief description of each.

-
- -
proportion_parameter

A parameter that is a double and bounded +

proportion_parameter
+

A parameter that is a double and bounded between zero and one.

-
integer_parameter

A parameter that is a integer.

-
numeric_parameter

A parameter that is a double.

+
integer_parameter
+

A parameter that is a integer.

+ -
binary_parameter

A parameter that is restricted to integer +

numeric_parameter
+

A parameter that is a double.

+ + +
binary_parameter
+

A parameter that is restricted to integer values of zero or one.

-
- - -

Examples

- 
# proportion parameter
-p1 <- proportion_parameter('prop', 0.5) # create new object
-print(p1) # print it
-
#> prop (0.5)
p1$get() # get value
-
#> [1] 0.5
p1$id # get id
-
#> id: dc75c525-7418-4c09-92cb-74f021782bc5
p1$validate(5) # check if 5 is a validate input
-p1$validate(0.1) # check if 0.1 is a validate input
-p1$set(0.1) # change value to 0.1
-print(p1)
-
#> prop (0.1)

-# binary parameter
-p2 <- binary_parameter('bin', 0) # create new object
-print(p2) # print it
-
#> bin (0)
p2$get() # get value
-
#> [1] 0
p2$id # get id
-
#> id: ee4b55f5-b27c-4ea3-8afe-7c7687bd2664
p2$validate(5) # check if 5 is a validate input
-p2$validate(1L) # check if 1L is a validate input
-p2$set(1L) # change value to 1L
-print(p1) # print it again
-
#> prop (0.1)

-# integer parameter
-p3 <- integer_parameter('int', 5L) # create new object
-print(p3) # print it
-
#> int (5)
p3$get() # get value
-
#> [1] 5
p3$id # get id
-
#> id: 6dae68e4-a89e-44d1-a5b5-edf4d9d2a49c
p3$validate(5.6) # check if 5.6 is a validate input
-p3$validate(2L) # check if 2L is a validate input
-p3$set(2L) # change value to 2L
-print(p3) # print it again
-
#> int (2)

-# numeric parameter
-p4 <- numeric_parameter('dbl', -7.6) # create new object
-print(p4) # print it
-
#> dbl (-7.6)
p4$get() # get value
-
#> [1] -7.6
p4$id # get id
-
#> id: 2f1e2a10-0b56-4e4c-9034-bea23a90b7b1
p4$validate(NA) # check if NA is a validate input
-p4$validate(8.9) # check if 8.9 is a validate input
-p4$set(8.9) # change value to 8.9
-print(p4) # print it again
-
#> dbl (8.9)

-# numeric parameter with lower bounds
-p5 <- numeric_parameter('bdbl', 6, lower_limit=0) # create new object
-print(p5) # print it
-
#> bdbl (6)
p5$get() # get value
-
#> [1] 6
p5$id # get id
-
#> id: 365a2fe6-34ba-4b71-bf4a-d10138762760
p5$validate(-10) # check if -10 is a validate input
-p5$validate(90) # check if 90 is a validate input
-p5$set(90) # change value to 8.9
-print(p5) # print it again
-
#> bdbl (90)

-
+ +
+ +
+

Examples

+ 
# proportion parameter
+p1 <- proportion_parameter('prop', 0.5) # create new object
+print(p1) # print it
+#> prop (0.5)
+p1$get() # get value
+#> [1] 0.5
+p1$id # get id
+#> id: 83111d5a-0878-4acf-85a4-4e89aced7154
+p1$validate(5) # check if 5 is a validate input
+p1$validate(0.1) # check if 0.1 is a validate input
+p1$set(0.1) # change value to 0.1
+print(p1)
+#> prop (0.1)
+
+# binary parameter
+p2 <- binary_parameter('bin', 0) # create new object
+print(p2) # print it
+#> bin (0)
+p2$get() # get value
+#> [1] 0
+p2$id # get id
+#> id: 53bca62a-02ef-433d-8d5e-9b37f0556279
+p2$validate(5) # check if 5 is a validate input
+p2$validate(1L) # check if 1L is a validate input
+p2$set(1L) # change value to 1L
+print(p1) # print it again
+#> prop (0.1)
+
+# integer parameter
+p3 <- integer_parameter('int', 5L) # create new object
+print(p3) # print it
+#> int (5)
+p3$get() # get value
+#> [1] 5
+p3$id # get id
+#> id: d3bb68f4-5d23-4d81-b17f-19a4ae6aa49a
+p3$validate(5.6) # check if 5.6 is a validate input
+p3$validate(2L) # check if 2L is a validate input
+p3$set(2L) # change value to 2L
+print(p3) # print it again
+#> int (2)
+
+# numeric parameter
+p4 <- numeric_parameter('dbl', -7.6) # create new object
+print(p4) # print it
+#> dbl (-7.6)
+p4$get() # get value
+#> [1] -7.6
+p4$id # get id
+#> id: dc000f44-9f47-4c72-bd24-bbc7ff2f7429
+p4$validate(NA) # check if NA is a validate input
+p4$validate(8.9) # check if 8.9 is a validate input
+p4$set(8.9) # change value to 8.9
+print(p4) # print it again
+#> dbl (8.9)
+
+# numeric parameter with lower bounds
+p5 <- numeric_parameter('bdbl', 6, lower_limit=0) # create new object
+print(p5) # print it
+#> bdbl (6)
+p5$get() # get value
+#> [1] 6
+p5$id # get id
+#> id: 38e23d65-e3ab-4c73-852b-9288c04fcb6a
+p5$validate(-10) # check if -10 is a validate input
+p5$validate(90) # check if 90 is a validate input
+p5$set(90) # change value to 8.9
+print(p5) # print it again
+#> bdbl (90)
+
+
+
+
- - - - + diff --git a/docs/reference/show.html b/docs/reference/show.html index 94a75f1..9243948 100644 --- a/docs/reference/show.html +++ b/docs/reference/show.html @@ -1,76 +1,12 @@ - - - - - - - -Show — show • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Show — show • oppr - - - - - - - - - - - +
-
- -
- -
+

Show

- Source: R/show.R + Source: R/show.R
@@ -126,67 +55,64 @@

Show

Display information about an object.

- 
# S4 method for ProjectModifier
-show(x)
-
-# S4 method for ProjectProblem
-show(x)
-
-# S4 method for Id
-show(x)
-
-# S4 method for OptimizationProblem
-show(x)
-
-# S4 method for Parameter
-show(x)
-
-# S4 method for Solver
-show(x)
- -

Arguments

- - - - - - -
x

Any object.

+
+ 
# S4 method for ProjectModifier
+show(x)
+
+# S4 method for ProjectProblem
+show(x)
+
+# S4 method for Id
+show(x)
+
+# S4 method for OptimizationProblem
+show(x)
+
+# S4 method for Parameter
+show(x)
+
+# S4 method for Solver
+show(x)
+
-

Value

+
+

Arguments

+
x
+

Any object.

-

None.

-

See also

+
+
+

Value

+ -

methods::show().

+

None.

+
+
+

See also

+

methods::show().

+
+
- - - - + diff --git a/docs/reference/sim_data.html b/docs/reference/sim_data.html index 3f8d257..c39e778 100644 --- a/docs/reference/sim_data.html +++ b/docs/reference/sim_data.html @@ -1,78 +1,12 @@ - - - - - - - -Simulated data — sim_data • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Simulated data — sim_data • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Simulated data

- Source: R/data.R + Source: R/data.R
-

Simulated data for prioritizing conservations projects.

+

Simulated data for prioritizing conservation projects.

- 
data(sim_actions)
-
-data(sim_projects)
-
-data(sim_features)
-
-data(sim_tree)
+
+ 
data(sim_actions)
+
+data(sim_projects)
+
+data(sim_features)
+
+data(sim_tree)
+
+
+

Format

+ +
sim_projects
+

tibble::tibble() object.

-

Format

+
sim_actions
+

tibble::tibble() object.

- -
-
sim_projects

tibble::tibble() object.

-
sim_actions

tibble::tibble() object.

-
sim_features

tibble::tibble() object.

-
sim_tree

ape::phylo() object.

+
sim_features
+

tibble::tibble() object.

-
+
sim_tree
+

ape::phylo() object.

-

Details

+
+
+

Details

The data set contains the following objects:

-
-
sim_projects

A tibble::tibble() object containing +

sim_projects
+

A tibble::tibble() object containing data for six simulated conservation projects. Each row corresponds to a different project and each column contains information about the -projects. This table contains the following columns: -

-
"name"

character name for each project.

-
"success"

numeric probability of each project +projects. This table contains the following columns:

"name"
+

character name for each project.

+ +
"success"
+

numeric probability of each project succeeding if it is funded.

-
"F1" ... "F5"

numeric columns for each + +

"F1" ... "F5"
+

numeric columns for each feature (i.e. "F1", "F2", "F3", "F4", "F5", indicating the enhanced probability that each feature will survive if it funded. Missing values (NA) indicate that a feature does not benefit from a project being funded.

-
"F1_action" ... "F5_action"

logical + +

"F1_action" ... "F5_action"
+

logical columns for each action, ranging from "F1_action" to "F5_action" indicating if an action is associated with a project (TRUE) or not (FALSE).

-
"baseline_action"

logical + +

"baseline_action"
+

logical column indicating if a project is associated with the baseline action (TRUE) or not (FALSE). This action is only -associated with the baseline project.

-
sim_actions

A tibble::tibble() object containing +associated with the baseline project.

+ + +
+ +
sim_actions
+

A tibble::tibble() object containing data for six simulated actions. Each row corresponds to a different action and each column contains information about the -actions. This table contains the following columns: -

-
"name"

character name for each action.

-
"cost"

numeric cost for each action.

-
"locked_in"

logical indicating if certain +actions. This table contains the following columns:

"name"
+

character name for each action.

+ +
"cost"
+

numeric cost for each action.

+ +
"locked_in"
+

logical indicating if certain actions should be locked into the solution.

-
"locked_out"

logical indicating if certain -actions should be locked out of the solution.

-
sim_features

A tibble::tibble() object containing + +

"locked_out"
+

logical indicating if certain +actions should be locked out of the solution.

+ + +
+ +
sim_features
+

A tibble::tibble() object containing data for five simulated features. Each row corresponds to a different feature and each column contains information about the -features. This table contains the following columns: -

-
"name"

character name for each feature.

-
"weight"

numeric weight for each feature.

-
tree

ape::phylo() phylogenetic tree for the features.

- -
- - -

Examples

- 
# load data
-data(sim_projects, sim_actions, sim_features, sim_tree)
-
-# print project data
-print(sim_projects)
-
#> # A tibble: 6 x 13
-#>   name           success     F1     F2      F3     F4     F5 F1_action F2_action
-#>   <chr>            <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>     <lgl>    
-#> 1 F1_project       0.919  0.791 NA     NA      NA     NA     TRUE      FALSE    
-#> 2 F2_project       0.923 NA      0.888 NA      NA     NA     FALSE     TRUE     
-#> 3 F3_project       0.829 NA     NA      0.502  NA     NA     FALSE     FALSE    
-#> 4 F4_project       0.848 NA     NA     NA       0.690 NA     FALSE     FALSE    
-#> 5 F5_project       0.814 NA     NA     NA      NA      0.617 FALSE     FALSE    
-#> 6 baseline_proj…   1      0.298  0.250  0.0865  0.249  0.182 FALSE     FALSE    
-#> # … with 4 more variables: F3_action <lgl>, F4_action <lgl>, F5_action <lgl>,
-#> #   baseline_action <lgl>
# print action data
-print(sim_actions)
-
#> # A tibble: 6 x 4
-#>   name             cost locked_in locked_out
-#>   <chr>           <dbl> <lgl>     <lgl>     
-#> 1 F1_action        94.4 FALSE     FALSE     
-#> 2 F2_action       101.  FALSE     FALSE     
-#> 3 F3_action       103.  TRUE      FALSE     
-#> 4 F4_action        99.2 FALSE     FALSE     
-#> 5 F5_action        99.9 FALSE     TRUE      
-#> 6 baseline_action   0   FALSE     FALSE     

-# print feature data
-print(sim_features)
-
#> # A tibble: 5 x 2
-#>   name  weight
-#>   <chr>  <dbl>
-#> 1 F1     0.211
-#> 2 F2     0.211
-#> 3 F3     0.221
-#> 4 F4     0.630
-#> 5 F5     1.59 
# plot phylogenetic tree
-plot(sim_tree)
-

-
+features. This table contains the following columns:

"name"
+

character name for each feature.

+ +
"weight"
+

numeric weight for each feature.

+ + +
+ +
tree
+

ape::phylo() phylogenetic tree for the features.

+ + +
+ +
+

Examples

+ 
# load data
+data(sim_projects, sim_actions, sim_features, sim_tree)
+
+# print project data
+print(sim_projects)
+#> # A tibble: 6 × 13
+#>   name       success     F1     F2      F3     F4     F5 F1_ac…¹ F2_ac…² F3_ac…³
+#>   <chr>        <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>   <lgl>   <lgl>  
+#> 1 F1_project   0.919  0.791 NA     NA      NA     NA     TRUE    FALSE   FALSE  
+#> 2 F2_project   0.923 NA      0.888 NA      NA     NA     FALSE   TRUE    FALSE  
+#> 3 F3_project   0.829 NA     NA      0.502  NA     NA     FALSE   FALSE   TRUE   
+#> 4 F4_project   0.848 NA     NA     NA       0.690 NA     FALSE   FALSE   FALSE  
+#> 5 F5_project   0.814 NA     NA     NA      NA      0.617 FALSE   FALSE   FALSE  
+#> 6 baseline_…   1      0.298  0.250  0.0865  0.249  0.182 FALSE   FALSE   FALSE  
+#> # … with 3 more variables: F4_action <lgl>, F5_action <lgl>,
+#> #   baseline_action <lgl>, and abbreviated variable names ¹​F1_action,
+#> #   ²​F2_action, ³​F3_action
+# print action data
+print(sim_actions)
+#> # A tibble: 6 × 4
+#>   name             cost locked_in locked_out
+#>   <chr>           <dbl> <lgl>     <lgl>     
+#> 1 F1_action        94.4 FALSE     FALSE     
+#> 2 F2_action       101.  FALSE     FALSE     
+#> 3 F3_action       103.  TRUE      FALSE     
+#> 4 F4_action        99.2 FALSE     FALSE     
+#> 5 F5_action        99.9 FALSE     TRUE      
+#> 6 baseline_action   0   FALSE     FALSE     
+
+# print feature data
+print(sim_features)
+#> # A tibble: 5 × 2
+#>   name  weight
+#>   <chr>  <dbl>
+#> 1 F1     0.211
+#> 2 F2     0.211
+#> 3 F3     0.221
+#> 4 F4     0.630
+#> 5 F5     1.59 
+# plot phylogenetic tree
+plot(sim_tree)
+
+
+
+
+
-
- - - + diff --git a/docs/reference/simulate_ppp_data.html b/docs/reference/simulate_ppp_data.html index 5913a09..c632b41 100644 --- a/docs/reference/simulate_ppp_data.html +++ b/docs/reference/simulate_ppp_data.html @@ -1,80 +1,14 @@ - - - - - - - -Simulate data for the 'Project Prioritization Protocol' — simulate_ppp_data • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Simulate data for the 'Project Prioritization Protocol' — simulate_ppp_data • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Simulate data for the 'Project Prioritization Protocol'

- Source: R/simulate_ppp_data.R + Source: R/simulate_ppp_data.R
@@ -132,145 +59,175 @@

Simulate data for the 'Project Prioritization Protocol'

similar to species-based prioritizations (e.g. Bennett et al. 2014).

- 
simulate_ppp_data(
-  number_features,
-  cost_mean = 100,
-  cost_sd = 5,
-  success_min_probability = 0.7,
-  success_max_probability = 0.99,
-  funded_min_persistence_probability = 0.5,
-  funded_max_persistence_probability = 0.9,
-  baseline_min_persistence_probability = 0.01,
-  baseline_max_persistence_probability = 0.4,
-  locked_in_proportion = 0,
-  locked_out_proportion = 0
-)
- -

Arguments

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
number_features

numeric number of features.

cost_mean

numeric average cost for the actions. Defaults to -100.

cost_sd

numeric standard deviation in action costs. Defaults -to 5.

success_min_probability

numeric minimum probability of the -projects succeeding if they are funded. Defaults to 0.7.

success_max_probability

numeric maximum probability of the -projects succeeding if they are funded. Defaults to 0.99.

funded_min_persistence_probability

numeric minimum probability +

+ 
simulate_ppp_data(
+  number_features,
+  cost_mean = 100,
+  cost_sd = 5,
+  success_min_probability = 0.7,
+  success_max_probability = 0.99,
+  funded_min_persistence_probability = 0.5,
+  funded_max_persistence_probability = 0.9,
+  baseline_min_persistence_probability = 0.01,
+  baseline_max_persistence_probability = 0.4,
+  locked_in_proportion = 0,
+  locked_out_proportion = 0
+)
+
+ +
+

Arguments

+
number_features
+

numeric number of features.

+ + +
cost_mean
+

numeric average cost for the actions. Defaults to +100.

+ + +
cost_sd
+

numeric standard deviation in action costs. Defaults +to 5.

+ + +
success_min_probability
+

numeric minimum probability of the +projects succeeding if they are funded. Defaults to 0.7.

+ + +
success_max_probability
+

numeric maximum probability of the +projects succeeding if they are funded. Defaults to 0.99.

+ + +
funded_min_persistence_probability
+

numeric minimum probability of the features persisting if projects are funded and successful. -Defaults to 0.5.

funded_max_persistence_probability

numeric maximum probability +Defaults to 0.5.

+ + +
funded_max_persistence_probability
+

numeric maximum probability of the features persisting if projects are funded and successful. -Defaults to 0.9.

baseline_min_persistence_probability

numeric minimum +Defaults to 0.9.

+ + +
baseline_min_persistence_probability
+

numeric minimum probability of the features persisting if only the baseline project -is funded. Defaults to 0.01.

baseline_max_persistence_probability

numeric maximum +is funded. Defaults to 0.01.

+ + +
baseline_max_persistence_probability
+

numeric maximum probability of the features persisting if only the baseline project is -funded. Defaults to 0.4.

locked_in_proportion

numeric of actions that are locked -into the solution. Defaults to 0.

locked_out_proportion

numeric of actions that are locked -into the solution. Defaults to 0.

- -

Value

- -

A list object containing the elements:

-
-
"projects"

A tibble::tibble() containing +funded. Defaults to 0.4.

+ + +
locked_in_proportion
+

numeric of actions that are locked +into the solution. Defaults to 0.

+ + +
locked_out_proportion
+

numeric of actions that are locked +into the solution. Defaults to 0.

+ +
+
+

Value

+ + +

A list object containing the elements:

+ + +
"projects"
+

A tibble::tibble() containing the data for the conservation projects. It contains the following -columns: -

-
"name"

character name for each project.

-
"success"

numeric probability of each project +columns:

"name"
+

character name for each project.

+ +
"success"
+

numeric probability of each project succeeding if it is funded.

-
"F1" ... "FN"

numeric columns for each + +

"F1" ... "FN"
+

numeric columns for each feature, ranging from "F1" to "FN" where N is the number of features, indicating the enhanced probability that each feature will persist if it funded. Missing values (NA) indicate that a feature does not benefit from a project being funded.

-
"F1_action" ... "FN_action"

logical + +

"F1_action" ... "FN_action"
+

logical columns for each action, ranging from "F1_action" to "FN_action" where N is the number of actions (equal to the number of features in this simulated data), indicating if an action is associated with a project (TRUE) or not (FALSE).

-
"baseline_action"

logical + +

"baseline_action"
+

logical column indicating if a project is associated with the baseline action (TRUE) or not (FALSE). This action is only -associated with the baseline project.

-
"actions"

A tibble::tibble() containing +associated with the baseline project.

+ + +
+ +
"actions"
+

A tibble::tibble() containing the data for the conservation actions. It contains the following -columns: -

-
"name"

character name for each action.

-
"cost"

numeric cost for each action.

-
"locked_in"

logical indicating if certain +columns:

"name"
+

character name for each action.

+ +
"cost"
+

numeric cost for each action.

+ +
"locked_in"
+

logical indicating if certain actions should be locked into the solution.

-
"locked_out"

logical indicating if certain -actions should be locked out of the solution.

-
"features"

A tibble::tibble() containing + +

"locked_out"
+

logical indicating if certain +actions should be locked out of the solution.

+ + +
+ +
"features"
+

A tibble::tibble() containing the data for the conservation features (e.g. species). It contains the -following columns: -

-
"name"

character name for each feature.

-
"weight"

numeric weight for each feature. +following columns:

"name"
+

character name for each feature.

+ +
"weight"
+

numeric weight for each feature. For each feature, this is calculated as the amount of time that elapsed between the present and the features' last common ancestor. In other words, the weights are calculated as the unique amount -of evolutionary history that each feature has experienced.

-
"tree"

ape::phylo() phylogenetic tree for the -features.

+of evolutionary history that each feature has experienced.

-
-

Details

+ +
"tree"
+

ape::phylo() phylogenetic tree for the +features.

+ + +
+
+

Details

The simulated data set will contain one conservation project for each features, and also a "baseline" (do nothing) project to reflect features' persistence when their conservation project is not funded. Each conservation project is associated with a single action, and no conservation projects share any actions. Specifically, the data are simulated as follows:

-
    -

  1. A conservation project is created for each feature, and each +

    1. A conservation project is created for each feature, and each project is associated with its own single action.

    2. Cost data for each action are simulated using a normal distribution and the cost_mean and cost_sd arguments.

      3. @@ -293,110 +250,109 @@

      Details set as the baseline_min_persistence_probability and baseline_max_persistence_probability arguments.

    3. A phylogenetic tree is simulated for the features using -ape::rcoal().

      4. +ape::rcoal().

    4. Feature data are created from the phylogenetic tree. The weights are calculated as the amount of evolutionary history that has elapsed between each feature and its last common ancestor.

      5. -

    - -

    References

    - +
+
+

References

Bennett JR, Elliott G, Mellish B, Joseph LN, Tulloch AI, Probert WJ, ... & Maloney R (2014) Balancing phylogenetic diversity and species numbers in conservation prioritization, using a case study of threatened species in New Zealand. Biological Conservation, 174: 47--54.

-

See also

- -

simulate_ptm_data().

- -

Examples

- 
# create a simulated data set
-s <- simulate_ppp_data(number_features = 5,
-                       cost_mean = 100,
-                       cost_sd = 5,
-                       success_min_probability = 0.7,
-                       success_max_probability = 0.99,
-                       funded_min_persistence_probability = 0.5,
-                       funded_max_persistence_probability = 0.9,
-                       baseline_min_persistence_probability = 0.01,
-                       baseline_max_persistence_probability = 0.4,
-                       locked_in_proportion = 0.01,
-                       locked_out_proportion = 0.01)
-
-# print data set
-print(s)
-
#> $projects
-#> # A tibble: 6 x 13
-#>   name  success     F1     F2     F3     F4     F5 F1_action F2_action F3_action
-#>   <chr>   <dbl>  <dbl>  <dbl>  <dbl>  <dbl>  <dbl> <lgl>     <lgl>     <lgl>    
-#> 1 F1_p…   0.711  0.830 NA     NA     NA     NA     TRUE      FALSE     FALSE    
-#> 2 F2_p…   0.879 NA      0.516 NA     NA     NA     FALSE     TRUE      FALSE    
-#> 3 F3_p…   0.728 NA     NA      0.872 NA     NA     FALSE     FALSE     TRUE     
-#> 4 F4_p…   0.809 NA     NA     NA      0.518 NA     FALSE     FALSE     FALSE    
-#> 5 F5_p…   0.944 NA     NA     NA     NA      0.578 FALSE     FALSE     FALSE    
-#> 6 base…   1      0.174  0.335  0.199  0.343  0.240 FALSE     FALSE     FALSE    
-#> # … with 3 more variables: F4_action <lgl>, F5_action <lgl>,
-#> #   baseline_action <lgl>
-#> 
-#> $actions
-#> # A tibble: 6 x 4
-#>   name             cost locked_in locked_out
-#>   <chr>           <dbl> <lgl>     <lgl>     
-#> 1 F1_action        105. FALSE     FALSE     
-#> 2 F2_action        110. TRUE      FALSE     
-#> 3 F3_action        104. FALSE     FALSE     
-#> 4 F4_action        100. FALSE     FALSE     
-#> 5 F5_action        105. FALSE     TRUE      
-#> 6 baseline_action    0  FALSE     FALSE     
-#> 
-#> $features
-#> # A tibble: 5 x 2
-#>   name  weight
-#>   <chr>  <dbl>
-#> 1 F1     0.483
-#> 2 F2     0.170
-#> 3 F3     0.170
-#> 4 F4     0.247
-#> 5 F5     0.499
-#> 
-#> $tree
-#> 
-#> Phylogenetic tree with 5 tips and 4 internal nodes.
-#> 
-#> Tip labels:
-#>   F1, F2, F3, F4, F5
-#> 
-#> Rooted; includes branch lengths.
-#> 

-
+
+
+

See also

+

simulate_ptm_data().

+
+ +
+

Examples

+ 
# create a simulated data set
+s <- simulate_ppp_data(number_features = 5,
+                       cost_mean = 100,
+                       cost_sd = 5,
+                       success_min_probability = 0.7,
+                       success_max_probability = 0.99,
+                       funded_min_persistence_probability = 0.5,
+                       funded_max_persistence_probability = 0.9,
+                       baseline_min_persistence_probability = 0.01,
+                       baseline_max_persistence_probability = 0.4,
+                       locked_in_proportion = 0.01,
+                       locked_out_proportion = 0.01)
+
+# print data set
+print(s)
+#> $projects
+#> # A tibble: 6 × 13
+#>   name        success     F1     F2     F3     F4     F5 F1_ac…¹ F2_ac…² F3_ac…³
+#>   <chr>         <dbl>  <dbl>  <dbl>  <dbl>  <dbl>  <dbl> <lgl>   <lgl>   <lgl>  
+#> 1 F1_project    0.711  0.830 NA     NA     NA     NA     TRUE    FALSE   FALSE  
+#> 2 F2_project    0.879 NA      0.516 NA     NA     NA     FALSE   TRUE    FALSE  
+#> 3 F3_project    0.728 NA     NA      0.872 NA     NA     FALSE   FALSE   TRUE   
+#> 4 F4_project    0.809 NA     NA     NA      0.518 NA     FALSE   FALSE   FALSE  
+#> 5 F5_project    0.944 NA     NA     NA     NA      0.578 FALSE   FALSE   FALSE  
+#> 6 baseline_p…   1      0.174  0.335  0.199  0.343  0.240 FALSE   FALSE   FALSE  
+#> # … with 3 more variables: F4_action <lgl>, F5_action <lgl>,
+#> #   baseline_action <lgl>, and abbreviated variable names ¹​F1_action,
+#> #   ²​F2_action, ³​F3_action
+#> 
+#> $actions
+#> # A tibble: 6 × 4
+#>   name             cost locked_in locked_out
+#>   <chr>           <dbl> <lgl>     <lgl>     
+#> 1 F1_action        105. FALSE     FALSE     
+#> 2 F2_action        110. TRUE      FALSE     
+#> 3 F3_action        104. FALSE     FALSE     
+#> 4 F4_action        100. FALSE     FALSE     
+#> 5 F5_action        105. FALSE     TRUE      
+#> 6 baseline_action    0  FALSE     FALSE     
+#> 
+#> $features
+#> # A tibble: 5 × 2
+#>   name  weight
+#>   <chr>  <dbl>
+#> 1 F1     0.483
+#> 2 F2     0.170
+#> 3 F3     0.170
+#> 4 F4     0.247
+#> 5 F5     0.499
+#> 
+#> $tree
+#> 
+#> Phylogenetic tree with 5 tips and 4 internal nodes.
+#> 
+#> Tip labels:
+#>   F1, F2, F3, F4, F5
+#> 
+#> Rooted; includes branch lengths.
+#> 
+
+
+
+
- - - - + diff --git a/docs/reference/simulate_ptm_data.html b/docs/reference/simulate_ptm_data.html index f078f40..fcbeddc 100644 --- a/docs/reference/simulate_ptm_data.html +++ b/docs/reference/simulate_ptm_data.html @@ -1,82 +1,16 @@ - - - - - - - -Simulate data for 'Priority threat management' — simulate_ptm_data • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Simulate data for 'Priority threat management' — simulate_ptm_data • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Simulate data for 'Priority threat management'

- Source: R/simulate_ptm_data.R + Source: R/simulate_ptm_data.R
@@ -136,157 +63,187 @@

Simulate data for 'Priority threat management'

share actions.

- 
simulate_ptm_data(
-  number_projects,
-  number_actions,
-  number_features,
-  cost_mean = 100,
-  cost_sd = 5,
-  success_min_probability = 0.7,
-  success_max_probability = 0.99,
-  funded_min_persistence_probability = 0.5,
-  funded_max_persistence_probability = 0.9,
-  baseline_min_persistence_probability = 0.01,
-  baseline_max_persistence_probability = 0.4,
-  locked_in_proportion = 0,
-  locked_out_proportion = 0
-)
- -

Arguments

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
number_projects

numeric number of projects. Note that this -does not include the baseline project.

number_actions

numeric number of actions. Note that this -does not include the baseline action.

number_features

numeric number of features.

cost_mean

numeric average cost for the actions. Defaults to -100.

cost_sd

numeric standard deviation in action costs. Defaults -to 5.

success_min_probability

numeric minimum probability of the -projects succeeding if they are funded. Defaults to 0.7.

success_max_probability

numeric maximum probability of the -projects succeeding if they are funded. Defaults to 0.99.

funded_min_persistence_probability

numeric minimum probability +

+ 
simulate_ptm_data(
+  number_projects,
+  number_actions,
+  number_features,
+  cost_mean = 100,
+  cost_sd = 5,
+  success_min_probability = 0.7,
+  success_max_probability = 0.99,
+  funded_min_persistence_probability = 0.5,
+  funded_max_persistence_probability = 0.9,
+  baseline_min_persistence_probability = 0.01,
+  baseline_max_persistence_probability = 0.4,
+  locked_in_proportion = 0,
+  locked_out_proportion = 0
+)
+
+ +
+

Arguments

+
number_projects
+

numeric number of projects. Note that this +does not include the baseline project.

+ + +
number_actions
+

numeric number of actions. Note that this +does not include the baseline action.

+ + +
number_features
+

numeric number of features.

+ + +
cost_mean
+

numeric average cost for the actions. Defaults to +100.

+ + +
cost_sd
+

numeric standard deviation in action costs. Defaults +to 5.

+ + +
success_min_probability
+

numeric minimum probability of the +projects succeeding if they are funded. Defaults to 0.7.

+ + +
success_max_probability
+

numeric maximum probability of the +projects succeeding if they are funded. Defaults to 0.99.

+ + +
funded_min_persistence_probability
+

numeric minimum probability of the features persisting if projects are funded and successful. -Defaults to 0.5.

funded_max_persistence_probability

numeric maximum probability +Defaults to 0.5.

+ + +
funded_max_persistence_probability
+

numeric maximum probability of the features persisting if projects are funded and successful. -Defaults to 0.9.

baseline_min_persistence_probability

numeric minimum +Defaults to 0.9.

+ + +
baseline_min_persistence_probability
+

numeric minimum probability of the features persisting if only the baseline project -is funded. Defaults to 0.01.

baseline_max_persistence_probability

numeric maximum +is funded. Defaults to 0.01.

+ + +
baseline_max_persistence_probability
+

numeric maximum probability of the features persisting if only the baseline project is -funded. Defaults to 0.4.

locked_in_proportion

numeric of actions that are locked -into the solution. Defaults to 0.

locked_out_proportion

numeric of actions that are locked -into the solution. Defaults to 0.

- -

Value

- -

A list object containing the elements:

-
-
"projects"

A tibble::tibble() containing +funded. Defaults to 0.4.

+ + +
locked_in_proportion
+

numeric of actions that are locked +into the solution. Defaults to 0.

+ + +
locked_out_proportion
+

numeric of actions that are locked +into the solution. Defaults to 0.

+ +
+
+

Value

+ + +

A list object containing the elements:

+ + +
"projects"
+

A tibble::tibble() containing the data for the conservation projects. It contains the following -columns: -

-
"name"

character name for each project.

-
"success"

numeric probability of each project +columns:

"name"
+

character name for each project.

+ +
"success"
+

numeric probability of each project succeeding if it is funded.

-
"F1" ... "FN"

numeric columns for each + +

"F1" ... "FN"
+

numeric columns for each feature, ranging from "F1" to "FN" where N is the number of features, indicating the enhanced probability that each feature will persist if it funded. Missing values (NA) indicate that a feature does not benefit from a project being funded.

-
"F1_action" ... "FN_action"

logical + +

"F1_action" ... "FN_action"
+

logical columns for each action, ranging from "F1_action" to "FN_action" where N is the number of actions (equal to the number of features in this simulated data), indicating if an action is associated with a project (TRUE) or not (FALSE).

-
"baseline_action"

logical + +

"baseline_action"
+

logical column indicating if a project is associated with the baseline action (TRUE) or not (FALSE). This action is only -associated with the baseline project.

-
"actions"

A tibble::tibble() containing +associated with the baseline project.

+ + +
+ +
"actions"
+

A tibble::tibble() containing the data for the conservation actions. It contains the following -columns: -

-
"name"

character name for each action.

-
"cost"

numeric cost for each action.

-
"locked_in"

logical indicating if certain +columns:

"name"
+

character name for each action.

+ +
"cost"
+

numeric cost for each action.

+ +
"locked_in"
+

logical indicating if certain actions should be locked into the solution.

-
"locked_out"

logical indicating if certain -actions should be locked out of the solution.

-
"features"

A tibble::tibble() containing + +

"locked_out"
+

logical indicating if certain +actions should be locked out of the solution.

+ + +
+ +
"features"
+

A tibble::tibble() containing the data for the conservation features (e.g. species). It contains the -following columns: -

-
"name"

character name for each feature.

-
"weight"

numeric weight for each feature. +following columns:

"name"
+

character name for each feature.

+ +
"weight"
+

numeric weight for each feature. For each feature, this is calculated as the amount of time that elapsed between the present and the features' last common ancestor. In other words, the weights are calculated as the unique amount -of evolutionary history that each feature has experienced.

-
"tree"

ape::phylo() phylogenetic tree for the -features.

+of evolutionary history that each feature has experienced.

-
-

Details

+ +
"tree"
+

ape::phylo() phylogenetic tree for the +features.

+ + +
+
+

Details

The simulated data set will contain one conservation project for each features, and also a "baseline" (do nothing) project to reflect features' persistence when their conservation project is not funded. Each conservation project is associated with a single action, and no conservation projects share any actions. Specifically, the data are simulated as follows:

-
    -

  1. A specified number of conservation projects, features, and +

    1. A specified number of conservation projects, features, and management actions are created.

    2. Cost data for each action are simulated using a normal distribution and the cost_mean and cost_sd arguments.

      3. @@ -309,115 +266,114 @@

      Details set as the baseline_min_persistence_probability and baseline_max_persistence_probability arguments.

    3. A phylogenetic tree is simulated for the features using -ape::rcoal().

      4. +ape::rcoal().

    4. Feature data are created from the phylogenetic tree. The weights are calculated as the amount of evolutionary history that has elapsed between each feature and its last common ancestor.

      5. -

    - -

    References

    - +
+
+

References

Carwardine J, Martin TG, Firn J, Ponce-Reyes P, Nicol S, Reeson A, Grantham HS, Stratford D, Kehoe L, Chades I (2019) Priority Threat Management for biodiversity conservation: A handbook. Journal of Applied Ecology, 56: 481--490.

-

See also

- -

simulate_ppp_data().

- -

Examples

- 
# create a simulated data set
-s <- simulate_ptm_data(number_projects = 6,
-                       number_actions = 8,
-                       number_features = 5,
-                       cost_mean = 100,
-                       cost_sd = 5,
-                       success_min_probability = 0.7,
-                       success_max_probability = 0.99,
-                       funded_min_persistence_probability = 0.5,
-                       funded_max_persistence_probability = 0.9,
-                       baseline_min_persistence_probability = 0.01,
-                       baseline_max_persistence_probability = 0.4,
-                       locked_in_proportion = 0.01,
-                       locked_out_proportion = 0.01)
-
-# print data set
-print(s)
-
#> $projects
-#> # A tibble: 7 x 16
-#>   name    success      F1      F2     F3     F4    F5 action_1 action_2 action_3
-#>   <chr>     <dbl>   <dbl>   <dbl>  <dbl>  <dbl> <dbl> <lgl>    <lgl>    <lgl>   
-#> 1 projec…   0.931 NA       0.533   0.606 NA     0.878 TRUE     TRUE     TRUE    
-#> 2 projec…   0.899  0.691  NA       0.668  0.509 0.889 TRUE     TRUE     TRUE    
-#> 3 projec…   0.867  0.644   0.544   0.845 NA     0.547 TRUE     TRUE     TRUE    
-#> 4 projec…   0.892 NA       0.791  NA     NA     0.666 TRUE     FALSE    TRUE    
-#> 5 projec…   0.876  0.556  NA       0.755  0.837 0.800 TRUE     FALSE    FALSE   
-#> 6 projec…   0.932  0.517   0.894  NA      0.520 0.663 TRUE     FALSE    TRUE    
-#> 7 baseli…   1      0.0868  0.0692  0.321  0.376 0.303 FALSE    FALSE    FALSE   
-#> # … with 6 more variables: action_4 <lgl>, action_5 <lgl>, action_6 <lgl>,
-#> #   action_7 <lgl>, action_8 <lgl>, baseline_action <lgl>
-#> 
-#> $actions
-#> # A tibble: 9 x 4
-#>   name             cost locked_in locked_out
-#>   <chr>           <dbl> <lgl>     <lgl>     
-#> 1 action_1        101.  FALSE     FALSE     
-#> 2 action_2         96.4 FALSE     FALSE     
-#> 3 action_3         96.3 FALSE     FALSE     
-#> 4 action_4         99.6 FALSE     FALSE     
-#> 5 action_5         95.7 TRUE      FALSE     
-#> 6 action_6         93.0 FALSE     FALSE     
-#> 7 action_7        109.  FALSE     FALSE     
-#> 8 action_8         90.4 FALSE     TRUE      
-#> 9 baseline_action   0   FALSE     FALSE     
-#> 
-#> $features
-#> # A tibble: 5 x 2
-#>   name  weight
-#>   <chr>  <dbl>
-#> 1 F1     0.125
-#> 2 F2     0.125
-#> 3 F3     0.376
-#> 4 F4     0.724
-#> 5 F5     3.13 
-#> 
-#> $tree
-#> 
-#> Phylogenetic tree with 5 tips and 4 internal nodes.
-#> 
-#> Tip labels:
-#>   F1, F2, F3, F4, F5
-#> 
-#> Rooted; includes branch lengths.
-#> 

-
+
+
+

See also

+

simulate_ppp_data().

+
+ +
+

Examples

+ 
# create a simulated data set
+s <- simulate_ptm_data(number_projects = 6,
+                       number_actions = 8,
+                       number_features = 5,
+                       cost_mean = 100,
+                       cost_sd = 5,
+                       success_min_probability = 0.7,
+                       success_max_probability = 0.99,
+                       funded_min_persistence_probability = 0.5,
+                       funded_max_persistence_probability = 0.9,
+                       baseline_min_persistence_probability = 0.01,
+                       baseline_max_persistence_probability = 0.4,
+                       locked_in_proportion = 0.01,
+                       locked_out_proportion = 0.01)
+
+# print data set
+print(s)
+#> $projects
+#> # A tibble: 7 × 16
+#>   name       success      F1      F2     F3     F4    F5 actio…¹ actio…² actio…³
+#>   <chr>        <dbl>   <dbl>   <dbl>  <dbl>  <dbl> <dbl> <lgl>   <lgl>   <lgl>  
+#> 1 project_1    0.931 NA       0.533   0.606 NA     0.878 TRUE    TRUE    TRUE   
+#> 2 project_2    0.899  0.691  NA       0.668  0.509 0.889 TRUE    TRUE    TRUE   
+#> 3 project_3    0.867  0.644   0.544   0.845 NA     0.547 TRUE    TRUE    TRUE   
+#> 4 project_4    0.892 NA       0.791  NA     NA     0.666 TRUE    FALSE   TRUE   
+#> 5 project_5    0.876  0.556  NA       0.755  0.837 0.800 TRUE    FALSE   FALSE  
+#> 6 project_6    0.932  0.517   0.894  NA      0.520 0.663 TRUE    FALSE   TRUE   
+#> 7 baseline_…   1      0.0868  0.0692  0.321  0.376 0.303 FALSE   FALSE   FALSE  
+#> # … with 6 more variables: action_4 <lgl>, action_5 <lgl>, action_6 <lgl>,
+#> #   action_7 <lgl>, action_8 <lgl>, baseline_action <lgl>, and abbreviated
+#> #   variable names ¹​action_1, ²​action_2, ³​action_3
+#> 
+#> $actions
+#> # A tibble: 9 × 4
+#>   name             cost locked_in locked_out
+#>   <chr>           <dbl> <lgl>     <lgl>     
+#> 1 action_1        101.  FALSE     FALSE     
+#> 2 action_2         96.4 FALSE     FALSE     
+#> 3 action_3         96.3 FALSE     FALSE     
+#> 4 action_4         99.6 FALSE     FALSE     
+#> 5 action_5         95.7 TRUE      FALSE     
+#> 6 action_6         93.0 FALSE     FALSE     
+#> 7 action_7        109.  FALSE     FALSE     
+#> 8 action_8         90.4 FALSE     TRUE      
+#> 9 baseline_action   0   FALSE     FALSE     
+#> 
+#> $features
+#> # A tibble: 5 × 2
+#>   name  weight
+#>   <chr>  <dbl>
+#> 1 F1     0.125
+#> 2 F2     0.125
+#> 3 F3     0.376
+#> 4 F4     0.724
+#> 5 F5     3.13 
+#> 
+#> $tree
+#> 
+#> Phylogenetic tree with 5 tips and 4 internal nodes.
+#> 
+#> Tip labels:
+#>   F1, F2, F3, F4, F5
+#> 
+#> Rooted; includes branch lengths.
+#> 
+
+
+
+
- - - - + diff --git a/docs/reference/solution_statistics.html b/docs/reference/solution_statistics.html index b34c815..67d1336 100644 --- a/docs/reference/solution_statistics.html +++ b/docs/reference/solution_statistics.html @@ -1,79 +1,13 @@ - - - - - - - -Solution statistics — solution_statistics • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Solution statistics — solution_statistics • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Solution statistics

- Source: R/solution_statistics.R + Source: R/solution_statistics.R

Calculate statistics describing a solution to a project prioritization -problem().

+problem().

- 
solution_statistics(x, solution)
- -

Arguments

- - - - - - - - - - -
x

project prioritization problem().

solution

base::data.frame() or -tibble::tibble() table containing the solutions. Here, +

+ 
solution_statistics(x, solution)
+
+ +
+

Arguments

+
x
+

project prioritization problem().

+ + +
solution
+

base::data.frame() or +tibble::tibble() table containing the solutions. Here, rows correspond to different solutions and columns correspond to different actions. Each column in the argument to solution should be named according to a different action in x. Cell values indicate if an action is funded in a given solution or not, and should be either zero or one. Arguments to solution can -contain additional columns, and they will be ignored.

+contain additional columns, and they will be ignored.

-

Value

+
+
+

Value

+ -

A tibble::tibble() table containing the following +

A tibble::tibble() table containing the following columns:

-
-
"cost"

numeric cost of each solution.

-
"obj"

numeric objective value for each solution. +

"cost"
+

numeric cost of each solution.

+ + +
"obj"
+

numeric objective value for each solution. This is calculated using the objective function defined for the argument to x.

-
x$project_names()

numeric column for each + +

x$project_names()
+

numeric column for each project indicating if it was completely funded (with a value of 1) or not (with a value of 0).

-
x$feature_names()

numeric column for each + +

x$feature_names()
+

numeric column for each feature indicating the probability that it will persist into the future given each solution.

-
- -

See also

- -

objectives, replacement_costs(), -project_cost_effectiveness().

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# print project data
-print(sim_projects)
-
#> # A tibble: 6 x 13
-#>   name           success     F1     F2      F3     F4     F5 F1_action F2_action
-#>   <chr>            <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>     <lgl>    
-#> 1 F1_project       0.919  0.791 NA     NA      NA     NA     TRUE      FALSE    
-#> 2 F2_project       0.923 NA      0.888 NA      NA     NA     FALSE     TRUE     
-#> 3 F3_project       0.829 NA     NA      0.502  NA     NA     FALSE     FALSE    
-#> 4 F4_project       0.848 NA     NA     NA       0.690 NA     FALSE     FALSE    
-#> 5 F5_project       0.814 NA     NA     NA      NA      0.617 FALSE     FALSE    
-#> 6 baseline_proj…   1      0.298  0.250  0.0865  0.249  0.182 FALSE     FALSE    
-#> # … with 4 more variables: F3_action <lgl>, F4_action <lgl>, F5_action <lgl>,
-#> #   baseline_action <lgl>

-# print action data
-print(sim_features)
-
#> # A tibble: 5 x 2
-#>   name  weight
-#>   <chr>  <dbl>
-#> 1 F1     0.211
-#> 2 F2     0.211
-#> 3 F3     0.221
-#> 4 F4     0.630
-#> 5 F5     1.59 

-# print feature data
-print(sim_actions)
-
#> # A tibble: 6 x 4
-#>   name             cost locked_in locked_out
-#>   <chr>           <dbl> <lgl>     <lgl>     
-#> 1 F1_action        94.4 FALSE     FALSE     
-#> 2 F2_action       101.  FALSE     FALSE     
-#> 3 F3_action       103.  TRUE      FALSE     
-#> 4 F4_action        99.2 FALSE     FALSE     
-#> 5 F5_action        99.9 FALSE     TRUE      
-#> 6 baseline_action   0   FALSE     FALSE     

-# build problem
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 400) %>%
-     add_feature_weights("weight") %>%
-     add_binary_decisions()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (400)]
-#>   targets:         none
-#>   weights:         min: 0.21136, max: 1.59167
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# create a table with some solutions
-solutions <- data.frame(F1_action =       c(0, 1, 1),
-                        F2_action =       c(0, 1, 0),
-                        F3_action =       c(0, 1, 1),
-                        F4_action =       c(0, 1, 0),
-                        F5_action =       c(0, 1, 1),
-                        baseline_action = c(1, 1, 1))
-
-# print the solutions
-# the first solution only has the baseline action funded
-# the second solution has every action funded
-# the third solution has only some actions funded
-print(solutions)
-
#>   F1_action F2_action F3_action F4_action F5_action baseline_action
-#> 1         0         0         0         0         0               1
-#> 2         1         1         1         1         1               1
-#> 3         1         0         1         0         1               1

-# calculate statistics
-solution_statistics(p, solutions)
-
#> # A tibble: 3 x 13
-#>    cost   obj F1_project F2_project F3_project F4_project F5_project
-#>   <dbl> <dbl>      <dbl>      <dbl>      <dbl>      <dbl>      <dbl>
-#> 1    0  0.581          0          0          0          0          0
-#> 2  498. 1.83           1          1          1          1          1
-#> 3  298. 1.43           1          0          1          0          1
-#> # … with 6 more variables: baseline_project <dbl>, F1 <dbl>, F2 <dbl>,
-#> #   F3 <dbl>, F4 <dbl>, F5 <dbl>
+ +
+ + +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# print project data
+print(sim_projects)
+#> # A tibble: 6 × 13
+#>   name       success     F1     F2      F3     F4     F5 F1_ac…¹ F2_ac…² F3_ac…³
+#>   <chr>        <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>   <lgl>   <lgl>  
+#> 1 F1_project   0.919  0.791 NA     NA      NA     NA     TRUE    FALSE   FALSE  
+#> 2 F2_project   0.923 NA      0.888 NA      NA     NA     FALSE   TRUE    FALSE  
+#> 3 F3_project   0.829 NA     NA      0.502  NA     NA     FALSE   FALSE   TRUE   
+#> 4 F4_project   0.848 NA     NA     NA       0.690 NA     FALSE   FALSE   FALSE  
+#> 5 F5_project   0.814 NA     NA     NA      NA      0.617 FALSE   FALSE   FALSE  
+#> 6 baseline_…   1      0.298  0.250  0.0865  0.249  0.182 FALSE   FALSE   FALSE  
+#> # … with 3 more variables: F4_action <lgl>, F5_action <lgl>,
+#> #   baseline_action <lgl>, and abbreviated variable names ¹​F1_action,
+#> #   ²​F2_action, ³​F3_action
+
+# print action data
+print(sim_features)
+#> # A tibble: 5 × 2
+#>   name  weight
+#>   <chr>  <dbl>
+#> 1 F1     0.211
+#> 2 F2     0.211
+#> 3 F3     0.221
+#> 4 F4     0.630
+#> 5 F5     1.59 
+
+# print feature data
+print(sim_actions)
+#> # A tibble: 6 × 4
+#>   name             cost locked_in locked_out
+#>   <chr>           <dbl> <lgl>     <lgl>     
+#> 1 F1_action        94.4 FALSE     FALSE     
+#> 2 F2_action       101.  FALSE     FALSE     
+#> 3 F3_action       103.  TRUE      FALSE     
+#> 4 F4_action        99.2 FALSE     FALSE     
+#> 5 F5_action        99.9 FALSE     TRUE      
+#> 6 baseline_action   0   FALSE     FALSE     
+
+# build problem
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 400) %>%
+     add_feature_weights("weight") %>%
+     add_binary_decisions()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (400)]
+#>   targets:         none
+#>   weights:         min: 0.21136, max: 1.59167
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# create a table with some solutions
+solutions <- data.frame(F1_action =       c(0, 1, 1),
+                        F2_action =       c(0, 1, 0),
+                        F3_action =       c(0, 1, 1),
+                        F4_action =       c(0, 1, 0),
+                        F5_action =       c(0, 1, 1),
+                        baseline_action = c(1, 1, 1))
+
+# print the solutions
+# the first solution only has the baseline action funded
+# the second solution has every action funded
+# the third solution has only some actions funded
+print(solutions)
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#> 1         0         0         0         0         0               1
+#> 2         1         1         1         1         1               1
+#> 3         1         0         1         0         1               1
+
+# calculate statistics
+solution_statistics(p, solutions)
+#> # A tibble: 3 × 13
+#>    cost   obj F1_pr…¹ F2_pr…² F3_pr…³ F4_pr…⁴ F5_pr…⁵ basel…⁶    F1    F2     F3
+#>   <dbl> <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl> <dbl> <dbl>  <dbl>
+#> 1    0  0.581       0       0       0       0       0       1 0.298 0.250 0.0865
+#> 2  498. 1.83        1       1       1       1       1       1 0.808 0.865 0.467 
+#> 3  298. 1.43        1       0       1       0       1       1 0.808 0.250 0.467 
+#> # … with 2 more variables: F4 <dbl>, F5 <dbl>, and abbreviated variable names
+#> #   ¹​F1_project, ²​F2_project, ³​F3_project, ⁴​F4_project, ⁵​F5_project,
+#> #   ⁶​baseline_project
+
+
+
- - - - + diff --git a/docs/reference/solve.html b/docs/reference/solve.html index 62774f0..6534da9 100644 --- a/docs/reference/solve.html +++ b/docs/reference/solve.html @@ -1,78 +1,12 @@ - - - - - - - -Solve — solve • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Solve — solve • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Solve

- Source: R/solve.R + Source: R/solve.R
-

Solve a conservation planning problem().

+

Solve a conservation planning problem().

+
+ +
+ 
# S4 method for OptimizationProblem,Solver
+solve(a, b, ...)
+
+# S4 method for ProjectProblem,missing
+solve(a, b, ...)
- 
# S4 method for OptimizationProblem,Solver
-solve(a, b, ...)
-
-# S4 method for ProjectProblem,missing
-solve(a, b, ...)
- -

Arguments

- - - - - - - - - - - - - - -
a

ProjectProblem or an -OptimizationProblem object.

b

Solver object. Not used if a is an -ProjectProblem object.

...

arguments passed to compile().

- -

Value

- -

The type of object returned from this function depends on the +

+

Arguments

+
a
+

ProjectProblem or an +OptimizationProblem object.

+ + +
b
+

Solver object. Not used if a is an +ProjectProblem object.

+ + +
...
+

arguments passed to compile().

+ +
+
+

Value

+ + +

The type of object returned from this function depends on the argument to a. If the argument to a is an -OptimizationProblem object, then the +OptimizationProblem object, then the solution is returned as a list containing the prioritization and additional information (e.g. run time, solver status). On the other hand, if the argument -to a is an ProjectProblem object, -then a tibble::tibble() table object will be returned. In this +to a is an ProjectProblem object, +then a tibble::tibble() table object will be returned. In this table, each row row corresponds to a different solution and each column describes a different property or result associated with each solution:

-
-
"solution"

integer solution identifier.

-
"status"

character describing each solution. +

"solution"
+

integer solution identifier.

+ + +
"status"
+

character describing each solution. For example, is the solution optimal, suboptimal, or was it returned because the solver ran out of time?

-
"obj"

numeric objective value for each solution. + +

"obj"
+

numeric objective value for each solution. This is calculated using the objective function defined for the argument to x.

-
"cost"

numeric total cost associated with each + +

"cost"
+

numeric total cost associated with each solution.

-
x$action_names()

numeric column for each action + +

x$action_names()
+

numeric column for each action indicating if they were funded in each solution or not.

-
x$project_names()

numeric column for each + +

x$project_names()
+

numeric column for each project indicating if it was completely funded (with a value of 1) or not (with a value of 0).

-
x$feature_names()

numeric column for each + +

x$feature_names()
+

numeric column for each feature indicating the probability that it will persist into the future given each solution.

-
- -

See also

- -

problem(), solution_statistics(), -solvers.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# print project data
-print(sim_projects)
-
#> # A tibble: 6 x 13
-#>   name           success     F1     F2      F3     F4     F5 F1_action F2_action
-#>   <chr>            <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>     <lgl>    
-#> 1 F1_project       0.919  0.791 NA     NA      NA     NA     TRUE      FALSE    
-#> 2 F2_project       0.923 NA      0.888 NA      NA     NA     FALSE     TRUE     
-#> 3 F3_project       0.829 NA     NA      0.502  NA     NA     FALSE     FALSE    
-#> 4 F4_project       0.848 NA     NA     NA       0.690 NA     FALSE     FALSE    
-#> 5 F5_project       0.814 NA     NA     NA      NA      0.617 FALSE     FALSE    
-#> 6 baseline_proj…   1      0.298  0.250  0.0865  0.249  0.182 FALSE     FALSE    
-#> # … with 4 more variables: F3_action <lgl>, F4_action <lgl>, F5_action <lgl>,
-#> #   baseline_action <lgl>

-# print action data
-print(sim_features)
-
#> # A tibble: 5 x 2
-#>   name  weight
-#>   <chr>  <dbl>
-#> 1 F1     0.211
-#> 2 F2     0.211
-#> 3 F3     0.221
-#> 4 F4     0.630
-#> 5 F5     1.59 

-# print feature data
-print(sim_actions)
-
#> # A tibble: 6 x 4
-#>   name             cost locked_in locked_out
-#>   <chr>           <dbl> <lgl>     <lgl>     
-#> 1 F1_action        94.4 FALSE     FALSE     
-#> 2 F2_action       101.  FALSE     FALSE     
-#> 3 F3_action       103.  TRUE      FALSE     
-#> 4 F4_action        99.2 FALSE     FALSE     
-#> 5 F5_action        99.9 FALSE     TRUE      
-#> 6 baseline_action   0   FALSE     FALSE     

-# build problem
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 400) %>%
-     add_feature_weights("weight") %>%
-     add_binary_decisions()
-
-# print problem
-print(p)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Maximum richness objective [budget (400)]
-#>   targets:         none
-#>   weights:         min: 0.21136, max: 1.59167
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# \dontrun{
-# solve problem
-s <- solve(p)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xa2bba4dd
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [2e-01, 2e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 4e+02]
-#> Found heuristic solution: objective 0.6654645
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 64 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 64 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 1.749045e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       1.7490448    1.74904  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 1.74904 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 1.749044775334e+00, best bound 1.749044775334e+00, gap 0.0000%

-# print output
-print(s)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL  1.75  395.         1         1         0         1         1
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>

-# print the solver status
-print(s$obj)
-
#> [1] 1.749045

-# print the objective value
-print(s$obj)
-
#> [1] 1.749045

-# print the solution cost
-print(s$cost)
-
#> [1] 394.5413

-# print which actions are funded in the solution
-s[, sim_actions$name, drop = FALSE]
-
#> # A tibble: 1 x 6
-#>   F1_action F2_action F3_action F4_action F5_action baseline_action
-#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
-#> 1         1         1         0         1         1               1

-# print the expected probability of persistence for each feature
-# if the solution were implemented
-s[, sim_features$name, drop = FALSE]
-
#> # A tibble: 1 x 5
-#>      F1    F2     F3    F4    F5
-#>   <dbl> <dbl>  <dbl> <dbl> <dbl>
-#> 1 0.808 0.865 0.0865 0.688 0.592
# }
-
+ +
+ + +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# print project data
+print(sim_projects)
+#> # A tibble: 6 × 13
+#>   name       success     F1     F2      F3     F4     F5 F1_ac…¹ F2_ac…² F3_ac…³
+#>   <chr>        <dbl>  <dbl>  <dbl>   <dbl>  <dbl>  <dbl> <lgl>   <lgl>   <lgl>  
+#> 1 F1_project   0.919  0.791 NA     NA      NA     NA     TRUE    FALSE   FALSE  
+#> 2 F2_project   0.923 NA      0.888 NA      NA     NA     FALSE   TRUE    FALSE  
+#> 3 F3_project   0.829 NA     NA      0.502  NA     NA     FALSE   FALSE   TRUE   
+#> 4 F4_project   0.848 NA     NA     NA       0.690 NA     FALSE   FALSE   FALSE  
+#> 5 F5_project   0.814 NA     NA     NA      NA      0.617 FALSE   FALSE   FALSE  
+#> 6 baseline_…   1      0.298  0.250  0.0865  0.249  0.182 FALSE   FALSE   FALSE  
+#> # … with 3 more variables: F4_action <lgl>, F5_action <lgl>,
+#> #   baseline_action <lgl>, and abbreviated variable names ¹​F1_action,
+#> #   ²​F2_action, ³​F3_action
+
+# print action data
+print(sim_features)
+#> # A tibble: 5 × 2
+#>   name  weight
+#>   <chr>  <dbl>
+#> 1 F1     0.211
+#> 2 F2     0.211
+#> 3 F3     0.221
+#> 4 F4     0.630
+#> 5 F5     1.59 
+
+# print feature data
+print(sim_actions)
+#> # A tibble: 6 × 4
+#>   name             cost locked_in locked_out
+#>   <chr>           <dbl> <lgl>     <lgl>     
+#> 1 F1_action        94.4 FALSE     FALSE     
+#> 2 F2_action       101.  FALSE     FALSE     
+#> 3 F3_action       103.  TRUE      FALSE     
+#> 4 F4_action        99.2 FALSE     FALSE     
+#> 5 F5_action        99.9 FALSE     TRUE      
+#> 6 baseline_action   0   FALSE     FALSE     
+
+# build problem
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 400) %>%
+     add_feature_weights("weight") %>%
+     add_binary_decisions()
+
+# print problem
+print(p)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Maximum richness objective [budget (400)]
+#>   targets:         none
+#>   weights:         min: 0.21136, max: 1.59167
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# \dontrun{
+# solve problem
+s <- solve(p)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0xa33f6587
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [2e-01, 2e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 4e+02]
+#> Found heuristic solution: objective 0.6654645
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 64 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 64 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.749045e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.7490448    1.74904  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.74904 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.749044775334e+00, best bound 1.749044775334e+00, gap 0.0000%
+
+# print output
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  1.75  395.         1       1       0       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# print the solver status
+print(s$obj)
+#> [1] 1.749045
+
+# print the objective value
+print(s$obj)
+#> [1] 1.749045
+
+# print the solution cost
+print(s$cost)
+#> [1] 394.5413
+
+# print which actions are funded in the solution
+s[, sim_actions$name, drop = FALSE]
+#> # A tibble: 1 × 6
+#>   F1_action F2_action F3_action F4_action F5_action baseline_action
+#>       <dbl>     <dbl>     <dbl>     <dbl>     <dbl>           <dbl>
+#> 1         1         1         0         1         1               1
+
+# print the expected probability of persistence for each feature
+# if the solution were implemented
+s[, sim_features$name, drop = FALSE]
+#> # A tibble: 1 × 5
+#>      F1    F2     F3    F4    F5
+#>   <dbl> <dbl>  <dbl> <dbl> <dbl>
+#> 1 0.808 0.865 0.0865 0.688 0.592
+# }
+
+
+
-
- - - + diff --git a/docs/reference/solvers.html b/docs/reference/solvers.html index 4f317cf..699f776 100644 --- a/docs/reference/solvers.html +++ b/docs/reference/solvers.html @@ -1,80 +1,14 @@ - - - - - - - -Problem solvers — solvers • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Problem solvers — solvers • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Problem solvers

- Source: R/solvers.R + Source: R/solvers.R

Specify the software and configuration used to solve a project prioritization -problem(). By default, the best available exact algorithm +problem(). By default, the best available exact algorithm solver will be used.

- -

Details

- +
+

Details

The following solvers can be used to find solutions for a -project prioritization problem():

-
- -
add_default_solver()

This solver uses the best software +project prioritization problem():

+
add_default_solver()
+

This solver uses the best software currently installed on the system.

-
add_gurobi_solver()

Gurobi + +

add_gurobi_solver()
+

Gurobi is a state-of-the-art commercial optimization software with an R package interface. It is by far the fastest solver that can be used by this package, however, it is also the only solver that is not freely @@ -151,7 +78,9 @@

Details gurobi package is distributed with the Gurobi software suite. This solver uses the gurobi package to solve problems.

-
add_rsymphony_solver()

SYMPHONY is an + +

add_rsymphony_solver()
+

SYMPHONY is an open-source integer programming solver that is part of the Computational Infrastructure for Operations Research (COIN-OR) project, an initiative to promote development of open-source tools for operations research (a @@ -159,251 +88,258 @@

Details provides an interface to COIN-OR and is available on CRAN. This solver uses the Rsymphony package to solve problems.

-
add_lpsymphony_solver()

The lpsymphony package + +

add_lpsymphony_solver()
+

The lpsymphony package provides a different interface to the COIN-OR software suite. Unlike the Rsymhpony package, the lpsymphony package is distributed through -Bioconductor. +Bioconductor. The lpsymphony package may be easier to install on Windows or Max OSX systems than the Rsymphony package.

-
add_lpsolveapi_solver()

lp_solve is an + +

add_lpsolveapi_solver()
+

lp_solve is an open-source integer programming solver. The lpSolveAPI package provides an interface to this solver and is available on CRAN. Although this solver is the slowest currently supported solver, it is also the only exact algorithm solver that can be installed on all operating systems without any manual installation steps.

-
add_heuristic_solver()

Generate solutions using + +

add_heuristic_solver()
+

Generate solutions using a backwards heuristic algorithm. Although these types of algorithms have conventionally been used to solve project prioritization problems, they are extremely unlikely to identify optimal solutions and provide no guarantees concerning solution quality.

-
add_random_solver()

Generate solutions by + +

add_random_solver()
+

Generate solutions by randomly funding actions. This can be useful when evaluating the performance of a funding scheme---though it is strongly recommended to evaluate the performance of a funding scheme by comparing it to an optimal solution identified using exact algorithms (e.g. -add_gurobi_solver(), add_rsymphony_solver()).

- - -
- -

See also

- -

constraints, decisions, -objectives, problem(), targets.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_binary_decisions()
-
-# build another problem, with the default solver
-p2 <- p1 %>%
-      add_default_solver()
-
-# build another problem, with the gurobi solver
-# \dontrun{
-p3 <- p1 %>%
-      add_gurobi_solver()
-# }
-
-# build another problem, with the Rsympony solver
-# \dontrun{
-p4 <- p1 %>%
-      add_rsymphony_solver()
-# }
-
-# build another problem, with the lpsymphony solver
-# \dontrun{
-p5 <- p1 %>%
-      add_lpsymphony_solver()
-# }
-
-# build another problem, with the lpSolveAPI solver
-p6 <- p1 %>%
-      add_lpsolveapi_solver()
-
-# build another problem, with the heuristic solver
-p7 <- p1 %>%
-      add_heuristic_solver()
-
-# build another problem, with the random solver
-p8 <- p1 %>%
-      add_random_solver()
-
-# \dontrun{
-# generate solutions using each of the solvers
-s <- rbind(solve(p2), solve(p3), solve(p4), solve(p5), solve(p6), solve(p7),
-           solve(p8))
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xab0d0209
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 2.19038 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
-#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xab0d0209
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [1e+00, 1e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 1.4456093
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 2.19038 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
-#> 
-#> Model name:  'project prioritization problem' - run #1    
-#> Objective:   Maximize(R0)
-#>  
-#> SUBMITTED
-#> Model size:       47 constraints,      47 variables,          102 non-zeros.
-#> Sets:                                   0 GUB,                  0 SOS.
-#>  
-#> Using DUAL simplex for phase 1 and PRIMAL simplex for phase 2.
-#> The primal and dual simplex pricing strategy set to 'Devex'.
-#>  
-#> 
-#> Relaxed solution       2.21077983146 after         34 iter is B&B base.
-#>  
-#> Feasible solution      1.91490153549 after         43 iter,         8 nodes (gap 9.2%)
-#> Improved solution       2.0146497578 after         47 iter,        11 nodes (gap 6.1%)
-#> Improved solution      2.19038073724 after         59 iter,        20 nodes (gap 0.6%)
-#>  
-#> Optimal solution       2.19038073724 after         59 iter,        20 nodes (gap 0.6%).
-#> 
-#> Excellent numeric accuracy ||*|| = 1.11022e-16
-#> 
-#>  MEMO: lp_solve version 5.5.2.0 for 64 bit OS, with 64 bit LPSREAL variables.
-#>       In the total iteration count 59, 16 (27.1%) were bound flips.
-#>       There were 11 refactorizations, 0 triggered by time and 1 by density.
-#>        ... on average 3.9 major pivots per refactorization.
-#>       The largest [LUSOL v2.2.1.0] fact(B) had 104 NZ entries, 1.0x largest basis.
-#>       The maximum B&B level was 6, 0.1x MIP order, 4 at the optimal solution.
-#>       The constraint matrix inf-norm is 103.226, with a dynamic range of 1193.9.
-#>       Time to load data was 1.000 seconds, presolve used 0.000 seconds,
-#>        ... 0.000 seconds in simplex solver, in total 1.000 seconds.
s$solver <- c("default", "gurobi", "Rsymphony", "lpsymphony", "lpSolveAPI",
-              "heuristic", "random")
-
-# print solutions
-print(as.data.frame(s))
-
#>   solution                    status      obj     cost F1_action F2_action
-#> 1        1                   OPTIMAL 2.190381 195.3907         1         1
-#> 2        1                   OPTIMAL 2.190381 195.3907         1         1
-#> 3        1 TM_OPTIMAL_SOLUTION_FOUND 2.190381 195.3907         1         1
-#> 4        1 TM_OPTIMAL_SOLUTION_FOUND 2.190381 195.3907         1         1
-#> 5        1    optimal solution found 2.190381 195.3907         1         1
-#> 6        1                      <NA> 2.190381 195.3907         1         1
-#> 7        1                      <NA> 2.190381 195.3907         1         1
-#>   F3_action F4_action F5_action baseline_action F1_project F2_project
-#> 1         0         0         0               1          1          1
-#> 2         0         0         0               1          1          1
-#> 3         0         0         0               1          1          1
-#> 4         0         0         0               1          1          1
-#> 5         0         0         0               1          1          1
-#> 6         0         0         0               1          1          1
-#> 7         0         0         0               1          1          1
-#>   F3_project F4_project F5_project baseline_project        F1        F2
-#> 1          0          0          0                1 0.8080322 0.8649623
-#> 2          0          0          0                1 0.8080322 0.8649623
-#> 3          0          0          0                1 0.8080322 0.8649623
-#> 4          0          0          0                1 0.8080322 0.8649623
-#> 5          0          0          0                1 0.8080322 0.8649623
-#> 6          0          0          0                1 0.8080322 0.8649623
-#> 7          0          0          0                1 0.8080322 0.8649623
-#>          F3        F4        F5     solver
-#> 1 0.0864612 0.2489246 0.1820005    default
-#> 2 0.0864612 0.2489246 0.1820005     gurobi
-#> 3 0.0864612 0.2489246 0.1820005  Rsymphony
-#> 4 0.0864612 0.2489246 0.1820005 lpsymphony
-#> 5 0.0864612 0.2489246 0.1820005 lpSolveAPI
-#> 6 0.0864612 0.2489246 0.1820005  heuristic
-#> 7 0.0864612 0.2489246 0.1820005     random
# }
-
+add_gurobi_solver(), add_rsymphony_solver()).

+ + + +
+ + +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_binary_decisions()
+
+# build another problem, with the default solver
+p2 <- p1 %>%
+      add_default_solver()
+
+# build another problem, with the gurobi solver
+# \dontrun{
+p3 <- p1 %>%
+      add_gurobi_solver()
+# }
+
+# build another problem, with the Rsympony solver
+# \dontrun{
+p4 <- p1 %>%
+      add_rsymphony_solver()
+# }
+
+# build another problem, with the lpsymphony solver
+# \dontrun{
+p5 <- p1 %>%
+      add_lpsymphony_solver()
+# }
+
+# build another problem, with the lpSolveAPI solver
+p6 <- p1 %>%
+      add_lpsolveapi_solver()
+
+# build another problem, with the heuristic solver
+p7 <- p1 %>%
+      add_heuristic_solver()
+
+# build another problem, with the random solver
+p8 <- p1 %>%
+      add_random_solver()
+
+# \dontrun{
+# generate solutions using each of the solvers
+s <- rbind(solve(p2), solve(p3), solve(p4), solve(p5), solve(p6), solve(p7),
+           solve(p8))
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x193cb636
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.19038 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x193cb636
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [1e+00, 1e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 1.4456093
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.190381e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       2.1903807    2.19038  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 2.19038 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.190380737245e+00, best bound 2.190380737245e+00, gap 0.0000%
+#> 
+#> Model name:  'project prioritization problem' - run #1    
+#> Objective:   Maximize(R0)
+#>  
+#> SUBMITTED
+#> Model size:       47 constraints,      47 variables,          102 non-zeros.
+#> Sets:                                   0 GUB,                  0 SOS.
+#>  
+#> Using DUAL simplex for phase 1 and PRIMAL simplex for phase 2.
+#> The primal and dual simplex pricing strategy set to 'Devex'.
+#>  
+#> 
+#> Relaxed solution       2.21077983146 after         34 iter is B&B base.
+#>  
+#> Feasible solution      1.91490153549 after         43 iter,         8 nodes (gap 9.2%)
+#> Improved solution       2.0146497578 after         47 iter,        11 nodes (gap 6.1%)
+#> Improved solution      2.19038073724 after         59 iter,        20 nodes (gap 0.6%)
+#>  
+#> Optimal solution       2.19038073724 after         59 iter,        20 nodes (gap 0.6%).
+#> 
+#> Excellent numeric accuracy ||*|| = 1.11022e-16
+#> 
+#>  MEMO: lp_solve version 5.5.2.0 for 64 bit OS, with 64 bit LPSREAL variables.
+#>       In the total iteration count 59, 16 (27.1%) were bound flips.
+#>       There were 11 refactorizations, 0 triggered by time and 1 by density.
+#>        ... on average 3.9 major pivots per refactorization.
+#>       The largest [LUSOL v2.2.1.0] fact(B) had 104 NZ entries, 1.0x largest basis.
+#>       The maximum B&B level was 6, 0.1x MIP order, 4 at the optimal solution.
+#>       The constraint matrix inf-norm is 103.226, with a dynamic range of 1193.9.
+#>       Time to load data was 0.000 seconds, presolve used 0.000 seconds,
+#>        ... 0.000 seconds in simplex solver, in total 0.000 seconds.
+s$solver <- c("default", "gurobi", "Rsymphony", "lpsymphony", "lpSolveAPI",
+              "heuristic", "random")
+
+# print solutions
+print(as.data.frame(s))
+#>   solution                    status      obj     cost F1_action F2_action
+#> 1        1                   OPTIMAL 2.190381 195.3907         1         1
+#> 2        1                   OPTIMAL 2.190381 195.3907         1         1
+#> 3        1 TM_OPTIMAL_SOLUTION_FOUND 2.190381 195.3907         1         1
+#> 4        1 TM_OPTIMAL_SOLUTION_FOUND 2.190381 195.3907         1         1
+#> 5        1    optimal solution found 2.190381 195.3907         1         1
+#> 6        1                      <NA> 2.190381 195.3907         1         1
+#> 7        1                      <NA> 2.190381 195.3907         1         1
+#>   F3_action F4_action F5_action baseline_action F1_project F2_project
+#> 1         0         0         0               1          1          1
+#> 2         0         0         0               1          1          1
+#> 3         0         0         0               1          1          1
+#> 4         0         0         0               1          1          1
+#> 5         0         0         0               1          1          1
+#> 6         0         0         0               1          1          1
+#> 7         0         0         0               1          1          1
+#>   F3_project F4_project F5_project baseline_project        F1        F2
+#> 1          0          0          0                1 0.8080322 0.8649623
+#> 2          0          0          0                1 0.8080322 0.8649623
+#> 3          0          0          0                1 0.8080322 0.8649623
+#> 4          0          0          0                1 0.8080322 0.8649623
+#> 5          0          0          0                1 0.8080322 0.8649623
+#> 6          0          0          0                1 0.8080322 0.8649623
+#> 7          0          0          0                1 0.8080322 0.8649623
+#>          F3        F4        F5     solver
+#> 1 0.0864612 0.2489246 0.1820005    default
+#> 2 0.0864612 0.2489246 0.1820005     gurobi
+#> 3 0.0864612 0.2489246 0.1820005  Rsymphony
+#> 4 0.0864612 0.2489246 0.1820005 lpsymphony
+#> 5 0.0864612 0.2489246 0.1820005 lpSolveAPI
+#> 6 0.0864612 0.2489246 0.1820005  heuristic
+#> 7 0.0864612 0.2489246 0.1820005     random
+# }
+
+
+
-
- - - + diff --git a/docs/reference/targets-1.png b/docs/reference/targets-1.png index 2b59ba9..16db146 100644 Binary files a/docs/reference/targets-1.png and b/docs/reference/targets-1.png differ diff --git a/docs/reference/targets-2.png b/docs/reference/targets-2.png index 23ddef3..d198e2e 100644 Binary files a/docs/reference/targets-2.png and b/docs/reference/targets-2.png differ diff --git a/docs/reference/targets.html b/docs/reference/targets.html index 637dade..d996a91 100644 --- a/docs/reference/targets.html +++ b/docs/reference/targets.html @@ -1,82 +1,16 @@ - - - - - - - -Targets — targets • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Targets — targets • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Targets

- Source: R/targets.R + Source: R/targets.R
@@ -137,191 +64,202 @@

Targets

- -

Details

- +
+

Details

The following functions can be used to specify targets for a -project prioritization problem():

-
- -
add_relative_targets()

Set targets as a proportion (between 0 and 1) of the maximum probability +project prioritization problem():

+
add_relative_targets()
+

Set targets as a proportion (between 0 and 1) of the maximum probability of persistence associated with the best project for each feature. For instance, if the best project for a feature has an 80% probability of persisting, setting a 50% (i.e. 0.5) relative target will correspond to a 40% threshold probability of persisting.

-
add_absolute_targets()

Set targets by specifying exactly what probability of persistence is + +

add_absolute_targets()
+

Set targets by specifying exactly what probability of persistence is required for each feature. For instance, setting an absolute target of 10% (i.e. 0.1) corresponds to a threshold 10% probability of persisting.

-
add_manual_targets()

Set targets by manually specifying all the required information for each -target.

- - -
- -

See also

-

constraints, decisions, -objectives, problem(), -solvers.

+
add_manual_targets()
+

Set targets by manually specifying all the required information for each +target.

-

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
 
-# build problem with minimum set objective and targets that require each
-# feature to have a 30% chance of persisting into the future
-p1 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_min_set_objective() %>%
-      add_absolute_targets(0.3) %>%
-      add_binary_decisions()
 
-# print problem
-print(p1)
-
#> Project Prioritization Problem
-#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
-#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
-#>   features         F1, F2, F3, ... (5 features)
-#>   action costs:    min: 0, max: 103.22583
-#>   project success: min: 0.81379, max: 1
-#>   objective:       Minimum set objective 
-#>   targets:         Absolute targets [targets (min: 0.3, max: 0.3)]
-#>   weights:         default
-#>   decisions        Binary decision 
-#>   constraints:     <none>
-#>   solver:          default

-# build problem with minimum set objective and targets that require each
-# feature to have a level of persistence that is greater than or equal to
-# 30% of the best project for conserving it
-p2 <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-      add_min_set_objective() %>%
-      add_relative_targets(0.3) %>%
-      add_binary_decisions()
+
+ -# print problem -print(p2) -
#> Project Prioritization Problem -#> actions F1_action, F2_action, F3_action, ... (6 actions) -#> projects F1_project, F2_project, F3_project, ... (6 projects) -#> features F1, F2, F3, ... (5 features) -#> action costs: min: 0, max: 103.22583 -#> project success: min: 0.81379, max: 1 -#> objective: Minimum set objective -#> targets: Relative targets [targets (min: 0.3, max: 0.3)] -#> weights: default -#> decisions Binary decision -#> constraints: <none> -#> solver: default
-# \dontrun{ -# solve problems -s1 <- solve(p1) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 46 rows, 42 columns and 92 nonzeros -#> Model fingerprint: 0xde05e947 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+00] -#> Objective range [9e+01, 1e+02] -#> Bounds range [1e+00, 1e+00] -#> RHS range [3e-01, 1e+00] -#> Found heuristic solution: objective 497.7671458 -#> Presolve removed 45 rows and 20 columns -#> Presolve time: 0.00s -#> Presolved: 1 rows, 22 columns, 2 nonzeros -#> Variable types: 0 continuous, 22 integer (22 binary) -#> -#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 497.767 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 4.977671458279e+02, best bound 4.977671458279e+02, gap 0.0000%
s2 <- solve(p2) -
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64) -#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads -#> Optimize a model with 46 rows, 42 columns and 92 nonzeros -#> Model fingerprint: 0xb55f4224 -#> Variable types: 0 continuous, 42 integer (42 binary) -#> Coefficient statistics: -#> Matrix range [9e-02, 1e+00] -#> Objective range [9e+01, 1e+02] -#> Bounds range [1e+00, 1e+00] -#> RHS range [1e-01, 1e+00] -#> Found heuristic solution: objective 304.1251127 -#> Presolve removed 24 rows and 11 columns -#> Presolve time: 0.00s -#> Presolved: 22 rows, 31 columns, 44 nonzeros -#> Variable types: 0 continuous, 31 integer (31 binary) -#> Presolved: 22 rows, 31 columns, 44 nonzeros -#> -#> -#> Root relaxation: objective 2.042172e+02, 5 iterations, 0.00 seconds -#> -#> Nodes | Current Node | Objective Bounds | Work -#> Expl Unexpl | Obj Depth IntInf | Incumbent BestBd Gap | It/Node Time -#> -#> * 0 0 0 204.2171997 204.21720 0.00% - 0s -#> -#> Explored 0 nodes (5 simplex iterations) in 0.00 seconds -#> Thread count was 1 (of 8 available processors) -#> -#> Solution count 1: 204.217 -#> -#> Optimal solution found (tolerance 0.00e+00) -#> Best objective 2.042171996644e+02, best bound 2.042171996644e+02, gap 0.0000%
-# print solutions -print(s1) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 498. 498. 1 1 1 1 1 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
print(s2) -
#> # A tibble: 1 x 21 -#> solution status obj cost F1_action F2_action F3_action F4_action F5_action -#> <int> <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> -#> 1 1 OPTIMAL 204. 204. 0 1 1 0 0 -#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>, -#> # F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>, -#> # baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>
-# plot solutions -plot(p1, s1) -
plot(p2, s2) -
# } -
+
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with minimum set objective and targets that require each
+# feature to have a 30% chance of persisting into the future
+p1 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_min_set_objective() %>%
+      add_absolute_targets(0.3) %>%
+      add_binary_decisions()
+
+# print problem
+print(p1)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Minimum set objective 
+#>   targets:         Absolute targets [targets (min: 0.3, max: 0.3)]
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# build problem with minimum set objective and targets that require each
+# feature to have a level of persistence that is greater than or equal to
+# 30% of the best project for conserving it
+p2 <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+      add_min_set_objective() %>%
+      add_relative_targets(0.3) %>%
+      add_binary_decisions()
+
+# print problem
+print(p2)
+#> Project Prioritization Problem
+#>   actions          F1_action, F2_action, F3_action, ... (6 actions)
+#>   projects         F1_project, F2_project, F3_project, ... (6 projects)
+#>   features         F1, F2, F3, ... (5 features)
+#>   action costs:    min: 0, max: 103.22583
+#>   project success: min: 0.81379, max: 1
+#>   objective:       Minimum set objective 
+#>   targets:         Relative targets [targets (min: 0.3, max: 0.3)]
+#>   weights:         default
+#>   decisions        Binary decision 
+#>   constraints:     <none>
+#>   solver:          default
+
+# \dontrun{
+# solve problems
+s1 <- solve(p1)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 46 rows, 42 columns and 92 nonzeros
+#> Model fingerprint: 0xde05e947
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+00]
+#>   Objective range  [9e+01, 1e+02]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [3e-01, 1e+00]
+#> Found heuristic solution: objective 497.7671458
+#> Presolve removed 45 rows and 20 columns
+#> Presolve time: 0.00s
+#> Presolved: 1 rows, 22 columns, 2 nonzeros
+#> Variable types: 0 continuous, 22 integer (22 binary)
+#> 
+#> Explored 0 nodes (0 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 497.767 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 4.977671458279e+02, best bound 4.977671458279e+02, gap 0.0000%
+s2 <- solve(p2)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 46 rows, 42 columns and 92 nonzeros
+#> Model fingerprint: 0xb55f4224
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+00]
+#>   Objective range  [9e+01, 1e+02]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e-01, 1e+00]
+#> Found heuristic solution: objective 304.1251127
+#> Presolve removed 24 rows and 11 columns
+#> Presolve time: 0.00s
+#> Presolved: 22 rows, 31 columns, 44 nonzeros
+#> Variable types: 0 continuous, 31 integer (31 binary)
+#> Root relaxation presolved: 22 rows, 31 columns, 44 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 2.042172e+02, 5 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0     204.2171997  204.21720  0.00%     -    0s
+#> 
+#> Explored 1 nodes (5 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 204.217 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 2.042171996644e+02, best bound 2.042171996644e+02, gap 0.0000%
+
+# print solutions
+print(s1)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  498.  498.         1       1       1       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+print(s2)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  204.  204.         0       1       1       0       0       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solutions
+plot(p1, s1)
+
+plot(p2, s2)
+
+# }
+
+
+
- - - - + diff --git a/docs/reference/tee.html b/docs/reference/tee.html index 1922311..777b63f 100644 --- a/docs/reference/tee.html +++ b/docs/reference/tee.html @@ -1,78 +1,12 @@ - - - - - - - -Tee operator — %T>% • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Tee operator — %T>% • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Tee operator

- Source: R/magrittr-operators.R + Source: R/magrittr-operators.R
@@ -129,68 +56,64 @@

Tee operator

-

Arguments

- - - - - - -
lhs, rhs

An object and a function.

- -

See also

- -

magrittr::%T>%(), pipe().

- -

Examples

- 
# the tee operator returns the left-hand side of the result and can be
-# useful when dealing with mutable objects. In this example we want
-# to use the function "f" to modify the object "e" and capture the
-# result
-
-# create an empty environment
-e <- new.env()
-
-# create a function to modify an environment and return NULL
-f <- function(x) {x$a <- 5; return(NULL)}
-
-# if we use the pipe operator we won't capture the result since "f"()
-# returns a NULL
-e2 <- e %>% f()
-print(e2)
-
#> NULL

-# but if we use the tee operator then the result contains a copy of "e"
-e3 <- e %T>% f()
-print(e3)
-
#> <environment: 0x55de4cbd5db8>

-
+
+

Arguments

+
lhs, rhs
+

An object and a function.

+ +
+
+

See also

+

magrittr::%T>%(), pipe().

+
+ +
+

Examples

+ 
# the tee operator returns the left-hand side of the result and can be
+# useful when dealing with mutable objects. In this example we want
+# to use the function "f" to modify the object "e" and capture the
+# result
+
+# create an empty environment
+e <- new.env()
+
+# create a function to modify an environment and return NULL
+f <- function(x) {x$a <- 5; return(NULL)}
+
+# if we use the pipe operator we won't capture the result since "f"()
+# returns a NULL
+e2 <- e %>% f()
+print(e2)
+#> NULL
+
+# but if we use the tee operator then the result contains a copy of "e"
+e3 <- e %T>% f()
+print(e3)
+#> <environment: 0x556a21f6e2d0>
+
+
+
+
- - - - + diff --git a/docs/reference/tibble-methods.html b/docs/reference/tibble-methods.html index f080f57..fafa12b 100644 --- a/docs/reference/tibble-methods.html +++ b/docs/reference/tibble-methods.html @@ -1,78 +1,12 @@ - - - - - - - -Manipulate tibbles — tibble-methods • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Manipulate tibbles — tibble-methods • oppr - - - - - - - - - - - - - +
-
- -
- -
+

Manipulate tibbles

- Source: R/tbl_df.R + Source: R/tbl_df.R
-

Assorted functions for manipulating tibble::tibble() objects.

+

Assorted functions for manipulating tibble::tibble() objects.

- 
# S4 method for tbl_df
-nrow(x)
-
-# S4 method for tbl_df
-ncol(x)
+    

+    
# S4 method for tbl_df
+nrow(x)
+
+# S4 method for tbl_df
+ncol(x)
+
+# S4 method for tbl_df
+as.list(x)

+    

 
-# S4 method for tbl_df
-as.list(x)
+
+

Arguments

+
x
+

tibble::tibble() object.

-

Arguments

- - - - - - -
x

tibble::tibble() object.

+
+
+

Details

+

The following methods are provided from manipulating +tibble::tibble() objects.

+
nrow
+

extract integer number of rows.

-

Details

-

The following methods are provided from manipulating -tibble::tibble() objects.

-
-
nrow

extract integer number of rows.

+
ncol
+

extract integer number of columns.

-
ncol

extract integer number of columns.

-
as.list

convert to a list.

+
as.list
+

convert to a list.

-
print

print the object.

+
print
+

print the object.

-
-

Examples

- 
# load tibble package
-require(tibble)
-
#> Loading required package: tibble

-# make tibble
-a <- tibble(value = seq_len(5))
+
-# number of rows -nrow(a) -
#> [1] 5
-# number of columns -ncol(a) -
#> [1] 1
-# convert to list -as.list(a) -
#> $value -#> [1] 1 2 3 4 5 -#>
+
+

Examples

+ 
# load tibble package
+require(tibble)
+#> Loading required package: tibble
+
+# make tibble
+a <- tibble(value = seq_len(5))
+
+# number of rows
+nrow(a)
+#> [1] 5
+
+# number of columns
+ncol(a)
+#> [1] 1
+
+# convert to list
+as.list(a)
+#> $value
+#> [1] 1 2 3 4 5
+#> 
+
+
+
- - - - + diff --git a/docs/reference/weights-1.png b/docs/reference/weights-1.png index b6aaf49..4c14674 100644 Binary files a/docs/reference/weights-1.png and b/docs/reference/weights-1.png differ diff --git a/docs/reference/weights.html b/docs/reference/weights.html index 7f64a8f..4ab4783 100644 --- a/docs/reference/weights.html +++ b/docs/reference/weights.html @@ -1,81 +1,15 @@ - - - - - - - -Weights — weights • oppr - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Weights — weights • oppr - - - - - - - - - - - - - - - - - - - - - - - - +
-
- -
- -
+

Weights

- Source: R/weights.R + Source: R/weights.R
@@ -135,111 +62,111 @@

Weights

+
+

Details

+

Currently, only one function can be used to specify weights:

+
add_feature_weights()
+

Set feature weights for a project prioritization problem().

-

Details

-

Currently, only one function can be used to specify weights:

-
- -
add_feature_weights()

Set feature weights for a project prioritization problem().

- - -
- -

See also

- -

constraints, decisions, -objectives, problem(), -solvers, targets.

- -

Examples

- 
# load data
-data(sim_projects, sim_features, sim_actions)
-
-# build problem with maximum richness objective, $300 budget, and
-# feature weights
-p <- problem(sim_projects, sim_actions, sim_features,
-             "name", "success", "name", "cost", "name") %>%
-     add_max_richness_objective(budget = 200) %>%
-     add_feature_weights("weight") %>%
-     add_binary_decisions()
-
-# \dontrun{
-# solve problem
-s <- solve(p)
-
#> Gurobi Optimizer version 9.1.2 build v9.1.2rc0 (linux64)
-#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
-#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
-#> Model fingerprint: 0xffde171d
-#> Variable types: 0 continuous, 42 integer (42 binary)
-#> Semi-Variable types: 5 continuous, 0 integer
-#> Coefficient statistics:
-#>   Matrix range     [9e-02, 1e+02]
-#>   Objective range  [2e-01, 2e+00]
-#>   Bounds range     [1e+00, 1e+00]
-#>   RHS range        [1e+00, 2e+02]
-#> Found heuristic solution: objective 0.6654645
-#> Presolve removed 16 rows and 12 columns
-#> Presolve time: 0.00s
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> Variable types: 0 continuous, 35 integer (35 binary)
-#> Presolved: 31 rows, 35 columns, 65 nonzeros
-#> 
-#> 
-#> Root relaxation: objective 1.511230e+00, 11 iterations, 0.00 seconds
-#> 
-#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
-#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
-#> 
-#> *    0     0               0       1.5112297    1.51123  0.00%     -    0s
-#> 
-#> Explored 0 nodes (11 simplex iterations) in 0.00 seconds
-#> Thread count was 1 (of 8 available processors)
-#> 
-#> Solution count 1: 1.51123 
-#> 
-#> Optimal solution found (tolerance 0.00e+00)
-#> Best objective 1.511229665304e+00, best bound 1.511229665304e+00, gap 0.0000%

-# print solution
-print(s)
-
#> # A tibble: 1 x 21
-#>   solution status    obj  cost F1_action F2_action F3_action F4_action F5_action
-#>      <int> <chr>   <dbl> <dbl>     <dbl>     <dbl>     <dbl>     <dbl>     <dbl>
-#> 1        1 OPTIMAL  1.51  199.         0         0         0         1         1
-#> # … with 12 more variables: baseline_action <dbl>, F1_project <dbl>,
-#> #   F2_project <dbl>, F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
-#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>

-# plot solution
-plot(p, s)
-
# }
-
+ +
+ + +
+

Examples

+ 
# load data
+data(sim_projects, sim_features, sim_actions)
+
+# build problem with maximum richness objective, $300 budget, and
+# feature weights
+p <- problem(sim_projects, sim_actions, sim_features,
+             "name", "success", "name", "cost", "name") %>%
+     add_max_richness_objective(budget = 200) %>%
+     add_feature_weights("weight") %>%
+     add_binary_decisions()
+
+# \dontrun{
+# solve problem
+s <- solve(p)
+#> Gurobi Optimizer version 9.5.2 build v9.5.2rc0 (linux64)
+#> Thread count: 4 physical cores, 8 logical processors, using up to 1 threads
+#> Optimize a model with 47 rows, 47 columns and 102 nonzeros
+#> Model fingerprint: 0x40fa7344
+#> Variable types: 0 continuous, 42 integer (42 binary)
+#> Semi-Variable types: 5 continuous, 0 integer
+#> Coefficient statistics:
+#>   Matrix range     [9e-02, 1e+02]
+#>   Objective range  [2e-01, 2e+00]
+#>   Bounds range     [1e+00, 1e+00]
+#>   RHS range        [1e+00, 2e+02]
+#> Found heuristic solution: objective 0.6654645
+#> Presolve removed 16 rows and 12 columns
+#> Presolve time: 0.00s
+#> Presolved: 31 rows, 35 columns, 65 nonzeros
+#> Variable types: 0 continuous, 35 integer (35 binary)
+#> Root relaxation presolved: 31 rows, 35 columns, 65 nonzeros
+#> 
+#> 
+#> Root relaxation: objective 1.511230e+00, 11 iterations, 0.00 seconds (0.00 work units)
+#> 
+#>     Nodes    |    Current Node    |     Objective Bounds      |     Work
+#>  Expl Unexpl |  Obj  Depth IntInf | Incumbent    BestBd   Gap | It/Node Time
+#> 
+#> *    0     0               0       1.5112297    1.51123  0.00%     -    0s
+#> 
+#> Explored 1 nodes (11 simplex iterations) in 0.00 seconds (0.00 work units)
+#> Thread count was 1 (of 8 available processors)
+#> 
+#> Solution count 1: 1.51123 
+#> 
+#> Optimal solution found (tolerance 0.00e+00)
+#> Best objective 1.511229665304e+00, best bound 1.511229665304e+00, gap 0.0000%
+
+# print solution
+print(s)
+#> # A tibble: 1 × 21
+#>   solution status    obj  cost F1_action F2_ac…¹ F3_ac…² F4_ac…³ F5_ac…⁴ basel…⁵
+#>      <int> <chr>   <dbl> <dbl>     <dbl>   <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
+#> 1        1 OPTIMAL  1.51  199.         0       0       0       1       1       1
+#> # … with 11 more variables: F1_project <dbl>, F2_project <dbl>,
+#> #   F3_project <dbl>, F4_project <dbl>, F5_project <dbl>,
+#> #   baseline_project <dbl>, F1 <dbl>, F2 <dbl>, F3 <dbl>, F4 <dbl>, F5 <dbl>,
+#> #   and abbreviated variable names ¹​F2_action, ²​F3_action, ³​F4_action,
+#> #   ⁴​F5_action, ⁵​baseline_action
+
+# plot solution
+plot(p, s)
+
+# }
+
+
+
- - - - + diff --git a/inst/WORDLIST b/inst/WORDLIST new file mode 100644 index 0000000..39e0dcc --- /dev/null +++ b/inst/WORDLIST @@ -0,0 +1,91 @@ +al +Araujo +Arponen +Benchmarking +Cabeza +cardinality +Carwardine +Chades +CMD +Combinatorial +complementarity +Complementarity +dgCMatrix +DK +doi +eco +eqn +eqns +et +Firn +Fonzo +FS +Gaston +ggplot +ggtree +Grantham +Guan +gurobi +Gurobi +Gurobi’ +irreplaceability +JM +JN +Kehoe +KJ +Korte +Leeuwen +lifecycle +lp +lpSolveAPI +Mackey +macOS +Maloney +Marxan +Mellish +MJ +MMI +Moilanen +Nicol +optimality +Optimality +Optimisation +OSX +phylogenies +phylogram +Possingham +PPP +pre +prioritisation +Prioritisation +prioritizations +Prioritizations +Probert +quadratically +README +Reeson +reproducibility +rescale +RJ +Rodrigues +species’ +Springer +Stokland +Stratford +Strimas +suboptimal +suboptimality +taxonomically +testthat +TG +tibble +tibbles +tidyr +tidytree +TTY +Tulloch +Verlag +Vygen +WJ +Yu +Zhu diff --git a/inst/doc/oppr.Rmd b/inst/doc/oppr.Rmd index 6257634..eb6d780 100644 --- a/inst/doc/oppr.Rmd +++ b/inst/doc/oppr.Rmd @@ -77,7 +77,7 @@ devtools::load_all() # Overview -The _oppr R_ package is decision support tool for prioritizing conservation projects. Prioritizations can be developed by maximizing expected feature richness, expected phylogenetic diversity, the number of features that meet persistence targets, or identifying a set of projects that meet persistence targets for minimal cost. Constraints (e.g. lock in specific actions) and feature weights can also be specified to further customize prioritizations. After defining a project prioritization problem, solutions can be obtained using exact alg'orithms, heuristic algorithms, or random processes. In particular, it is recommended to install the ['Gurobi' optimizer](https://www.gurobi.com) because it can identify optimal solutions very quickly. Finally, methods are provided for comparing different prioritizations and evaluating their benefits. +The _oppr R_ package is decision support tool for prioritizing conservation projects. Prioritizations can be developed by maximizing expected feature richness, expected phylogenetic diversity, the number of features that meet persistence targets, or identifying a set of projects that meet persistence targets for minimal cost. Constraints (e.g. lock in specific actions) and feature weights can also be specified to further customize prioritizations. After defining a project prioritization problem, solutions can be obtained using exact algorithms, heuristic algorithms, or random processes. In particular, it is recommended to install the ['Gurobi' optimizer](https://www.gurobi.com) because it can identify optimal solutions very quickly. Finally, methods are provided for comparing different prioritizations and evaluating their benefits. # Tutorial diff --git a/inst/doc/oppr.html b/inst/doc/oppr.html index d9a77bf..fd56025 100644 --- a/inst/doc/oppr.html +++ b/inst/doc/oppr.html @@ -26,6 +26,7 @@ +