Merge pull request #97 from CenterForOpenScience/dev

v0.2.4

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: osfr
 Title: R Interface to OSF
-Version: 0.2.3
+Version: 0.2.4
 Authors@R: c(
     person("Aaron", "Wolen",, "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0003-2542-2202")),

NEWS.md

@@ -1,3 +1,13 @@
+# osfr 0.2.4
+
+## Minor fixes
+
+* Listing files within a specified `path` would fail if sibling directories
+shared a common substring in their names (#95)
+* Setting `verbose=TRUE` now works properly for `osf_upload()`
+* A startup message is printed when `OSF_SERVER` is defined
+* Improved documentation for `n_max`, GUIDs and the mysterious `meta` column
+
 # osfr 0.2.3
 
 ## New features

R/osf_ls_files.R

@@ -13,7 +13,8 @@
 #' @template n_max
 #' @template verbose
 #'
-#' @return An [`osf_tbl_file`] with one row for each file or directory.
+#' @return An [`osf_tbl_file`] with one row for each file or directory, ordered
+#'   by modification time.
 #' @examples
 #' \dontrun{
 #' # Retrieve the Psychology Reproducibility Project from OSF

R/osf_ls_nodes.R

@@ -10,7 +10,8 @@
 #' @template n_max
 #' @template verbose
 #'
-#' @return An [`osf_tbl_node`] with one row for each OSF project or component.
+#' @return An [`osf_tbl_node`] with one row for each OSF project or component,
+#'   ordered by modification time.
 #' @examples
 #' \dontrun{
 #' # List your recent projects and components

R/osf_mkdir.R

@@ -84,6 +84,9 @@ recurse_path <- function(x, path, missing_action = "error", verbose = FALSE) {
   path_root <- fs::path_split(path)[[1]][1]
   root_dir <- osf_ls_files(x, type = "folder", pattern = path_root)
 
+  # ensure the retrieved directory and path_root have the same name
+  root_dir <- root_dir[root_dir$name == path_root, ]
+
   if (nrow(root_dir) == 0) {
     if (missing_action == "error") {
       abort(sprintf("Can't find directory '%s' in `%s`", path_root, x$name))

R/osf_retrieve.R

@@ -1,13 +1,30 @@
 #' Retrieve an entity from OSF
 #'
-#' Create an [`osf_tbl`] for an existing OSF project, component, file, or user
-#' based on the associated unique identifier. Usually this is a 5-character
-#' global unique identifier (GUID) but for files or directories, it could also
-#' be a 24-character Waterbutler ID.
+#' Create an [`osf_tbl`] representation of an existing OSF project, component,
+#' file, or user based on the associated unique identifier. Usually this is a
+#' 5-character global unique identifier (GUID) but for files or directories, it
+#' could also be an 11-character Waterbutler ID. See below for details.
 #'
+#' @section OSF identifiers: A 5-character GUID is assigned to every user,
+#'   project, component, and file on OSF and forms the basis for the service's
+#'   URL scheme. For example the GUID for a project accessible at
+#'   <https://osf.io/ezum7> is simply `ezum7`. You can learn more about GUIDs
+#'   [here](http://help.osf.io/m/faqs/l/726460-faqs#what-s-a-globally-unique-identifier-guid-what-metadata-is-maintained-about-them).
+#'
+#' An important detail is that files and directories are handled internally on
+#' OSF by another serviced called [Waterbutler](http://www.waterbutler.io/),
+#' which uses 11-character identifiers. Although Waterbutler IDs are largely
+#' hidden from users on <https://osf.io>, they represent the primary method for
+#' identifying files/directories by the OSF API. In fact, files do not receive a
+#' GUID until it is viewed directly on <https://osf.io> and directories never
+#' receive a GUID. Therefore, osfr relies on Waterbutler IDs for files and
+#' directories, and always includes them (rather than GUIDs) in [`osf_tbl_file`]
+#' objects.
+#'
+#' @section Retrieving OSF objects:
 #' To begin using osfr to interact with resources on OSF you must use one of the
 #' following *retrieve* functions to create an [`osf_tbl`] that contains
-#' the entity interest. Note the functions are entity-type specific, use:
+#' the entity of interest. Note the functions are entity-type specific, use:
 #' * `osf_retrieve_node()` to retrieve a project or component
 #' * `osf_retrieve_file()` to retrieve a file or directory
 #' * `osf_retrieve_user()` to retrieve a user

R/osf_tbl.R

@@ -4,17 +4,14 @@
 #' data frames based on the [tibble][tibble::tibble-package] class. See below
 #' for additional details.
 #'
-#' Each row of an `osf_tbl` represents a single OSF entity, which could be a
+#' Each row of an `osf_tbl` represents a single OSF entity. This could be a
 #' user, project, component, directory, or file. An `osf_tbl` must include
-#' the following 3 variables:
+#' the following 3 columns:
 #'
-#' 1. `name`: the name or title of the entity.
-#' 2. `id`: the unique identifier assigned to the entity.
+#' 1. `name`: indicates the name or title of the entity.
+#' 2. `id`: the unique identifier assigned by OSF.
 #' 3. `meta`: a list-column that stores the processed response returned by OSF's
-#' API.
-#'
-#' The `meta` column is primarily intended for use by `osfr`'s functions and
-#' should not be altered by users.
+#'    API. See the *Meta column* section below for more information.
 #'
 #' @section Subclasses:
 #'
@@ -33,6 +30,22 @@
 #' project or component). Because projects and components are functionally
 #' identical, osfr uses the same [`osf_tbl_node`] class to represent both.
 #'
+#' @section Meta column:
+#'
+#' The `meta` column contains all of the information returned from OSF's API for
+#' a single entity, structed as a named list with 3 elements:
+#'
+#' 1. `attributes` contains metadata about the entity (e.g., names,
+#'    descriptions, tags, etc).
+#' 2. `links` contains urls to API endpoints with alternative representations of
+#'    the entity or actions that may be performed on the entity.
+#' 3. `relationships` contains URLs to other entities with relationships to the
+#'    entity (e.g., collaborators attached to a project).
+#'
+#' This information is critical for `osfr`'s internal functions and should not
+#' be altered by users. For even more information about these elements, see
+#' [OSF's API documentation](https://developer.osf.io/#tag/Entities-and-Entity-Collections).
+#'
 #' @section Acknowledgments:
 #'
 #' Our implementation of the `osf_tbl` class is based on `dribble` objects from
@@ -71,6 +84,9 @@ as_osf_tbl.list <- function(x, subclass = NULL) {
   # handle empty lists returned by e.g. .osf_node_children() for childless nodes
   if (rlang::is_empty(x)) return(osf_tbl(subclass = subclass))
 
+  # remove 'data' name that otherwise remains only w/ singleton entities
+  x <- unname(x)
+
   name_field <- switch(subclass,
     osf_tbl_node = "title",
     osf_tbl_file = "name",

R/osf_upload.R

@@ -68,9 +68,9 @@ osf_upload.osf_tbl_node <-
   osf_file <- items[items$name == name, ]
 
   if (nrow(osf_file) == 0) {
-    out <- upload_file(as_id(x), path, name)
+    out <- upload_file(as_id(x), path, name, verbose = verbose)
   } else {
-    out <- update_file(as_id(x), path, as_id(osf_file), overwrite)
+    out <- update_file(as_id(x), path, as_id(osf_file), overwrite, verbose)
   }
 
   as_osf_tbl(out["data"], "osf_tbl_file")

R/zzz.R

@@ -24,4 +24,11 @@
   if (!is.null(getOption("osfr.pat"))) {
     packageStartupMessage("Automatically registered OSF personal access token")
   }
+
+  server <- Sys.getenv("OSF_SERVER")
+  if (nzchar(server)) {
+    packageStartupMessage(
+      sprintf("<Testing server enabled: %s.osf.io>", tolower(server))
+    )
+  }
 }

README.Rmd

@@ -47,7 +47,9 @@ remotes::install_github("centerforopenscience/osfr")
 
 Many researchers use OSF to archive and share their work. You can use osfr to explore publicly accessible projects and download the associated files---all you need to get started is the project's URL or GUID (global unique identifier).
 
-Here we'll retrieve the main project for the Cancer Reproducibility Project (<https://osf.io/e81xl/>).
+Every user, project, component, and file on OSF is assigned a GUID that is embedded in the corresponding entity's URL. For example, you can access the main OSF project for the *Cancer Reproducibility Project* at <https://osf.io/e81xl/>. The GUID for this project is `e81xl`.
+
+We can then use osfr to *retrieve* this project and load it into R by providing the GUID:
 
 ```{r message=FALSE}
 library(osfr)
@@ -82,11 +84,17 @@ cr_project %>%
   osf_ls_files()
 ```
 
-We could continue this pattern of exploration and even download local copies of project files using `osf_download()`.
+We could continue this pattern of exploration and even download local copies of project files using `osf_download()`. Or, if you come across a publication that  directly references a file's OSF URL, you could quickly download it to your project directory by providing the URL or simply the GUID:
+
+```{r}
+osf_retrieve_file("https://osf.io/btgx3/") %>% 
+  osf_download()
+```
+
 
 ### Managing Projects
 
-You can use osfr to create projects, add sub-components or directories, and upload files. See the [Getting Started vignette][getting-started] to learn more about building projects with osfr, but here is a quick example in which we:
+You can use osfr to [create projects][osf-create], [add sub-components][osf-create] or [directories][osf-mkdir], and [upload files][osf-upload]. See [Getting Started][getting-started] to learn more about building projects with osfr, but here is a quick example in which we:
 
 1. Create a new project called *Motor Trend Car Road Tests*
 2. Create a sub-component called *Car Data*
@@ -129,6 +137,10 @@ Big thanks to Rusty Speidel for designing our logo and [Tim Errington][tim] for
 
 Check out the [Contributing Guidelines](.github/CONTRIBUTING.md) to get started with osfr development and note that by contributing to this project, you agree to abide by the terms outlined in the [Contributor Code of Conduct](.github/CODE_OF_CONDUCT.md).
 
+```{r cleanup, include=FALSE}
+unlink("Study_19_Figure_1.pdf")
+```
+
 <!-- links -->
 [osf]: https://osf.io "Open Science Framework"
 [cos]: https://cos.io "Center for Open Science"
@@ -153,3 +165,6 @@ Check out the [Contributing Guidelines](.github/CONTRIBUTING.md) to get started
 [getting-started]: http://centerforopenscience.github.io/osfr/articles/getting_started.html
 [auth]: http://centerforopenscience.github.io/osfr/articles/auth.html
 
+[osf-create]: https://centerforopenscience.github.io/osfr/reference/osf_create.html
+[osf-mkdir]: https://centerforopenscience.github.io/osfr/reference/osf_mkdir.html
+[osf-upload]: https://centerforopenscience.github.io/osfr/reference/osf_upload.html

README.md

@@ -50,8 +50,13 @@ osfr to explore publicly accessible projects and download the associated
 files—all you need to get started is the project’s URL or GUID (global
 unique identifier).
 
-Here we’ll retrieve the main project for the Cancer Reproducibility
-Project (<https://osf.io/e81xl/>).
+Every user, project, component, and file on OSF is assigned a GUID that
+is embedded in the corresponding entity’s URL. For example, you can
+access the main OSF project for the *Cancer Reproducibility Project* at
+<https://osf.io/e81xl/>. The GUID for this project is `e81xl`.
+
+We can then use osfr to *retrieve* this project and load it into R by
+providing the GUID:
 
 ``` r
 library(osfr)
@@ -125,13 +130,32 @@ cr_project %>%
 ```
 
 We could continue this pattern of exploration and even download local
-copies of project files using `osf_download()`.
+copies of project files using `osf_download()`. Or, if you come across a
+publication that directly references a file’s OSF URL, you could quickly
+download it to your project directory by providing the URL or simply the
+GUID:
+
+``` r
+osf_retrieve_file("https://osf.io/btgx3/") %>% 
+  osf_download()
+#> # A tibble: 1 x 4
+#>   name                 id                     local_path          meta     
+#> * <chr>                <chr>                  <chr>               <list>   
+#> 1 Study_19_Figure_1.p… 5751d71d9ad5a10207937… Study_19_Figure_1.… <list [3…
+```
 
 ### Managing Projects
 
-You can use osfr to create projects, add sub-components or directories,
-and upload files. See the [Getting Started
-vignette](http://centerforopenscience.github.io/osfr/articles/getting_started.html)
+You can use osfr to [create
+projects](https://centerforopenscience.github.io/osfr/reference/osf_create.html),
+[add
+sub-components](https://centerforopenscience.github.io/osfr/reference/osf_create.html)
+or
+[directories](https://centerforopenscience.github.io/osfr/reference/osf_mkdir.html),
+and [upload
+files](https://centerforopenscience.github.io/osfr/reference/osf_upload.html).
+See [Getting
+Started](http://centerforopenscience.github.io/osfr/articles/getting_started.html)
 to learn more about building projects with osfr, but here is a quick
 example in which we:
 

man-roxygen/n_max.R

@@ -1 +1,2 @@
-#' @param n_max Number of results to return from OSF.
+#' @param n_max Maximum number of results to return from OSF (default is 10).
+#'   Set to `Inf` to return *all* results.