[REVIEW]: PupillometryR: An R package for preparing and analysing pupillometry data

[whedon]

Submitting author: @samhforbes (Samuel Forbes)
Repository: https://github.com/samhforbes/PupillometryR
Version: v0.0.3
Editor: @oliviaguest
Reviewer: @paulinepalma, @Athanasiamo
Archive: 10.5281/zenodo.3897291

⚠️ JOSS reduced service mode ⚠️

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

Status

Status badge code:

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

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) by leaving comments 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

@paulinepalma & @Athanasiamo, 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.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @oliviaguest know.

✨ Please try and complete your review in the next six weeks ✨

Review checklist for @paulinepalma

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

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

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@samhforbes) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• 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

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• 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

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

Review checklist for @Athanasiamo

Conflict of interest

• I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

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

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Contribution and authorship: Has the submitting author (@samhforbes) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• 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

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• 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

• Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• State of the field: Do the authors describe how this software compares to other commonly-used packages?
• Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[whedon]

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @paulinepalma, @Athanasiamo it looks like you're currently assigned to review this paper 🎉.

⚠️ JOSS reduced service mode ⚠️

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

⭐ Important ⭐

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:

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

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@whedon generate pdf

[whedon]

Reference check summary:

OK DOIs

- 10.12688/wellcomeopenres.15191.1 is OK
- 10.3758/s13428-017-1007-2 is OK
- 10.3758/s13428-018-01190-1 is OK
- 10.31234/osf.io/gvcxb is OK
- 10.1007/978-1-4757-7107-7 is OK
- 10.1111/j.1467-7687.2008.00805.x is OK
- 10.3758/s13428-011-0109-5 is OK
- 10.1177/2331216519832483 is OK
- 10.3758/s13423-018-1432-y is OK
- 10.1177/2331216518800869 is OK
- 10.1126/science.143.3611.1190 is OK
- 10.1037/h0026952 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

👉 Check article proof 📄 👈

[oliviaguest]

👋 @paulinepalma, @Athanasiamo: Any code-related questions feel free to open issues on the package's repo itself and then link to whatever issue you open from here. Everything important about the PDF or the package, like high-level questions to me or @samhforbes, discussions and feedback, just leave it here as a comment directly. ✨ 🌷

[drmowinckels]

General checks

❌ License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
- LICENCE file does not contain any information on the type of licence to apply to the package.
- recommendation: utilise usethis::use_[xx]_licence to create a valid licence file.
- Noted in this isse
✅ Contribution and authorship: Has the submitting author (@samhforbes) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
- One other contributor in a single minor commit. This looks ok to me.
- Another package author is listed without any commit history. This person is mentioned in the paper acknowledgement.

Documentation

✅ Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
* since the package is also on CRAN, installation instructions should clearly state that, and only point to github installation for development versions. I had to read the paper to know it was on CRAN. noted in this issue
➖ Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
* yes but not in an ideal way. in my opinion.
* Great with data shipped with the package so one can give the functions a go.
* in my opinion, the readme as a whole should be moved into a vignette folder and be compiled as such. This will also then run the vignette code during build checks, making sure that the vignette is actually executable (easiest way to do so it to use usethis::use_vignette() ). Noted in this issue
* please add link to Sylvains tutorial in the README Noted in this issue
* A new readme just highlighting some core functionality of the package can be used in stead.
* Instead of informing about patch updates ( like the top of the current readme), use a NEWS file instead for this sort of information. noted in this issue
✅ Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)? Good
✅ Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
- function examples are run on build checks, and everything checks out fine.
- But there are no CI checks.
❌ 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.
- There is no such information, as noted in this issue

[oliviaguest]

@Athanasiamo thank you for this, can you also check/tick them off above in the OP as well?

[oliviaguest]

@openjournals/joss-editors @openjournals/joss-eics has anybody seen a case where the reviewer cannot tick/check the boxes above? @Athanasiamo is not able to interact with the OP, is there a simple solution we are not aware of? She is logged in and I have sent her a video of what it looks like from my end. I have no idea what is wrong — thanks.

[danielskatz]

@whedon re-invite @Athanasiamo as reviewer

[whedon]

The reviewer already has a pending invite.

@athanasiamo please accept the invite by clicking this link: https://github.com/openjournals/joss-reviews/invitations

[drmowinckels]

jup that did it. Seems like I did not complete the invite when I clicked it the first time. Sorry about the bother.

[paulinepalma]

Hi Olivia, I think I have the same problem as Athanasia. Could you please send me the invite again? Sorry about that! Pauline Le mar. 2 juin 2020, à 09 h 53, whedon <notifications@github.com> a écrit :

…

The reviewer already has a pending invite. @Athanasiamo <https://github.com/Athanasiamo> please accept the invite by clicking this link: https://github.com/openjournals/joss-reviews/invitations — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2285 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AKOWI7KUNVHXYZYPF5SJSBDRUT75VANCNFSM4NQCGMHQ> .

-- Sent from my ouija board

[danielskatz]

@paulinepalma - Can you try just accepting the invitation in the first comment in this thread?

[oliviaguest]

@danielskatz thank you so much for this! I should have realised it was that. 😊

[danielskatz]

@oliviaguest - if the invite has expired, the whedon re-invite command can also be used, but in this case, it seems unlike that the invite would have expired :)

[paulinepalma]

Hi Daniel, That is what I did initially, but here is the message I got: "Sorry, we couldn't find that repository invitation. It is possible that the invitation was revoked or that you are not logged into the invited account." I am logged into my github account. Pauline Le mar. 2 juin 2020, à 10 h 27, Daniel S. Katz <notifications@github.com> a écrit :

…

@oliviaguest <https://github.com/oliviaguest> - if the invite has expired, the whedon re-invite command can also be used, but in this case, it seems unlike that the invite would have expired :) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2285 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AKOWI7P2UYDIOMEBQH6D2YDRUUD3VANCNFSM4NQCGMHQ> .

-- Sent from my ouija board

[oliviaguest]

@whedon re-invite @paulinepalma as reviewer

[whedon]

OK, the reviewer has been re-invited.

@paulinepalma please accept the invite by clicking this link: https://github.com/openjournals/joss-reviews/invitations

[oliviaguest]

@paulinepalma lemme know if that works, hopefully yes! 🌺

[paulinepalma]

It works! Thank you very much :) Le mar. 2 juin 2020, à 10 h 58, Olivia Guest <notifications@github.com> a écrit :

…

@paulinepalma <https://github.com/paulinepalma> lemme know if that works, hopefully yes! 🌺 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2285 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AKOWI7IAXQYVYQP4KDBLDUTRUUHS3ANCNFSM4NQCGMHQ> .

-- Sent from my ouija board

[paulinepalma]

@oliviaguest I started going through the repository and I am having difficulties installing the developper version of the package (under R version 4.0.0). I ended up installing the CRAN version, which works. It could be an issue with my own computer, so I am unsure whether I should mention this in the issues?

[oliviaguest]

@paulinepalma I think this is exactly the kind of problem/solution @samhforbes should be able to solve for users (and might even already know how to solve). So, yes, please try and discuss with him here. 💯

[samhforbes]

Yes @paulinepalma if you can let me know where it fails, we can hopefully work it out. The development version was made with 4.0.0

[oliviaguest]

Also yes — sorry! — @paulinepalma feel free if you want (if you think it's needed) to create a specific issue for that at the repo. Basically whatever is sensible for you and @samhforbes. As always link to it from here if you do make any related issues. 🌷

[paulinepalma]

Ok! I'll create the issue now.

[paulinepalma]

General checks
✅ Contribution and authorship: Has the submitting author (@samhforbes) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
One contributor (TJ Mahr) made a small commit at some point, should they be in the acknowledgements somewhere? They are also mentioned in the vignette.

Functionality
➖Installation: Does installation proceed as outlined in the documentation?
Problem encountered with the developer installation, not with the released CRAN version (samhforbes/PupillometryR#12 (comment)). Maybe OS problem on my end? It may be good to specify which version of R and operating system are needed to run the package.

Documentation
➖Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
Examples from the vignette are clear and detailed. However, with the released version, an error occurs when retrieving the “vignette(‘PupillometryR’)” potentially because the released version does not include the vignette (see samhforbes/PupillometryR#12 (comment))
✅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
Link to the issues board recently added to the Readme.

Software paper
✅Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
A few typos, see samhforbes/PupillometryR#13 (comment)
➖References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?
There are a few issues with the references of the paper and of the Readme file, see samhforbes/PupillometryR#14 (comment)

[oliviaguest]

@paulinepalma @Athanasiamo thanks for both your reviews so far! Super helpful and I really appreciate the work you are putting in. 👏

I edited your comments. I hope/think I left only the points with relevant info over and above the tick (if I removed anything vital, please feel free to put it back — and sorry if so!). TBC it's to help @samhforbes focus on what he needs to address. The stuff that just has a ✅ is already in the OP. I hope this makes sense!

[oliviaguest]

Yeah — sorry! I got paranoid. 😑
Apologies, @xuanxu!

[oliviaguest]

@samhforbes if you are OK with the final proofs, I will ask to get this properly published ASAP. 🥳

[samhforbes]

@oliviaguest this looks good!

[oliviaguest]

@openjournals/joss-eics please publish this! 😸

[arfon]

@whedon accept deposit=true

[whedon]

Doing it live! Attempting automated processing of paper acceptance...

[whedon]

🐦🐦🐦 👉 Tweet for this paper 👈 🐦🐦🐦

[whedon]

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 Creating pull request for 10.21105.joss.02285 joss-papers#1506
1. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.02285
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? notify your editorial technical team...

[arfon]

@paulinepalma, @Athanasiamo - many thanks for your reviews here and to @oliviaguest for editing this submission ✨

@samhforbes - your paper is now accepted into JOSS ⚡🚀💥

[whedon]

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

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

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

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.02285">
  <img src="https://joss.theoj.org/papers/10.21105/joss.02285/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: https://joss.theoj.org/papers/10.21105/joss.02285/status.svg
   :target: https://doi.org/10.21105/joss.02285

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: https://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://numfocus.org/donate-to-joss