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

[editorialbot]

Submitting author: @AndreasKuhn-ak (Andreas Kuhn)
Repository: https://github.com/AndreasKuhn-ak/WS2022_Julia
Branch with paper.md (empty if default branch):
Version: V1.0.0
Editor: @arm61
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]

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]

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]

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]

Paper file info:

📄 Wordcount for paper.md is 1166

✅ The paper includes a Statement of need section

[editorialbot]

License info:

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

[editorialbot]

👉📄 Download article proof 📄 View article proof on GitHub 📄 👈

[arm61]

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]

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]

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]

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]

Review checklist for @jarvist

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)?

[jarvist]

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]

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]

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]

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]

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]

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]

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]

@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]

@editorialbot generate my checklist

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

[arm61]

@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]

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

[jarvist]

@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]

@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]

@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?