Make check_dependencies a user-facing function

bodkan · Jul 13, 2023 · 6ae6ce0 · 6ae6ce0
1 parent 1fe6e09
commit 6ae6ce0
Show file tree

Hide file tree

Showing 7 changed files with 53 additions and 39 deletions.
diff --git a/R/compilation.R b/R/compilation.R
@@ -235,7 +235,7 @@ setting `direction = 'backward'.`", call. = FALSE)
 #'   in a SLiM simulation, if applicable)
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'

diff --git a/R/engines.R b/R/engines.R
@@ -29,7 +29,7 @@
 #'   vector, respectively.
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -228,7 +228,7 @@ msprime <- function(model, sequence_length, recombination_rate, samples = NULL,
 #'   vector, respectively.
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE, slim = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, slim = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'

diff --git a/R/interface.R b/R/interface.R
@@ -1193,7 +1193,7 @@ area <- function(x) {
 #'   from, how many individuals to sample
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -1485,7 +1485,7 @@ clear_env <- function(force = FALSE) {
 #'   (slendr Python environment is not present).
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #' check_env()

diff --git a/R/tree-sequences.R b/R/tree-sequences.R
@@ -30,7 +30,7 @@
 #'   map
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -113,7 +113,7 @@ ts_load <- function(file, model = NULL) {
 #' @return No return value, called for side effects
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -173,7 +173,7 @@ ts_save <- function(ts, file) {
 #'   map
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -301,7 +301,7 @@ ts_recapitate <- function(ts, recombination_rate, Ne = NULL, demography = NULL,
 #'   map
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -463,7 +463,7 @@ ts_simplify <- function(ts, simplify_to = NULL, keep_input_roots = FALSE,
 #'   map
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -527,7 +527,7 @@ ts_mutate <- function(ts, mutation_rate, random_seed = NULL,
 #' @return List of metadata fields extracted from the tree-sequence object
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -556,7 +556,7 @@ ts_metadata <- function(ts) {
 #'   of simulated individuals in columns
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -748,7 +748,7 @@ ts_vcf <- function(ts, path, chrom = NULL, individuals = NULL) {
 #' @return Standard phylogenetic tree object implemented by the R package ape
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -985,7 +985,7 @@ ts_phylo <- function(ts, i, mode = c("index", "position"),
 #'   as a spatial object of the class \code{sf}.
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -1092,7 +1092,7 @@ ts_table <- function(ts, table = c("individuals", "edges", "nodes", "mutations")
 #'   start-end coordinates of edges across space
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -1124,7 +1124,7 @@ ts_edges <- function(x) {
 #' @return Table of individuals scheduled for sampling across space and time
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -1166,7 +1166,7 @@ ts_samples <- function(ts) {
 #'   way up to the root of the tree sequence
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -1294,7 +1294,7 @@ ts_ancestors <- function(ts, x, verbose = FALSE, complete = TRUE) {
 #'   way down to the leaves of the tree sequence
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -1416,7 +1416,7 @@ ts_descendants <- function(ts, x, verbose = FALSE, complete = TRUE) {
 #' @return Python-reticulate-based object of the class tskit.trees.Tree
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -1464,7 +1464,7 @@ ts_tree <- function(ts, i, mode = c("index", "position"), ...) {
 #' @return No return value, called for side effects
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -1532,7 +1532,7 @@ ts_draw <- function(x, width = 1000, height = 1000, labels = FALSE,
 #'   (tskit Python 0-based) indices of trees which failed the coalescence test
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -1617,7 +1617,7 @@ ts_coalesced <- function(ts, return_failed = FALSE) {
 #'   for that pair)
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -1818,7 +1818,7 @@ ts_f4 <- function(ts, W, X, Y, Z, mode = c("site", "branch", "node"),
 #' @return Data frame with statistics calculated for the given sets of individuals
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -1941,7 +1941,7 @@ multiway_stat <- function(ts, stat = c("fst", "divergence"),
 #'   of Fst values (one for each window)
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -1972,7 +1972,7 @@ ts_fst <- function(ts, sample_sets, mode = c("site", "branch", "node"),
 #'   vector of divergence values (one for each window)
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -2054,7 +2054,7 @@ oneway_stat <- function(ts, stat, sample_sets, mode, windows, span_normalise = N
 #'   vector of diversity values (one for each window)
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -2090,7 +2090,7 @@ ts_segregating <- function(ts, sample_sets, mode = c("site", "branch", "node"),
 #'   vector of diversity values (one for each window)
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -2138,7 +2138,7 @@ ts_diversity <- function(ts, sample_sets, mode = c("site", "branch", "node"),
 #'   vector of Tajima's D values (one for each window)
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'
@@ -2194,7 +2194,7 @@ ts_tajima <- function(ts, sample_sets, mode = c("site", "branch", "node"),
 #'   links in the description for more detail on how tskit handles things.
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'

diff --git a/R/utils.R b/R/utils.R
@@ -1,26 +1,39 @@
-#' Check that all dependencies are available for slendr examples
+#' Check that the required dependencies are available for slendr to work
 #'
 #' @param python Is the slendr Python environment required?
 #' @param slim Is SLiM required?
+#' @param quit Should the R interpreter quit if required slendr dependencies are
+#'   missing? This option (which is not turned on by default, being set to
+#'   \code{FALSE}) is used mainly in avoiding running slendr man page examples on
+#'   machines which lack dependencies. If set to \code{TRUE}, a logical value
+#'   is returned.
 #'
-#' @return No return value. Called only to result in an error message if a
-#'   particular software dependency is missing for an example to run.
+#' @return If \code{quit = TRUE}, no values is returned, if \code{quit = FALSE},
+#'   a scalar logical value is returned indicating whether or not the dependencies
+#'   are present.
 #'
 #' @export
-#' @keywords internal
-check_dependencies <- function(python = FALSE, slim = FALSE) {
+check_dependencies <- function(python = FALSE, slim = FALSE, quit = FALSE) {
   # check whether SLiM and Python are present (only if needed!)
   missing_slim <- if (slim) !all(Sys.which("slim") != "") else FALSE
   missing_python <- if (python) !is_slendr_env_present() else FALSE
 
-  if (missing_slim | missing_python) {
+  fail <- missing_slim || missing_python
+
+  if (fail) {
     if (interactive()) {
       error_slim <- if (missing_slim) "SLiM" else ""
       error_python <- if (missing_python) "slendr Python environment" else ""
       stop(sprintf("Missing requirements for this example: %s",
                    paste(error_slim, error_python, sep = ", ")), call. = FALSE)
-    } else
-      q()
+    } else {
+      if (quit)
+        q()
+      else
+        return(FALSE)
+    }
+  } else {
+    return(invisible(TRUE))
   }
 }
 

diff --git a/R/visualization.R b/R/visualization.R
@@ -263,7 +263,7 @@ sort_splits <- function(model) {
 #' @return A ggplot2 object with the visualized slendr model
 #'
 #' @examples
-#' \dontshow{check_dependencies(python = TRUE) # make sure dependencies are present
+#' \dontshow{check_dependencies(python = TRUE, quit = TRUE) # dependencies must be present
 #' }
 #' init_env()
 #'

diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -60,12 +60,13 @@ reference:
     - read_model
     - schedule_sampling
 
-  - title: Installation and configuration of Python dependencies
+  - title: Installation and configuration of external dependencies
     contents:
     - setup_env
     - init_env
     - check_env
     - clear_env
+    - check_dependencies
 
   - title: Model components
     contents: