[REVIEW]: FDS Python: Fundamentals and Data Structures with Python

whedon commented 5 years ago

Submitting author: @rambasnet (Ram Basnet) Repository: https://github.com/rambasnet/thinkpythonnotebooks Version: v1.0.0 Editor: @labarba Reviewer: @AllenDowney, @mcburton Archive: Pending

Status

Status badge code:

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

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

@AllenDowney & @mcburton, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

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

The reviewer guidelines are available here: https://jose.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @labarba know.

Review checklist for @AllenDowney

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)
[ ] Version: Does the release version given match the repository release (v1.0.0)?
[ ] Authorship: Has the submitting author (@rambasnet) 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?
[ ] 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?
[x] 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?
[ ] 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 @mcburton

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)
[ ] Version: Does the release version given match the repository release (v1.0.0)?
[x] Authorship: Has the submitting author (@rambasnet) 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?
[x] 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.)
[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)
[ ] 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?
[ ] 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 commented 5 years ago

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @AllenDowney, it looks like you're currently assigned as the reviewer for this paper :tada:.

: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:

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

watching

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

notifications

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

@whedon commands

whedon commented 5 years ago

Attempting PDF compilation. Reticulating splines etc...

whedon commented 5 years ago

:point_right: Check article proof :page_facing_up: :point_left:

labarba commented 5 years ago

👋 @AllenDowney, @mcburton — We've started the review! This is where it happens. You each have a review checklist at the top of this issue, to guide you through. The version item is something we can check off in the end, as we will ask the authors to do a release after any revisions. Statement of need should be a section in the paper (the checklist has it also in the Documentation, but that's optional).

Feel free to ask any questions here, and @katyhuff will help you out. You can also post questions to the author, or open issues in the submission repository.

Please tick off your Conflict of Interest and Code of Conduct items ASAP, so we all see the review has started. Thanks!

AllenDowney commented 5 years ago

Under General Checks:

Version: Does the release version given match the repository release (v1.0.0)?

I don't see a version number in the repo.

Authorship: Has the submitting author (@rambasnet) made visible contributions to the module?

Yes.

Does the full list of authors seem appropriate and complete?

It looks like there is just one author, and only one contributor to the repo, so I guess I'll check this box.

AllenDowney commented 5 years ago

It looks like these notebooks are based on How to Think Like a Computer Scientist: Learning with Python 3 (RLE), but the documentation refers to Think Python. These are different books (although they share a common ancestor). Ideally, the paper and documentation should refer to How to Think, and remove references to Think Python.

katyhuff commented 5 years ago

I don't see a version number in the repo.

To create the DOI on submission, the author will need to create a release. Typically, this is done before the JOSS submission. However, if the authors prefer, sometimes the review is merely conducted on the most recent commit to the default branch and the version (in this case (1.0.0)) is assigned at the review completion when the software DOI is assigned.

It looks like there is just one author, and only one contributor to the repo, so I guess I'll check this box.

Yes, unless there's reason to believe other authors exist, we do go by commits.

It looks like these notebooks are based on How to Think Like a Computer Scientist: Learning with Python 3 (RLE), but the documentation refers to Think Python. These are different books (although they share a common ancestor). Ideally, the paper and documentation should refer to How to Think, and remove references to Think Python.

@rambasnet please note the above comment.

rambasnet commented 5 years ago

@katyhuff here's my comments:

I don't see a version number in the repo.

To create the DOI on submission, the author will need to create a release. Typically, this is done before the JOSS submission. However, if the authors prefer, sometimes the review is merely conducted on the most recent commit to the default branch and the version (in this case (1.0.0)) is assigned at the review completion when the software DOI is assigned.

It looks like there is just one author, and only one contributor to the repo, so I guess I'll check this box.

Yes, unless there's reason to believe other authors exist, we do go by commits. There's a release: https://github.com/rambasnet/ThinkPythonNotebooks/releases but I'd prefer the review conducted on the most recent commit to the default branch if possible.

It looks like these notebooks are based on How to Think Like a Computer Scientist: Learning with Python 3 (RLE), but the documentation refers to Think Python. These are different books (although they share a common ancestor). Ideally, the paper and documentation should refer to How to Think, and remove references to Think Python.

@rambasnet please note the above comment. Noted and fixed.

rambasnet commented 5 years ago

Hi, @labarba @katyhuff @AllenDowney, I was just curious about the review status as I've not noticed any progress since the last comment. Are reviewers waiting for my response on me for anything that I missed? Thanks in advance!

katyhuff commented 5 years ago

Thank you for pinging this item @rambasnet .

@mcburton & @AllenDowney : Can you estimate a time of completion for your reviews? I recognize that summer (e.g. the SciPy conference this week) may impede progress somewhat. Please let us know what timeline will be reasonable for your review completion.

labarba commented 5 years ago

@AllenDowney, @mcburton — hi folks! May we have an update from you on the status of your review? Thank you! 🙏

AllenDowney commented 5 years ago

@rambasnet The installation instructions look good, but it doesn't look like there is a list of requirements. Consider adding requirements.txt or environment.yml (although it looks like the notebooks run on Binder, so maybe you have no requirements other than Python and Jupyter).

rambasnet commented 5 years ago

@AllenDowney Yes, all it needs is Python 3 and Jupyter Notebook.

AllenDowney commented 5 years ago

@rambasnet On the question of Content quality, I think the primary contribution here is porting the code examples and exercises from the book into notebooks. Currently, the text in the notebooks is minimal, so they would not work well on their own, but I understand they are mean to supplement the book. Over time, it might be nice to flesh out the text in the notebooks.

AllenDowney commented 5 years ago

@rambasnet It looks like the references in paper.md are missing. And the format is a little strange, but I don't know if there's a template it's supposed to follow.

rambasnet commented 5 years ago

@AllenDowney, I agree with your comment on the content bing minimal which is intentional as the goal is not to compliment the text but to supplement. Also, research shows students do not always read text and we hope that these notebooks will force them to read. References are in paper.bib file that is how the editorial wants.

labarba commented 5 years ago

Reading this thread, I'm concerned that this project may not be quite what JOSE is looking for. We seek to publish computational learning modules that are ready for adoption by other researchers, and are complete in that sense. Maybe a case can be made, since the textbook these notebooks complement is openly available. But spartan notebooks made up of mostly code in general would not be sufficient for a JOSE publication.

rambasnet commented 5 years ago

main contributions:

all the important keywords, terms, topics, and definitions used in typical CS1 and CS2 courses are included in easy to read fashion making it easier for instructors to use during class (instead of jumping between powerpoint/text and code editor). This, of course, is mostly based on the original text with minor addition and or tweak where applicable. Every chapter has a direct link to corresponding online chapter in the textbook and other resources e.g. from python documentation. We don't see a value in completely replicating a great textbook.
code visualization using http://pythontutor.com/ where appropriate right in Notebook or on the site with pre filled code thus saving time for instructors to work on many examples (text doesn't provide this feature to the best of my knowledge)
include challenging and fun problems where applicable from https://open.kattis.com -- repo of programming contest problems (text doesn't provide this feature)

I hope this clarifies some of the doubt you may have about the importance and contributions of these notebooks in teaching problem solving using Python using hands-on approach.

labarba commented 5 years ago

@rambasnet — I've had a browse into your notebooks, and read the paper, and as the handling editor, I do maintain several concerns about the submission. It doesn't seem ready to be published. Generally, we'd expect fully narrated and ready-to-use lessons. I do recognize that the purpose and design of this collection of notebooks is not a "learning module" using computing to learn by the JOSE expectation, due to the fact that this set supplements an existing open textbook.

However, even if we consider the notebooks as dependent on the textbook, they still look unfinished. For example, the first notebook has a link to the corresponding chapter in the book, but the next few (I didn't click through all of them) do not. The reader needs to use the README as a guide.

In the paper, the Statement of Need is supposed to address the need for the content submitted here. You do not need to discuss the need for Python or Jupyter notebooks, but the need for the materials you created.

Given that this submission is unlike others in JOSE (not being self-contained), it is more important to take the time to explain to readers why they might need this content and how they might use it.

Please give some thought to these comments, and let us know if you think you can work on your submission to make it closer to a "finished product."

rambasnet commented 5 years ago

@labarba - Thank you for the feedback! We'll continue to use these notebooks in our classrooms and improve them with your suggestions in mind to make it closer to a "finished product."

labarba commented 5 years ago

@AllenDowney, @mcburton — I'm going to pause the review, in light of the exchange with the author just above ☝️ This collection of notebooks needs a bit of work before they are in publishable form. We are very grateful for the time you've contributed to this review so far, and hope you'll be willing to come back to it when the authors revive their submission 🙏

AllenDowney commented 5 years ago

Ok, thanks, Lorena.

On Tue, Jul 30, 2019, at 6:27 AM, Lorena A. Barba wrote:

@AllenDowney https://github.com/AllenDowney, @mcburton https://github.com/mcburton — I'm going to pause the review, in light of the exchange with the author just above ☝️ This collection of notebooks needs a bit of work before they are in publishable form. We are very grateful for the time you've contributed to this review so far, and hope you'll be willing to come back to it when the authors revive their submission 🙏

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/openjournals/jose-reviews/issues/52?email_source=notifications&email_token=AAOLP3K364IGY337UYIC3OLQCAJQZA5CNFSM4HMRPZ3KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD3DQ3MQ#issuecomment-516361650, or mute the thread https://github.com/notifications/unsubscribe-auth/AAOLP3MF5H6RMK234Q4RNF3QCAJQZANCNFSM4HMRPZ3A.

rambasnet commented 4 years ago

Hi Lorena, @labarba I've cleaned up and reorganized the notebooks quite a bit while using them in two courses beginning and advanced programming with Python this semester. I was hoping if I could get the review resumed on this submission. Thank you for your time!

labarba commented 4 years ago

👋 @AllenDowney, @mcburton — The author of this submission has checked in and reports a refactoring of the materials. Are you willing to step back into reviewing this for JOSE? I see that you both had made lots of progress already.

labarba commented 4 years ago

(I have now sent a new ping to the reviewers via direct message.)

mcburton commented 4 years ago

Yes, I can review this submission.

mcburton commented 4 years ago

I am excited to see the direction that these materials are going, but I think there is still more work to be done clarifying how these are to be used and how much explanatory content should be included in the notebooks.

Major Comments

The paper.md indicates these notebooks are being used at Colorado Mesa University, but additional details specifically how they are being used would strengthen the paper. How are these notebooks intended to be used with the book? The notebook chapters don’t fully correspond to chapters in the book, especially for new content.
There needs to be some work distinguishing these materials from the ThinkCSPy book. Much of the content in these notebooks is derived directly from the book, but then additional chapters, like the chapter on sqliteDB appears to be fundamentally new.
The new content is very sparse and includes very little discussion both for students and teachers besides the code and headers. With few pointers for how it aught to be used I’m not sure these notebooks are ready for someone to just pick up and use. This may be less of a problem for the notebooks at accompany the book, but is challenging for the new content.
The content in each notebook would be strengthened with an explicit set of learning objectives at the beginning and some summative statements of what was learned at the end of each notebook.

Minor changes

The paper.md is still missing references. They are in the bib file but should be included in a human readable format in paper.md
There is a minor markdown syntax error in the statement of need header in paper.md
The table of contents ordering is not in sync with notebook ordering in the repository starting with chapter 20.

In summary, I think @rambasnet has done some work to address the concerns that @AllenDowney and @labarba had raised in earlier comments in this thread, but I don't think the changes are complete. These materials need additional work in terms of expository comments within the individual notebooks. I understand @rambasnet's desire to not write a textbook, but if the idea of these notebooks is to be sparse then there needs to be additional content for the instructor (instructor's notes perhaps?) that provide some guidance about how these materials are to be used. The ThinkCSPy book does this for some of the chapters, but these materials don't have a 1 to 1 relationship with that book.

I think there is a sweet spot between sparse notebooks filled with code and a full textbook. Some additional specific details about how these materials are intended to be used may help clarify and set expectations.

If you have any questions please let me know.

rambasnet commented 4 years ago

Thank you for the review @mcburton. I appreciate your feedback.

I've a strong feeling that my intentions of these notebooks will not meet the requirements of the JOSE journal. So, I, respectfully, would like to withdraw my submission.

Thank you all @labarba and @AllenDowney for your valuable time to give this submission a chance.

labarba commented 4 years ago

No problem @rambasnet. Thank you for your efforts and considering JOSE to showcase your work.

I will now withdraw your submission.

Many thanks to @AllenDowney and @mcburton for the time invested in reviewing this work 🙏

openjournals / jose-reviews