Joss-reviews: [REVIEW]: Eniric: Extended NIR Information Content

[whedon]

Submitting author: @jason-neal (Neal, Jason J.)
Repository: https://github.com/jason-neal/eniric
Version: v1.0.0
Editor: @arfon
Reviewer: @crawfordsm
Archive: 10.5281/zenodo.2658917

Status

Status badge code:

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

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

@crawfordsm, 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.

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

Review checklist for @crawfordsm

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.0.0)?
• [x] Authorship: Has the submitting author (@jason-neal) 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. @crawfordsm 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]

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

[arfon]

:wave: @crawfordsm - thanks again for agreeing to review this submission.

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: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html

Any questions/concerns please let me know.

[jason-neal]

Hi @crawfordsm.
I am currently trying to finish and submit my PhD thesis this month (November). So I will not be readily available to address any issues immediately this month.
Just letting you know so you are aware and can plan/schedule your review accordingly.

[crawfordsm]

HI @jason-neal Thanks for the information and good luck with your thesis. I just wanted to let you know that I have started to review the code and I hope to complete it over the next couple of days.

When I do need to open an issues, do you prefer for me to do so as one single issue related to the review or multiple issues in your repository?

[jason-neal]

Multiple issues is fine.

[crawfordsm]

Eniric is software to compute the theoretical precision of stellar radial velocity computations for stellar spectra. It is an updated python version of the code presented in Figueria et al (2016) . The software is timely and useful and would be worthy of publication in JOSS after some revisions. The code comes with a suite of tests, notebooks demonstrating its usage, and scripts to simplify the process of running the software. The code is able to reproduce the results in Figueria and comes with a number of additional useful features.

The major issue with the submission is that the documentation appears to be incomplete. While the installation, configuration, and basic usage are included in the README, the information on the README is incomplete on the full usage of the package and the further documentation that is part of the wiki does not fill in this information. Furthermore, there are a set of Jupyter notebooks detailing the usage, and while they have different levels of quality, they are not well linked to from the documentation. Further documentation with examples would also help verify the results with the Figueria paper.

The functionality that is part of Eniric to calculate the theoretical signal to noise measurements would be useful beyond calculating the S/N and precision measurements. It would be a significant benefit to provide more information to the user about how to use this functionality. Using tools like sphinx and read the docs, the documentation and API can be built automatically, and I would highly recommend moving from the wiki based documentation to an automatically built documentation. This would also make the well written doc strings more accessible. If you are unfamiliar with these, I'm happy to recommend some resource with more information.

Overall, the code and repository look appropriate for publication and provide a useful tool for calculating the theoretical limit on the precision of RV calculations. The additional update of the documentation will make the code more accessible and useful to the community.

Minor comments will be opened in the repository and linked to this issue.

[crawfordsm]

Those are the minor comments -- thanks for writing the code and let me know if you have any questions or if anything was not clear.

[jason-neal]

Thanks for the review.
Yes, I am aware that the documentation is incomplete and I will take the advice to move it to an automated build on Read the Docs.
I have used Sphinx and Read the Docs previously in 2016 but if you have a favourite or up-to-date resource (other than the basic sphinx/read the doc documentation) on the matter that would be helpful.

I will attempt to get this implemented over December. (Currently about to move from Portugal back to New Zealand)

[arfon]

:wave: @jason-neal - how are you getting along here?

[jason-neal]

I have achieved some progress with fixing up the documentation and putting it on read the docs, but it is still a work in progress https://eniric.readthedocs.io/en/newdocs/.

I am currently focusing on a hard thesis deadline of February 8th.

[arfon]

@whedon commands

[whedon]

Here are some things you can ask me to do:

# List all of Whedon's capabilities
@whedon commands

# Assign a GitHub user as the sole reviewer of this submission
@whedon assign @username as reviewer

# Add a GitHub user to the reviewers of this submission
@whedon add @username as reviewer

# Remove a GitHub user from the reviewers of this submission
@whedon remove @username as reviewer

# List of editor GitHub usernames
@whedon list editors

# List of reviewers together with programming language preferences and domain expertise
@whedon list reviewers

# Change editorial assignment
@whedon assign @username as editor

# Set the software archive DOI at the top of the issue e.g.
@whedon set 10.0000/zenodo.00000 as archive

# Set the software version at the top of the issue e.g.
@whedon set v1.0.1 as version

# Open the review issue
@whedon start review

# Compile the paper
@whedon generate pdf

# Ask Whedon to accept the paper and deposit with Crossref
@whedon accept

[labarba]

👋 @jason-neal — I think we're waiting on you to make some improvements here. What's your status?

[jason-neal]

The thesis is now submitted so I can focus on completing this.
I have made quite a few of the changes (with commits referencing the issues) in the newdocs branch.

I still have some issues with learning/getting the auto-documentation correct on readthedocs.

[labarba]

@jason-neal — Have you been able to make progress on this submission in the past month? What's your status?

[jason-neal]

I have managed to finish documentation on read the docs https://eniric.readthedocs.io/en/latest/

The latest version is currently still in the develop branch but will merge into master and change to v1.0 once it is approved.

[jason-neal]

@whedon generate pdf from branch develop

[whedon]

Attempting PDF compilation from custom branch develop. Reticulating splines etc...

[whedon]

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

[jason-neal]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[jason-neal]

@labarba It is ready now and merged into master.

[whedon]

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

% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed

0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0
100 17 0 17 0 0 360 0 --:--:-- --:--:-- --:--:-- 369

[arfon]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

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

[arfon]

@jason-neal - could you merge this PR? It will fix the citation formatting for multiple references: https://github.com/jason-neal/eniric/pull/141

[jason-neal]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

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

[jason-neal]

Merged thanks.

[arfon]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

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

[arfon]

@jason-neal - this is looking pretty good to me. The only issue I see is with the figure placement. Do you think you could try moving the figure up nearer the top of the paper, that way it might not end up floating in the references section at the end of the paper.

[arfon]

@crawfordsm - just a quick ping to see if you're happy with these changes? I believe @jason-neal has addressed your feedback at this point?

[jason-neal]

@whedon generate pdf from branch paper-figure-placement

[whedon]

Attempting PDF compilation from custom branch paper-figure-placement. Reticulating splines etc...

[whedon]

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

[jason-neal]

That has brought the image forward a page.

[arfon]

That has brought the image forward a page.

That looks great.

[crawfordsm]

@jason-neal You have done a really great job of updating the documentation along with the notebooks! It really makes the package much more accessible and now I really feel I can jump in to using it with the clear API.

I recommend Eniric for publication in JOSS.

[arfon]

I recommend Eniric for publication in JOSS.

👍 thanks @crawfordsm.

@jason-neal - 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.

[jason-neal]

Here you go

[arfon]

Thanks @jason-neal - one more thing - could you please update the authors on the Zenodo archive to match those of the paper? I'm currently listed as an author 😁

[jason-neal]

@afron Do you know how to do that? I have edited the authors on Zenodo and saved it but it does not seem to affect the shown authors. Do I need to publish it to make the change?

[arfon]

@afron Do you know how to do that? I have edited the authors on Zenodo and saved it but it does not seem to affect the shown authors. Do I need to publish it to make the change?

I'm not sure sorry. If there's a publish button then perhaps click it?

[jason-neal]

@afron That seemed to work.

[arfon]

@whedon accept

[whedon]

No archive DOI set. Exiting...

[arfon]

@whedon set 10.5281/zenodo.2658917 as archive

[whedon]

OK. 10.5281/zenodo.2658917 is the archive.

[arfon]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

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

Can't find any papers to compile :-(

[whedon]

```Reference check summary:

OK DOIs

• 10.1117/12.2055663 is OK
• 10.1017/CBO9781316036570 is OK
• 10.1051/0004-6361/201322068 is OK
• 10.3847/1538-3881/aabc4f is OK
• 10.1109/MCSE.2007.55 is OK

MISSING DOIs

• None

INVALID DOIs

• 10/gfdcsn is INVALID
• 10/gfdcsp is INVALID
• 10/gfdcsg is INVALID
• 10/gfdcsf is INVALID
• 10/cqg52h is INVALID
• 10/gfdcst is INVALID
• 10/gfdcsz is INVALID
• 10/dk66bp is INVALID
• 10/gdmwfg is INVALID
• 10/gddxj4 is INVALID
• 12.1002/asna.201312004 is INVALID
  ```

[arfon]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

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

Can't find any papers to compile :-(

[whedon]

```Reference check summary:

OK DOIs

• 10.1117/12.2055663 is OK
• 10.1017/CBO9781316036570 is OK
• 10.1051/0004-6361/201322068 is OK
• 10.3847/1538-3881/aabc4f is OK
• 10.1109/MCSE.2007.55 is OK

MISSING DOIs

• None

INVALID DOIs

• 10/gfdcsn is INVALID
• 10/gfdcsp is INVALID
• 10/gfdcsg is INVALID
• 10/gfdcsf is INVALID
• 10/cqg52h is INVALID
• 10/gfdcst is INVALID
• 10/gfdcsz is INVALID
• 10/dk66bp is INVALID
• 10/gdmwfg is INVALID
• 10/gddxj4 is INVALID
• 12.1002/asna.201312004 is INVALID
  ```

[arfon]

- 10/gfdcsn is INVALID
- 10/gfdcsp is INVALID
- 10/gfdcsg is INVALID
- 10/gfdcsf is INVALID
- 10/cqg52h is INVALID
- 10/gfdcst is INVALID
- 10/gfdcsz is INVALID
- 10/dk66bp is INVALID
- 10/gdmwfg is INVALID
- 10/gddxj4 is INVALID
- 12.1002/asna.201312004 is INVALID

@jason-neal please fix up these DOIs ☝️in your bibtex file.

[jason-neal]

@afron Ahh sorry, so much for using shortDOI's. They have been changed now.

[jason-neal]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

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

[arfon]

@whedon check references

[whedon]

Attempting to check references...

[whedon]

```Reference check summary:

OK DOIs

• 10.1051/0004-6361/201425481 is OK
• 10.1088/0004-637x/812/2/128 is OK
• 10.1051/0004-6361/201322383 is OK
• 10.1051/0004-6361/201219058 is OK
• 10.1051/0004-6361:20010730 is OK
• 10.1051/0004-6361/201526900 is OK
• 10.18727/0722-6691/5034 is OK
• 10.1117/12.2055663 is OK
• 10.1007/BF00653671 is OK
• 10.1051/0004-6361/201732054 is OK
• 10.3847/1538-3881/aab77d is OK
• 10.1002/asna.201312004 is OK
• 10.1017/CBO9781316036570 is OK
• 10.1051/0004-6361/201322068 is OK
• 10.3847/1538-3881/aabc4f is OK
• 10.1109/MCSE.2007.55 is OK

MISSING DOIs

• None

INVALID DOIs

• None
  ```

[arfon]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

```Reference check summary:

OK DOIs

• 10.1051/0004-6361/201425481 is OK
• 10.1088/0004-637x/812/2/128 is OK
• 10.1051/0004-6361/201322383 is OK
• 10.1051/0004-6361/201219058 is OK
• 10.1051/0004-6361:20010730 is OK
• 10.1051/0004-6361/201526900 is OK
• 10.18727/0722-6691/5034 is OK
• 10.1117/12.2055663 is OK
• 10.1007/BF00653671 is OK
• 10.1051/0004-6361/201732054 is OK
• 10.3847/1538-3881/aab77d is OK
• 10.1002/asna.201312004 is OK
• 10.1017/CBO9781316036570 is OK
• 10.1051/0004-6361/201322068 is OK
• 10.3847/1538-3881/aabc4f is OK
• 10.1109/MCSE.2007.55 is OK

MISSING DOIs

• None

INVALID DOIs

• None
  ```

[whedon]

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

% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed

0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0
100 17 0 17 0 0 361 0 --:--:-- --:--:-- --:--:-- 361
[WARNING] Could not fetch resource './precisions.png': replacing image with description
sh: 0: getcwd() failed: No such file or directory
sh: 0: getcwd() failed: No such file or directory
sh: 0: getcwd() failed: No such file or directory
pandoc: 10.21105.joss.01053.pdf: openBinaryFile: does not exist (No such file or directory)
Looks like we failed to compile the PDF

[arfon]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

```Reference check summary:

OK DOIs

• 10.1051/0004-6361/201425481 is OK
• 10.1088/0004-637x/812/2/128 is OK
• 10.1051/0004-6361/201322383 is OK
• 10.1051/0004-6361/201219058 is OK
• 10.1051/0004-6361:20010730 is OK
• 10.1051/0004-6361/201526900 is OK
• 10.18727/0722-6691/5034 is OK
• 10.1117/12.2055663 is OK
• 10.1007/BF00653671 is OK
• 10.1051/0004-6361/201732054 is OK
• 10.3847/1538-3881/aab77d is OK
• 10.1002/asna.201312004 is OK
• 10.1017/CBO9781316036570 is OK
• 10.1051/0004-6361/201322068 is OK
• 10.3847/1538-3881/aabc4f is OK
• 10.1109/MCSE.2007.55 is OK

MISSING DOIs

• None

INVALID DOIs

• None
  ```

[arfon]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

```Reference check summary:

OK DOIs

• 10.1051/0004-6361/201425481 is OK
• 10.1088/0004-637x/812/2/128 is OK
• 10.1051/0004-6361/201322383 is OK
• 10.1051/0004-6361/201219058 is OK
• 10.1051/0004-6361:20010730 is OK
• 10.1051/0004-6361/201526900 is OK
• 10.18727/0722-6691/5034 is OK
• 10.1117/12.2055663 is OK
• 10.1007/BF00653671 is OK
• 10.1051/0004-6361/201732054 is OK
• 10.3847/1538-3881/aab77d is OK
• 10.1002/asna.201312004 is OK
• 10.1017/CBO9781316036570 is OK
• 10.1051/0004-6361/201322068 is OK
• 10.3847/1538-3881/aabc4f is OK
• 10.1109/MCSE.2007.55 is OK

MISSING DOIs

• None

INVALID DOIs

• None
  ```

[whedon]

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

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

[arfon]

@whedon accept deposit=true

[whedon]

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

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

[arfon]

@crawfordsm - many thanks for your review here ✨

@jason-neal - your paper is now accepted into JOSS :zap::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 snippets:

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

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

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

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