Joss-reviews: [REVIEW]: rtdpy: A python package for residence time distributions

[whedon]

Submitting author: @MatthewFlamm (Matthew Flamm)
Repository: https://github.com/Merck/rtdpy
Version: v0.5.1
Editor: @xuanxu
Reviewer: @ctdegroot, @dandavies99
Archive: 10.5281/zenodo.3371640

Status

Status badge code:

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

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

@ctdegroot & @dandavies99, 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 @xuanxu know.

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

Review checklist for @ctdegroot

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: v0.5.1
• [x] Authorship: Has the submitting author (@MatthewFlamm) 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 @dandavies99

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: v0.5.1
• [x] Authorship: Has the submitting author (@MatthewFlamm) 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. @ctdegroot, @dandavies99 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:

[ctdegroot]

A few comments as I am going through the review:

• Please add your import statements to the example given in the readme.
• I do not see any community guidelines if someone wanted to contribute to the project.
• Please add instructions to run the tests; I'm guessing pytest?

[MatthewFlamm]

Thanks @ctdegroot. I attempted to address items 1 and 3.

For item 2, I need to get internal guidance on this and will update here once I have a path forward.

[ctdegroot]

@MatthewFlamm Looks good. Regarding item 2, the checklist says "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". I think that (1) could be optional (@xuanxu please advise), but reporting issues and seeking support should be mandatory and is probably easy for you to do.

[MatthewFlamm]

Thanks for the friendly suggestion on path forward @ctdegroot. I'm exploring being able to satisfy the checklist to the fullest, but there is a middle way that satisfies 90% of the intent IMO. I propose that instead of a 'Contributing to the software' section that includes point 1) from the cheklist, that this submission have a 'Extending the software' section that describes how to create a new RTD model class, for example. But, it will not give explicit instructions on how to contribute it back to the repo, nor will it say that it cannot be contributed back. This would give detailed instructions on the 'How to develop on top of the package', but make no statement on 'How to make the PR back into the library'.

If this is not good enough, I will continue pursuing the fullest method of 'Contributing to the software' avenue.

[ctdegroot]

@MatthewFlamm This makes sense to me and I would accept it. There is nothing stopping someone from making a PR anyways, and it would be up to you if you'd want to accept it.

[xuanxu]

@MatthewFlamm As stated in the review criteria: There should be clear guidelines for people wanting to contribute to the software. Here the definition of _contribute_ is quite relaxed: proposing a new feature, finding a bug or just fixing a typo in the readme can be considered contributions. Of course that doesn't mean any of their contributions will be accepted or merged into the software, but if someone want to help there should be a clear statement on how to do it, so a user can easily find what is the _official_ preferred way (a PR, a github issue, an email?).

That could be a detailed CONTRIBUTING.md file or something as simple as a short sentence like "_If you want to contribute code, fixes, or report bugs please open a Github issue here_",
but you have to include some pointer in the right direction for the users willing to help.

[MatthewFlamm]

Thanks for the input. I added a CONTRIBUTING.md file.

[ctdegroot]

@xuanxu With this latest addition, I am finished with my review. This is a nicely packaged piece of software that seems really useful for chemical reactor engineering. Well done @MatthewFlamm !

[xuanxu]

@ctdegroot Great, thanks!

[dandavies99]

It was a pleasure to review this software, really nice work @MatthewFlamm. Even though the application area is quite outside my own area of expertise in chemistry, I found the package easy to install, use and understand.

Like @ctdegroot, my main concern was the lack of community guidelines for contribution, but this has been dealt with now. My only remaining, very minor suggestion would be to elaborate slightly on how tests should be carried out, and roughly what the expected output should look like. There are lots of ways to implement tests in Python and as someone who has never used pytest before, it took me a little while to work out what I was doing.

Other than that, the repo and paper both look to be in very good shape!

[MatthewFlamm]

Thanks @dandavies99 . While in my experience pytest is a widely used test framework in python, I think it is a good idea to lower the barrier to entry as much as possible. This is a good suggestion. To this end, I've added a short section in the README.md about how to setup a development/testing environment and invoke the tests.

IMO the default output is easy to understand from pytest. I hope it suffices to link directly to the pytest documentation, which I've found to be very readable and useful. If there was something specific you wanted clarity on in the test results output, I could add more clarification.

to elaborate slightly on how tests should be carried out,

I had interpreted this to be about how to run the tests, not to understand the tests themselves. Do you think the tests themselves need more documentation?

[dandavies99]

This looks great @MatthewFlamm; exactly what was needed to lower the barrier to entry. @xuanxu I'm also done with my review now and will be very happy to see this useful package in JOSS.

[xuanxu]

Thanks @dandavies99!

[xuanxu]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

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

[xuanxu]

@whedon check references

[whedon]

Attempting to check references...

[whedon]

```Reference check summary:

OK DOIs

• 10.1016/0009-2509(53)80001-1 is OK
• 10.1007/s12247-015-9238-1 is OK
• 10.1021/ie50579a034 is OK
• 10.1029/2002gl014743 is OK
• 10.1038/35000537 is OK

MISSING DOIs

• None

INVALID DOIs

• None
  ```

[xuanxu]

@MatthewFlamm I found a typo in the paper, Merck/rtdpy#1 should fix it.

[MatthewFlamm]

On triple reading this, I noticed a few minor things as well. I was inconsistent in capitalization in one list. I also am missing the journal title for one reference. I will regenerate PDF here when done.

[MatthewFlamm]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

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

[MatthewFlamm]

Im still missing the journal title for the Levenspiel reference that has the title starting with Longitudinal, even though I have the journal in the bib file. I need to read up on bib file format, I am probably missing something.

[xuanxu]

@MatthewFlamm I can see the title of that article in the references, Longitudinal Mixing of Fluids Flowing in Circular Pipes, right before the other Levenspiel book.

[MatthewFlamm]

I meant the journal name, https://github.com/Merck/rtdpy/blob/master/paper/paper.bib#L32

[MatthewFlamm]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

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

[MatthewFlamm]

Fixed it, I had to escape the ampersand

[xuanxu]

@whedon check references

[whedon]

Attempting to check references...

[whedon]

```Reference check summary:

OK DOIs

• 10.1016/0009-2509(53)80001-1 is OK
• 10.1007/s12247-015-9238-1 is OK
• 10.1021/ie50579a034 is OK
• 10.1029/2002gl014743 is OK
• 10.1038/35000537 is OK

MISSING DOIs

• None

INVALID DOIs

• None
  ```

[xuanxu]

Ok, everything looks good @MatthewFlamm, here are the next steps:

• Please make a new tagged release that includes all changes made during this review
• Archive that release in Zenodo
• Check the Zenodo deposit has the correct metadata: title and author name should match the paper; you may also add your ORCID.

Once you do that please report here the version number and the Zenodo DOI.

[MatthewFlamm]

Do I need to update the version number in the paper too, if I update the version for the state of the review?

[xuanxu]

Where do you mention the version number in the paper? I think the paper is OK as it is now, I don't see any mention to a specific version in it.

[MatthewFlamm]

Sorry for the confusion. For some reason I thought the version number at the top of this review issue was taken from the metadata of the paper. You are right that the version number is nowhere in the paper.

[MatthewFlamm]

I archived on zenodo

version: 0.5.1

Zenodo DOI: 10.5281/zenodo.3371640

link

[MatthewFlamm]

Thanks @dandavies99 and @ctdegroot for making this open source package better. I appreciate your comments as it is always hard to view your own creation through others eyes.

[xuanxu]

Thanks, @MatthewFlamm!

[xuanxu]

@whedon set v0.5.1 as version

[whedon]

OK. v0.5.1 is the version.

[xuanxu]

@whedon set 10.5281/zenodo.3371640 as archive

[whedon]

OK. 10.5281/zenodo.3371640 is the archive.

[xuanxu]

All ready por publication :tada:. Pinging @openjournals/joss-eics for final acceptance.

[kyleniemeyer]

Hi @MatthewFlamm, I'm nearly ready to accept this, but I noticed that in the paper Figure 1 isn't referenced/discussed in the text. Could you add a sentence or two that does this?

[MatthewFlamm]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

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

[MatthewFlamm]

@kyleniemeyer I added the generating code for Figure 1 as an example usage. The formatting now isn't my favorite with the code snippet after the figure, but I think it still all makes sense. The code can simply be pasted in IPython, for example, and run after installing rtdpy and matplotlib. plt.show() may or may not be necessary depending on the setup of the IPython console and matplotlib settings. A basic python terminal execution would require a plt.savefig('filename') command, etc.

If this is all too nuanced, I'm also okay removing the code block entirely since it may not run as expected in everyone's console. We can just leave as the explanatory text.

[kyleniemeyer]

@MatthewFlamm I like what you added—code snippets like that are definitely encouraged when practical.

[kyleniemeyer]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

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

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

[MatthewFlamm]

OH do I need a new zenodo archive?

[kyleniemeyer]

@MatthewFlamm nope, since the software wasn't changed—the final paper itself is archived by us.

[kyleniemeyer]

@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/914
2. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.01621
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...

[kyleniemeyer]

Congrats @MatthewFlamm on your article's publication in JOSS! Many thanks to @xuanxu for editing, and @ctdegroot and @dandavies99 for reviewing.

[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.01621/status.svg)](https://doi.org/10.21105/joss.01621)

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

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

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