osfr: R interface to OSF

[aaronwolen]

Submitting Author: Aaron Wolen (@aaronwolen)
Repository: https://github.com/CenterForOpenScience/osfr
Version submitted: 0.2.1
Editor: TBD
Reviewer 1: TBD
Reviewer 2: TBD
Archive: TBD
Version accepted: TBD

---

• Paste the full DESCRIPTION file inside a code block below:

Package: osfr
Title: R Interface to OSF
Version: 0.2.1
Authors@R: c(
    person("Aaron", "Wolen",, "aaron@wolen.com", role = c("aut", "cre"),
           comment = c(ORCID = "0000-0003-2542-2202")),
    person("Chris","Hartgerink",, "chjh@protonmail.com", role = "aut"),
    person("Timothy", "York",, "timothypyork@gmail.com", role = "ctb"),
    person("Richards", "Brian",, "brian.g.richards@gmail.com", role = "ctb"),
    person("Courtney", "Soderberg",, "courtney@cos.io", role = "ctb"))
Description: Manage your projects and access open research materials and data on OSF.
Depends: R (>= 3.1.0)
Imports:
    crul,
    jsonlite,
    stringi,
    purrr,
    tibble,
    rlang,
    fs
License: Apache License 2.0 | file LICENSE
URL: 
    http://centerforopenscience.github.io/osfr, 
    https://github.com/centerforopenscience/osfr
BugReports: https://github.com/centerforopenscience/osfr/issues
LazyData: true
Suggests:
    dplyr,
    testthat,
    knitr,
    rmarkdown,
    lintr,
    covr
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 6.1.1
VignetteBuilder: knitr

Scope

• Please indicate which category or categories from our package fit policies this package falls under: (Please check an appropriate box below. If you are unsure, we suggest you make a pre-submission inquiry.):

  • data retrieval
  • data extraction
  • database access
  • data munging
  • data deposition
  • reproducibility
  • geospatial data
  • text analysis

• Explain how the and why the package falls under these categories (briefly, 1-2 sentences):

  osfr provides a suite of functions for interacting with OSF (https://osf.io), a project management repository that supports researchers across their entire project lifecycle. Using osfr and OSF, researchers can create and manage projects, upload and share materials, or explore publicly accessible projects and download the associated files.

• Who is the target audience and what are scientific applications of this package?

  Any R users who rely on OSF for managing their research or working with collaborators.

• Are there other R packages that accomplish the same thing? If so, how does yours differ or meet our criteria for best-in-category?

  No.

• If you made a pre-submission enquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted.

Technical checks

Confirm each of the following by checking the box. This package:

• does not violate the Terms of Service of any service it interacts with.
• has a CRAN and OSI accepted license.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions.
• contains a vignette with examples of its essential functions and uses.
• has a test suite.
• has continuous integration, including reporting of test coverage using services such as Travis CI, Coveralls and/or CodeCov.

Publication options

• Do you intend for this package to go on CRAN?
• Do you wish to automatically submit to the Journal of Open Source Software? If so:

JOSS Options

• The package has an obvious research application according to JOSS's definition.
  • The package contains a paper.md matching JOSS's requirements with a high-level description in the package root or in inst/.
  • The package is deposited in a long-term repository with the DOI:
  • (Do not submit your package separately to JOSS)

• Do you wish to submit an Applications Article about your package to Methods in Ecology and Evolution? If so:

MEE Options

• The package is novel and will be of interest to the broad readership of the journal.
• The manuscript describing the package is no longer than 3000 words.
• You intend to archive the code for the package in a long-term repository which meets the requirements of the journal (see MEE's Policy on Publishing Code)
• (Scope: Do consider MEE's Aims and Scope for your manuscript. We make no guarantee that your manuscript will be within MEE scope.)
• (Although not required, we strongly recommend having a full manuscript prepared when you submit here.)
• (Please do not submit your package separately to Methods in Ecology and Evolution)

Code of conduct

• I agree to abide by ROpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

[sckott]

thanks for your submission @aaronwolen

@maelle has been assigned as editor

[maelle]

Editor checks:

• Fit: The package meets criteria for fit and overlap
• Automated tests: Package has a testing suite and is tested via Travis-CI or another CI service.
• License: The package has a CRAN or OSI accepted license
• Repository: The repository link resolves correctly
• Archive (JOSS only, may be post-review): The repository DOI resolves correctly
• Version (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)?

---

Editor comments

Thanks for your submission @aaronwolen! Here are a few questions/comments before I can start looking for reviewers.

• The installation instructions should include information about the authentication, and make it clear a token will be needed. Moreover, in a CONTRIBUTING.md file you could explain what scope a token needs for testing the package. I created one with scope for everything. 😁

• The repo also lacks a code of conduct see https://ropensci.github.io/dev_guide/collaboration.html#friendlyfiles

• Two tests fail

── Test failures ────────────────────────────────────────────────────────── testthat ────

> library(testthat)
> library(osfr)
Automatically registered OSF personal access token
> 
> test_check("osfr")
── 1. Error: (unknown) (@test-osf_ls.R#5)  ──────────────────────────────────────────────
Not found.
       HTTP status code 404.
1: osf_retrieve_node("brfza") at testthat/test-osf_ls.R:5
2: raise_error(out)
3: http_error(x$status_code, x$errors[[1]]$detail)
4: stop(args, msg, call. = FALSE)

── 2. Error: (unknown) (@test-osf_tbl.R#37)  ────────────────────────────────────────────
Not found.
       HTTP status code 404.
1: osf_retrieve_node("brfza") at testthat/test-osf_tbl.R:37
2: raise_error(out)
3: http_error(x$status_code, x$errors[[1]]$detail)
4: stop(args, msg, call. = FALSE)

══ testthat results  ════════════════════════════════════════════════════════════════════
OK: 90 SKIPPED: 1 FAILED: 2
1. Error: (unknown) (@test-osf_ls.R#5) 
2. Error: (unknown) (@test-osf_tbl.R#37) 

Error: testthat unit tests failed
Execution halted

1 error ✖ | 0 warnings ✔ | 0 notes ✔

I have not looked in detail, is it because this is a node that only exists in the account you use for testing? Couldn't the node be created before testing so that anyone can run the tests?

• goodpractice::gp() mentions a few too long code lines.

• I see there are a few open issues in your repo, labelled "feature requests". Are these features you plan to implement in the near future? In particular, before reviews?

---

Reviewers: @HeidiSeibold @cboettig
Due date: 2018-02-20

[aaronwolen]

Hi, @maelle! Thanks for checking out the package and I apologize for the delayed response—I’ve been out traveling most of this week and am still playing catchup.

I made the following changes based on your comments:

• added a code of conduct (ropensci/osfr@e6db814)

• added a note to the README explaining a PAT is necessary to manage projects and upload files, along with a link to the Authenticating osfr vignette (ropensci/osfr@68e29f3)

• indicated that contributors need to generate a PAT on the testing server with all scopes enabled (ropensci/osfr@1f601ca, ropensci/osfr@3f520fa)

• reformatted many of the overly long lines (ropensci/osfr@eb9a81b)

  (There are still a few places where I’m breaking the 80 line rule, primarily for errors, warnings, and other messages that aren’t as easily split up.)

Regarding the test failures you encountered, I believe the problem was the tests were run on the main OSF server (osf.io) and several of the required resources are located on OSF’s testing server (test.osf.io), which is where COS prefers development take place. The contributing guidelines mention you need to set OSF_SERVER=test to switch to the testing server, but it’s easy to miss.

This really underscored that the testing infrastructure was a little fragile, so I did some restructuring and added checks to skip certain tests if they’re being run on the production server or if no PAT is defined (ropensci/osfr@81cfe71). It was a big enough change that I bumped the version to 0.2.2.

Thanks again for looking it over and please let me know if you have any other questions or follow-up comments.

[maelle]

Thanks @aaronwolen, great work! Sorry for missing the contributing guidelines! Two small suggestions:

• "Create a .Renviron file in the root of your project directory" or one could edit the existing general .Renviron/create one (that's what I did :-) ). You could mention the handy usethis::edit_r_environ() function for that.

• Regarding the long lines, you could add # nolint at the end of the ones you do not want to split cf https://github.com/jimhester/lintr#project-configuration

I'll now look for reviewers! 😸

[aaronwolen]

Great suggestions! I did not know about edit_r_environ()—that package is just chock full of goodness—I’ll be sure to mention it.

[maelle]

@aaronwolen Great definition of usethis 😁

[maelle]

@HeidiSeibold @cboettig Thanks for accepting to review this package! 😸 Your reviews are due on 2019-02-20. As a reminder here's our guide for reviewers and the review template.

[aaronwolen]

@maelle, a new version of purrr was just released that, unfortunately, introduced a bug in osfr. It's fixed in the dev branch but I wanted to verify it's okay to merge the new version now that reviewers have been assigned?

[maelle]

Congrats on fixing that bug so quickly! Yes I think it's fine, I don't think they started reviewing yet (feel free to disagree, @HeidiSeibold and @cboettig). In general we prefer a stable version but bug fixes are a good reason to change stuff. 😸

[HeidiSeibold]

I will just add my review template below, so you know what I am up to 😸

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

• As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

• A statement of need clearly stating problems the software is designed to solve and its target audience in README
• Installation instructions: for the development version of package and any non-standard dependencies in README
• Vignette(s) demonstrating major functionality that runs successfully locally
• Function Documentation: for all exported functions in R help
• Examples for all exported functions in R Help that run successfully locally
• Community guidelines including contribution guidelines in the README or CONTRIBUTING, and DESCRIPTION with URL, BugReports and Maintainer (which may be autogenerated via Authors@R).

Functionality

• Installation: Installation succeeds as documented.
• Functionality: Any functional claims of the software been confirmed.
• Performance: Any performance claims of the software been confirmed.
• Automated tests: Unit tests cover essential functions of the package
  and a reasonable range of inputs and conditions. All tests pass on the local machine.
• Packaging guidelines: The package conforms to the rOpenSci packaging guidelines

Final approval (post-review)

• The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing: 10

---

Review Comments

• I have limited expertise on how to correctly test functionality of a package which talks to a server, so I checked the Automated tests-Box, but just because I could not see any obvious problems and the check ran through. If you need an expert here, I could ask if @giuseppec can take a look.

• Documentation on osf_upload() says:

overwrite    Logical, overwrite an existing file with the same name (default FALSE)? If TRUE, OSF will automatically update the file and record the previous version. 

What happens for FALSE? Does it not upload at all or does it upload as a separate file?

• The error message does not really help me solve the problem. Why does the authentication say it is ok, but then it does not work?

> osf_auth(token = "<mytoken>")
Registered PAT from the provided token
> osf_retrieve_node("vk95n")
 Error: User provided an invalid OAuth2 access token
       HTTP status code 401. 

(Btw. the issue for me was that I was using the token from the test server instead of the actual osf, where the project lives)

• How do I list all components within a project?

• For one of my projects I do not receive all components, when I ask for it (e.g. talk_2015_07_user , compare code to screenshot).

> proj <- osf_retrieve_node("vk95n")
> osf_ls_nodes(proj)
# A tibble: 10 x 3
   name                             id    meta      
   <chr>                            <chr> <list>    
 1 talk_2017_09_novartis            rknwh <list [3]>
 2 talk_2017_10_advisory_board      7uj8p <list [3]>
 3 talk_2017_11_biogen              8tzr6 <list [3]>
 4 talk_2017_11_helmholtz           f5bnu <list [3]>
 5 talk_2018_01_institutskolloquium n26z5 <list [3]>
 6 talk_2018_03_defense             gqzrf <list [3]>
 7 talk_2018_07_ecda                azcqx <list [3]>
 8 talk_2019_01_KI_med              3j4a8 <list [3]>
 9 talk_2015_07_isnps               e93gh <list [3]>
10 talk_2015_06_iroes               9npxe <list [3]>

https://osf.io/vk95n/ Any idea what is causing this?

• If I understand correctly, your main object in the package is osf_tbl_node, which consists of name, id and meta. I would appreciate some more documentation on the meta part. What info does it contain?

  • I assumed that meta would also contain the info on the components of the project, but this seems to not be the case.
  • I would like to see a deeper documentation of osf_tbl
  • Maybe also a note on the connection between the weblink and the id might be helpful for many users.

• What is the difference between a project, a component and a directory? I think I have a rough understanding of it, but it might be helpful to write this down somewhere explicitly.

• Will osfr in the future also allow interacting with files on e.g. GitHub, which are connected to osf?
  (Related to above question, but more of a personal interest question: if I have files connected to osf from GitHub, would the files be lost if GitHub was shut down?)

• Are you planing on creating a pkgdown-website?

@aaronwolen if you have time, I would appreciate you already answering my current questions. This way it will be easier for me to move forward. Thanks :)

[maelle]

@HeidiSeibold live-updated review, that's open science for sure. 😉

[HeidiSeibold]

Question: what is the difference between:
remotes::install_github()
and
devtools::install_github()

The package README is instructing to use the former. Does that matter at all @maelle?

[maelle]

@richfitz said "devtools::install_github calls remotes::install_github in recent devtools versions (since 2.0.0)" so there shouldn't be any difference. :-)

[HeidiSeibold]

I am trying to build the package on my computer (Debian):

hseibold(08:32)~/Documents/git$ git clone git@github.com:CenterForOpenScience/osfr.git
Cloning into 'osfr'...
remote: Enumerating objects: 127, done.
remote: Counting objects: 100% (127/127), done.
remote: Compressing objects: 100% (79/79), done.
remote: Total 4223 (delta 76), reused 76 (delta 45), pack-reused 4096
Receiving objects: 100% (4223/4223), 1.15 MiB | 2.46 MiB/s, done.
Resolving deltas: 100% (2810/2810), done.
hseibold(08:33)~/Documents/git$ cd osfr/
hseibold(08:33)~/Documents/git/osfr (master)$ R CMD build .
* checking for file ‘./DESCRIPTION’ ... OK
* preparing ‘osfr’:
* checking DESCRIPTION meta-information ... OK
* installing the package to build vignettes
* creating vignettes ... ERROR
Warning in engine$weave(file, quiet = quiet, encoding = enc) :
  Pandoc (>= 1.12.3) and/or pandoc-citeproc not available. Falling back to R Markdown v1.
Warning in engine$weave(file, quiet = quiet, encoding = enc) :
  Pandoc (>= 1.12.3) and/or pandoc-citeproc not available. Falling back to R Markdown v1.

Attaching package: 'dplyr'

The following objects are masked from 'package:stats':

    filter, lag

The following objects are masked from 'package:base':

    intersect, setdiff, setequal, union

Quitting from lines 48-50 (getting_started.Rmd) 
Error: processing vignette 'getting_started.Rmd' failed with diagnostics:
Authentication credentials were not provided.
       HTTP status code 401.
Execution halted

The pandoc issue is probably something I have to fix.

How do you solve the authentication issue @aaronwolen?

The reason why I wanted to build it myself was to have a nicely viewable Vignette, which I apparently don't get if I install from GitHub.

> browseVignettes(package = "osfr")
No vignettes found by browseVignettes(package = "osfr")

[maelle]

@HeidiSeibold I had the same authentication issues before @aaronwolen pointed me to https://github.com/CenterForOpenScience/osfr/blob/master/.github/CONTRIBUTING.md :-)

[aaronwolen]

Hi, @HeidiSeibold! I just noticed your edits and responded below:

• Documentation on osf_upload() says:

overwrite    Logical, overwrite an existing file with the same name (default FALSE)? If TRUE, OSF will automatically update the file and record the previous version. 

What happens for FALSE? Does it not upload at all or does it upload as a separate file?

The default behavior is to throw the following error

 Error: File already exists at destination
* Set `overwrite=TRUE` to upload a new version

---

(Btw. the issue for me was that I was using the token from the test server instead of the actual osf, where the project lives)

I've run into this several times myself. I'm considering adding a startup message that informs the user when OSF_SERVER is defined and they're running on the test server.

---

• How do I list all components within a project?

The n_max argument determines how many components will be listed (really just limiting the number of calls made to the API). The default is 10 but setting it to Inf will return all components.

I see now that this behavior is not documented! I'll improve the documentation for this argument in the dev branch. Thanks for pointing that out!

---

Thanks for the questions! I'll keep checking back for more.

[HeidiSeibold]

@maelle I have trouble checking

• Vignette(s) demonstrating major functionality that runs successfully locally

and

• Examples for all exported functions in R Help that run successfully locally

because for many examples it does not make sense to run them without modification. I will just check them anyway because I can use and modify the examples so it works for me.

[maelle]

@HeidiSeibold I'm not sure I understand your problem?

[maelle]

Awesome! Note that there might be some delay on my side over the holidays (happy holidays everyone in this thread by the way 😉).

[aaronwolen]

Hi, @maelle! Just wanted to let you know the paper has been pushed to the repo.

[maelle]

@HeidiSeibold I've just realized you didn't get a chance to approve the package (the remaining box in your review) -- it's fine if you don't have time to. If you don't answer within a week I'll do a few more checks myself.

@aaronwolen

• I noticed that the docs of ?osfr don't include more info about components/folders as discussed in a comment of yours and the following comment? The explanations in the paper are very clear. You could re-use an Rmd fragment in the README, vignette and also package level docs, see this blog post about Rmd fragments and roxygen2 docs about Rmd use](https://roxygen2.r-lib.org/articles/rd.html#including-external--rmd-md-files).

• @cboettig had written "I would appreciate more guidance up-front on file size limits, project size limits, and permission management in the Getting Started Vignette, etc.". Has this been added?

• The paper looks fine (minus 2 typos in a PR) but where is paper.bib?

• is there an ETA on v0.2.8 checklist osfr#103?

[HeidiSeibold]

Thanks @maelle. I am really busy this week unfortunately. 🌻

[aaronwolen]

Thanks, @maelle! I added in the missing bib file and I'm working on updating the docs. Thanks for the Rmd fragment tip!

[maelle]

@HeidiSeibold Thanks, no problem, I'll re-read your review after @aaronwolen updates the docs.

@aaronwolen I'm using Rmd fragments in codemetar dev branch and really liking them. Feel free to comment on their use at ropensci/dev_guide#159

[aaronwolen]

Hi @maelle, I think I've addressed the remaining issues. Here's a quick summary of recent changes:

• added in this missing bibliography
• merged your PR to fix those 2 typos in the paper (Thanks!)
• vignette has been overhauled and now utilizes the multi-file upload/download features that were added after the original vignette was written
• vignette now includes information about projects/components, storage limits, and permissions, as well as links to relevant OSF guides
• added some information about OSF, projects/components and storage limits to ?osfr, as well as links to the vignette and other helpful OSF guides

These are currently on the dev branch in case any additional changes are required, that way I can cut a single release upon merging to master.

[maelle]

Approved, the changes look good! Thanks @aaronwolen for submitting and @HeidiSeibold @cboettig for your reviews! 😺

To-dos:

• (Suggestion) In http://centerforopenscience.github.io/osfr/articles/auth.html#using-your-pat you could add more links, e.g. to https://rstats.wtf/r-startup.html, https://usethis.r-lib.org/reference/edit.html.
• Merge dev into master.
• Transfer the repo to rOpenSci's "ropensci" GitHub organization under "Settings" in your repo. I have invited you to a team that should allow you to do so. You'll be made admin once you do. (edit: we discussed the fact that you probably won't transfer it)
• Add the rOpenSci footer to the bottom of your README
  " [![ropensci_footer](https://ropensci.org/public_images/ropensci_footer.png)](https://ropensci.org)"
• Fix all links to the GitHub repo to point to the repo under the ropensci organization.
• If you already had a pkgdown website, fix its URL to point to https://docs.ropensci.org/package_name and deactivate the automatic deployment you might have set up, since it will not be built centrally like for all rOpenSci packages, see http://devdevguide.netlify.com/#docsropensci (it might take 1-2 days for the system to pick it up). In addition, in your DESCRIPTION file, include the docs link in the URL field alongside the link to the GitHub repository, e.g.: URL: https://docs.ropensci.org/foobar (website) https://github.com/ropensci/foobar I think you might need to read Jeroen's note about precomputing vignettes since the docs server can't access credentials.
• Fix any links in badges for CI and coverage to point to the ropensci URL. We no longer transfer Appveyor projects to ropensci Appveyor account so after transfer of your repo to rOpenSci's "ropensci" GitHub organization the badge should be [![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/ropensci/pkgname?branch=master&svg=true)](https://ci.appveyor.com/project/individualaccount/pkgname).
• We're starting to roll out software metadata files to all ropensci packages via the Codemeta initiative, see https://github.com/ropensci/codemetar/#codemetar for how to include it in your package, after installing the package - should be easy as running codemetar::write_codemeta() in the root of your package.
• Activate Zenodo watching the repo
• Tag and create a release so as to create a Zenodo version and DOI
• Submit to JOSS at https://joss.theoj.org/papers/new, using the rOpenSci GitHub repo URL. When a JOSS "PRE REVIEW" issue is generated for your paper, add the comment: This package has been reviewed by rOpenSci: https://LINK.TO/THE/REVIEW/ISSUE, @ropensci/editors

Should you want to acknowledge your reviewers in your package DESCRIPTION, you can do so by making them "rev"-type contributors in the Authors@R field (with their consent). More info on this here.

Welcome aboard! We'd love to host a blog post about your package - either a short introduction to it with one example or a longer post with some narrative about its development or something you learned, and an example of its use. If you are interested, review the instructions, and tag @stefaniebutland in your reply. She will get in touch about timing and can answer any questions.

We've put together an online book with our best practice and tips, this chapter starts the 3d section that's about guidance for after onboarding. Please tell us what could be improved, the corresponding repo is here.

[maelle]

The process took just less than one year, pfiew! 😉

[aaronwolen]

🎉 🎉 🎉 That's great news, @maelle! Thank you so much for all of the help and keeping this process on track. And a sincere thanks to @cboettig and @HeidiSeibold for your great comments/suggestions. I think the package is much stronger for having gone through this process—it's certainly older 😄.

I'll work on those remaining to-dos and double-check with the COS folks about migrating the repo to the ropensci org.

[aaronwolen]

@maelle, COS has okayed transferring the repo but it will have to be handled by the admin for their organization. Could you add @mfraezz to the ropensci team so he can make the move?

[maelle]

Thanks, done!

Once the repo is transferred, ping me so that I might give both of you admin rights again (note that my timezone is UTC+1).

[mfraezz]

Repo successfully transferred, @maelle - https://github.com/ropensci/osfr

[aaronwolen]

Thanks, @mfraezz!

[maelle]

@mfraezz thanks! I don't see you as collaborator of the repo but I gave admin rights to @aaronwolen.

[mfraezz]

I'm an owner of the CenterForOpenScience organization, so it was implicit before. I'd recommend updating the repo description to include the new GH pages url, https://ropensci.github.io/osfr/ , but otherwise have no real need for access.

[aaronwolen]

@cboettig and @HeidiSeibold, any objections to being listed as reviewers in the package DESCRIPTION?

[cboettig]

fine by me!

[HeidiSeibold]

@cboettig and @HeidiSeibold, any objections to being listed as reviewers in the package DESCRIPTION?

I'd be honored :)

[maelle]

@aaronwolen now that you've submitted the package to JOSS I think the only missing item from my list is your adding a codemeta.json to the repo (via codemetar::write_codemeta(), I recommend the dev version remotes::install_github("ropensci/codemetar", ref = "dev")).

[aaronwolen]

Thanks, @maelle! Just added the missing codemeta.json to master. Meanwhile, I'm waiting to hear back from CRAN 🤞.

[maelle]

👀 https://lockedata.github.io/cransays/articles/dashboard.html

[aaronwolen]

Yes! ❤️ it! I discovered it last week week and try really hard not to check it daily.