Refactoring the README

[wlandau]

Currently, the README and vignette have almost identical content. I recommend diverging them because

1. Maintaining 2 copies of the same writeup is hard, and
2. These documents have different purposes. As I understand it, the README should be a high-level first exposure for new users, and the vignettes should go into usage details.

Suggested section outline

• Why DataPackageR?
• Installation
• Minimal example
• Preprint and publication
• Code of conduct

Suggested motivation section

I think it would be helpful to take a couple steps back here. Maybe it could flow like this:

• Why package your data?
  • Reproducibility
  • Collaboration
  • Documentation
  • Convenience
• Challenges
  • 5 MB limit makes it hard to ship data in packages.
  • Usually there is a lot of manual effort to set up the proper file system.
• DataPackageR
  • Lets you keep the large raw data, only ship the processed data, and maintain a reproducible record of the preprocessing.
  • Helps you set up the package files.
• Comparison to similar work
  • datastorr
  • fst
  • Other work from https://github.com/noamross/2018-04-18-rstats-nyc/blob/master/Noam_Ross_ModernDataPkg_rstatsnyc_2018-04-20.pdf
  • https://github.com/ropensci/rrrpkg
  • https://github.com/cboettig/template

Suggested minimal example

library(DataPackageR)
library(data.tree)

# Let's reproducibly package up
# the cars in the mtcars dataset
# with speed > 20.
# Our dataset will be called cars_over_20.

# Get the code file that turns the raw data
# to our packaged and processed analysis-ready dataset.
processing_code <- system.file(
  "extdata", "tests", "subsetCars.Rmd", package = "DataPackageR"
)

# Create the package framework.
DataPackageR::datapackage.skeleton(
  "mtcars20", force=TRUE, code_files = processing_code, r_object_names = "cars_over_20") 

# Run the preprocessing code to build cars_over_20
# and reproducibly enclose it in a package.
DataPackageR:::package_build("mtcars20") 

# Let's use the package we just created.
install.packages("mtcars20_1.0.tar.gz", type = "source", repos = NULL)
library(mtcars20)
data("cars_over_20") # load the data
cars_over_20  # Now we can use it.
?cars_over_20 # See the documentation you wrote in data-raw/documentation.R.

# We have our dataset!
# Since we preprocessed it,
# it is clean and under the 5 MB limit for data in packages.
cars_over_20

# We can easily check the version of the data
DataPackageR::dataVersion("mtcars20")

If you include the output of this code chunk, I would encourage suppressing the most verbose messages. For example, maybe set quiet to TRUE in knit() or render().

Consider README.Rmd

It is becoming standard practice to generate the README.md from a README.Rmd (example here). It is much easier this way to keep code chunk output synchronized with everything else. usethis::use_readme_rmd() makes it easy.

[wlandau]

Also, I think this code chunk could point to raw-data/documentation.R. I updated the example code chunk above.

# Let's use the package we just created.
install.packages("mtcars20_1.0.tar.gz", type = "source", repos = NULL)
library(mtcars20)
data("cars_over_20") # load the data
cars_over_20  # Now we can use it.
?cars_over_20 # See the documentation you wrote in data-raw/documentation.R.

[wlandau]

To be clear, the suggested structure in #24 (comment) is just meant to give you ideas, not force you into writing a certain way. You may also find it helpful to check out the official rOpenSci guidance on READMEs and this thread on vignette standards.

[wlandau]

Ref: ropensci/software-review#230

[wlandau]

You did a tone of work on the new README, and I really like it. It is neatly outlined and concise, and it operates at the right level of detail. Right under "Why package data sets?", would you consider adding an explicit definition of a data package? Maybe something like "A data package is a formal R package whose sole purpose is to contain, access, and/or document datasets."

[gfinak]

Glad to. Will be back in front of a computer by Monday, will deal with it then.
Thanks again.

[wlandau]

Very helpful, thank you.