Joss-reviews: [REVIEW]: ORIS: An interactive software tool for prediction of replication origin in prokaryotic genomes

[whedon]

Submitting author: @urmi-21 (Urminder Singh)
Repository: https://github.com/urmi-21/ORIS
Version: v1.0
Editor: @csoneson
Reviewer: @jdeligt, @holtgrewe
Archive: 10.5281/zenodo.3357162

Status

Status badge code:

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

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

@jdeligt & @holtgrewe, 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 @csoneson know.

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

Review checklist for @jdeligt

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: v1.0
• [x] Authorship: Has the submitting author (@urmi-21) 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 @holtgrewe

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: v1.0
• [x] Authorship: Has the submitting author (@urmi-21) 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, a robot that can help you with some common editorial tasks. @jdeligt, @holtgrewe it looks like you're currently assigned to review 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

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

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[csoneson]

@jdeligt, @holtgrewe - please perform your review in this issue (see further instructions in the post above). Don't hesitate to ping me if you have any questions.

[csoneson]

@urmi-21 - to simplify the review process, please have a look at the reviewer checklists above and make sure all the required parts are available in your submissions - otherwise, you can fix that already now.

[urmi-21]

@csoneson I think all the checklist points are sufficiently addressed in the submission. I'd be happy to make changes if the reviewers disagree. Thanks.

[urmi-21]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[urmi-21]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[holtgrewe]

@csoneson Is checking that the software is deposited in figshare/zenodo etc. part of the editor tasks or might this be missing from the checklist?

[holtgrewe]

OK, the software is runnable and does what it's supposed to do by the user guide and the GIFs on the home page. I cannot speak for content but trust the author that it's the same functionality they used in other published and reviewed research. @urmi-21 I have a number of additional (software engineering) suggestions that I'll open as a separate ticket in the repository.

[csoneson]

@holtgrewe The final zenodo archive is generated at the time when the submission is accepted. So there doesn't have to be one at this time.

[urmi-21]

OK, the software is runnable and does what it's supposed to do by the user guide and the GIFs on the home page. I cannot speak for content but trust the author that it's the same functionality they used in other published and reviewed research. @urmi-21 I have a number of additional (software engineering) suggestions that I'll open as a separate ticket in the repository.

@holtgrewe Thanks for the review. I really appreciate your efforts.

[jdeligt]

The submission is looking good and thanks to the suggestions by @csoneson and @holtgrewe and the subsequent changes by @urmi-21 most checks are looking excellent. I'll be testing it on some real data over the weekend on a cluster and locally to ensure it can install and run on a diverse architecture. If I encounter and deal breakers I'll link the issues here. Any suggestions or minor points I'll report as issues in the repo but won't let them hold up the progress.

[urmi-21]

The submission is looking good and thanks to the suggestions by @csoneson and @holtgrewe and the subsequent changes by @urmi-21 most checks are looking excellent. I'll be testing it on some real data over the weekend on a cluster and locally to ensure it can install and run on a diverse architecture. If I encounter and deal breakers I'll link the issues here. Any suggestions or minor points I'll report as issues in the repo but won't let them hold up the progress.

@jdeligt Looking forward to it. Thank you.

[jdeligt]

The software can be download and installed according to the instructions. I would personally prefer build instructions to be specified for those users that would like to check out the code and build themselves. A precompiled jar is subject to injections, i.e. not guaranteed to be the source of the repo, I've raised an issue urmi-21/ORIS#13 for this. I understand the target audience is less code savvy but I think this is good practice for OSS.

For my second point (urmi-21/ORIS#14) I would like the input from @csoneson . In the light of reproducible research I looked for options to log the actions performed through the GUI. I was unable to find it and the default behavior doesn't log it to STDout or a file. @urmi-21 if I missed it sorry please point it out to me. If this is indeed the case I feel it will require a lot of documentation / logging by the user to be able to use the obtained results in their research. Thereby limiting the usefulness and ease of use of the software. This is not part of the default checklist and as such would like a second opinion if we want to hold up the publication based on this or not.

[jdeligt]

@csoneson I've closed urmi-21/ORIS#13 and check the last box since the software meets the basic requirements of JOSS. I'm leaving urmi-21/ORIS#14 since I personally feel it does somewhat limit the usefullness in science especially when dealing with non coders they might not realise how important a specifc setting or algorithm might influence their findings. But that doesn't mean it is not a usefull piece of software and as such I am okay with progressing the publication.

[csoneson]

@urmi-21 - I agree with @jdeligt about the importance of somehow tracking the user's actions in the interest of reproducibility as well as record keeping. One option would be to store a snapshot of the settings when a file is saved (perhaps into a separate file, with a suffix compared to the main output file). Some of the text files output by ORIS already contain some such information, like the window size. Storing the value of all the settings (including the name of the input file) should allow the user to reproduce (and remember) the analyses going into a saved text file or plot.

[csoneson]

@urmi-21 a couple of additional small points:

• [ ] The software expects a single-sequence fasta file - I think it would be helpful if an error was raised if the user provides a multi-fasta file (i.e., if there are multiple > characters in the file). Otherwise the IDs of the following sequences will be treated as part of the sequence.
• [ ] Why is X used instead of the standard IUPAC code N to represent "any" base?
• [ ] There are several consistent (and some inconsistent) typos in the software and documentation. E.g., "increament", "sequnce", "gaped" - please have another round through and correct these

[urmi-21]

@jdeligt @csoneson Thanks for your comments and suggestions regarding tracking user actions. I can see that it will be helpful for users and that will make the software more user-friendly. But if not necessary for this publication I would like to keep this update for future releases. Thanks, @jdeligt for opening this issue in the ORIS repository and thanks for reviewing my submission. I really appreciate your efforts

[urmi-21]

@urmi-21 a couple of additional small points:

* [ ]  The software expects a single-sequence fasta file - I think it would be helpful if an error was raised if the user provides a multi-fasta file (i.e., if there are multiple > characters in the file). Otherwise, the IDs of the following sequences will be treated as part of the sequence.

* [ ]  Why is X used instead of the standard IUPAC code N to represent "any" base?

* [ ]  There are several consistent (and some inconsistent) typos in the software and documentation. E.g., "increament", "sequnce", "gaped" - please have another round through and correct these

@csoneson Thanks for your comments.

1. I have addressed the first issue and now an error message is thrown if a multi fasta file is read.

2. X is used instead of N to actually distinguish N from other bases (A, G, C, T). While searching user can choose to explicitly match N or match X, which will match N and other bases.
   E.g.
   Target seq ATGCGANTG
   Searching NTG will give one match
   Searching XTG will give two matches (ATG and NTG)

3. Sorry for not closely checking the spellings before. I have fixed the typos now.

[csoneson]

@jdeligt @csoneson Thanks for your comments and suggestions regarding tracking user actions. I can see that it will be helpful for users and that will make the software more user-friendly. But if not necessary for this publication I would like to keep this update for future releases. Thanks, @jdeligt for opening this issue in the ORIS repository and thanks for reviewing my submission. I really appreciate your efforts

@urmi-21 - I am willing to move forward with this submission without the tracking of user actions, leaving it to future releases; however, in that case I would ask you to add a statement in the paper clarifying that this feature is currently not implemented, so that users are aware of what they have to keep track of manually in order to achieve reproducibility.

[csoneson]

@jdeligt, @holtgrewe - since you have checked all the boxes in the reviewer checklists, could you please confirm whether you are satisfied with the current state of this submission, or if you have additional outstanding issues or concerns? Thanks!

[holtgrewe]

@csoneson I share @jdeligt's concerns regarding reproducible (as always with UI tools) and also reproducing builds. The first is appropriately tackled IMO once the author adds clarification to the manual. The second is addressed in an issue already.

Actually, I'd like to see a change in JOSS policy requiring automated builds (not CI but using a common, non-IDE build system approach, e.g., at least Ant or Maven for Java as in this case) and nudging towards reproducibility/tracing. However, that's not for me to decide.

Overall, yes, I think this follows the current JOSS guidelines appropriately and I thus have no concerns regarding it fulfilling JOSS requirements.

[jdeligt]

@csoneson thanks for the input and suggesting the addtion to the manual. As @holtgrewe points out build systems aren't currently coverd and there is room for improvement there. The tool and publication meet the guidelines and look forward to the authors continuing to work on the reproducibility. As such I'm happy to progress the publication.

[urmi-21]

Hi @holtgrewe @jdeligt @csoneson
Thank you very much for your comments. @holtgrewe and @jdeligt Thank you for reviewing my submission and pointing out important enhancements which could improve the software. I am really grateful.
@csoneson I have updated the paper as suggested.

Thank you

[urmi-21]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[urmi-21]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[csoneson]

@urmi-21 - I have made a PR with a couple of formatting fixes to the paper. Please review and merge, and generate a new pdf proof.

In addition to that, the next step is to make a tagged release of your software, and create a Zenodo archive. Please make sure that the Zenodo archive has exactly the same title and authors as the paper. Once that's done, please report back here with the DOI of the Zenodo archive.

[urmi-21]

@csoneson Thanks for the PR I have merged the changes. Here is the DOI generated by zenodo

10.5281/zenodo.3357162

[urmi-21]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[urmi-21]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[csoneson]

@whedon check references

[whedon]

Attempting to check references...

[whedon]

```Reference check summary:

OK DOIs

• 10.1201/9781315815015 is OK
• 10.1101/cshperspect.a010108 is OK
• 10.1111/j.1365-2958.2005.04622.x is OK
• 10.1093/bioinformatics/16.6.560 is OK
• 10.1186/1471-2105-9-79 is OK
• 10.1016/j.biosystems.2011.09.003 is OK
• 10.1016/j.biosystems.2011.11.006 is OK
• 10.1111/febs.14150 is OK

MISSING DOIs

• None

INVALID DOIs

• None
  ```

[csoneson]

@whedon set 10.5281/zenodo.3357162 as archive

[whedon]

OK. 10.5281/zenodo.3357162 is the archive.

[csoneson]

@whedon set v1.0.2 as version

[whedon]

OK. v1.0.2 is the version.

[csoneson]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

Check final proof :point_right: https://github.com/openjournals/joss-papers/pull/876

If the paper PDF and Crossref deposit XML look good in https://github.com/openjournals/joss-papers/pull/876, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.
@whedon accept deposit=true

[csoneson]

@openjournals/joss-eics - I believe we are ready to have this paper accepted!

[labarba]

The title of the release doesn't match the tag (says "v1.0" while tag is "v1.0.2")
https://github.com/urmi-21/ORIS/releases

[labarba]

@urmi-21 — I wonder if you would be amenable to making some final improvements in your paper. It felt like a bit of a slog to have to read half a page of background before getting to a statement about what the software does. Could you look into placing a few sentences about the software right at the top of your summary? I feel like the first portion of the _last_ paragraph, with slight edits, would make a good opening. The reader wants to know at the start: Who is this software for? What does it do?

Also, could you remove the link to the repository that appears twice on the second page? The link to the repo will be part of the first-page margin decorators, so you can simply mention it in the text body without adding the URL.

And while you're editing, a final suggestion I have is to try to remove some unnecessary passive constructions that make sentences long and less readable.

[urmi-21]

@csoneson Thank you for accepting the paper.
@labarba Thank you for the comments. I have fixed the tag issue. the current release in now v1.0 this is also reflected in the zenodo archive. The doi is the same i.e.

10.5281/zenodo.3357162

I have reformatted the paper as suggested. I hope it's acceptable now.

[urmi-21]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

:point_right: Check article proof :page_facing_up: :point_left:

[urmi-21]

@whedon check references

[whedon]

Attempting to check references...

[whedon]

```Reference check summary:

OK DOIs

• 10.1201/9781315815015 is OK
• 10.1101/cshperspect.a010108 is OK
• 10.1111/j.1365-2958.2005.04622.x is OK
• 10.1093/bioinformatics/16.6.560 is OK
• 10.1186/1471-2105-9-79 is OK
• 10.1016/j.biosystems.2011.09.003 is OK
• 10.1016/j.biosystems.2011.11.006 is OK
• 10.1111/febs.14150 is OK
• 10.3389/fmicb.2017.02352 is OK

MISSING DOIs

• None

INVALID DOIs

• None
  ```

[labarba]

I'm confused: the release number goes _back_ from v1.0.2 to v1.0?

[urmi-21]

I'm confused: the release number goes _back_ from v1.0.2 to v1.0?

Sorry. Yes, it might be confusing. I have made it so that it's consistent with what is mentioned in the software. I would like this release to be v1.0. I have deleted the other releases/tags from GitHub.

[labarba]

@whedon set v1.0 as version

[whedon]

OK. v1.0 is the version.

[labarba]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

Check final proof :point_right: https://github.com/openjournals/joss-papers/pull/877

If the paper PDF and Crossref deposit XML look good in https://github.com/openjournals/joss-papers/pull/877, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.
@whedon accept deposit=true

[labarba]

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

1. Check final PDF and Crossref metadata that was deposited :point_right: https://github.com/openjournals/joss-papers/pull/878
2. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.01589
3. If everything looks good, then close this review issue.

4. Party like you just published a paper! 🎉🌈🦄💃👻🤘

   Any issues? notify your editorial technical team...

[labarba]

Congratulations, @urmi-21, your JOSS paper is published! 🚀

Huge thanks to our editor: @csoneson, and the reviewers: @jdeligt, @holtgrewe — your contribution to JOSS is greatly appreciated 🙏

[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 snippets:

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

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

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

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.salsalabs.org/donate-to-joss

[urmi-21]

@holtgrewe @jdeligt @csoneson @labarba I would like to thank you all again 🙏