Joss-reviews: [REVIEW]: OpenEPSim: An Open Exclusion Process Simulation Tool

[whedon]

Submitting author: @caley (Caley Finn)
Repository: https://github.com/caley/OpenEPSim
Version: v0.1.0
Editor: @arfon
Reviewer: @stuartcampbell, @dlagrava
Archive: 10.5281/zenodo.1218513

Status

Status badge code:

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

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

@stuartcampbell & @dlagrava, 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.

Review checklist for @stuartcampbell

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.1.0)?
• [x] Authorship: Has the submitting author (@caley) 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)?

Review checklist for @dlagrava

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.1.0)?
• [x] Authorship: Has the submitting author (@caley) 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?
• [ ] 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).
• [ ] 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?
• [ ] 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. @stuartcampbell, 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]

--> Check article proof :page_facing_up: <--

[arfon]

@stuartcampbell, @dlagrava - 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.

[dlagrava]

@arfon This is actually my first review, I really appreciate the JOSS idea and I am very happy to collaborate.

I have started the review and even though the documentation looks good, when trying to run the code I am not getting anywhere (I let the sample run for 1 hour). How should I proceed forward? Do we contact the author? If so, how?

Thanks a lot.

[arfon]

I have started the review and even though the documentation looks good, when trying to run the code I am not getting anywhere (I let the sample run for 1 hour). How should I proceed forward? Do we contact the author? If so, how?

Thanks for your efforts thus far @dlagrava. We encourage you to engage the author (@caley) either here in this GitHub issue thread or by opening issues on the software repository (https://github.com/caley/OpenEPSim) and linking to those issues here.

[dlagrava]

@caley Hello, I am reviewing your submission to JOSS. Both the installation from the release and compilation from source using maven work as metioned on your README.md.

However, when I try to run the sample code (esap.json), I don't get any results after 1 hour. This both from the release .jar and generating one with maven. I also see no CPU activity from running the code during this time. I have tried both OpenJDK and OracleJDK 1.8 on my Ubuntu machine. Could you tell me if there are extra requirements on the JDK or so?

Thanks a lot.

[caley]

@dlagrava First off, thanks for taking the time to do the review! The sample file asep.json should take less than 30 seconds to run (13 seconds on my new laptop), so something is going wrong.

The Oracle JDK should definitely be fine, and you would get a error message from the Java run time if there was a problem. Have you run the command exactly as in the README.md file? The program expects to read the input configuration from stdin (so you need the input redirection '... < samples/asep.json ...'). If you leave out the '<' you'll get the behaviour you see - no CPU activity, as the program is actually just waiting for input.

If that doesn't work, can you send me the exact commands that you have run? In any case, I'll update the README to emphasise that it expects the input from stdin.

[dlagrava]

@caley Thanks for the info, this is what I was doing wrong, silly me. I misinterpreted the < and > as markers for the input. Personally I prefer allowing command line parameters for the main program, but this is totally my own opinion.

[dlagrava]

@caley I have almost finished the review. I am happy with the documentation of the repo and the code. The only thing from the checklist I see missing on the repo is a section with guidelines on how to contribute to the code, file bugs and ask general questions about it. Could you please add this?

[stuartcampbell]

I'm also nearly done with the review - I agree with @dlagrava about the missing community aspects.

[caley]

@dlagrava, @stuartcampbell I've added a section to the readme on contributing.

[dlagrava]

@arfon I have finished my review of OpenEPSim, everything is there, so from my side this is good to go.

[stuartcampbell]

@arfon - Sorry I forgot to post a message saying that I had finished my review.

[arfon]

@caley - 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.

[caley]

@arfon - I've put it on Zenodo. The doi is https://doi.org/10.5281/zenodo.1218513.

[arfon]

@whedon set 10.5281/zenodo.1218513 as archive

[whedon]

OK. 10.5281/zenodo.1218513 is the archive.

[arfon]

@stuartcampbell & @dlagrava - many thanks for your reviews here ✨

@caley - your paper is now accepted into JOSS and your DOI is https://doi.org/10.21105/joss.00650 ⚡️: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.00650/status.svg)](https://doi.org/10.21105/joss.00650)

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=