Merge pull request #28 from AlexsLemonade/jashapiro/example-vignette

Add intro vignette

Author: jashapiro

.Rbuildignore

@@ -1,13 +1,17 @@
+^.claude$
 ^LICENSE\.md$
 ^ScPCAr\.Rproj$
 ^\.Rproj\.user$
 ^\.github$
 ^\.pre-commit-config\.yaml$
 ^_pkgdown\.yml$
 ^air\.toml$
+^claude.md$
 ^docs$
 ^pkgdown$
 ^renv$
 ^renv\.lock$
 ^scpca_data$
 ^typos.toml$
+^vignettes/articles$
+^vignettes/scpca_data$

.gitignore

@@ -52,3 +52,4 @@ po/*~
 rsconnect/
 .Rproj.user
 docs
+inst/doc

.pre-commit-config.yaml

@@ -23,7 +23,7 @@ repos:
     rev: v6.0.0
     hooks:
       - id: check-added-large-files
-        args: ["--maxkb=200"]
+        args: ["--maxkb=400"]
       - id: file-contents-sorter
         files: '^\.Rbuildignore$'
       - id: end-of-file-fixer

DESCRIPTION

@@ -15,10 +15,18 @@ Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
 Suggests:
+    devtools,
+    ggplot2,
+    here,
     httptest2,
+    knitr,
+    rmarkdown,
+    scater,
+    SingleCellExperiment,
     testthat (>= 3.2.0),
     withr
 Config/testthat/edition: 3
+VignetteBuilder: knitr
 Imports:
     curl,
     dplyr,
@@ -27,6 +35,7 @@ Imports:
     purrr,
     readr,
     stringr,
+    tibble,
     tidyr,
     utils
 URL: https://alexslemonade.github.io/ScPCAr/

NAMESPACE

@@ -8,6 +8,7 @@ export(get_project_libraries)
 export(get_project_samples)
 export(get_sample_info)
 export(scpca_projects)
+export(view_terms)
 import(httr2)
 importFrom(curl,curl_download)
 importFrom(dplyr,.data)

R/auth.R

@@ -1,5 +1,10 @@
 #' Get an authorization token from the ScPCA API
 #'
+#' `get_auth()` allows obtaining an authorization token string from the ScPCA API,
+#'  after providing an email address and agreeing to the terms of use.
+#'
+#' To view the terms of use before agreeing to them, use `view_terms()`, which opens the terms of use page in a web browser.
+#'
 #' @param email The user's email address
 #' @param agree A logical indicating whether the user agrees to the terms of service
 #'
@@ -10,7 +15,7 @@
 #' @examples
 #' \dontrun{
 #' # Get a token (make sure to agree to the terms of service)
-#' auth_token <- get_auth("me@email.net", agree = TRUE)
+#' auth_token <- get_auth("your.email@example.com", agree = TRUE)
 #' }
 #'
 #' @export
@@ -27,3 +32,17 @@ get_auth <- function(email, agree = FALSE) {
 
   response$id
 }
+
+
+#' View Terms of Use
+#' @export
+#' @rdname get_auth
+#' @examples
+#' \dontrun{
+#' view_terms()
+#' }
+view_terms <- function() {
+  url <- "https://scpca.alexslemonade.org/terms-of-use"
+  utils::browseURL(url)
+  invisible(url)
+}

R/downloads.R

@@ -78,7 +78,7 @@ validate_format <- function(format) {
 #' @examples
 #' \dontrun{
 #' # Get a token first
-#' auth_token <- get_auth("me@email.net", agree = TRUE)
+#' auth_token <- get_auth("your.email@example.com", agree = TRUE)
 #' # Then ask for a sample download
 #' download_sample("SCPCS000001", auth_token, destination = "scpca_data", format = "sce")
 #'
@@ -105,7 +105,7 @@ download_sample <- function(
   if (!dir.exists(destination)) {
     dir.create(destination, recursive = TRUE)
   }
-  sample_info <- get_sample_info(sample_id)
+  sample_info <- get_sample_info(sample_id, simplifyVector = FALSE)
 
   file_ids <- get_computed_file_ids(sample_info, filters = computed_files_filter(format_str))
 
@@ -175,7 +175,7 @@ download_sample <- function(
 #'
 #' \dontrun{
 #' # Get a token first
-#' auth_token <- get_auth("me@email.net", agree = TRUE)
+#' auth_token <- get_auth("your.email@example.com", agree = TRUE)
 #' # Then ask for a sample download
 #' download_project("SCPCS000001", auth_token, destination = "scpca_data", format = "sce")
 #'
@@ -218,7 +218,7 @@ download_project <- function(
     dir.create(destination, recursive = TRUE)
   }
 
-  project_info <- get_project_info(project_id)
+  project_info <- get_project_info(project_id, simplifyVector = FALSE)
 
   # default to include multiplexed for SCE, not for others (where they are not available)
   if (is.null(include_multiplexed)) {
@@ -289,8 +289,8 @@ download_and_extract_file <- function(url, parent_dir, overwrite, redownload, qu
       "Directory {destination_dir} already exists; skipping download.",
       "\nUse 'overwrite = TRUE' to replace existing files."
     ))
-    # no files downloaded, return empty vector
-    return(c())
+    # return contents of the existing directory
+    return(list.files(destination_dir, full.names = TRUE, recursive = TRUE))
   }
 
   # check for existing directory with same base name (without date)

R/projects.R

@@ -10,7 +10,7 @@
 #' @param simplify A logical indicating whether to simplify the resulting data frame
 #'  by removing list columns. Default is TRUE.
 #'
-#' @returns a data frame of project information from the ScPCA API.
+#' @returns a data frame (tibble) of project information from the ScPCA API.
 #'
 #' @import httr2
 #' @importFrom dplyr .data
@@ -47,17 +47,22 @@ scpca_projects <- function(simplify = TRUE) {
       created_at = as.POSIXct(.data$created_at),
       updated_at = as.POSIXct(.data$updated_at)
     ) |>
-    dplyr::relocate(scpca_project_id = "scpca_id")
+    dplyr::relocate(
+      scpca_project_id = "scpca_id",
+      "sample_count",
+      "title",
+      "pi_name"
+    )
 
-  project_df
+  tibble::as_tibble(project_df)
 }
 
 #' Get project metadata by project ID
 #'
 #' @param project_id The ScPCA project ID (e.g. "SCPCP000001")
 #' @param simplifyVector Simplify the returned list structure,
 #'  creating vectors and data frames instead of lists when possible.
-#'  Default is FALSE.
+#'  Default is TRUE.
 #'
 #' @returns A nested list of project metadata from the ScPCA API.
 #'
@@ -69,7 +74,7 @@ scpca_projects <- function(simplify = TRUE) {
 #' # Get metadata for a specific project
 #' project_info <- get_project_info("SCPCP000001")
 #' }
-get_project_info <- function(project_id, simplifyVector = FALSE) {
+get_project_info <- function(project_id, simplifyVector = TRUE) {
   stopifnot(
     "Invalid project_id." = grepl("^SCPCP\\d{6}$", project_id)
   )
@@ -102,7 +107,7 @@ get_project_info <- function(project_id, simplifyVector = FALSE) {
 #' @param simplify A logical indicating whether to simplify the resulting data frame
 #'  by removing list columns. Default is TRUE.
 #'
-#' @returns A data frame of sample information for the specified project from the ScPCA API.
+#' @returns A data frame (tibble) of sample information for the specified project from the ScPCA API.
 #'
 #' @import httr2
 #' @importFrom dplyr .data
@@ -137,9 +142,12 @@ get_project_samples <- function(project_id, simplify = TRUE) {
       created_at = as.POSIXct(.data$created_at),
       updated_at = as.POSIXct(.data$updated_at)
     ) |>
-    dplyr::relocate(scpca_sample_id = "scpca_id", scpca_project_id = "project")
+    dplyr::relocate(
+      scpca_sample_id = "scpca_id",
+      scpca_project_id = "project"
+    )
 
-  sample_df
+  tibble::as_tibble(sample_df)
 }
 
 
@@ -200,7 +208,7 @@ get_project_libraries <- function(project_id, auth_token) {
   is_cols <- stringr::str_subset(colnames(library_metadata), "^(is|has|includes)_")
   library_metadata <- library_metadata |>
     dplyr::mutate(dplyr::across(dplyr::all_of(is_cols), as.logical))
-  library_metadata
+  tibble::as_tibble(library_metadata)
 }
 
 

R/samples.R

@@ -3,7 +3,7 @@
 #' @param sample_id The ScPCA sample ID (e.g. "SCPCS000001")
 #' @param simplifyVector Simplify the returned list structure,
 #'  creating vectors and data frames instead of lists when possible.
-#'  Default is FALSE.
+#'  Default is TRUE.
 #'
 #' @returns A nested list of sample metadata from the ScPCA API.
 #'
@@ -15,7 +15,7 @@
 #' # Get metadata for a specific sample
 #' sample_info <- get_sample_info("SCPCS000001")
 #' }
-get_sample_info <- function(sample_id, simplifyVector = FALSE) {
+get_sample_info <- function(sample_id, simplifyVector = TRUE) {
   stopifnot(
     "Invalid sample_id" = grepl("^SCPCS\\d{6}$", sample_id)
   )

ScPCAr.Rproj

@@ -5,8 +5,13 @@ SaveWorkspace: No
 AlwaysSaveHistory: Default
 
 EnableCodeIndexing: Yes
+UseSpacesForTab: Yes
+NumSpacesForTab: 2
 Encoding: UTF-8
 
+RnwWeave: Sweave
+LaTeX: pdfLaTeX
+
 AutoAppendNewline: Yes
 StripTrailingWhitespace: Yes
 LineEndingConversion: Posix