[REVIEW]: PCP Notebooks: A Preparation Course for Python with a Focus on Signal Processing

[whedon]

Submitting author: @sebastianrosenzweig (Sebastian Rosenzweig)
Repository: https://github.com/meinardmueller/PCP
Version: v1.1.2
Editor: @moorepants
Reviewer: @boisgera , @alfredocarella
Archive: 10.5281/zenodo.5817272

⚠️ JOSS reduced service mode ⚠️

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.

Status

Status badge code:

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

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

@boisgera & @alfredocarella, 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 @moorepants 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 @boisgera

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: v1.1.2
• Authorship: Has the submitting author (@sebastianrosenzweig) 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)?

Review checklist for @alfredocarella

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: v1.1.2
• Authorship: Has the submitting author (@sebastianrosenzweig) 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? #153
• 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. @boisgera , @alfredocarella it looks like you're currently assigned to review this paper 🎉.

⚠️ JOSS reduced service mode ⚠️

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.

⭐ Important ⭐

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]

Software report (experimental):

github.com/AlDanial/cloc v 1.88  T=0.07 s (373.7 files/s, 161106.5 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Jupyter Notebook                11              0           7891           1251
Python                          12            456            586            952
Markdown                         2             19              0             33
YAML                             1              2              1             17
-------------------------------------------------------------------------------
SUM:                            26            477           8478           2253
-------------------------------------------------------------------------------


Statistical information for the repository 'b31bb231c8fbec1d6937a53f' was
gathered on 2021/11/01.
The following historical commit information, by author, was found:

Author                     Commits    Insertions      Deletions    % of changes
Meinard Müller                   6          1637              9           73.48
Peter Meier                      1             2              2            0.18
sebastianrosenzweig              3           478            112           26.34

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
Meinard Müller             1520           92.9          0.0                7.76
Peter Meier                   2          100.0         10.8                0.00
sebastianrosenzweig         472           98.7          0.6               13.56

[whedon]

PDF failed to compile for issue #148 with the following error:

 Can't find any papers to compile :-(

[moorepants]

@whedon generate pdf from branch paper

[whedon]

Attempting PDF compilation from custom branch paper. Reticulating splines etc...

[whedon]

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

[moorepants]

@whedon remind @Reviewer in 3 weeks

[whedon]

Reminder set for @Reviewer in 3 weeks

[alfredocarella]

@moorepants I am afraid I missed the invitation to review the article that was sent 10 days ago. Would you mind sending it again? Thanks!

[moorepants]

I'm not sure what invitation you are referring to. The invitation/instructions are at the top of this issue.

[alfredocarella]

@moorepants that is correct. The mentioned invite link (quote below) expired after 7 days.
I can no longer access https://github.com/openjournals/jose-reviews/invitations to accept the role as reviewer

Reviewer instructions & questions

@boisgera & @alfredocarella, 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

[moorepants]

Got it! There is a command for this:

@whedon re-invite @alfredocarella as reviewer

[moorepants]

@whedon re-invite @alfredocarella as reviewer

[whedon]

OK, the reviewer has been re-invited.

@alfredocarella please accept the invite by clicking this link: https://github.com/openjournals/jose-reviews/invitations

[whedon]

👋 @alfredocarella, please update us on how your review is going (this is an automated reminder).

[whedon]

👋 @boisgera , please update us on how your review is going (this is an automated reminder).

[boisgera]

Issues

I have noticed a small number of typos and made a PR here.

I have also described some small issues here :

• String Formatting meinardmueller/PCP#6
• Matrices, Vectors and Arrays meinardmueller/PCP#7

but this is mostly some nitpicking, and should not been considered show-stoppers (I would be ok with a "won't fix").

Review

The content provided by the authors is nicely structured, the scope of the content consistent with the stated aim
and the mix of Python introduction and audio / signal processing works really well in my humble opinion. More generally many aspects of the material (notebooks formatting, scope, length and balance, learning objectives, exercices, documentation wrt execution, etc.) demonstrate that a great care has been taken to design the material and make it useful.

I have initially been surprised by the large amount of raw HTML in markdown cells (for example hyperlinks are frequently given in HTML form) and then I noticed the use of bootstrap classes to provide a better styling of the content cells, where HTML is indeed required. While I'd rather have more markdown and less HTML (less technical for authors), the styling is undeniably useful (for example to easily spot exercises with a different color), so the option selected actually makes sense.

With respect to the checklist, I find only one thing that is lacking at this point (unless I am mistaken) :

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

I feel that the GitHub issue system is sufficiently known to consider that 2) is covered. IMHO, if the discussions features of github was activated and a brief mention of it was made in the README, that would also cover 3). The status of 1) could be explicited in the Acknowledgements section of the README (for example).

Once this point has been resolved, I recommend the submission to be accepted without any reservation. And I'd like to thank the authors for this contribution!

[moorepants]

@boisgera, thank you for the thoughtful review. @sebastianrosenzweig you are welcome to work on addressing the comments before the second review comes in.

[sebastianrosenzweig]

@boisgera many thanks for your thorough review and the pull requests! We are happy that our work is well appreciated.
@moorepants we will implement the changes in the next few days. Also we'll make clearer in the README.md how to contribute, report issues, or seek support.

[moorepants]

@alfredocarella can you give us a status update on your review?

[alfredocarella]

@moorepants I am just beginning to go through the content after the preliminary checks. It looks very well so far. I will submit my comments as soon as I have them

[moorepants]

Ok, sounds good. Let us know if there are any hurdles.

[alfredocarella]

Comments:

• I have submitted 2 pull requests here and here, suggesting fixes for small typos and some broken links. These are minimal issues, but I believe the changes reflect what the authors intended to do.

• As mentioned by the other reviewer, a very brief paragraph with guidelines for contributing (or eventually a statement that contributions are not expected) would be nice.

Suggestions (optional, and subjective)

• In my humble and subjective opinion, using f-strings consistently throughout the course might be the most intuitive approach for students.

• It might be helpful for users to add some numbering system to the notebook file names (for example "PCP_01_getstarted.ipynb"). This way a Jupyter notebook user will not need to revisit "PCP.ipynb" to find out which notebook in the series is next.

Overall review

The selection and treatment of topics is very good. The notebook content achieves the outcome of providing tangible and concrete examples that feel (and are) useful, without overwhelming students with details. Moreover the consistent style and formatting reduce the cognitive load by giving visual cues that help in navigating the notebooks quickly and effectively. The exercises are challenging enough to require a bit of time, but not so much as to be discouraging.
I confidently recommend this submission for publication, as I am sure it will be helpful for many.

[moorepants]

@whedon recommend-accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

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

OK DOIs

- 10.3233/978-1-61499-649-1-87 is OK
- 10.1038/s41586-020-2649-2 is OK
- 10.1109/MCSE.2007.55 is OK
- 10.5281/zenodo.3527872 is OK
- 10.3390/signals2020018 is OK
- 10.1007/978-3-030-69808-9 is OK
- 10.25080/Majora-7b98e3ed-003 is OK
- 10.1109/MSP.2021.3052181 is OK
- 10.1109/MSP.2018.2875349 is OK
- 10.21105/joss.03326 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

👋 @openjournals/jose-eics, this paper is ready to be accepted and published.

Check final proof 👉 openjournals/jose-papers#75

If the paper PDF and Crossref deposit XML look good in openjournals/jose-papers#75, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true

[moorepants]

@sebastianrosenzweig, you still need to address this comment:

hi @sebastianrosenzweig wave — Could you edit the metadata of the Zenodo archive, so the title and author list match the JOSE paper? Zenodo pulls these automatically from the repo and includes every committer by default.

[sebastianrosenzweig]

Dear @moorepants,
First of all Happy New Year and sorry, for the delay in the process.
We had to update the notebooks again to fix some links, update the year and references. Also we published a new version 1.1.2 .
Could you please use v1.1.2 for the article? The Zenodo DOI is: 10.5281/zenodo.5817272
We also changed the Zenodo authors to match the JOSE authors.
Thanks!

[moorepants]

@whedon set v1.1.2 as version

[whedon]

OK. v1.1.2 is the version.

[moorepants]

@whedon set 10.5281/zenodo.5817272 as archive

[whedon]

OK. 10.5281/zenodo.5817272 is the archive.

[moorepants]

@whedon recommend-accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

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

OK DOIs

- 10.3233/978-1-61499-649-1-87 is OK
- 10.1038/s41586-020-2649-2 is OK
- 10.1109/MCSE.2007.55 is OK
- 10.5281/zenodo.3527872 is OK
- 10.3390/signals2020018 is OK
- 10.1007/978-3-030-69808-9 is OK
- 10.25080/Majora-7b98e3ed-003 is OK
- 10.1109/MSP.2021.3052181 is OK
- 10.1109/MSP.2018.2875349 is OK
- 10.21105/joss.03326 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

👋 @openjournals/jose-eics, this paper is ready to be accepted and published.

Check final proof 👉 openjournals/jose-papers#76

If the paper PDF and Crossref deposit XML look good in openjournals/jose-papers#76, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true

[moorepants]

@openjournals/jose-eics, this should now be ready for full acceptance. The PR #76 looks correct to me.

[labarba]

@sebastianrosenzweig — Would you mind updating the metadata of the Zenodo deposit so the title of the archive matches the title of the paper?

[sebastianrosenzweig]

@labarba Done, we changed the title.

[moorepants]

@openjournals/jose-eics, is the change satisfactory to finalize this publication?

[moorepants]

@openjournals/jose-eics Hi, just checking on this again. It may only need the final approval. Hopefully all concerns are addressed.

[labarba]

@whedon accept deposit=true

[whedon]

Doing it live! Attempting automated processing of paper acceptance...

[whedon]

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSE! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 Creating pull request for 10.21105.jose.00148 jose-papers#78
1. Wait a couple of minutes, then verify that the paper DOI resolves https://doi.org/10.21105/jose.00148
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? Notify your editorial technical team...

[labarba]

Congratulations, @sebastianrosenzweig, your JOSE paper is published! 🚀

Huge thanks to our Editor: @moorepants, and Reviewers: @boisgera , @alfredocarella — your contributions make this adventure in indie publishing a reality and we are grateful 🙏

[whedon]

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](https://jose.theoj.org/papers/10.21105/jose.00148/status.svg)](https://doi.org/10.21105/jose.00148)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/jose.00148">
  <img src="https://jose.theoj.org/papers/10.21105/jose.00148/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: https://jose.theoj.org/papers/10.21105/jose.00148/status.svg
   :target: https://doi.org/10.21105/jose.00148

This is how it will look in your documentation:

We need your help!

Journal of Open Source Education is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: http://jose.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://numfocus.org/donate-to-jose

[sebastianrosenzweig]

Thank you @moorepants @alfredocarella @boisgera @labarba for this excellent review process and for your initiative.
We are grateful and happy at the same time! :-)

[moorepants]

Congrats @sebastianrosenzweig! And thanks to the reviewers @boisgera and @alfredocarella. It was a pleasure working with you all on this.