All unit tests are passing after internal refactoring.

Now it's time to just focus on documentation.

NAMESPACE

@@ -19,9 +19,11 @@ export(feature_info)
 export(file_info)
 export(file_path)
 export(geo_id_type)
+export(meta)
 export(sample_covariates)
 export(sample_info)
 export(sample_table)
+export(sources)
 import(checkmate)
 import(dplyr)
 import(purrr)

R/Archs4Repository.R

@@ -37,8 +37,8 @@ Archs4Repository <- function(datadir = getOption("archs4.datadir")) {
     sample_stats = bind_rows(gstats, tstats),
     sample_table = asi)
 
-  # We're going to make a "remote" or "service" version of the
-  # Archs4 data in due time ...
+  # You *know* we're going to make a "remote" or "service" version of an
+  # Archs4Repository, in due time ...
   class(out) <- c("LocalArchs4Repository", "Archs4Repository")
   out
 }
@@ -104,14 +104,12 @@ datadir <- function(x, ...) {
 #' @export
 #' @rdname archs4_feature_info
 #' @param x an `Archs4Repository`
-feature_info <- function(x, feature_type = c("gene", "transcript"),
-                         source = archs4_sources(),
-                         distinct_symbol = TRUE, augmented = TRUE, ...) {
+feature_info <- function(x, feature_type = "gene", source = "human",
+                         augmented = TRUE, ...) {
   assert_class(x, "Archs4Repository")
-  feature_type <- match.arg(feature_type)
-  source <- match.arg(source)
-  archs4_feature_info(feature_type, source, distinct_symbol, augmented,
-                      datadir(x), ...)
+  assert_choice(feature_type, c("gene", "transcript"))
+  assert_choice(source, sources(x))
+  archs4_feature_info(feature_type, source, augmented, datadir(x), ...)
 }
 
 #' @export

R/data-access.R → R/archs4-functional.R

@@ -1,3 +1,25 @@
+# These functions define a "high-level" interface to working with the data
+# downloaded into an ARCHS4 Data Directory. They are the workhorses of this
+# package.
+#
+# Although users can interact with the ARCHS4 data directory "directly" using
+# these functions, most will find it more convenient to interact with ARCHS4
+# using an `Archs4Repository`. Many of the functions here are also available
+# against an `Archs4Repository` object, and are named by stripping the archs4_
+# prefix here.
+#
+# For instance, the following are equivalent:
+#
+#     R> archs4_feature_info(datadir)
+#
+#   and
+#
+#     R> a4 <- Archs4Repository(datadir)
+#     R> feature_info(a4)
+#
+# Interacting with these data via the `Archs4Repository` should also better
+# future-proof your code.
+
 
 #' Retrieves the feature (gene/transcript) information for the archs4 data
 #'
@@ -18,15 +40,15 @@
 #' @param datadir the directory that stores the ARCHS4 data files
 #' @param ... pass through
 #' @return a tibble of information
-archs4_feature_info <- function(feature_type = c("gene", "transcript"),
-                                source = archs4_sources(), augmented = TRUE,
+archs4_feature_info <- function(feature_type = "gene", source = "human",
+                                augmented = TRUE,
                                 datadir = getOption("archs4.datadir"), ...) {
+  assert_choice(feature_type, c("gene", "transcript"))
+  assert_choice(source, archs4_sources(datadir))
   assert_flag(augmented)
-  feature_type <- match.arg(feature_type)
-  source <- match.arg(source)
 
-  h5.fn <- archs4_file_path(paste(source, feature_type, sep = "_"),
-                            datadir = datadir)
+  fkey <- paste(source, feature_type, sep = "_")
+  h5.fn <- archs4_file_path(fkey, datadir = datadir)
 
   if (feature_type == "gene") {
     # I am using `a4name` instead of symbol, because the values stored here
@@ -105,11 +127,10 @@ archs4_file_info <- function(datadir = getOption("archs4.datadir")) {
 #' upon lookup. To return the *expected* path to the, even if it does not
 #' exist on the file system, set `stop_if_missing = FALSE`.
 #'
-#'
 #' @export
 #'
 #' @param key the lookup key for the file, ie. `"human_gene"` or `"mouse_gene"`.
-#'   The known keys are enumerated in `archs4_file_info()[["key"]]`.
+#'   The known keys are enumerated in `archs4_file_info()$keyb`.
 #' @param stop_if_missing defaults to `TRUE`, which causes this function to
 #'   throw an error if the file does not exist at the expected `file_path`.
 #'   Set this to `FALSE` to simply raise a warning

tests/testthat/test-data-accessors.R → tests/testthat/test-archs4-functional.R

@@ -1,4 +1,4 @@
-context("Data Accessors")
+context("ARCHS4 Functional Interface")
 
 if (!exists("a4")) {
   # This is loaded by the testthat/helper-all.R script when testthat is running
@@ -11,17 +11,31 @@ test_that("feature-level metadata retrieval works", {
   # retrieve gene-level feature information with unique symbols
   mg <- feature_info(a4, feature_type = "gene", source = "mouse",
                      distinct_symbol = TRUE)
-  expect_true(all(substr(mg$ensembl_gene_id, 1, 7) == "ENSMUSG"))
+
+  # all a4name entries should be non NA and nchar() >= 1
+  expect_true(all(nchar(mg$a4name) >= 1))
+  expect_true(all(!is.na(mg$a4name)))
   expect_is(mg$h5idx, "integer")
   expect_true(all(!is.na(mg$h5idx)))
   # no duplicated symbols
   expect_equal(sum(duplicated(mg$symbol) & !is.na(mg$symbol)), 0)
 
+  # There are some entries that we couldn't get identifiers for, but the ones
+  # we got should all be prefixed with the mouse prefix.
+  mg.ens <- filter(mg, !is.na(gene_id))
+  expect_true(all(substr(mg.ens$gene_id, 1, 7) == "ENSMUSG"))
+
+
   hg <- feature_info(a4, feature_type = "gene", source = "human",
                      distinct_symbol = TRUE)
-  expect_true(all(substr(hg$ensembl_gene_id, 1, 4) == "ENSG"))
+  # all a4name entries should be non NA and nchar() >= 1
+  expect_true(all(nchar(hg$a4name) >= 1))
+  expect_true(all(!is.na(hg$a4name)))
   expect_is(hg$h5idx, "integer")
   expect_true(all(!is.na(hg$h5idx)))
   # no duplicated symbols
   expect_equal(sum(duplicated(hg$symbol) & !is.na(hg$symbol)), 0)
+
+  hg.ens <- filter(hg, !is.na(gene_id))
+  expect_true(all(substr(hg.ens$gene_id, 1, 4) == "ENSG"))
 })