Joss-reviews: [REVIEW]: DynamicalBilliards.jl : An easy-to-use, modular and extendable Julia package for Dynamical Billiard systems in two dimensions.

[whedon]

Submitting author: @Datseris (George Datserus)
Repository: https://github.com/JuliaDynamics/DynamicalBilliards.jl
Version: v1.6.1
Editor: @kyleniemeyer
Reviewer: @ahwillia
Archive: 10.5281/zenodo.1059092

Status

Status badge code:

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

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 questions

@ahwillia, please carry out your review in this issue by updating the checklist below (please make sure you're logged in to GitHub). The reviewer guidelines are available here: http://joss.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @kyleniemeyer 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 (v1.6.1)?
• [x] Authorship: Has the submitting author (@Datseris) 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. @ahwillia 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 as 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

[kyleniemeyer]

👋 @Datseris @ahwillia @mlxd

[Datseris]

Thank you very much for accepting to review my submission.

[mlxd]

Happy to participate. It will likely be the coming weekend before I can spend time going through everything in detail. As suggested by @kyleniemeyer I will leave comments to the above check-box items.

[ahwillia]

Overall this looks excellent - really appreciate your attention to detail while putting this together!

@Datseris - what do you think about having an examples/ folder containing jupyter notebooks? These could just contain the code that you have under Tutorials in the docs (but without the long text). That way people can flip back and forth between reading your docs and trying it. Right now there is an awkward copy-paste step.

Other than that I'm inclined to approve this. But we can wait for @mlxd to weigh in.

[ahwillia]

Oh two other short comments

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

Is this listed anywhere explicitly?

References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

Do you mind adding DOI links to the references in your paper.md document? Thanks!

[Datseris]

Thanks for the kind words @ahwillia . I've just added guidelines for issue reports.

I will now do your other requests:

• Add DOIS to paper.md
• Add a dedicated paragraph on the homepage of the documentation about support (we have our own chatroom on gitter)
• Add a dedicated contributors_guide file either in the repo first page or in the documentation page.

About the Jupyter notebooks... Is it possible to avoid this step? My only issue is that I have never used Jupyter and it make take a while/be tricky to set it up etc.

I know it is kind of annoying to copy/paste that much but fortunately the documentation allows you to copy an entire code-block by clicking the top - right corner of each code block.

[ahwillia]

Yep - I'm fine with no jupyter notebooks, just a suggestion.

On Wed, Nov 15, 2017 at 3:21 PM, George Datseris [e-mail]
wrote:

Thanks for the kind words @ahwillia https://github.com/ahwillia . I've
just added guidelines for issue reports.

I will now do your other requests:

• Add DOIS to paper.md
• Add a dedicated paragraph on the homepage of the documentation about
  support (we have our own chatroom on gitter)
• Add a dedicated contributors_guide file either in the repo first
  page or in the documentation page.

About the Jupyter notebooks... Is it possible to avoid this step? My only
issue is that I have never used Jupyter and it make take a while/be tricky
to set it up etc.

I know it is kind of annoying to copy/paste that much but fortunately the
documentation allows you to copy an entire code-block by clicking the top -
right corner of each code block.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/openjournals/joss-reviews/issues/458#issuecomment-344716545,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAm20dI5z-Qc2fx_q_LCBZimQScZFJIAks5s20fagaJpZM4QfdCf
.

[Datseris]

@ahwillia I have done the requested changes. Now all citations of the paper.md have DOIs, and the homepage has 2 sections: One for support and one for contributing.

See this link: https://juliadynamics.github.io/DynamicalBilliards.jl/latest/#support

Of course, the changes apply only on the latest version, and not on the release tag 1.6.1. Should a new tag be required let me know and I will tag it.

[ahwillia]

I'm happy to accept this - I was able to install, run tests, and reproduce some simple plots. The package supports a well-defined need and is reasonably mature. Looking forward to seeing future developments!

Now we'll just wait on @mlxd to check it over.

[mlxd]

Everything is clearly documented, installation and use is as described. This is a very useful package, and I'd be happy to accept this too. I agree with all of @ahwillia's comments and checkboxes.

I do have one suggestion on the documentation for the examples:
For the Julia-logo Billiard example (and potentially elsewhere) [https://juliadynamics.github.io/DynamicalBilliards.jl/stable/tutorials/examples/], the file save path seems Windows specific (sname = "C:\*\anim").

While it works for me on Mac, it does create a lot of "C:***\anim_99.png" files in the current directory, which may go elsewhere on a Windows machine due to the path (I have not tested). I would suggest a more platform-independent save string with the correct format for Win/Mac/LNX. Maybe explicitly setting the savedir as the current working directory (pwd()) would suffice for all platforms, and users can run the example code without changing. Though, feel free to ignore this, as it is merely a suggestion.

[Datseris]

This was simply a "dummy" name (indicated by the *)... I expected users to put as a string wherever they want to save their files.

I will just replace pwd() since you are right, it is better.

[mlxd]

Great. Excellent work on this. It was very easy to review and recommend for acceptance. Unless @ahwillia has anything else, I think we are done.

[Datseris]

Awesome. Thank you for the swift and concise review!

[kyleniemeyer]

@Datseris sounds like we are nearly good to go—let me know when you make the change mentioned by @mlxd above.

[Datseris]

@kyleniemeyer the change is already done: https://juliadynamics.github.io/DynamicalBilliards.jl/latest/#julia-billiard-animation

[kyleniemeyer]

@Datseris ok, there are a few changes required for the paper.

1. The references need to be extracted from the Markdown paper file, put in a BibTeX .bib file, and then cited in the paper. You can see an example in the JOSS author guidelines. This is necessary for our LaTeX-based compiling of the paper PDF, and also depositing the citation info in CrossRef.

2. The animated GIF you have is nice for the README, but it won't work for the paper, which is generated as a static PDF. Instead of the logo, could you perhaps include an example figure using results produced by the package (perhaps from one of the examples/tutorials), along with a brief description? That would be more useful and informative.

3. As for the actual content of the paper, the layout you have is not quite appropriate—again, it works for a README-type document, but not the paper. Links to your software repository will already be included in the paper (see an example compiled PDF for a different paper under review), so please remove those from the top.

Also, to the summary or introductory paragraph, could you describe the research application of the software for a diverse, non-specialist audience? Many people may not be familiar with billiard systems in the context of research.

1. A few minor typos/suggested edits:
2. "In [2] this is described perfectly, where Bunimovich and Vela-Arevalo (two pioneers in the field) summarize new insights in the field of dynamical billiards" -> "Bunimovich and Vela-Arevalo (two pioneers in the field) summarized new insights in the field of dynamical billiards [2]."
3. "Our package has plenty of applications" is quite informal and not descriptive
4. "which results to accuracies" -> "which results in accuracies"
5. I would eliminate the use of italics to emphasize words throughout; it makes the paper read as more persuasive than is intended/appropriate, I think.

[Datseris]

@kyleniemeyer I have done all the changes you requested. Please see the latest files here: https://github.com/JuliaDynamics/DynamicalBilliards.jl/tree/master/paper

I have a problem though. You said that "links to the repository will be included in the paper". I saw the example you cited but nowhere in that example there was a link to a documentation page. There was a link to a GitHub repository, but for me this is not enough.

I would like to have a direct link to the documentation of the package somewhere in the paper. This could be either at the side, as part of this typical information or in-text. I do not mind.

The users of a package are users, not developers. They should never have to know what git or GitHub is. To use the package you should just have a link to the documentation without having to go through links to other links to search for a documentation page.

[kyleniemeyer]

@Datseris sure, that's fine—perhaps you could link on "detailed documentation archive" in the summary at the top of the paper?

[Datseris]

@kyleniemeyer I am glad we could come to an agreement. I have added an in-text hyperlink.

Is that all from my side?

[kyleniemeyer]

@Datseris thanks! I'm going to see if the paper compiles. The last step from you is archiving the final version of the software etc. (like using Zenodo) and then telling me the DOI here; but, wait until we're sure the paper doesn't need any more changes.

[kyleniemeyer]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[kyleniemeyer]

@arfon ruh roh. any way to see what went wrong?

[arfon]

Yeah, I'm debugging now. Getting errors reported back in here is somewhat tricky.

[whedon]

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

 pandoc-citeproc: Could not find none
CallStack (from HasCallStack):
  error, called at src/Text/CSL/Pandoc.hs:224:39 in pandoc-citeproc-0.10.4-BdOyQb33rzG2TMOLj4Fbp9:Text.CSL.Pandoc
pandoc: Error running filter pandoc-citeproc
Filter returned error status 1
Looks like we failed to compile the PDF

[arfon]

@Datseris - looks like you need to link to the paper.bib file. You currently have this set as bibliography: none

[whedon]

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

 pandoc-citeproc: Could not find none
CallStack (from HasCallStack):
  error, called at src/Text/CSL/Pandoc.hs:224:39 in pandoc-citeproc-0.10.4-BdOyQb33rzG2TMOLj4Fbp9:Text.CSL.Pandoc
pandoc: Error running filter pandoc-citeproc
Filter returned error status 1
Looks like we failed to compile the PDF

[Datseris]

@arfon I have changed it to bibliography: paper.bib. I hope this is enough.

[Datseris]

@kyleniemeyer I actually do not know what you mean with:

The last step from you is archiving the final version of the software etc. (like using Zenodo) and then telling me the DOI here;

Isn't the DOI the duty of the Journal and not the author? I also do not know what "Zenodo" is.

[kyleniemeyer]

@Datseris we provide a DOI associated with the paper, but the author is responsible for archiving the accepted version of the software (i.e., your repository on GitHub). We do not archive the software and associated material, just the paper. You can see an example in a recently published paper with the "Archive" link to the left.

This is from the JOSS About page:

Upon successful completion of the review, deposit a copy of your (updated) software repository with a data-archiving service such as Zenodo or figshare, issue a DOI for the software archive, and update the review issue thread with your DOI.

I recommend using Zenodo, but Figshare is another option. Both are free, and used commonly for this purpose.

[kyleniemeyer]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

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

 pandoc-citeproc: Could not find none
CallStack (from HasCallStack):
  error, called at src/Text/CSL/Pandoc.hs:224:39 in pandoc-citeproc-0.10.4-BdOyQb33rzG2TMOLj4Fbp9:Text.CSL.Pandoc
pandoc: Error running filter pandoc-citeproc
Filter returned error status 1
Looks like we failed to compile the PDF

[Datseris]

@kyleniemeyer okay I see. Seems simple enough. Let me know when whedon can compile the pdf and then I will do it. Or should I do it now?

[kyleniemeyer]

Let's wait to see if any other changes are needed for the paper first, since it looks there is still some problem.

@arfon it looks like whedon is raising the same error, but I can see in the paper.md that the bibliography seems set correctly now.

[arfon]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

https://github.com/openjournals/joss-papers/blob/joss.00458/10.21105.joss.00458.pdf

[Datseris]

@arfon The compiled pdf does not have a a hyperlink to the documentation page.

[kyleniemeyer]

@Datseris the link is actually present if you download the PDF, but the text is just not colored blue.

@arfon is there perhaps a hyperref setting for href links that is needed in the LaTeX template?

[kyleniemeyer]

(Sorry for the paper gen hiccups @Datseris, we are still testing out our new automated paper compilation)

[Datseris]

No problem! I also apologize because I did not realise that there was a link there. If you can add the standard hyperref color that would be much appreciated. If in the end of the day it appears not to be possible, then I can live with it being a "hidden link".

As a side note: how soon after the pdf generation works can I get a working DOI/reference to your journal? I am going to submit a publication (to another journal) next week and I am thinking if I can wait so I can include an official JOSS reference instead of a reference to the documentation page in my paper.

[kyleniemeyer]

@Datseris you will have the JOSS DOI basically as soon as we sort out this paper issue, so you should be able to include the full published JOSS reference.

[Datseris]

That is excellent. Since the paper seems to be in a final form besides this small hyperref detail, should I go ahead and perform this "Zenodo" process you described?

[kyleniemeyer]

Actually, I caught one final typo fix to make first:
change

The package is mainly used to simulate any kind of 2 dimensional system where particle motion is interrupted by collisions, like e.g. a gas infused with big molecules.

to

The package is mainly used to simulate any kind of two-dimensional system where particle motion is interrupted by collisions, e.g., a gas infused with big molecules.

Once you make that fix, please go ahead and archive the repository, and then report the DOI here. On Zenodo, you can do this manually by uploading a .zip (e.g.) of the repository; alternatively, Zenodo has a nice GitHub integration where it will automatically grab everything if you make a release on GitHub. (I do this for most of my own software packages.)

[Datseris]

Wow, the process was extremely smooth and straightforward!
I am pasting the badge here:

[kyleniemeyer]

@whedon set 10.5281/zenodo.1059092 as archive

[whedon]

OK. 10.5281/zenodo.1059092 is the archive.

[arfon]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

https://github.com/openjournals/joss-papers/blob/joss.00458/10.21105.joss.00458.pdf

[arfon]

@kyleniemeyer @Datseris - the links in the paper are looking a bit better now.

[kyleniemeyer]

Yes, looks great! Ready to accept/publish.

[arfon]

@ahwillia - many thanks for your review here and to @kyleniemeyer for editing this submission ✨

@Datseris - your paper is now accepted into JOSS and your DOI is https://doi.org/10.21105/joss.00458 ⚡️ 🚀 💥

[Datseris]

Awesome! Thanks everybody for their effort!

[Datseris]

@ahwillia @kyleniemeyer I am sorry about this but is it possible to recompile the paper? Or "update" it?

I realized that even though I am acknowledging people properly in the repository page, this is not very transparent in the paper. Therefore I copied the Acknowledgements page from the repository and added it to the paper.md as well, so that they are more transparent.

I am sorry for forgetting this.

[arfon]

@Datseris - yes, that's OK. The @username syntax in the paper is confusing Pandoc though:

[arfon]

I think you should be able to quote their usernames in back-ticks e.g.

`@arfon`

[Datseris]

@arfon Thanks a lot for the flexibility you provide. I changed the nametags to have back-ticks.

[Datseris]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

https://github.com/openjournals/joss-papers/blob/joss.00458/joss.00458/10.21105.joss.00458.pdf

[Datseris]

@arfon everything is fine with the pdf! The only issue is that when I go to the DOI page,
the pdf linked there is not updated (it still has the old version): http://joss.theoj.org/papers/10.21105/joss.00458

[arfon]

@arfon everything is fine with the pdf! The only issue is that when I go to the DOI page,
the pdf linked there is not updated (it still has the old version): http://joss.theoj.org/papers/10.21105/joss.00458

Yep, I've not updated them yet. Will get to this either later today or tomorrow.

[arfon]

@arfon everything is fine with the pdf! The only issue is that when I go to the DOI page,
the pdf linked there is not updated (it still has the old version): http://joss.theoj.org/papers/10.21105/joss.00458

@Datseris - ok, these should be updated now.

[Datseris]

@arfon thank you very much, everything looks very nice. Quick question: what is the "formal"/official form for the bibtex entry for your journal? From my DOI link I can see:

Citation:
Datseris, (2017). DynamicalBilliards.jl: An easy-to-use, modular and extendable Julia package for Dynamical Billiard systems in two dimensions.. Journal of Open Source Software, 2(19), 458, doi:10.21105/joss.00458

Is there any way to export the citation as a bibtex entry?

[kyleniemeyer]

@Datseris you can try using https://www.doi2bib.org/; we used to rely on it, but it isn’t always working.

[danielskatz]

also see https://github.com/openjournals/joss/issues/341