[REVIEW]: Scientific programming in Julia - An introductory course

editorialbot commented 7 months ago

Submitting author: !--author-handle-->@AndreasKuhn-ak@arm61<!--end-editor-- Reviewers: @jarvist, @gcdeshpande Archive: Pending Paper kind: learning module

Status

Status badge code:

HTML: <a href="https://jose.theoj.org/papers/f53501246f3b960a2a7bab3797a85546"><img src="https://jose.theoj.org/papers/f53501246f3b960a2a7bab3797a85546/status.svg"></a>
Markdown: [![status](https://jose.theoj.org/papers/f53501246f3b960a2a7bab3797a85546/status.svg)](https://jose.theoj.org/papers/f53501246f3b960a2a7bab3797a85546)

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) by leaving comments 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

@jarvist & @gcdeshpande, your review will be checklist based. Each of you will have a separate checklist that you should update when carrying out your review. First of all you need to run this command in a separate comment to create the checklist:

@editorialbot generate my checklist

The reviewer guidelines are available here: https://openjournals.readthedocs.io/en/jose/reviewer_guidelines.html. Any questions/concerns please let @arm61 know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Checklists

📝 Checklist for @jarvist

editorialbot commented 7 months ago

Hello humans, I'm @editorialbot, a robot that can help you with some common editorial tasks.

For a list of things I can do to help you, just type:

@editorialbot commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@editorialbot generate pdf

editorialbot commented 7 months ago

Software report:

github.com/AlDanial/cloc v 1.90  T=0.09 s (424.4 files/s, 602629.2 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
CSV                              5              1              0          37679
Jupyter Notebook                18              0          10687           1974
TOML                             2            254              1           1156
TeX                              1             18              0            261
Julia                            2             43             20            201
Markdown                         2             91              0            121
YAML                             1              1              4             18
JSON                             6              0              0              6
-------------------------------------------------------------------------------
SUM:                            37            408          10712          41416
-------------------------------------------------------------------------------

Commit count by author:

    98  AndreasKuhn-ak
    15  Sabine Fischer
     6  Kilian Volmer
     2  HackMD

editorialbot commented 7 months ago

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1038/d41586-019-02310-3 is OK
- 10.1137/141000671 is OK
- 10.48550/arXiv.1209.5145 is OK
- 10.1016/j.cosrev.2020.100254 is OK
- 10.48550/arXiv.2109.09973 is OK
- 10.1016/j.cpc.2018.02.004 is OK
- 10.21105/joss.03349 is OK
- 10.1002/mrm.28792 is OK
- 10.1007/s10614-020-09983-3 is OK
- 10.1371/journal.pone.0209358 is OK
- 10.48550/arXiv.2211.02740 is OK
- 10.48550/arXiv.2212.07293 is OK
- 10.21105/joss.03349 is OK

MISSING DOIs

- No DOI given, and none found for title: How to solve the same numerical Problem in 7 diffe...
- No DOI given, and none found for title: Julia Language Delivers Petascale HPC Performance
- No DOI given, and none found for title: Julia Micro-Benchmarks

INVALID DOIs

- None

editorialbot commented 7 months ago

Paper file info:

📄 Wordcount for paper.md is 1166

✅ The paper includes a Statement of need section

editorialbot commented 7 months ago

License info:

🟡 License found: Other (Check here for OSI approval)

editorialbot commented 7 months ago

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

arm61 commented 7 months ago

It looks to me that the license for the code is MIT and the license for the material is CC-SA-4.0. Can you confirm this @AndreasKuhn-ak?

arm61 commented 7 months ago

Okay, we are ready to roll!

@jarvist and @gcdeshpande, thanks for agreeing to review this exciting work! If you work through the checklist and there are any problems/comments about the material, I recommend opening an issue on the material repository, and the authors can sort them out. More information about the review guidelines can be found on the Open Journals documentation pages: https://openjournals.readthedocs.io/en/jose/reviewer_guidelines.html

If anyone has any questions, ping me on here!

AndreasKuhn-ak commented 7 months ago

It looks to me that the license for the code is MIT and the license for the material is CC-SA-4.0. Can you confirm this @AndreasKuhn-ak?

Yes, that is correct.

arm61 commented 4 months ago

Hey @jarvist and @gcdeshpande, I noticed that there has been no change on this review for a few months. Any chance of getting it going?

jarvist commented 4 months ago

Review checklist for @jarvist

Conflict of interest

[x] As the reviewer I confirm that I have read the JOSE 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 JOSE code of conduct.

General checks

[x] Repository: Is the source for this learning module available at the https://github.com/AndreasKuhn-ak/WS2022_Julia?
[x] License: Does the repository contain a plain-text LICENSE file with the contents of a standard license? (OSI-approved for code, Creative Commons for content)
[x] Version: Does the release version given match the repository release?
[x] Authorship: Has the submitting author (@AndreasKuhn-ak) made visible contributions to the module? Does the full list of authors seem appropriate and complete?

Documentation

[ ] A statement of need: Do the authors clearly state the need for this module and who the target audience is?
[ ] Installation instructions: Is there a clearly stated list of dependencies?
[ ] Usage: Does the documentation explain how someone would adopt the module, and include examples of how to use it?
[ ] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the module 2) Report issues or problems with the module 3) Seek support

Pedagogy / Instructional design (Work-in-progress: reviewers, please comment!)

[ ] Learning objectives: Does the module make the learning objectives plainly clear? (We don't require explicitly written learning objectives; only that they be evident from content and design.)
[ ] Content scope and length: Is the content substantial for learning a given topic? Is the length of the module appropriate?
[ ] Pedagogy: Does the module seem easy to follow? Does it observe guidance on cognitive load? (working memory limits of 7 +/- 2 chunks of information)
[ ] Content quality: Is the writing of good quality, concise, engaging? Are the code components well crafted? Does the module seem complete?
[ ] Instructional design: Is the instructional design deliberate and apparent? For example, exploit worked-example effects; effective multi-media use; low extraneous cognitive load.

JOSE paper

[x] Authors: Does the paper.md file include a list of authors with their affiliations?
[x] A statement of need: Does the paper clearly state the need for this module and who the target audience is?
[x] Description: Does the paper describe the learning materials and sequence?
[x] Does it describe how it has been used in the classroom or other settings, and how someone might adopt it?
[x] Could someone else teach with this module, given the right expertise?
[ ] Does the paper tell the "story" of how the authors came to develop it, or what their expertise is?
[x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

jarvist commented 4 months ago

Both the Release and the Paper are written targeting the Version 1.0 (Aug 2023) release. This is fine, but you may also want to update both as it's been a while & there are some edits made in the Autumn of 2023 @AndreasKuhn-ak .

jarvist commented 4 months ago

In terms of the paper, I think one thing that would be useful to add is some idea of what level of programming background is ideal. You say that any scientific programmer can use it, but would the content still be useful for an intermediate or further on programmer? Similarly, in the 'experience of use' section it would be good to know what the background of the 13 self-study people were. PhD students? Undergraduates? People in industry? etc.

jarvist commented 4 months ago

Also, is the intent for this material to be a self-study only course, or do you envisage that it would be useful / adaptable for classroom teaching? Some kind of more clear guide in the documentation would be really useful.

gcdeshpande commented 4 months ago

Review checklist for @gcdeshpande

Conflict of interest

[ ] As the reviewer I confirm that I have read the JOSE 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 JOSE code of conduct.

General checks

[ ] Repository: Is the source for this learning module available at the https://github.com/AndreasKuhn-ak/WS2022_Julia?
[ ] License: Does the repository contain a plain-text LICENSE file with the contents of a standard license? (OSI-approved for code, Creative Commons for content)
[ ] Version: Does the release version given match the repository release?
[ ] Authorship: Has the submitting author (@AndreasKuhn-ak) made visible contributions to the module? Does the full list of authors seem appropriate and complete?

Documentation

[ ] A statement of need: Do the authors clearly state the need for this module and who the target audience is?
[ ] Installation instructions: Is there a clearly stated list of dependencies?
[ ] Usage: Does the documentation explain how someone would adopt the module, and include examples of how to use it?
[ ] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the module 2) Report issues or problems with the module 3) Seek support

Pedagogy / Instructional design (Work-in-progress: reviewers, please comment!)

[ ] Learning objectives: Does the module make the learning objectives plainly clear? (We don't require explicitly written learning objectives; only that they be evident from content and design.)
[ ] Content scope and length: Is the content substantial for learning a given topic? Is the length of the module appropriate?
[ ] Pedagogy: Does the module seem easy to follow? Does it observe guidance on cognitive load? (working memory limits of 7 +/- 2 chunks of information)
[ ] Content quality: Is the writing of good quality, concise, engaging? Are the code components well crafted? Does the module seem complete?
[ ] Instructional design: Is the instructional design deliberate and apparent? For example, exploit worked-example effects; effective multi-media use; low extraneous cognitive load.

JOSE paper

[ ] Authors: Does the paper.md file include a list of authors with their affiliations?
[ ] A statement of need: Does the paper clearly state the need for this module and who the target audience is?
[ ] Description: Does the paper describe the learning materials and sequence?
[ ] Does it describe how it has been used in the classroom or other settings, and how someone might adopt it?
[ ] Could someone else teach with this module, given the right expertise?
[ ] Does the paper tell the "story" of how the authors came to develop it, or what their expertise is?
[ ] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

AndreasKuhn-ak commented 3 months ago

Both the Release and the Paper are written targeting the Version 1.0 (Aug 2023) release. This is fine, but you may also want to update both as it's been a while & there are some edits made in the Autumn of 2023 @AndreasKuhn-ak .

Sorry for the late response. I was on vacation when you wrote, and I didn't check my emails thoroughly afterward. I can create a new release that incorporates the changes I made in Autumn 2023. I don't think the paper needs an update regarding the new release, as these changes were only corrections of some typos.

AndreasKuhn-ak commented 3 months ago

In terms of the paper, I think one thing that would be useful to add is some idea of what level of programming background is ideal. You say that any scientific programmer can use it, but would the content still be useful for an intermediate or further on programmer? Similarly, in the 'experience of use' section it would be good to know what the background of the 13 self-study people were. PhD students? Undergraduates? People in industry? etc.

I will expand this part in the paper and add the requested information.

AndreasKuhn-ak commented 3 months ago

Also, is the intent for this material to be a self-study only course, or do you envisage that it would be useful / adaptable for classroom teaching? Some kind of more clear guide in the documentation would be really useful.

I would say the primary intent is for this to be a self-study course, and we have used it in this way. However, I believe the course can also be effectively taught in a classroom setting for undergraduate students of any subject and graduate students without prior experience in programming, without any modifications. For example, a suitable format could be a block course where, in the morning, there is a teaching block of one or two lessons (depending on the size), and in the afternoon, students work alone or in groups on the exercises. In the evening or the next day, there could be a session where the solutions to the exercises are presented, and any questions regarding the exercises are answered.

I am very confident that this approach would work without major problems, as we teach a very similar Python course in exactly this format every semester for undergraduate biology students.

I will expand the target audience section accordingly.

@jarvist Thank you for taking the time to review our paper.

AndreasKuhn-ak commented 3 months ago

@jarvist, Thank you for your suggestions. I have updated the paper and README file based on your feedback. I believe it would be best to only create a new release once the review process is complete. This will ensure that the final, polished version is shared, rather than potentially releasing multiple updates during the review stage. Please let me know if you have any other suggestions or feedback. I appreciate you taking the time to review the materials and help me improve the quality of the work.

arm61 commented 3 months ago

@editorialbot generate my checklist

I am investigating why this didn't work. Sorry, I didn't notice.

arm61 commented 2 months ago

@gcdeshpande, could you please try again to generate the checklist? There was a space at the start of your comment that might have caused the editorial bot an issue.

arm61 commented 2 months ago

@gcdeshpande just checking in. Could you try again with the checklist generation?

jarvist commented 2 months ago

@jarvist, Thank you for your suggestions. I have updated the paper and README file based on your feedback. I believe it would be best to only create a new release once the review process is complete. This will ensure that the final, polished version is shared, rather than potentially releasing multiple updates during the review stage. Please let me know if you have any other suggestions or feedback. I appreciate you taking the time to review the materials and help me improve the quality of the work.

A pleasure! Please give me a poke once @gcdeshpande has been able to have a look, and I'll re-review.

I believe it's absolutely fine to 'stamp' the final release as part of the post-acceptance checklist, make sure all the different versions are sync'd up etc.

labarba commented 1 month ago

@gcdeshpande – I've edited your comment manually and copied over a review checklist for you. I don't know why it failed when you issued the command, but we should be ready to proceed now. Thank you for your contributions!

arm61 commented 1 week ago

@gcdeshpande, I have tried contacting by email with no reply. Are you still willing to review this work? If not, we will find another reviewer?

openjournals / jose-reviews