Joss-reviews: [REVIEW]: checkr: An R package for Assertive Programming

[whedon]

Submitting author: @joethorley (Joseph Thorley)
Repository: https://github.com/poissonconsulting/checkr
Version: v0.0.2
Editor: @arfon
Reviewer: @boshek
Archive: 10.5281/zenodo.1208141

Status

Status badge code:

HTML: <a href="http://joss.theoj.org/papers/05940085572e81079caad4d1f27df912"><img src="http://joss.theoj.org/papers/05940085572e81079caad4d1f27df912/status.svg"></a>
Markdown: [![status](http://joss.theoj.org/papers/05940085572e81079caad4d1f27df912/status.svg)](http://joss.theoj.org/papers/05940085572e81079caad4d1f27df912)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@boshek, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

1. Make sure you're logged in to your GitHub account
2. Be sure to accept the invite at this URL: https://github.com/openjournals/joss-reviews/invitations

The reviewer guidelines are available here: https://joss.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @arfon know.

### Conflict of interest

• [x] As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

Code of Conduct

• [x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• [x] Repository: Is the source code for this software available at the repository url?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Version: Does the release version given match the GitHub release (v0.0.2)?
• [x] Authorship: Has the submitting author (@joethorley) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [x] Functionality: Have the functional claims of the software been confirmed?
• [x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [x] Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?
• [x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [x] Authors: Does the paper.md file include a list of authors with their affiliations?
• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

[whedon]

Hello human, I'm @whedon. I'm here to help you with some common editorial tasks. @boshek it looks like you're currently assigned as the reviewer for this paper :tada:.

:star: Important :star:

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

1. Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

1. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

For a list of things I can do to help you, just type:

@whedon commands

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

PDF failed to compile for issue #624 with the following error:

/app/vendor/bundle/ruby/2.3.0/bundler/gems/whedon-a31a5c2a9125/lib/whedon.rb:98:in []': no implicit conversion of String into Integer (TypeError) from /app/vendor/bundle/ruby/2.3.0/bundler/gems/whedon-a31a5c2a9125/lib/whedon.rb:98:inblock in parse_affiliations'
from /app/vendor/bundle/ruby/2.3.0/bundler/gems/whedon-a31a5c2a9125/lib/whedon.rb:97:in each' from /app/vendor/bundle/ruby/2.3.0/bundler/gems/whedon-a31a5c2a9125/lib/whedon.rb:97:inparse_affiliations'
from /app/vendor/bundle/ruby/2.3.0/bundler/gems/whedon-a31a5c2a9125/lib/whedon.rb:84:in parse_authors' from /app/vendor/bundle/ruby/2.3.0/bundler/gems/whedon-a31a5c2a9125/lib/whedon.rb:68:ininitialize'
from /app/vendor/bundle/ruby/2.3.0/bundler/gems/whedon-a31a5c2a9125/lib/whedon/processor.rb:29:in new' from /app/vendor/bundle/ruby/2.3.0/bundler/gems/whedon-a31a5c2a9125/lib/whedon/processor.rb:29:inset_paper'
from /app/vendor/bundle/ruby/2.3.0/bundler/gems/whedon-a31a5c2a9125/bin/whedon:37:in prepare' from /app/vendor/bundle/ruby/2.3.0/gems/thor-0.20.0/lib/thor/command.rb:27:inrun'
from /app/vendor/bundle/ruby/2.3.0/gems/thor-0.20.0/lib/thor/invocation.rb:126:in invoke_command' from /app/vendor/bundle/ruby/2.3.0/gems/thor-0.20.0/lib/thor.rb:387:indispatch'
from /app/vendor/bundle/ruby/2.3.0/gems/thor-0.20.0/lib/thor/base.rb:466:in start' from /app/vendor/bundle/ruby/2.3.0/bundler/gems/whedon-a31a5c2a9125/bin/whedon:99:in from /app/vendor/bundle/ruby/2.3.0/bin/whedon:22:in load' from /app/vendor/bundle/ruby/2.3.0/bin/whedon:22:in

'

[arfon]

@boshek - please carry out your review in this issue by updating the checklist above and giving feedback in this issue. The reviewer guidelines are available here: http://joss.theoj.org/about#reviewer_guidelines

Any questions/concerns please let me know.

[arfon]

Here's the PDF: 10.21105.joss.00624.pdf

[arfon]

@joethorley - this PR will fix the paper compilation issues: https://github.com/poissonconsulting/checkr/pull/6

[boshek]

@joethorley, @arfon - This is an excellent package and I can immediately see it's utility for all sorts of applications especially when writing scripts. I have several specific minor comments below. Overall though this is an excellently written package with very good code coverage, a clear purpose and meets all the JOSS guidelines.

General comment

I think you have nicely provided a clear interface for a relatively new R user to begin implementing some added rigour into their R scripts/packages. I think the point in an R user's skill development where this becomes useful is when they understand what a vector, a class, an environment etc. all mean. I think two places where you can link a new user with your nice set of check_* functions are a) the Description in each help file, where some of terminology can be explained more fully and b) a "checkr for the absolute beginner" vignette.

Minor comments

• Currently the argument description exclusive in several functions is a little misleading:

  A flag indicating whether other classes/ columns etc are permitted.

  This implies that other classes/columns are permitted when exclusive = TRUE. Consider revising

• Description in the help files is a little sparse. Consider expanding for a new user.

• Consider generating some package level documentation. usethis::use_package_doc() would provide this quite easily. This is often an entry point for new users: i.e. ?checkr

• Possibly consider replacing 1:nrow() with seq_len() in check_join(). I am not sure how an empty data frame can make it past !all_y && !nrow(x) but just to be certain this may be prudent to avoid returning 1:0.

• I think you could emphasize the use of checkr in scripts as its easily understood goals are well suited to transfer to the non-developer R script writer in a more introductory vignette. This would be in addition to the comparison piece.

• I think that the audience for this package could be more clearly stated in both the DESCRIPTION file and in the JOSS paper.

• I wonder if a very short example in the JOSS paper may be instructive.

• This vignette could benefit from a summary of why a new user should choose checkr over the other assertive programming tools currently available in R.

• Consider using a .github folder and ISSUE and PULL REQUEST templates. rOpenSci has some excellent examples here

[joethorley]

@boshek thanks for the helpful review - your comments all make sense to me.

[arfon]

Thanks for the thorough and thoughtful review @boshek. @joethorley - please let me know when you've had a chance to incorporate @boshek's review feedback.

[joethorley]

@arfon I've incorporated @boshek 's review feedback. In particular I've

• revised the exclusive argument documentation so that it reads "A flag indicating whether other names are not permitted."

• added a description for each function

• generated package level documentation using usethis::use_package_doc() - this is a helpful function I was not aware of.

• replaced 1:nrow(x) with seq_len(nrow(x))

• add a vignette checkr-naming which provides an overview of the functions and their naming scheme and should serve as a starting point.

• both the DESCRIPTION and JOSS paper state that the functions are designed to be used in scripts and packages.

• added a short example to the JOSS paper

• added the following text to the vignette

  In short the checkr package is recommended over the alternatives if you are looking for a set of expressive, dependency-free, pipe-friendly assertive functions with customisable object names.

• added a .github folder with customized ISSUE and PULL REQUEST templates - I didn't know about this - its very cool

[arfon]

Great. Thanks @joethorley! @boshek - would you be able to take another look?

[boshek]

@joethorley So good! In particular I really like the new vignette. Everything looks great to me. @arfon I say ship it.

[arfon]

@joethorley - At this point could you make an archive of the reviewed software in Zenodo/figshare/other service and update this thread with the DOI of the archive? I can then move forward with accepting the submission.

[joethorley]

@arfon here it is https://doi.org/10.5281/zenodo.1208141.

[arfon]

@whedon set 10.5281/zenodo.1208141 as archive

[whedon]

OK. 10.5281/zenodo.1208141 is the archive.

[arfon]

@boshek - many thanks for your review here ✨

@joethorley - your paper is now accepted into JOSS and your DOI is https://doi.org/10.21105/joss.00624 ⚡️:rocket: :boom:

[whedon]

:tada::tada::tada: Congratulations on your paper acceptance! :tada::tada::tada:

If you would like to include a link to your paper from your README use the following code snippet:

[![DOI](http://joss.theoj.org/papers/10.21105/joss.00624/status.svg)](https://doi.org/10.21105/joss.00624)

This is how it will look in your documentation:

We need your help!

Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: http://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://www.flipcause.com/secure/cause_pdetails/Mjk3Nzk=

[joethorley]

Many @arfon and @boshek - for acting as editor and reviewer - it was a positive experience

[boshek]

@joethorley Great for me as well. Looking forward to incorporating checkr in some future work.