From 93b315945127edb4c514c779d74fcc9a52615b5a Mon Sep 17 00:00:00 2001
From: rmgpanw <rmgpanw@ucl.ac.uk>
Date: Fri, 21 Jun 2024 09:17:00 +0100
Subject: [PATCH] update get_downloads_page_data() and add test

---
 R/get_downloads_page_data.R                   | 70 +++++++++++++++----
 man/get_downloads_page_data.Rd                | 34 +++++++--
 tests/testthat/test-get_downloads_page_data.R | 13 ++++
 3 files changed, 99 insertions(+), 18 deletions(-)
 create mode 100644 tests/testthat/test-get_downloads_page_data.R

diff --git a/R/get_downloads_page_data.R b/R/get_downloads_page_data.R
index 1c3617c..f885a89 100644
--- a/R/get_downloads_page_data.R
+++ b/R/get_downloads_page_data.R
@@ -1,22 +1,64 @@
-#'Get Downloads Page Data
+#' Get Downloads Page Data
 #'
-#'@description
-#' - Retrieves all the files belonging to the given project_id for display on the Downloads Page
+#' @description Retrieves all the files belonging to the given `project_id` for
+#' display on the `Downloads Page`
 #'
-#'[GTEx Portal API
-#'documentation](https://gtexportal.org/api/v2/redoc#tag/Datasets-Endpoints/operation/get_downloads_page_data_api_v2_dataset_openAccessFilesMetadata_get)
+#' [GTEx Portal API
+#' documentation](https://gtexportal.org/api/v2/redoc#tag/Datasets-Endpoints/operation/get_downloads_page_data_api_v2_dataset_openAccessFilesMetadata_get)
 #'
-#'@inheritParams gtexr_arguments
+#' @details Note: The GTEx Portal API documentation states "GTEx currently has
+#' one project available: gtex". However, `project_id` values "adult-gtex" and
+#' "egtex" both return results, whereas "gtex" does not (see examples).
 #'
-#'@return A Tibble
-#'@export
-#'@family Datasets Endpoints
+#' @inheritParams gtexr_arguments
+#'
+#' @return A Tibble
+#' @export
+#' @family Datasets Endpoints
 #'
 #' @examples
-#' get_downloads_page_data()
+#' \dontrun{
+#'  # "adult-gtex" (default `project_id` value) and "egtex" both return results
+#'  get_downloads_page_data()
+#'  egtex <- get_downloads_page_data("egtex")
+#'  egtex
+#'
+#'  # ..."gtex" does not
+#'  get_downloads_page_data("gtex")
+#'
+#'  # get details for whole blood methylation data, including download URL
+#'  purrr::pluck(
+#'    egtex$children,
+#'    1,
+#'    "folders",
+#'    "Methylation - EPIC Array",
+#'    "children",
+#'    "folders",
+#'    "mQTLs",
+#'    "children",
+#'    "files",
+#'    "WholeBlood.mQTLs.regular.txt.gz"
+#'  )
+#' }
 get_downloads_page_data <- function(project_id = "adult-gtex") {
-  gtex_query(endpoint = "dataset/openAccessFilesMetadata",
-             return_raw = TRUE)$data |>
-    purrr::map(tibble::as_tibble) |>
-    dplyr::bind_rows()
+  result <- gtex_query(endpoint = "dataset/openAccessFilesMetadata",
+             return_raw = TRUE)
+
+  result |>
+    purrr::map(name_unnamed_items, name_item = "displayName") |>
+    tibble::as_tibble() |>
+    tidyr::unnest_wider("data") |>
+    dplyr::arrange(dplyr::pick(dplyr::any_of("order")))
+}
+
+name_unnamed_items <- function(x, name_item) {
+
+  if (inherits(x, "list")) {
+    if (is.null(names(x))) {
+      names(x) <- purrr::map_chr(x, \(item) item[[name_item]])
+    }
+    x <- purrr::map(x, name_unnamed_items, name_item = name_item)
+  }
+
+  return(x)
 }
diff --git a/man/get_downloads_page_data.Rd b/man/get_downloads_page_data.Rd
index 64992f9..d23f0b7 100644
--- a/man/get_downloads_page_data.Rd
+++ b/man/get_downloads_page_data.Rd
@@ -13,14 +13,40 @@ get_downloads_page_data(project_id = "adult-gtex")
 A Tibble
 }
 \description{
-\itemize{
-\item Retrieves all the files belonging to the given project_id for display on the Downloads Page
-}
+Retrieves all the files belonging to the given \code{project_id} for
+display on the \verb{Downloads Page}
 
 \href{https://gtexportal.org/api/v2/redoc#tag/Datasets-Endpoints/operation/get_downloads_page_data_api_v2_dataset_openAccessFilesMetadata_get}{GTEx Portal API documentation}
 }
+\details{
+Note: The GTEx Portal API documentation states "GTEx currently has
+one project available: gtex". However, \code{project_id} values "adult-gtex" and
+"egtex" both return results, whereas "gtex" does not (see examples).
+}
 \examples{
-get_downloads_page_data()
+\dontrun{
+ # "adult-gtex" (default `project_id` value) and "egtex" both return results
+ get_downloads_page_data()
+ egtex <- get_downloads_page_data("egtex")
+ egtex
+
+ # ..."gtex" does not
+ get_downloads_page_data("gtex")
+
+ # get details for whole blood methylation data, including download URL
+ purrr::pluck(
+   egtex$children,
+   1,
+   "folders",
+   "Methylation - EPIC Array",
+   "children",
+   "folders",
+   "mQTLs",
+   "children",
+   "files",
+   "WholeBlood.mQTLs.regular.txt.gz"
+ )
+}
 }
 \seealso{
 Other Datasets Endpoints: 
diff --git a/tests/testthat/test-get_downloads_page_data.R b/tests/testthat/test-get_downloads_page_data.R
new file mode 100644
index 0000000..84a8175
--- /dev/null
+++ b/tests/testthat/test-get_downloads_page_data.R
@@ -0,0 +1,13 @@
+test_that(
+  "`get_downloads_page_data()` runs without error for `project_id` = 'gtex' (which returns no results)",
+  {
+    expect_equal(
+      with_mocked_bindings(
+        code = get_downloads_page_data("gtex"),
+        gtex_query = function(...)
+          list(data = list())
+      ),
+      tibble::tibble()
+    )
+  }
+)