JOSS paper repo layout

[ml-evs]

Hi @ayush4921, some quick comments upon first inspection of the joss folder (might not get time to have a more detailed look at the code and paper contents until the end of the week). There's more useful info at https://joss.readthedocs.io/en/latest/submitting.html and you can find an example from my own work here: https://github.com/Materials-Consortia/optimade-python-tools/tree/master/paper.

1. The JOSS paper should probably be named paper.md in the JOSS sub-folder - I think this is what the JOSS build system (called Whedon) expects. JOSS provides a useful web service to preview your paper build here: https://whedon.theoj.org/ or as a GitHub action (maybe overkill).
2. You should provide your author metadata at the top of the markdown file as a special yaml block.
3. You should write a BibTeX-style bibliography instead of an inline references list (typically called paper.bib). You can then cite the keys in the bibfile directly from the paper as e.g. [@Evans2022]. You may also want to cite other GitHub repositories directly with links, rather than just providing package names (e.g. pyami).
4. It might be more helpful to include figures 2 and 4 as code snippets rather than images.

Apologies if this is stuff you already know but didn't have time for yet!

[ayush4921]

Thanks so much @ml-evs ! I have added the bibliography and formatted the paper to be compatible with joss.

[petermr]

Thank you so much, Matthew. This is very useful and is ultimately smoothing the process of submission and review.

…

On Sat, Feb 26, 2022 at 12:04 PM Ayush Garg ***@***.***> wrote: Thanks so much @ml-evs <https://github.com/ml-evs> ! I have added the bibliography and formatted the paper to be compatible with joss. — Reply to this email directly, view it on GitHub <#34 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFTCSYEKOILIDFNM7QPUL3U5C6U5ANCNFSM5O7EJXNA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

-- Peter Murray-Rust Founder ContentMine.org and Reader Emeritus in Molecular Informatics Dept. Of Chemistry, University of Cambridge, CB2 1EW, UK

[ml-evs]

Hi @ayush4921 and @petermr, looks like you have handled all my initial suggestions, the paper build looks good to me (there is a missing affiliation for Richard Smith-Unna but I assume that will be taken care of).

Some minor comments:

1. You should probably remove the HTML bits from the paper markdown, they appear in the PDF build currently (even though they are used for rendering by GitHub). It also gets a bit confused about figure captions; I must admit I am not sure what the procedure for including code snippets for captions is for JOSS, they can probably advise you on submission (e.g. your Fig 3 is currently auto-labelled as Fig 1).
2. Whilst the text is engaging, it is also quite informal in places (e.g., "please give me the results"), and the authors are referred to as "We" in several places. Again, this depends on the precise journal style which I cannot comment on, but the passive voice is normally preferred in scientific papers (rightly or wrongly).
3. Bulletpoint formatting does not work in the latter sections of the paper (e.g. the raw data section but also elsewhere). I think it just needs a newline before the list (as it works in the section "generic downloading concerns". I guess one difference between JOSS and other journals is that it is your responsibility to make sure everything is formatted correctly 🙃
4. The Design section could be expanded upon, whilst bulletpoints are fine, it needs at least a connecting sentence to the rest of the paper.
5. Some of the article references are missing DOIs (not important for @misc refs) - I think this is checked by JOSS.
6. I would add an additional section heading "pygetpapers" or "Summary" after the first paragraph. You could also replace "Justification" with "Motivation" or "Introduction" as it seemed a little out of place to me.

[kjappelbaum]

as part of the "official" JOSS review I'd also add one query about the author list. "Richard D Smith-Unna" didn't appear in the commit history, whereas it seems that there have been some more substantial contributions by ShweataNHegde. Am I am embarrassing myself and it is the same person?

I'd encourage to double-check the authorship criteria and perhaps even add an acknowledgment section?

[kjappelbaum]

since i agree with Matthew's assessment I'll only add some minor points (still WIP):

• why not directly reference getpapers to make it easier for the reader? Perhaps you can even archive a version in Zenodo and then cite the DOI.
• "for easier distribution and integration" - in the proceeding sentence you mention that you want a simple CLI - node.js is perfect for doing that. Perhaps a more important reason for Python is to integrate it with the other scientific ecosystem. Perhaps you could add an example of what is now possible with the Python version that has not been possible with the JS version.
• the Wind, L. L. DOI link is broken due to a trailing .

[petermr]

Thanks for the reply. I have copied Ayush and Rik and Shweata in.

On Fri, Jun 3, 2022 at 8:15 PM Kevin Jablonka ***@***.***> wrote: as part of the "official" JOSS review I'd also add one query about the author list. "Richard D Smith-Unna" didn't appear in the commit history, whereas it seems that there have been some more substantial contributions by ShweataNHegde <https://github.com/ShweataNHegde>. Am I am embarrassing myself and it is the same person?

We would welcome guidance from you and others with editorial experience. Rik wrote getpapers (sic) in 2014/5 and has committed it at https://github.com/ContentMine/getpapers (see https://github.com/ContentMine/getpapers/commits/master?after=915fc89575e0d0ea3db899c7a9b6238cad3dea8e+69&branch=master&qualified_name=refs%2Fheads%2Fmaster for list of commits). The code was largely finished in 2015, with some maintenance additions later by Tom Arrow. 2 years ago we needed a Python equivalent and Ayush started work as a volunteer on pygetpapers. pygetpapers is a complete rewrite of the getpapers strategy (not a wrapper). It incorporates the logic and design of getpapers but adds a lot more (it is much more than a port). There are no lines of code from Rik (or Tom). Shweata has developed a document analysing tool (https://github.com/petermr/docanalysis, in Python) which directly calls pygetpapers and her contributions are interfacing and testing. My cntributions have been mentoring Ayush through the design, especially code reviews, although I have not made any code commits.

I'd encourage to double-check the authorship criteria <https://joss.readthedocs.io/en/latest/submitting.html#authorship> and perhaps even add an acknowledgment section?

I felt that Rik deserved credit for the work on getpapers. I believe it was a transformational design - simple but extremely effective and (still) unique. (most/all other systems require some manual tasks or scripting.) I therefore invited him to be an author. If you feel this is inappropriate - and we should acknowledge him and getpapers - I suspect he would be happy with that. I hope this helps to give a picture of contributions. We'd be happy to add a list on the repos if that is useful. P.

…

— Reply to this email directly, view it on GitHub <#34 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFTCS722RXMWSFFDSHG34TVNJKVDANCNFSM5O7EJXNA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

-- Peter Murray-Rust Founder ContentMine.org and Reader Emeritus in Molecular Informatics Dept. Of Chemistry, University of Cambridge, CB2 1EW, UK

[kjappelbaum]

I felt that Rik deserved credit for the work on getpapers. I believe it was
a transformational design - simple but extremely effective and (still)
unique. (most/all other systems require some manual tasks or scripting.) I
therefore invited him to be an author. If you feel this is inappropriate -
and we should acknowledge him and getpapers - I suspect he would be happy
with that.

Thanks for the clarification - by no means do I want to say that Rik should not be on the author list. I instead wondered why Shweata is not on the author list.
I only feel that it can be useful (but it is not required by JOSS!) to list author contributions and to acknowledge others (e.g. Tom) that might have helped. A useful format for the author contributions might be CRediT

[petermr]

On Sat, Jun 4, 2022 at 11:21 AM Kevin Jablonka ***@***.***> wrote: I felt that Rik deserved credit for the work on getpapers. I believe it was a transformational design - simple but extremely effective and (still) unique. (most/all other systems require some manual tasks or scripting.) I therefore invited him to be an author. If you feel this is inappropriate - and we should acknowledge him and getpapers - I suspect he would be happy with that. Thanks for the clarification - by no means do I want to say that Rik should not be on the author list. I instead wondered why Shweata is not on the author list. I only feel that it can be useful (but it is not required by JOSS!) to list author contributions and to acknowledge others (e.g. Tom) that might have helped. A useful format for the author contributions might be CRediT <https://www.elsevier.com/authors/policies-and-guidelines/credit-author-statement>

Good - I like the idea of CRediT - and I'm happy to expand the authorlist. P

…

— Reply to this email directly, view it on GitHub <#34 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFTCS45ROOATFBWUD42O7LVNMU2TANCNFSM5O7EJXNA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

-- Peter Murray-Rust Founder ContentMine.org and Reader Emeritus in Molecular Informatics Dept. Of Chemistry, University of Cambridge, CB2 1EW, UK

[ayush4921]

@kjappelbaum kjappelbaum I have added the credit statement along with acknowledgments

[khinsen]

While the paper looks good when read as Markdown on GitHub, there are six sections with PDF rendering issues of bullet lists:

This list also contains the text "[URL]" in two places, which looks like a reminder to add URLs.

[ml-evs]

Not wanting to intermingle with the official JOSS review (although I think I am too late for that!), but I have found the Whedon preview very useful when building papers for JOSS: https://whedon.theoj.org/

I'm going to unsubscribe from all my issues on this repo, feel free to reach out over email or re-tag me if you want @ayush4921!

[ayush4921]

@khinsen Thanks alot for pointing this out.

Turns out JOSS paper builder requires a blank line before and after every bullet point. I have fixed the paper and it should be fine now.

I have also added the URLs.

Thanks and regards,
Ayush Garg.

[kjappelbaum]

This section can perhaps be a bit "beautified" using the LateX $\le$ and (perhaps?) rendering the enumeration as an enumerated list. (Made a PR #41)

[ayush4921]

@kjappelbaum Thanks a lot for the PR. I have merged it.