Add manuscript files for 2023 JOSS publication

[kandersolar]

@pvlib/pvlib-core here are draft files for the proposed 2023 JOSS publication. Please review and leave comments at your leisure.

I have archived the original files from the 2018 publication in a 2018 subdirectory. Unfortunately github is rendering the new files as diffs from the old rather than replacements. For convenience, I've configured a CI job to build a PDF which is a bit nicer to read. Here is the latest: paper.pdf. New versions should appear as artifacts within this PR's CI job.

Also, I've included the scripts that generate the figures so that they are in the PR's history for future reference, but plan to remove them before merging.

[AdamRJensen]

I think it might be nice to mention that the authors represent the core pvlib team.

Note, that I've provided a pre-review of the paper thus most of my feedback has been provided prior to this PR.

[kandersolar]

Thank you @cwhanse and @AdamRJensen.

Here is an updated draft after the initial reviews: draft 2023-09-14.pdf

[wholmgren]

This is a great paper - thanks! I didn't realize quite how much has changed since the initial JOSS paper but perhaps not surprising given that pvlib is now ~twice as old as it was then.

I think it's notable that we've doubled the number of maintainers, especially since it's the new ones that are driving this effort :)

[adriesse]

Nicely written!

I do think the author order merits some reflection. I'm always self-conscious of advocating for alphabetical given my name, but on the other hand it doesn't seem like such a bad option here. Of course there are huge differences in what we have contributed to this text and to pvlib overall, but we all operate under different constraints.

[kandersolar]

Thanks @wholmgren and @adriesse for the reviews. Here is the latest rendering: draft 2023-09-15.pdf

Regarding author order, I am -1 to alphabetical. If we do that here then it presumably sets a precedent for any future publications, and it's not fair for me to arbitrarily be the perpetual beneficiary of whatever significance people assign to the ordering.

I think the current ordering, other than myself, was based on github's reporting of commit counts here: https://github.com/pvlib/pvlib-python/graphs/contributors

If ordering by commits is a reasonable approach, perhaps it would make more sense to order by commits since the last paper: https://github.com/pvlib/pvlib-python/graphs/contributors?from=2018-09-07&to=2023-09-15&type=c

(edit: corrected the publication date of the paper in the above link)

Of course commit count only captures one dimension of contribution to the project, and rather loosely at that. Ideas for other objective ordering methods are welcome!

[AdamRJensen]

If ordering by commits is a reasonable approach, perhaps it would make more sense to order by commits since the last paper: https://github.com/pvlib/pvlib-python/graphs/contributors?from=2018-09-07&to=2023-09-15&type=c

I'm inclined to agree that this seems the best option, albeit not perfect.

[mikofski]

Great paper! I really like the milestone charts! And also the growth of functions! Mind blowing! It would be interesting in the section on criticality to list any PV technological breakthroughs as a result of research or models that leveraged pvlib — perhaps the next update? Regarding name order feel free to put my name last. Of course I’m proud to be associated with pvlib but I’m far from the most prolific contributor and I think Kevin and Adam are the most consistent voices I hear in the PR’s. Thanks for putting together such a cogent update!

[kandersolar]

Thanks everyone for the input and kind words. Since all of us have reviewed, I will merge this PR and begin the JOSS submission.

Note that we can still make additional manuscript changes if needed; JOSS reviews usually take a while to get going.

[adriesse]

I think ranking core team members is fundamentally undesirable. As I pointed out, we all operate under different constraints. This allows some of us to spend much more time on pvlib than others. It would probably be easier to change my name than to change my constraints. Furthermore, the core team is not homogeneous, so contributions will vary in nature and size and countability, and I doubt any ranking could get it right.

Even if we agreed on having no ranking (open question) there's no getting around the fact that the author list is an ordered list and that readers have preconceived notions about the meaning of that order. So we have to deal with it. Having the main writer listed as first author is, in my opinion, not always justified or necessary. It is perhaps even less so in this case, where the paper itself is a minor thing. Looking through a few JOSS papers I see that many use a symbol to indicate corresponding author (rather than placing them first) and a star to identify equally contributing authors.

The idea that is forming is to place Cliff first (perhaps as a substitute for the PVSC award) and the rest alphabetically, with Kevin identified as corresponding author.

If the present ranking (system) is maintained by majority vote, then I would ask that you add stars to the names with the explanation: "authors are sorted by number of commits" below the authors' names.

[kandersolar]

Good point about mentioning the ordering method in the manuscript somehow. After looking into it, the JOSS build system doesn't seem to provide much flexibility in the authors list beyond the "equal-contrib" and "corresponding" flags, which both display hard-coded text as far as I can tell :/ The best option I've found to include this explanation is in a footnote, which renders like this: paper-order-footnote.pdf. In that PDF I added the footnote to only one name; I also tried adding the footnote symbol to each name, but the resulting PDF had the same footnote text 6 times with 6 different symbols. Once the review begins, we can ask the JOSS folks if there is a better option.

Regarding the choice of ordering itself, it seems that 5 out of the 6 of us thought the current ordering is reasonable. If the group can be swayed to some other majority or consensus then I'll happily edit accordingly!