Verbose, argument naming... (#17)

* up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * Update documents * update docs * up * up * up * preserve old behavior and functions * up * up * Remove things causing errors and warnings in build check * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * up * verbose * up
EBI-Metagenomics · Mar 21, 2023 · 09cee88 · 09cee88
1 parent 43aee51
commit 09cee88
Show file tree

Hide file tree

Showing 18 changed files with 196 additions and 132 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -52,5 +52,5 @@ Collate:
     'getFile.R'
     'getMetadata.R'
     'utils.R'
-    'getResults.R'
+    'getResult.R'
     'searchAnalysis.R'
diff --git a/NAMESPACE b/NAMESPACE
@@ -4,7 +4,7 @@ export(MgnifyClient)
 export(doQuery)
 export(getFile)
 export(getMetadata)
-export(getResults)
+export(getResult)
 export(mgnify_analyses_from_samples)
 export(mgnify_analyses_from_studies)
 export(mgnify_client)
@@ -20,7 +20,7 @@ export(searchFile)
 exportMethods(doQuery)
 exportMethods(getFile)
 exportMethods(getMetadata)
-exportMethods(getResults)
+exportMethods(getResult)
 exportMethods(searchAnalysis)
 exportMethods(searchFile)
 import(MultiAssayExperiment)

diff --git a/R/MgnifyClient.R b/R/MgnifyClient.R
@@ -52,12 +52,12 @@ MgnifyClient <- setClass(
 #' @param password A single character value specifying an optional password for
 #' authentication. (By default: \code{password = NULL})
 #'
-#' @param use.cache A single boolean value specifying whether to enable on-disk
+#' @param useCache A single boolean value specifying whether to enable on-disk
 #' caching of results during this session. In most use cases should be TRUE.
-#' (By default: \code{use.cache = FALSE})
+#' (By default: \code{useCache = FALSE})
 #'
-#' @param cache.dir A single character value specifying a folder to contain the
-#' local cache. If NULL, and use.cache is TRUE, the new subdirectory
+#' @param cacheDir A single character value specifying a folder to contain the
+#' local cache. If NULL, and useCache is TRUE, the new subdirectory
 #' \code{.MGnifyR_cache} in the current working directory will be used. Note
 #' that cached files are persistent, so the cache directory may be reused
 #' between sessions, taking advantage of previously downloaded results. The
@@ -68,14 +68,14 @@ MgnifyClient <- setClass(
 #' output during invocation of some MGnifyR functions.
 #' (By default: \code{warnings = FALSE})
 #'
-#' @param use.memcache A single boolean value specifying whether to indicate
+#' @param useMemCache A single boolean value specifying whether to indicate
 #' whether functional results obtained when \code{bulk_dl} is \code{TRUE}
 #' in \code{mgnify_get_analyses_results} should be stored in an in-memory
 #' cache, rather than the cached input being re-read for each accession. this
 #' is currently NOT working properly and should therefore be set \code{FALSE}.
 #' It has the potential to speed up searches considerably though, especially
 #' for studies with a large number of samples, so will be implemented properly
-#' in the future. (By default: \code{use.memcache = FALSE})
+#' in the future. (By default: \code{useMemCache = FALSE})
 #'
 #' @param ... optional arguments:
 #' \itemize{
@@ -90,7 +90,7 @@ MgnifyClient <- setClass(
 #' \dontrun{
 #' my_client <- MgnifyClient(
 #'     username = "Webin-1122334", password = "SecretPassword",
-#'     use.cache = TRUE, cache.dir = "/scratch/MGnify_cache_location"
+#'     useCache = TRUE, cacheDir = "/scratch/MGnify_cache_location"
 #'     )
 #'}
 #'
@@ -101,8 +101,8 @@ NULL
 #' @importFrom methods new
 #' @export
 MgnifyClient <- function(
-        username = NULL, password = NULL, use.cache = FALSE, cache.dir = NULL,
-        warnings = FALSE, use.memcache = FALSE, ...){
+        username = NULL, password = NULL, useCache = FALSE, cacheDir = NULL,
+        warnings = FALSE, useMemCache = FALSE, ...){
     ############################### INPUT CHECK ################################
     if( !(is.null(username) || .is_non_empty_string(username)) ){
         stop("'username' must be NULL or single character value specifying ",
@@ -112,16 +112,16 @@ MgnifyClient <- function(
         stop("'password' must be NULL or single character value specifying ",
              "the password.", call. = FALSE)
     }
-    if( !.is_a_bool(use.cache) ){
-        stop("'use.cache' must be a boolean value specifying whether to use ",
+    if( !.is_a_bool(useCache) ){
+        stop("'useCache' must be a boolean value specifying whether to use ",
              "on-disk caching.", call. = FALSE)
     }
-    if( !(is.null(cache.dir) || .is_non_empty_string(cache.dir)) ){
-        stop("'cache.dir' must be NULL or single character value specifying ",
+    if( !(is.null(cacheDir) || .is_non_empty_string(cacheDir)) ){
+        stop("'cacheDir' must be NULL or single character value specifying ",
              "the the directory for cache.", call. = FALSE)
     }
-    if( !.is_a_bool(use.memcache) ){
-        stop("'use.memcache' must be a boolean value specifying whether use ",
+    if( !.is_a_bool(useMemCache) ){
+        stop("'useMemCache' must be a boolean value specifying whether use ",
              "on-disk memory.", call. = FALSE)
     }
     ############################# INPUT CHECK END ##############################
@@ -148,19 +148,19 @@ MgnifyClient <- function(
     # Assume we're not using it
     cachepath <- NA_character_
     # If user has specified that on-disk cache will be used
-    if(use.cache){
-        if (is.null(cache.dir) ){
+    if(useCache){
+        if (is.null(cacheDir) ){
             cachepath <- paste(getwd(), ".MGnifyR_cache", sep = "/")
         } else{
-            cachepath <- cache.dir
+            cachepath <- cacheDir
         }
         # Make it if needed - assume the user is sensible and the path will work...
         dir.create(cachepath, showWarnings = FALSE)
     }
     # Return the final object
     obj <- new("MgnifyClient", url = url, authTok = authtok,
                cacheDir = cachepath, warnings = warnings, memCache = list(),
-               useMemCache = use.memcache)
+               useMemCache = useMemCache)
     return(obj)
 }
 

diff --git a/R/deprecate.R b/R/deprecate.R
@@ -65,8 +65,8 @@ mgnify_client <- function(
     .Deprecated("MgnifyClient")
     MgnifyClient(url = url,
                  username = username, password = password,
-                 use.cache = usecache, cache.dir = cache_dir, warnings = warnings,
-                 use.memcache = use_memcache)
+                 useCache = usecache, cacheDir = cache_dir, warnings = warnings,
+                 useMemCache = use_memcache)
 }
 
 #' @rdname deprecate
@@ -126,11 +126,11 @@ mgnify_download <- function(
 mgnify_get_analyses_results <- function(
         client=NULL, accessions, retrievelist = c(), compact_results = TRUE,
         usecache = TRUE, bulk_dl = FALSE, ...){
-    .Deprecated("getResults")
+    .Deprecated("getResult")
     if( length(retrievelist) == 0 ){
         retrievelist <- FALSE
     }
-    getResults(
+    getResult(
         x = client, accession = accessions, get.taxa = FALSE,
         get.func = retrievelist, output = "list", usecache = TRUE,
         as.df = compact_results, ...)
@@ -141,9 +141,9 @@ mgnify_get_analyses_results <- function(
 mgnify_get_analyses_phyloseq <- function(
         client = NULL, accessions, usecache = TRUE, returnLists = FALSE,
         tax_SU = "SSU", get_tree = FALSE, ...){
-    .Deprecated("getResults")
+    .Deprecated("getResult")
     output <- ifelse(returnLists, "list", "phyloseq")
-    getResults(
+    getResult(
         x = client, accession = accessions, get.taxa = TRUE, get.func = FALSE,
         output = output, use.cache = usecache, tax.su = tax_SU,
         get.tree = get_tree, ...

diff --git a/R/getFile.R b/R/getFile.R
@@ -139,6 +139,9 @@ setMethod("getFile", signature = c(x = "MgnifyClient"), function(
 #' @param use.cache A single boolean value specifying whether to use the
 #' on-disk cache to speed up queries. (By default: \code{use.cache = TRUE})
 #'
+#' @param verbose A single boolean value to specify whether to show
+#' the progress bar. (By default: \code{verbose = TRUE})
+#'
 #' @return \code{data.frame} containing all discovered downloads. If
 #' multiple \code{accessions} are queried, the \code{accessions} column
 #' may to filter the results - since rownames are not set (and wouldn;'t
@@ -168,7 +171,7 @@ NULL
 setGeneric("searchFile", signature = c("x"), function(
         x, accession, type = c("studies", "samples", "analyses", "assembly",
                                  "genome", "run"),
-        use.cache = TRUE, ...
+        use.cache = TRUE, verbose = TRUE, ...
         )
     standardGeneric("searchFile"))
 
@@ -177,7 +180,7 @@ setGeneric("searchFile", signature = c("x"), function(
 setMethod("searchFile", signature = c(x = "MgnifyClient"), function(
         x, accession, type = c("studies", "samples", "analyses", "assembly",
                                 "genome", "run"),
-        use.cache = TRUE, ...
+        use.cache = TRUE, verbose = TRUE, ...
         ){
     ############################### INPUT CHECK ################################
     if( !.is_non_empty_character(accession) ){
@@ -194,10 +197,16 @@ setMethod("searchFile", signature = c(x = "MgnifyClient"), function(
         stop("'use.cache' must be a single boolean value specifying whether to ",
              "use on-disk caching.", call. = FALSE)
     }
+    if( !.is_a_bool(verbose) ){
+        stop("'verbose' must be a single boolean value specifying whether to ",
+             "show progress.", call. = FALSE)
+    }
+    verbose <- ifelse(verbose, "text", "none")
     ############################# INPUT CHECK END ##############################
     # Get file urls
     result <- .mgnify_get_download_urls(
-        client = x, accession = accession, type = type, use.cache = use.cache)
+        client = x, accession = accession, type = type, use.cache = use.cache,
+        verbose = verbose)
     return(result)
 })
 
@@ -263,7 +272,8 @@ setMethod("searchFile", signature = c(x = "MgnifyClient"), function(
     result
 }
 
-.mgnify_get_download_urls <- function(client, accession, type, use.cache){
+.mgnify_get_download_urls <- function(
+        client, accession, type, use.cache, verbose){
     results <- llply(accession, function(x){
         download_list <- .mgnify_retrieve_json(
             client, paste(type,x,"downloads", sep="/"), use.cache = use.cache)
@@ -287,6 +297,6 @@ setMethod("searchFile", signature = c(x = "MgnifyClient"), function(
             df$download_url <- urls
         }
         df
-    }, .progress="text")
+    }, .progress = verbose)
     do.call(rbind.fill, results)
 }
diff --git a/R/getMetadata.R b/R/getMetadata.R
@@ -13,11 +13,14 @@
 #' @param use.cache A single boolean value specifying whether to use the disk
 #' based cache. (By default: \code{use.cache = TRUE})
 #'
-#' @return \code{data.frame} of metadata for each analysis in the
-#' \code{accession} list.
+#' @param verbose A single boolean value to specify whether to show
+#' the progress bar. (By default: \code{verbose = TRUE})
 #'
 #' @param ... Optional arguments; not currently used.
 #'
+#' @return \code{data.frame} of metadata for each analysis in the
+#' \code{accession} list.
+#'
 #' @examples
 #' \dontrun{
 #' # Download all associated study/sample and analysis metadata
@@ -35,15 +38,15 @@ NULL
 #' @importFrom dplyr bind_rows
 #' @export
 setGeneric("getMetadata", signature = c("x"), function(
-        x, accession, use.cache = TRUE,
+        x, accession, use.cache = TRUE, verbose = TRUE,
         ...
 )
     standardGeneric("getMetadata"))
 
 #' @rdname getMetadata
 #' @export
 setMethod("getMetadata", signature = c(x = "MgnifyClient"), function(
-        x, accession, use.cache = TRUE,
+        x, accession, use.cache = TRUE, verbose = TRUE,
         ...){
     ############################### INPUT CHECK ################################
     if( !is.character(accession) ){
@@ -54,18 +57,25 @@ setMethod("getMetadata", signature = c(x = "MgnifyClient"), function(
         stop("'use.cache' must be a boolean value specifying whether to use ",
              "on-disk caching.", call. = FALSE)
     }
+    if( !.is_a_bool(verbose) ){
+        stop("'verbose' must be a single boolean value specifying whether to ",
+             "show progress.", call. = FALSE)
+    }
+    verbose <- ifelse(verbose, "text", "none")
     ############################# INPUT CHECK END ##############################
     # Get metadata
     result <- .mgnify_get_analyses_metadata(
-        client = x, accession = accession, use.cache = use.cache)
+        client = x, accession = accession, use.cache = use.cache,
+        verbose = verbose)
     return(result)
 })
 
 ################################ HELP FUNCTIONS ################################
 
-.mgnify_get_analyses_metadata <- function(client, accession, use.cache){
+.mgnify_get_analyses_metadata <- function(
+        client, accession, use.cache, verbose){
     # TODO: Chnage to biocparallel?
-    reslist <- llply(as.list(accession), .progress = "text", function(x){
+    reslist <- llply(as.list(accession), .progress = verbose, function(x){
         .mgnify_get_single_analysis_metadata(client, x, use.cache = use.cache)
     })
     df <- do.call(bind_rows, reslist)