DataPackageR submission

[gfinak]

Summary

• What does this package do? (explain in 50 words or less):

A package to reproducibly process raw data into packaged, analysis-ready data sets.

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

Package: DataPackageR
Type: Package
Title: Construct Reproducible Analytic Data Sets as R Packages
Authors@R:
    c(person(given = "Greg Finak", role=c("aut","cre","cph"), email="gfinak@fredhutch.org"),
      person(given = "Paul Obrecht", role=c("ctb")))
Version: 0.13.2
Date: 2017-10-13
Description: Construct reproducible analytic data sets as R packages. 
License: MIT + file LICENSE
Depends: R (>= 3.5.0)
Imports:
    optparse,
    digest,
    knitr,
    utils,
    rmarkdown,
    desc,
    yaml,
    purrr,
    here,
    roxygen2 (>= 6.0.1),
    devtools (>= 1.12.0),
    assertthat,
    stringr,
    futile.logger,
    rprojroot,
    data.tree,
    DT
VignetteBuilder: knitr
RoxygenNote: 6.0.1
Collate: autodoc.R
    build.R
    dataversion.r
    digests.R
    load_save.R
    processData.R
    skeleton.R
    devtool_functions.R
    rmarkdown_functions.R
    roxygen2_functions.R
    mergeDocumentation.R
    parseDocumentation.R
    yamlR.R
Suggests:
    testthat,
    covr

• URL for the package (the development repository, not a stylized html page):

https://github.com/RGLab/DataPackageR

• Please indicate which category or categories from our package fit policies this package falls under *and why(? (e.g., data retrieval, reproducibility. If you are unsure, we suggest you make a pre-submission inquiry.):
  [e.g., "data extraction, because the package parses a scientific data file format"]

reproducibility, because the package provides a framework for reproducibly processing raw data into analysis-ready data sets in R data packages.

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

The target audience are data analysts, data scientists and any users working with diverse, large, raw data sets that need significant preprocessing to transform them into analysis-ready data sets. This processing may be time consuming and the raw data too large to include in a package. DataPackageR simplifies the process of ensuring that this data processing is done reproducibly by ensuring vignettes are constructed that track how data is processed, ensure data set objects are documented, verifies checksums of individual objects and bumps data sets versions automatically, and decouples the data transformation from the usual build and installation process. The latter is particularly useful when raw data cannot be shared with the package or if processing such data is too time consuming to be re-run each time the package is build and installed using the usual R CMD BUILD process. The tool is useful for preparing analysis-ready data for publication with manuscripts, or sharing it for collaborative data analysis.

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

The drake and workflowr packages are similar, in that they allow one to build reproducible workflows. DataPackageR is different in that its aim is to provide tool to help users implement the ideas found in ropensci/rrrpkg and cboettig/template and elsewhere, using their existing code with minimal effort. That code may leverage tools like workflowr and drake, but does not have to. DataPackageR provides the infrastructure to automate building, and documentation, and tracking data provenance via automated construction of vignettes documenting the transformation of raw data sets to R data objects ready for analysis, and packaging those into R data packages that can be shared.

•   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.

Requirements

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.
• I agree to abide by ROpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

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:
  • 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:
  • 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 gaurantee that your manuscript willl 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)

Detail

• Does R CMD check (or devtools::check()) succeed? Paste and describe any errors or warnings:

• Does the package conform to rOpenSci packaging guidelines? Please describe any exceptions:

The package name uses camel case as it has been around for several years, used internally by our research group.

• If this is a resubmission following rejection, please explain the change in circumstances:

• If possible, please provide recommendations of reviewers - those with experience with similar packages and/or likely users of your package - and their GitHub user names:

Suggested reviewers

Jenny Bryan (jennybc)
Carl Boettiger (cboettig)
Ted Laderas (laderast)

[maelle]

Thanks for your submission @gfinak! 😺 Below are the results of my editorial checks and comments. Please tackle the changes, I'll then look for and assign reviewers. 🙏

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

• Please put codecov and Travis config files in .gitignore. Use e.g. usethis::use_build_ignore(c(".travis.yml", "codecov.yml")) (in the future when developing a package you can actually use usethis::use_travis() and usethis::use_coverage() to help with such setup steps).

• Edit the top of the README.md that's currently weirdly formatted (remains of a Rmd header I think).

• Given that your package interacts with the file system, please add CI for Windows too via Appveyor, cf this chapter in our packaging guide. There's an usethis::use_appveyor() function.

• Please delete the Maintainer field in DESCRIPTION, it'll get populated automatically from Authors@R when building the package.

• Why having the collate field in DESCRIPTION?

• Please add a code of conduct (e.g. via usethis::usethis::use_code_of_conduct()) and contributing guidelines to your repo. We're working on a template for that, cf this chapter.

• goodpractice output

It is good practice to

  ✖ omit "Date" in DESCRIPTION. It is not
    required and it gets invalid quite often. A build
    date will be added to the package when you perform
    `R CMD build` on it.

  ✖ add a "URL" field to DESCRIPTION. It
    helps users find information about your package
    online. If your package does not have a homepage,
    add an URL to GitHub, or the CRAN package package
    page.
  ✖ add a "BugReports" field to DESCRIPTION,
    and point it to a bug tracker. Many online code
    hosting services provide bug trackers for free,
    https://github.com, https://gitlab.com, etc.

Just run usethis::use_github_links() 😸

  ✖ use '<-' for assignment instead of '='.
    '<-' is the standard, and R users and developers
    are used it and it is easier to read your code for
    them if you use '<-'.

    R\processData.R:241:31
    R\processData.R:242:48
    tests\testthat\test-skeleton.R:274:10
    tests\testthat\test-skeleton.R:275:10
    tests\testthat\test-skeleton.R:288:10

For that I recommend using styler.

  ✖ avoid long code lines, it is bad for
    readability. Also, many people prefer editor
    windows that are about 80 characters wide. Try
    make your lines shorter than 80 characters

    R\processData.R:64:1
    R\processData.R:142:1
    R\processData.R:145:1
    R\processData.R:236:1
    R\processData.R:242:1
    ... and 10 more lines

I think styler will help with that too.

  ✖ avoid calling setwd(), it changes the
    global environment. If you need it, consider using
    on.exit() to restore the working directory.

    R\processData.R:53:20
    R\processData.R:62:9
    R\processData.R:77:26
    R\processData.R:88:26
    R\processData.R:97:26
    ... and 7 more lines

Well unless it's needed for the specific context of your package's use case!

  ✖ avoid sapply(), it is not type safe. It
    might return a vector, or a list, depending on the
    input data. Consider using vapply() instead.

    R\digests.R:10:13
    R\digests.R:11:13
    R\load_save.R:25:5
    R\processData.R:317:17
    R\processData.R:330:13

  ✖ avoid 1:length(...), 1:nrow(...),
    1:ncol(...), 1:NROW(...) and 1:NCOL(...)
    expressions. They are error prone and result 1:0
    if the expression on the right hand side is zero.
    Use seq_len() or seq_along() instead.

    R\parseDocumentation.R:16:20

  ✖ not import packages as a whole, as this
    can cause name clashes between the imported
    packages. Instead, import only the specific
    functions you need.

See http://r-pkgs.had.co.nz/namespace.html#imports

Ask me any question you might have!

---

Reviewers: @karawoo @wlandau
Due date: 2018-07-23

[gfinak]

@maelle , thanks for the package review. I believe I've addressed all the issues with the latest commits.
Best,

Greg

[maelle]

Thanks @gfinak! I see much progress indeed! Here are a few more points from goodpractice and me

• Please replace the use of devtools unexported functions by the use of desc. In general, there's a devtools diaspora going on, so check the different small packages of the r-lib organization to see if some of the ones that are on CRAN contain functions you're using now. Maybe usethis has some of the functions you need for other things?

• Regarding imports it'd be better to do as stated in Hadley Wickham's book " In fact, this is what I recommend: list the package in DESCRIPTION so that it’s installed, then always refer to it explicitly with pkg::fun(). ". It's a bit a pain when not doing it right away so you'll have a bit of work but it makes things clearer for reviewers (who'd see right away where a function comes from), and even you later. One case could be your wanting to replace a dependency, it'd be much easier to just search for all "dependency::" occurrences.

It is good practice to

  ✖ write unit tests for all functions, and all
    package code in general. 78% of code lines are
    covered by test cases.

    R/build.R:27:NA
    R/build.R:29:NA
    R/build.R:30:NA
    R/build.R:32:NA
    R/build.R:33:NA
    ... and 250 more lines

Please increase the coverage a bit by testing

• Your error messages (and their logging?) e.g. I see such potential in https://codecov.io/gh/RGLab/DataPackageR/src/5acdc5650b4a5813b9fbc7e338556f4a7f86c18c/R/build.R

• The different options, e.g. the behaviour when an argument is null.

  ✖ avoid long code lines, it is bad for
    readability. Also, many people prefer editor windows
    that are about 80 characters wide. Try make your
    lines shorter than 80 characters

    R\processData.R:56:1
    R\processData.R:85:1
    R\processData.R:147:1
    R\processData.R:428:1
    R\yamlR.R:180:1
    ... and 10 more lines

Please shorten the lines unless they contain URLs or so. In which case add lintr exceptions using # nolint cf https://github.com/jimhester/lintr#project-configuration

  ✖ avoid calling setwd(), it changes the
    global environment. If you need it, consider using
    on.exit() to restore the working directory.

    R\processData.R:44:11
    R\processData.R:82:13
    R\processData.R:83:5
    tests\testthat\test-skeleton.R:38:11
    tests\testthat\test-skeleton.R:39:3

Can you confirm they're needed?

  ✖ avoid sapply(), it is not type safe. It
    might return a vector, or a list, depending on the
    input data. Consider using vapply() instead.

    R\load_save.R:27:3

Please replace the use of sapply.

  ✖ fix this R CMD check NOTE: Namespace in
    Imports field not imported from: 'optparse' All
    declared Imports should be used.

Unnecessary dependency?

  ✖ fix this R CMD check WARNING: LaTeX errors
    when creating PDF version. This typically indicates
    Rd problems. LaTeX errors found: ! LaTeX Error: File
    `inconsolata.sty' not found. Type X to quit or
    <RETURN> to proceed, or enter new name. (Default
    extension: sty) ! Emergency stop. <read *> l.276 ^^M
    !  ==> Fatal error occurred, no output PDF file
    produced!

Not sure what that is, can you please investigate?

[gfinak]

@maelle
I've gone through the remaining issues.
goodpractice passes: there are a few setwd() used in my tests to cover some test cases, but they are no longer in the package code.
I've addressed the NAMESPACE imports, and use desc and usethis over devtools unexported functions.
Test coverage is now at 100%.
I cannot reproduce the R CMD check WARNING about the inconsolata.sty LaTeX file when I build on my system or any of the CI builds. Could it be a local LaTeX installation issue?

[maelle]

yes it might be since I use tinytex? Will start looking for reviewers now. Thanks for all your efforts!

[maelle]

Reviewers now assigned! Thanks @karawoo and @wlandau for accepting to review this package. 😺 Your reviews are due on 2018-17-23.

Our brand-new and WIP gitbook includes the reviewer's guide as a chapter that you'll find here. 📖

[wlandau]

Package Review

• 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).

For packages co-submitting to JOSS

• The package has an obvious research application according to JOSS's definition

The package contains a paper.md matching JOSS's requirements with:

• A short summary describing the high-level functionality of the software
• Authors: A list of authors with their affiliations
• A statement of need clearly stating problems the software is designed to solve and its target audience.
• References: with DOIs for all those that have one (e.g. papers, datasets, software).

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: 4

---

Review Comments

DataPackageR addresses the unresolved need for tools that properly package and version datasets. I believe it is a worthy contribution to reproducibility and collaboration. This is how I understand the appeal:

1. Data packages have a mixed reputation because the practice does not tend to suit very large datasets. But now, we have a method to
   1. Only include the condensed/processed data in the built package, and
   2. Maintain a reproducible record of the data processing in the package source.
2. DataPackageR has an automated mechanism to increment the version of the package when the fingerprint of any of the datasets changes.
3. Setting up a data package is just smoother and easier. I think the role of DataPackageR is a bit like that of devtools in this space.

Relative to the potential impact, I believe the documentation is a bit modest and detail-oriented. It would be great to take a step back, explain the general concept of a data package, and sell DataPackageR on the above points. My other feedback is minor by comparison. Issues 21 through 32 detail the changes I would like to see.

• Mentioning similar work: datastorr, fst, etc. DataPackageR#21: Discuss datastorr, fst, and similar work in data packaging.
• Checking data versions with less code DataPackageR#22: Consider a new assert_data_version() function.
• A separate NEWS.md file DataPackageR#23: Use a separate NEWS.md file.
• Refactoring the README DataPackageR#24: Consider focusing the README on a high-level introduction, with the details left to the vignette.
• Refactoring the vignette DataPackageR#25: Consider using the vignette to dive deeper into usage.
• Pkg here is in the DESCRIPTION, but not the NAMESPACE DataPackageR#26: Include the here package in the NAMESPACE file (via roxygen2 of course).
• Error running suppressed examples DataPackageR#27: Fix directory conflicts so that devtools::run_examples("DataPackageR", run = FALSE) runs smoothly.
• Elaborate on the use of Rmd files DataPackageR#28: In your example Rmd file that produces cars_over_20, consider explaining how DataPackageR detects and saves cars_over_20.
• Documentation in ?DataPackageR-package is out of date with the README DataPackageR#29: Synchronize the package help file with the README and vignette (e.g. datasets.R).
• Exported functions without examples DataPackageR#30: Make sure all exported functions have examples in the help files.
• Consider standardizing the way functions are named DataPackageR#31: Consider standardizing the style of function names.
• Consider a dedicated guide on just the YAML configuration file DataPackageR#32: Consider a separate vignette on the details of working with YAML configuration files.