JOSS Submission Review (Reviewer 2): Software paper

[damar-wicaksono]

This issue is related to the JOSS submission review.

Below are my remarks and suggestions regarding the software paper. Just let me know if further clarifications are need. Thank you!

Summary

• [ ] I think the first paragraph of the next section ("Statement of need") should be switched as the "Summary" of the paper as it better describes the high-level functionality and purpose of the package. Furthermore, the summary should also include the target audience of the package which the authors have also stated in the last paragraph of the next section.
• [ ] "...more hostile environment compared to...": Perhaps simply "than" is better than "compared to".
• [ ] "...and able to combine together different sources...": I think "together" is unnecessary.
• [ ] "...and real data (i.e., measurements)...": Perhaps to be succinct, this can be written simply as "measurement data"
• [ ] "...the dynamics of un-observable complex field...": Somewhere else in the paper "non-observable" is used, perhaps simply pick one?

Statement of need

• [ ] As noted above, I think the first paragraph should be switched with the paragraph in "Summary". The paragraph in Summary better describes the need that is served by the package.
• [ ] Because pyforce is an abbreviation perhaps the expanded term should appear directly after "pyforce"
• [ ] "...mainly for the Nuclear Engineering world.": Perhaps "in" instead of "for"
• [ ] "...Nuclear Engineering...": Is the capitalization really necessary?
• [ ] "The package is part of the ROSE...": Is there a reference to ROSE perhaps a link or a document?
• [ ] "at reducing..., at searching... and at integrating...": I think there is no need to repeat the preposition "at" due to already parallel structure
• [ ] Figure 1 should be better clarified by the second paragraph in this section; the figure contains mathematical symbols and notations that should be defined briefly and explicitly in the passage (if these symbols and notations are kept in the end). For instance, reading the paragraph it is not clear the starting point of the whole scheme (is it the field according to the full order model, or something else?).
• [ ] I would suggest that the list of implemented features are rewritten (perhaps in tabular form) to correspond to the figure better; which ones belong specifically to the offline and online phase, just the offline phase, or just the online phase. The list structure gives the impression that these features serve similar exchangeable purposes.
• [ ] "...either regularised with Tikhonov or not...": Perhaps it would be better to write as "either with or without Tikhonov's regularisation"
• [ ] "...for the Online Phase": Before there was no capitalization for "Online Phase". Is the capitalization intentional?

Contribution and authorship

Currently, the paper list three authors, namely S. Riva, C. Introini, and A. Cammi. Looking at the commit contributions page, I've seen two contributors have made commits. As @Steriva is S. Riva so the question regarding "Contribution and Authorship" is settled. Is Neko-tan also one of the authors?

Related to the paper, I would like to also suggest including a list of the contributions of each author separately in the paper. Some JOSS papers (for example, here) adopted the CRediT taxonomy to clarify those roles. Perhaps the authors would consider adding such section to the paper?

[Steriva]

Thank you @damar-wicaksono for the insightful comments (including #8 and #9). In the coming weeks, I'll update the repository following your suggestions.

Just a quick note about the authors: @Neko-tan is Carolina Introini, whereas A. Cammi is the professor supervising all the activities: I'll add the CRediT taxonomy to the paper to clarify the roles.

Thank you again!

[Steriva]

Response Letter: Software Paper

Thank you very much for the useful comments and suggestions. Here are listed the response and the changes made to the joss-paper.

The changes are reported in pull request #12.

Summary

1. I think the first paragraph of the next section ("Statement of need") should be switched as the "Summary" of the paper as it better describes the high-level functionality and purpose of the package. Furthermore, the summary should also include the target audience of the package which the authors have also stated in the last paragraph of the next section.
   • [x] The paragraphs have been switched and more insights about the target audience of the package are added.
2. "...more hostile environment compared to...": Perhaps simply "than" is better than "compared to".
   • [x] Fixed
3. "...and able to combine together different sources...": I think "together" is unnecessary."
   • [x] Fixed
4. "...and real data (i.e., measurements)...": Perhaps to be succinct, this can be written simply as "measurement data"
   • [x] Changed to measurements data (i.e., local evaluations of quantities of interest).
5. "...the dynamics of un-observable complex field...": Somewhere else in the paper "non-observable" is used, perhaps simply pick one?
   • [x] Fixed.

Statement of need

1. Because pyforce is an abbreviation perhaps the expanded term should appear directly after "pyforce"
   • [x] Changed
2. "...mainly for the Nuclear Engineering world.": Perhaps "in" instead of "for"
   • [x] Fixed
3. "...Nuclear Engineering...": Is the capitalization really necessary?
   • [x] No, it isn't: changed
4. "The package is part of the ROSE...": Is there a reference to ROSE perhaps a link or a document?
   • [x] Some comments about ROSE (an acronym used within the ERMETE-Lab to refer to ROM related applications to multi-physics for nuclear reactors).
5. "at reducing..., at searching... and at integrating...": I think there is no need to repeat the preposition "at" due to already parallel structure
   • [x] Fixed
6. Figure 1 should be better clarified by the second paragraph in this section; the figure contains mathematical symbols and notations that should be defined briefly and explicitly in the passage (if these symbols and notations are kept in the end). For instance, reading the paragraph it is not clear the starting point of the whole scheme (is it the field according to the full order model, or something else?).
   • [x] The description of the Figure has been greatly expanded, the Figure itself has been updated to reflect the one present on the README of the Github repo.
7. I would suggest that the list of implemented features are rewritten (perhaps in tabular form) to correspond to the figure better; which ones belong specifically to the offline and online phase, just the offline phase, or just the online phase. The list structure gives the impression that these features serve similar exchangeable purposes.
   • [x] Implemented
8. "...either regularised with Tikhonov or not...": Perhaps it would be better to write as "either with or without Tikhonov's regularisation"
   • [x] Changed
9. "...for the Online Phase": Before there was no capitalization for "Online Phase". Is the capitalization intentional?
   • [x] No, it isn't: changed

Contribution and authorship

CRediT taxonomy has been added to clarify the roles, reported below.

• Stefano Riva: Conceptualization, Data curation, Formal analysis, Software, Visualization, Writing – original draft
• Carolina Introini: Conceptualization, Formal analysis, Software, Supervision, Writing – review & editing
• Antonio Cammi: Conceptualization, Project administration, Resources, Supervision, Writing – review & editing

[damar-wicaksono]

@Steriva: Thank you very much for taking the time going through my comments! So that I can verify the changes and close this issue, is the updated draft can already be built into a PDF file from the JOSS review page? I'm asking because it seems that the pull request is still open...

[Steriva]

I've just merged the pull request into the main branch. Thank you very much for all the valuable comments!