[REVIEW]: Module on dust aerosol detection, monitoring and forecasting

[whedon]

Submitting author: @jwagemann (Julia Wagemann) Repository: https://gitlab.eumetsat.int/eumetlab/atmosphere/dust-monitoring Branch with paper.md (empty if default branch): Version: v0.2 Editor: @yabellini Reviewers: @RomiNahir, @cosimameyer, @yabellini Archive: 10.5281/zenodo.12807595 Paper kind: learning module

Status

Status badge code:

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

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

@RomiNahir & @s-m-e, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

1. Make sure you're logged in to your GitHub account
2. Be sure to accept the invite at this URL: https://github.com/openjournals/jose-reviews/invitations

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @yabellini 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 ✨

Review checklist for @RomiNahir

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 repository url?
• [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 (v0.1)?
• [x] Authorship: Has the submitting author (@jwagemann) made visible contributions to the module? Does the full list of authors seem appropriate and complete?

Documentation

• [x] A statement of need: Do the authors clearly state the need for this module and who the target audience is?
• [x] Installation instructions: Is there a clearly stated list of dependencies?
• [x] 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!)

• [x] 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.)
• [x] Content scope and length: Is the content substantial for learning a given topic? Is the length of the module appropriate?
• [x] Pedagogy: Does the module seem easy to follow? Does it observe guidance on cognitive load? (working memory limits of 7 +/- 2 chunks of information)
• [x] Content quality: Is the writing of good quality, concise, engaging? Are the code components well crafted? Does the module seem complete?
• [x] 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?
• [x] 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)?

Review checklist for @sbanchero

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 repository url?
• [ ] 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 (v0.1)?
• [ ] Authorship: Has the submitting author (@jwagemann) 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)?

[whedon]

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @RomiNahir, @s-m-e it looks like you're currently assigned to review this paper :tada:.

:warning: JOSS reduced service mode :warning:

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

:star: Important :star:

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/jose-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

1. Set yourself as 'Not watching' https://github.com/openjournals/jose-reviews:

2. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

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

@whedon commands

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

@whedon generate pdf

[whedon]

Wordcount for paper.md is 1640

[whedon]

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

[whedon]

Software report (experimental):

github.com/AlDanial/cloc v 1.88  T=0.44 s (64.1 files/s, 273242.9 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Jupyter Notebook                24              0         117214           1717
Markdown                         2             84              0            205
YAML                             1              0              0             45
TeX                              1              0              0             37
-------------------------------------------------------------------------------
SUM:                            28             84         117214           2004
-------------------------------------------------------------------------------


Statistical information for the repository 'c644813d48822785d482fb19' was
gathered on 2023/03/07.
The following historical commit information, by author, was found:

Author                     Commits    Insertions      Deletions    % of changes
Julia Wagemann                   7         28169          28265           99.59
jwagemann                        2           163             67            0.41

Below are the number of rows from each author that have survived and are still
intact in the current revision:

Author                     Rows      Stability          Age       % in comments

[whedon]

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

OK DOIs

- None

MISSING DOIs

- None

INVALID DOIs

- None

[RomiNahir]

Overall, this article is an excellent guide to learn and implement dust monitoring and detection with clear objectives and comprehensible modules. The learning platform has an easy access with high quality exercises and examples. I think the implementation of this algorithms in other world regions won't be complicated to adapt.

[whedon]

:wave: @s-m-e, please update us on how your review is going (this is an automated reminder).

[whedon]

:wave: @RomiNahir, please update us on how your review is going (this is an automated reminder).

[yabellini]

@jwagemann @RomiNahir finished her review and mention you need to add this point:

• 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 Please, work on it while I look for a new second reviewer.

[yabellini]

Hi @s-m-e, since we have not hard from you in several weeks, we are now looking for a new reviewer. Thank you for your original willingness to contribute a review.

[yabellini]

@whedon remove @s-m-e as reviewer

[whedon]

OK, @s-m-e is no longer a reviewer

[yabellini]

Hi @yxqd, you volunteer to review for JOSE. Will you be willing to review this submission about: Module on dust aerosol detection, monitoring and forecasting ?

[yabellini]

Hi @sbanchero, thanks for agreeing to review this work :-)

[yabellini]

@whedon add @sbanchero as reviewer

[whedon]

OK, @sbanchero is now a reviewer

[yabellini]

@sbanchero inform us that he will try to tackle this review during July.

[yabellini]

@whedon commands

[editorialbot]

My name is now @editorialbot

[yabellini]

@editorialbot commands

[editorialbot]

Hello @yabellini, here are the things you can ask me to do:

# List all available commands
@editorialbot commands

# Add to this issue's reviewers list
@editorialbot add @username as reviewer

# Remove from this issue's reviewers list
@editorialbot remove @username from reviewers

# Get a list of all editors's GitHub handles
@editorialbot list editors

# Assign a user as the editor of this submission
@editorialbot assign @username as editor

# Remove the editor assigned to this submission
@editorialbot remove editor

# Remind an author, a reviewer or the editor to return to a review after a 
# certain period of time (supported units days and weeks)
@editorialbot remind @reviewer in 2 weeks

# Check the references of the paper for missing DOIs
@editorialbot check references

# Perform checks on the repository
@editorialbot check repository

# Adds a checklist for the reviewer using this command
@editorialbot generate my checklist

# Set a value for version
@editorialbot set v1.0.0 as version

# Set a value for branch
@editorialbot set jose-paper as branch

# Set a value for repository
@editorialbot set https://github.com/organization/repo as repository

# Set a value for the archive DOI
@editorialbot set set 10.5281/zenodo.6861996 as archive

# Mention the EiCs for the correct track
@editorialbot ping track-eic

# Generates the pdf paper
@editorialbot generate pdf

# Recommends the submission for acceptance
@editorialbot recommend-accept

# Generates a LaTeX preprint file
@editorialbot generate preprint

# Flag submission with questionable scope
@editorialbot query scope

# Get a link to the complete list of reviewers
@editorialbot list reviewers

# Creates a post-review checklist with editor and authors tasks
@editorialbot create post-review checklist

# Open the review issue
@editorialbot start review

[yabellini]

@editorialbot remove @sbanchero from reviewers

[editorialbot]

@sbanchero removed from the reviewers list!

[yabellini]

@editorialbot add @cosimameyer as reviewer

[editorialbot]

@cosimameyer added to the reviewers list!

[yabellini]

Thanks so much @cosimameyer for agree reviewing this work. Please use @editorialbot generate my checklist to adds a checklist for your review. Let me know if you have any questions.

[cosimameyer]

Review checklist for @cosimameyer

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 code for this software available at the https://gitlab.eumetsat.int/eumetlab/atmosphere/dust-monitoring?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Version: Does the release version given match the GitHub release?
• [x] Authorship: Has the submitting author (@jwagemann) made substantial contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• [ ] Installation: Does installation proceed as outlined in the documentation? (and documentation is sufficient?)
• [ ] Functionality: Have the functional claims of the software been confirmed?
• [x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• [x] A statement of need: Do the authors clearly state the need for this software and who the target audience is?
• [x] Installation instructions: Is there a clearly stated list of dependencies? (Ideally these should be handled with an automated package management solution.)
• [ ] Example usage: Do the authors include examples of how to use the software?
• [ ] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [ ] Tests: Are there automated tests or manual steps described so that the function of the software can be verified?
• [ ] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [x] Authors: Does the paper.md file include a list of authors with their affiliations?
• [x] A statement of need: Do the authors clearly state the need for this software and who the target audience is?
• [x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

[cosimameyer]

Thanks so much for the opportunity to review this exciting material! Besides the topical relevance and the fact that the authors make learning content publicly available, I commend the choice of hosting the material on a separate website (JupyterBook) which lowers the entry barriers.

Going through the submission, I collected some notes that may help to make the submission even more appealing. I recommend publishing the submissions once the requirements for the journal are met.

General Checks

• I appreciate the nicely structured GitHub repo and the possibility to jump from the TOC in the README to the notebooks.
• Repository: One small thing to mention, the link to the exercises seems to be broken. The fix is to add a leading 0 to “03_practical_case_study” (e.g., https://gitlab.eumetsat.int/eumetlab/atmosphere/dust-monitoring/-/blob/main/03_practical_case_study/01_exercise.ipynb).

Functionality

• Installation: While I really appreciate that the content is also hosted on a platform, it looks like you have to sign up for a user account to access the exercises. In this case, I would like to get a (short) tutorial from the authors that explains to new users how to use the open source materials (for the hosted content: what are the login requirements when using the standalone website/platform? (e.g., is the account free? Is account creation limited to a certain group of people (academics, students of institute X?); for the material hosted on GitLab: What are the steps a user needs to follow to use the Jupyter notebooks? What version of Python is required? What libraries are needed and how to get them? (The authors are using conda and the environment.yml, so I'd recommend giving a short tutorial on how to set things up (including how to set up conda (or at least some helpful links pointing to tutorials that explain how to set it up on different operating systems as it may significantly increase the entry barriers for new users). Alternatively, as a low-barrier approach, adding a requirements.txt file and explaining how to use it might be sufficient). Documentation
• Functionality: It wasn't always clear to me which model/data needs to be downloaded to perform each exercise (I am not a topical expert, which may complicate the decision but I wondered if - unless for pedagogical reasons or permission issues - it doesn't make sense to host the data somewhere else while referring to the original data source?) If not, I recommend adding a specific description of which file needs to be downloaded (ideally, if possible, also a direct link).

Documentation

• Example usage: The point raised above also affects the example usage.
• Functionality documentation: The point raised above also affects the functionality documentation.
• Community guidelines: Similar to Romi, I would like to see some community guidelines ("Clear guidelines for third parties who wish to 1) Contribute to the module 2) Report issues or problems with the module 3) Seek support"). Maybe I haven't seen them (which might also indicate that they need to be made more visible).

Thanks again for submitting the content, I'm very much looking forward to seeing it published!

Side note @yabellini The review checklist has “Tests: Are there automated tests or manual steps described so that the function of the software can be verified?” in it. I don’t see any tests (but also don't see the need for additional tests). Can we check it off anyway or are there specific tests required for this kind of submission?

[yabellini]

@cosimameyer thank you so much for you review.

[yabellini]

@jwagemann the reviewers finished their work and let some comments for you. Please let us know when you work on these observations.