[REVIEW]: pvlib python: a python package for modeling solar energy systems

[whedon]

Submitting author: @wholmgren (William F. Holmgren)
Repository: https:/pvlib/pvlib-python
Version: v0.5.2
Editor: @katyhuff
Reviewer: @sjpfenninger, @ecotillasanchez
Archive: 10.5281/zenodo.1411511

Status

Status badge code:

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

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

@sjpfenninger & @ecotillasanchez, 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:/openjournals/joss-reviews/invitations

The reviewer guidelines are available here: https://joss.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @katyhuff know.

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

Review checklist for @sjpfenninger

Conflict of interest

• 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

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Version: Does the release version given match the GitHub release (v0.5.2)?
• Authorship: Has the submitting author (@wholmgren) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• 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

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• 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)?
• 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

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

Review checklist for @ecotillasanchez

Conflict of interest

• 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

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Version: Does the release version given match the GitHub release (v0.5.2)?
• Authorship: Has the submitting author (@wholmgren) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• 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

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• 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)?
• 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

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• 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. @sjpfenninger, it looks like you're currently assigned as the reviewer for this paper 🎉.

⭐ Important ⭐

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https:/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:/openjournals/joss-reviews:

2. You may also like to change your default settings for this watching repositories in your GitHub profile here: https:/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 📄 <--

[sjpfenninger]

It was a pleasure to review this submission. The software is well structured and the documentation is extensive and easy to follow. Just one (minor) item not checked on the checklist: references Holmgren2017 and Holmgren2018 don't have a DOI - can that be remedied, or could they be linked to a PDF instead (@wholmgren)?

Some other minor comments:

• You could set the repository's website at the very top of the GitHub page to the documentation, making it quicker to get there from the repository
• Installation docs could explicitly list requirements (right now, they do so only implicitly in the conda create command under "Install as an editable library", as far as I can see)
• tracking.LocalizedSingleAxisTracker has a somewhat mysterious docstring
• A conda-forge package would be highly appreciated 😄

[arfon]

@ecotillasanchez - please remember to get to this review sometime soon. Thanks!

[ecotillasanchez]

Excellent work in this contribution, a pleasure to review and test. One can easily see the comprehensive functionality and the seamless support for a variety of external sources of data. This is very valuable for benchmarking. Besides the comments raised above, I will only add one other suggestion. In the documentation, the main functionality could be structured around a tutorial or use cases, so that the user has a clear flow of what to read first and what to read next. For example, ModelChain shows up nearly on top on the left panel, and then it becomes a submenu within API reference.

[wholmgren]

Thanks @sjpfenninger and @ecotillasanchez for your reviews!

You could set the repository's website at the very top of the GitHub page to the documentation, making it quicker to get there from the repository

Good idea. Done.

Installation docs could explicitly list requirements (right now, they do so only implicitly in the conda create command under "Install as an editable library", as far as I can see)

We expanded the Compatibility section to address this. It looks likely that we'll add a requirements.txt file to the package in the near future, so I'd like to defer a larger Installation docs reorganization until then. pvlib/pvlib-python#533

tracking.LocalizedSingleAxisTracker has a somewhat mysterious docstring

Fixed in pvlib/pvlib-python#534

A conda-forge package would be highly appreciated 😄

We've actually had one for the last ~2 years or so, but I neglected to add it to the installation documentation until now. See here. pvlib/pvlib-python#533

the main functionality could be structured around a tutorial or use cases

@ecotillasanchez would moving Modeling paradigms out of Package Overview and into its own top-level documentation address this concern? Perhaps we could rename it something like "Intro examples" to make it more clear.

For example, ModelChain shows up nearly on top on the left panel, and then it becomes a submenu within API reference.

In this case, the left panel ModelChain documentation provides a comprehensive discussion of the feature, while the submenu within API reference provides, well, API reference. The same situation applies to "Clear sky" and "Forecasting".

To do:

• "references Holmgren2017 and Holmgren2018 don't have a DOI - can that be remedied, or could they be linked to a PDF instead". obtained DOIs for my conference proceedings. Also Mikofski2017. asked @mikofski to get a DOI for his conf. proceeding.
• add joss badge to pvlib readme. bundled in branch with paper.bib updates above
• move "Package Overview" to top level TOC and rename to "Intro examples".

cc @mikofski @cwhanse

[ecotillasanchez]

The "Intro examples" idea sounds like a good plan @wholmgren . Thanks for the quick response!

[wholmgren]

@sjpfenninger @ecotillasanchez I believe we've addressed all of your helpful comments. Let us know if we're missing anything. Thanks!

[katyhuff]

Thanks for quickly handling all of the reviewer comments @wholmgren ! It looks to me like the comments from @sjpfenninger and @ecotillasanchez have been handled. @sjpfenninger and @ecotillasanchez can you confirm that you approve these changes? Once you confirm, we'll be ready to move forward with acceptance.

[ecotillasanchez]

Confirmed. Thanks!

[sjpfenninger]

I also confirm!

[wholmgren]

@katyhuff is there anything I need to do to move this forward?

[katyhuff]

Ah -- I'm so sorry wholmgren -- I missed the last notification.

Indeed, it's time for the next step!

Could you please 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! (You may want to be sure to double check the paper, all minor details, etc. before creating the archive).

[katyhuff]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[wholmgren]

Thanks. Looks like we have some issues with reference formatting. I'll try to fix those. Is it possible to run the pdf compilation locally without too much trouble?

We are very close to a new release so maybe best to wait a few days for that DOI.

[wholmgren]

I've looked at a handful recent JOSS pdfs and corresponding paper.bib files. I can't figure out the logic for how the citations are rendered. It's ok with me if they stay the way they are.

[katyhuff]

Hi @wholmgren the references look ok to me. Perhaps I'm not sufficiently discerning. Can you give an example of what the problem is in the reference formatting?

Regarding the DOI, technically we'd like the DOI to be representative of the reviewed version of the code. However, if it's really just a few days to release, I think waiting for the updated doi is fine as long as new changes in your upcoming release don't alter the functionality we reviewed, do contain their own appropriate test coverage, and don't challenge any of the other elements necessary for successful JOSS review (docs, etc). I think with the development workflow you have demonstrated, this shouldn't be a problem for this project.

[wholmgren]

Thanks @katyhuff. I believe that the reviewers ultimately approved commit 845a75. I could describe this as v0.6.0-alpha and follow the normal GitHub Release --> Zenodo archive process. Alternatively, I could download the repo at that commit and upload it as a separate Zenodo archive. Is one approach preferable to the other?

Re references, I was expecting all citations in the text to be rendered as e.g. Lastname (Year), Lastname and Lastname (Year), or Lastname et al (Year). I was confused about the presence of initials and especially full first names. Maybe it's because many of our citations are proceedings. In any case, it's fine with me if it's fine with you. The References section looks ok.

[katyhuff]

• Both DOI generation approaches are equivalent, from the perspective of JOSS.
• Regarding the references -- I see. Indeed, I think that's happening at the level of the bibstyle, so it's right according to JOSS.

Thanks @wholmgren !

[wholmgren]

@katyhuff please DOI at https://zenodo.org/record/1411511

[katyhuff]

@whedon set 10.5281/zenodo.1411511 as archive

[whedon]

OK. 10.5281/zenodo.1411511 is the archive.

[katyhuff]

@whedon set https://doi.org/10.5281/zenodo.1411511 as archive

[whedon]

OK. 10.5281/zenodo.1411511 is the archive.

[katyhuff]

@sjpfenninger @ecotillasanchez : Thank you for your prompt and helpful reviews.
@wholmgren Thank you for your submission, and congratulations.

@arfon We're ready to accept this submission!

[arfon]

@sjpfenninger, @ecotillasanchez - many thanks for your reviews here and to @katyhuff for editing this submission ✨

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

[whedon]

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

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

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

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

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=

[wholmgren]

Thank you @katyhuff @sjpfenninger @ecotillasanchez @arfon! I would be happy to review a future submission.