More prepping for release

Author: gregorgorjanc

RcppTskit/DESCRIPTION

@@ -9,19 +9,19 @@ Authors@R: c(
     person("Tskit Developers", role = "cph",
            comment = "Authors of included tskit C library")
   )
-Description: `Tskit` enables performant storage, manipulation, and
+Description: 'Tskit' enables performant storage, manipulation, and
     analysis of ancestral recombination graphs (ARGs) using succinct tree
-    sequence encoding. See https://tskit.dev for project news,
-    documentation, and tutorials. `Tskit` provides Python, C, and Rust
+    sequence encoding. See <https://tskit.dev> for project news,
+    documentation, and tutorials. 'Tskit' provides Python, C, and Rust
     application programming interfaces (APIs). The Python API can be
-    called from R via the `reticulate` R package to seamlessly load and
+    called from R via the 'reticulate' R package to seamlessly load and
     analyse a tree sequence as described at
-    https://tskit.dev/tutorials/tskitr.html. `RcppTskit` provides R
-    access to the `tskit` C API for use cases where the `reticulate`
+    <https://tskit.dev/tutorials/tskitr.html>. 'RcppTskit' provides R
+    access to the 'tskit' C API for use cases where the 'reticulate'
     option is not optimal. For example, for high-performance and low-level
-    work with tree sequences. Currently, `RcppTskit` provides a limited
+    work with tree sequences. Currently, 'RcppTskit' provides a limited
     number of R functions due to the availability of extensive Python API
-    and the `reticulate` option.
+    and the 'reticulate' option.
 License: MIT + file LICENSE
 URL: https://github.com/HighlanderLab/RcppTskit
 BugReports: https://github.com/HighlanderLab/RcppTskit/issues

RcppTskit/NAMESPACE

@@ -1,6 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
 export(TreeSequence)
+export(check_tskit_py)
 export(get_tskit_py)
 export(kastore_version)
 export(ts_load)

RcppTskit/R/Class-TreeSequence.R

@@ -106,11 +106,14 @@ TreeSequence <- R6Class(
     #' ts_r$num_samples() # 160
     #'
     #' # Transfer the tree sequence to reticulate Python and use tskit Python API
-    #' ts_py <- ts_r$r_to_py()
-    #' is(ts_py)
-    #' ts_py$num_samples # 160
-    #' ts2_py <- ts_py$simplify(samples = c(0L, 1L, 2L, 3L))
-    #' ts2_py$num_samples # 4
+    #' tskit <- get_tskit_py()
+    #' if (check_tskit_py(tskit)) {
+    #'   ts_py <- ts_r$r_to_py()
+    #'   is(ts_py)
+    #'   ts_py$num_samples # 160
+    #'   ts2_py <- ts_py$simplify(samples = c(0L, 1L, 2L, 3L))
+    #'   ts2_py$num_samples # 4
+    #' }
     r_to_py = function(tskit_module = get_tskit_py(), cleanup = TRUE) {
       ts_r_to_py_ptr(
         self$pointer,

RcppTskit/R/RcppTskit.R

@@ -3,36 +3,41 @@
 #' @title Get the reticulate Python tskit module
 #' @description This function imports the reticulate Python \code{tskit} module
 #'   and if it is not yet installed, then it attempts to install it first.
-#' @param obj_name character name of the object holding \code{tskit} reticulate
+#' @param object_name character name of the object holding \code{tskit} reticulate
 #'   Python module. If this object exists in the global R environment and is a
 #'   reticulate Python object, then it is returned. Otherwise, the function
 #'   attempts to install and import tskit before returning it. If \code{NULL},
 #'   then the function directly attempts to install and import tskit before
 #'   returning it.
+#' @param object reticulate Python module object, hopefully.
+#' @param stop logical for throwing an error in \code{check_tskit_py}.
 #' @details This function is meant for users running \code{tskit <- get_tskit_py()}
 #'   or similar code, but also by other functions in this package that need the
 #'   \code{tskit} reticulate Python module. The point of \code{get_tskit_py} is
 #'   to avoid importing the module repeatedly, if it has been imported already.
-#' @return \code{tskit} reticulate Python module.
+#' @return \code{get_tskit_py} returns \code{tskit} reticulate Python module.
+#'   \code{check_tskit_py} returns \code{TRUE} if
 #' @examples
 #' tskit <- get_tskit_py()
 #' is(tskit)
-#' tskit$ALLELES_01
+#' if (check_tskit_py(tskit)) {
+#'   tskit$ALLELES_01
+#' }
 #' @export
-get_tskit_py <- function(obj_name = "tskit") {
-  test <- !is.null(obj_name) &&
-    exists(obj_name, envir = .GlobalEnv, inherits = FALSE)
+get_tskit_py <- function(object_name = "tskit") {
+  test <- !is.null(object_name) &&
+    exists(object_name, envir = .GlobalEnv, inherits = FALSE)
   if (test) {
-    tskit <- get(obj_name, envir = .GlobalEnv, inherits = FALSE)
+    tskit <- get(object_name, envir = .GlobalEnv, inherits = FALSE)
     test <- reticulate::is_py_object(tskit) &&
       is(tskit) == "python.builtin.module"
     if (test) {
       return(tskit)
     } else {
       txt <- paste0(
         "Object '",
-        obj_name,
-        "' exists in the global environment but is not a reticulate Python module"
+        object_name,
+        "' exists in the global environment but is not a reticulate Python module!"
       )
       stop(txt)
     }
@@ -42,13 +47,31 @@ get_tskit_py <- function(obj_name = "tskit") {
   # nocov start
   if (!reticulate::py_module_available("tskit")) {
     txt <- "Python module 'tskit' is not available. Attempting to install it ..."
-    cat(txt)
+    message(txt)
     reticulate::py_require("tskit")
   }
   # nocov end
   return(reticulate::import("tskit", delay_load = TRUE))
 }
 
+#' @describeIn get_tskit_py Test if \code{get_tskit_py} returned a reticulate Python module object
+#' @export
+check_tskit_py <- function(object, stop = FALSE) {
+  test <- reticulate::is_py_object(object) &&
+    ("python.builtin.module" %in% is(object))
+  if (test) {
+    return(TRUE)
+  } else {
+    msg <- "object must be a reticulate Python module object!"
+    if (stop) {
+      stop(msg)
+    } else {
+      message(msg)
+    }
+    return(FALSE)
+  }
+}
+
 #' @title Load a tree sequence from a file
 #' @param file a string specifying the full path of the tree sequence file.
 #' @param options integer bitwise options (see details at
@@ -182,9 +205,7 @@ ts_r_to_py_ptr <- function(ts, tskit_module = get_tskit_py(), cleanup = TRUE) {
   if (!is(ts, "externalptr")) {
     stop("ts must be an object of externalptr class!")
   }
-  if (!reticulate::is_py_object(tskit_module)) {
-    stop("tskit_module must be a reticulate Python module object!")
-  }
+  check_tskit_py(tskit_module, stop = TRUE)
   ts_file <- tempfile(fileext = ".trees")
   if (cleanup) {
     on.exit(file.remove(ts_file))
@@ -247,16 +268,18 @@ ts_py_to_r_ptr <- function(ts, cleanup = TRUE) {
 #'
 #' # Use the tskit Python API to work with a tree sequence (via reticulate)
 #' tskit <- get_tskit_py()
-#' ts_py <- tskit$load(ts_file)
-#' is(ts_py)
-#' ts_py$num_samples # 160
-#' ts2_py <- ts_py$simplify(samples = c(0L, 1L, 2L, 3L))
-#' ts2_py$num_samples # 4
+#' if (check_tskit_py(tskit)) {
+#'   ts_py <- tskit$load(ts_file)
+#'   is(ts_py)
+#'   ts_py$num_samples # 160
+#'   ts2_py <- ts_py$simplify(samples = c(0L, 1L, 2L, 3L))
+#'   ts2_py$num_samples # 4
 #'
-#' # Transfer the tree sequence to R and use RcppTskit
-#' ts2_r <- ts_py_to_r(ts2_py)
-#' is(ts2_r)
-#' ts2_r$num_samples() # 4
+#'   # Transfer the tree sequence to R and use RcppTskit
+#'   ts2_r <- ts_py_to_r(ts2_py)
+#'   is(ts2_r)
+#'   ts2_r$num_samples() # 4
+#' }
 #' @export
 ts_py_to_r <- function(ts, cleanup = TRUE) {
   ptr <- ts_py_to_r_ptr(ts = ts, cleanup = cleanup)

RcppTskit/man/TreeSequence.Rd

@@ -2,11 +2,14 @@
 
 ## Next TODOs
 
+# TODO: Create a minimal package to demonstrate how to link against RcppTskit and call tskit C API
+        https://github.com/HighlanderLab/RcppTskit/issues/48
+
+
+
 TODO: Add citation for tskit to DESCRIPTION file #46
       https://github.com/HighlanderLab/RcppTskit/issues/46
 
-# TODO: Create a minimal package to demonstrate how to link against RcppTskit and call tskit C API
-
 # Release (TODO)
 # TODO: Tag a release #15
 #       https://github.com/HighlanderLab/RcppTskit/issues/15

RcppTskit/man/get_tskit_py.Rd

@@ -1,5 +1,3 @@
-context("TreeSequence$new()")
-
 test_that("TreeSequence$new() works", {
   ts_file <- system.file("examples/test.trees", package = "RcppTskit")
   expect_error(TreeSequence$new(), regexp = "Provide a file name or a pointer!")

RcppTskit/man/ts_py_to_r.Rd

@@ -1,13 +1,11 @@
-context("get_tskit_py()")
-
 test_that("get_tskit_py() works", {
   # Testing that get_tskit_py() fails with a non-module object
   # Next two lines ensure that testthat is looking into the global environment
   # as is get_tskit_py()
   assign("rubbish", "something_else_than_a_py_module", envir = .GlobalEnv)
   on.exit(rm("rubbish", envir = .GlobalEnv), add = TRUE)
   expect_error(
-    get_tskit_py(obj_name = "rubbish"),
+    get_tskit_py(object_name = "rubbish"),
     regexp = "Object 'rubbish' exists in the global environment but is not a reticulate Python module"
   )
 
@@ -42,9 +40,40 @@ test_that("get_tskit_py() works", {
   expect_equal(tskit$`__name__`, tskit2$`__name__`)
 
   # Re-importing
-  tskit3 <- get_tskit_py(obj_name = NULL)
+  tskit3 <- get_tskit_py(object_name = NULL)
   # lobstr::obj_addr(tskit3)
   # "0x161ec00f0" --> different address because we are obtaining a new object
   # but it is still the same module
   expect_equal(tskit$`__name__`, tskit3$`__name__`)
 })
+
+test_that("check_tskit_py() validates python module objects", {
+  expect_message(
+    expect_false(check_tskit_py(1)),
+    "object must be a reticulate Python module object!"
+  )
+  expect_error(
+    check_tskit_py(1, stop = TRUE),
+    "object must be a reticulate Python module object!"
+  )
+
+  if (!reticulate::py_available(initialize = FALSE)) {
+    skip("Python not available for reticulate tests.")
+  }
+
+  obj <- reticulate::py_eval("1")
+  expect_message(
+    expect_false(check_tskit_py(obj)),
+    "object must be a reticulate Python module object"
+  )
+
+  sys <- reticulate::import("sys")
+  expect_silent(expect_true(check_tskit_py(sys)))
+
+  if (reticulate::py_module_available("tskit")) {
+    tskit <- get_tskit_py()
+    expect_true(check_tskit_py(tskit))
+  } else {
+    skip("tskit module not available for reticulate tests.")
+  }
+})