Add check_requires() function and update installation docs

CHANGELOG.md

@@ -47,6 +47,8 @@ For more information, please visit the [package website](https://laminr.lamin.ai
 
 * Remove link tables from object print output (PR #55)
 
+* Improve checking for suggested packages and provide installation instructions if missing (PR #56)
+
 ## TESTING
 
 * Add a simple unit test which queries laminlabs/lamindata (PR #27).
@@ -71,6 +73,8 @@ For more information, please visit the [package website](https://laminr.lamin.ai
 
 * Set Python requirements to `lamindb[aws]` for now (PR #33). Will be changed to `lamin_cli` once 
   [laminlabs/lamin-cli#90](https://github.com/laminlabs/lamin-cli/issues/90) is solved.
+
+* Improve documentation for installing suggested dependencies and what they are requrire for (PR #56)
 
 ## BUG FIXES
 

DESCRIPTION

@@ -1,26 +1,18 @@
 Package: laminr
 Title: 'LaminDB' Interface in R
 Version: 0.1.0
-Authors@R:
-    c(person("Robrecht", "Cannoodt",
-        role = c("aut", "cre"),
-        email = "[email protected]",
-        comment = c(ORCID = "0000-0003-3641-729X", github = "rcannood")
-    ),
-    person(
-        "Luke", "Zappia",
-        role = "aut",
-        email = "[email protected]",
-        comment = c(ORCID = "0000-0001-7744-8565", github = "lazappi")
-    ),
-    person("Data Intuitive", email = "[email protected]", role = c("aut")),
-    person("Lamin Labs", email = "[email protected]", role = c("aut", "cph")))
-Description: Interact with 'LaminDB' from R. 'LaminDB' is an open-source data framework for biology.
-    This package allows you to query and download data from 'LaminDB' instances.
+Authors@R:c(
+    person("Robrecht", "Cannoodt", , "[email protected]", role = c("aut", "cre"),
+           comment = c(ORCID = "0000-0003-3641-729X", github = "rcannood")),
+    person("Luke", "Zappia", , "[email protected]", role = "aut",
+           comment = c(ORCID = "0000-0001-7744-8565", github = "lazappi")),
+    person("Data Intuitive", , , "[email protected]", role = "aut"),
+    person("Lamin Labs", , , "[email protected]", role = c("aut", "cph"))
+  )
+Description: Interact with 'LaminDB' from R. 'LaminDB' is an open-source
+    data framework for biology.  This package allows you to query and
+    download data from 'LaminDB' instances.
 License: Apache License (>= 2)
-Encoding: UTF-8
-Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2
 URL: https://laminr.lamin.ai, https://github.com/laminlabs/laminr
 BugReports: https://github.com/laminlabs/laminr/issues
 Depends:
@@ -30,12 +22,17 @@ Imports:
     httr,
     jsonlite,
     purrr,
-    R6
+    R6,
+    rlang
 Suggests:
     anndata,
     quarto,
     s3 (>= 1.1.0),
     testthat (>= 3.0.0),
     withr
-VignetteBuilder: quarto
+VignetteBuilder: 
+    quarto
 Config/testthat/edition: 3
+Encoding: UTF-8
+Roxygen: list(markdown = TRUE)
+RoxygenNote: 7.3.2

R/Artifact.R

@@ -19,7 +19,7 @@ ArtifactRecord <- R6::R6Class( # nolint object_name_linter
       file_path <- self$cache()
 
       if (artifact_accessor == "AnnData") {
-        requireNamespace("anndata", quietly = TRUE)
+        check_requires("Loading AnnData objects", "anndata")
         anndata::read_h5ad(file_path)
       } else {
         cli_abort(paste0("Unsupported accessor: ", artifact_accessor))
@@ -37,7 +37,7 @@ ArtifactRecord <- R6::R6Class( # nolint object_name_linter
       artifact_key <- private$get_value("key")
 
       if (artifact_storage$type == "s3") {
-        requireNamespace("s3", quietly = TRUE)
+        check_requires("Caching artifacts from s3", "s3")
         root_dir <- file.path(Sys.getenv("HOME"), ".cache", "lamindb")
         s3::s3_get(
           paste0(artifact_storage$root, "/", artifact_key),

R/utils.R

@@ -0,0 +1,32 @@
+#' Check required packages
+#'
+#' Check that required packages are available and give a nice error message with
+#' install instructions if not
+#'
+#' @param what A message stating what the packages are required for. Used at the
+#'   start of the error message e.g. "{what} requires...".
+#' @param requires Character vector of required package names
+#'
+#' @return `TRUE` invisibly if all packages are available, otherwise calls
+#'   [cli::cli_abort()]
+#' @noRd
+check_requires <- function(what, requires) {
+  is_available <- purrr::map_lgl(requires, requireNamespace, quietly = TRUE)
+
+  if (any(!is_available)) {
+    missing <- requires[!is_available]
+    missing_str <- paste0("'", paste(missing, collapse = "', '"), "'") # nolint object_usage_linter
+    cli_abort(
+      c(
+        "{what} requires the {.pkg {missing}} package{?s}",
+        "i" = paste(
+          "To continue, install {cli::qty(missing)}{?it/them} using",
+          "{.code install.packages(c({missing_str}))}"
+        )
+      ),
+      call = rlang::caller_env()
+    )
+  }
+
+  invisible(TRUE)
+}

README.md

@@ -22,6 +22,13 @@ Install the development version from GitHub:
 remotes::install_github("laminlabs/laminr")
 ```
 
+To install all suggested dependencies required for some functionality,
+use:
+
+``` r
+remotes::install_github("laminlabs/laminr", dependencies = TRUE)
+```
+
 You will also need to install `lamindb`:
 
 ``` bash

README.qmd

@@ -24,6 +24,12 @@ Install the development version from GitHub:
 remotes::install_github("laminlabs/laminr")
 ```
 
+To install all suggested dependencies required for some functionality, use:
+
+```R
+remotes::install_github("laminlabs/laminr", dependencies = TRUE)
+```
+
 You will also need to install `lamindb`:
 
 ```bash

tests/testthat/test-utils.R

@@ -0,0 +1,7 @@
+test_that("check_requires works", {
+  expect_true(check_requires("Imported packages", "cli"))
+  expect_error(
+    check_requires("Missing packages", "a_missing_package"),
+    regexp = "Missing packages requires"
+  )
+})

vignettes/usage.Rmd

@@ -20,18 +20,44 @@ This vignette will show you how to use the `laminr` package to interact with Lam
 
 ## Initial setup
 
-As part of a first-time set up, you will need to install `laminr`, the Python `lamin-cli` package, and set up an instance for first use.
+### Python package
+
+As part of a first-time set up, you will need to install the Python `lamin-cli` package, and set up an instance for first use.
 
 ```bash
 pip install lamin-cli
 lamin connect laminlabs/cellxgene
 ```
 
-```R
-install.packages("remotes")
+### R package
+
+You will also need to install the `laminr` R package.
+
+```{r install, eval = FALSE}
+# Install the remotes package if needed
+if (!requireMethods("remotes", quiety = TRUE)) {
+  install.packages("remotes")
+}
 remotes::install_github("laminlabs/laminr")
 ```
 
+#### Suggested dependencies
+
+Some functionality requires additional suggested dependencies.
+You will be prompted to install these packages when needed, or you can install them in advance.
+Setting `dependencies = TRUE` will install all suggested packages.
+
+```{r install-suggested, eval = FALSE}
+remotes::install_github("laminlabs/laminr", dependencies = TRUE)
+```
+
+Or individual suggested packages can be installed with `install.packages()`.
+
+Suggested dependecies:
+
+- [anndata](https://cran.r-project.org/package=anndata) - Loading and saving `AnnData` objects
+- [s3](https://cran.r-project.org/package=s3) - Caching objects to/from S3 storage
+
 ## Connect to a LaminDB instance
 
 This vignette uses the [`laminlabs/cellxgene`](https://lamin.ai/laminlabs/cellxgene) instance, which is a LaminDB instance that interfaces the CELLxGENE data.