[REVIEW]: A short course about fitting models with the `scipy.optimize` module

whedon commented 6 years ago

Submitting author: @arokem (Ariel Rokem) Repository: https://github.com/arokem/scipy-optimize Version: 0.1 Editor: @labarba Reviewer: @oliviaguest, @ThomasA Archive: 10.5281/zenodo.1304473

Status

Status badge code:

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

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

@oliviaguest & @ThomasA, 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 @oliviaguest

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 (0.1)?
[x] Authorship: Has the submitting author (@arokem) made substantial 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] Example usage: Do the authors include examples of how to use the module?
[x] 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

Pedagogy / Instructional design

[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: Do the authors clearly state the need for this module and who the target audience is?
[x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

Review checklist for @ThomasA

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 (0.1)?
[x] Authorship: Has the submitting author (@arokem) made substantial 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] Example usage: Do the authors include examples of how to use the module?
[x] 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

Pedagogy / Instructional design

[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: Do the authors clearly state the need for this module and who the target audience is?
[x] References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

whedon commented 6 years ago

Hello human, I'm @whedon. I'm here to help you with some common editorial tasks. @oliviaguest, 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 6 years ago

Attempting PDF compilation. Reticulating splines etc...

whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

labarba commented 6 years ago

👋 @oliviaguest, @ThomasA — Thank you for agreeing to review this submission to JOSE. Have a look at the Reviewer Guidelines, and feel free to ask any questions here.

Each of you has a reviewer checklist at the top of this issue thread. You should check off each item, as you complete your review. You're also encouraged to open new issues on the submission's repository, as needed, adding a reference to them here.

oliviaguest commented 6 years ago

Hi @arokem @labarba — I am not sure how to go about this, but if I understand correctly all items in my checklist are present/addressed except the final one. My issue is here: https://github.com/arokem/scipy-optimize/issues/4

labarba commented 6 years ago

You've gone about it precisely as we want 👍

ThomasA commented 6 years ago

@labarba, is this a software submission or a learning module submission (your reviewer guidelines)? I assume a learning module?

ThomasA commented 6 years ago

If it's OK by you I am just going to comment here bit by bit as I go through the review.

ThomasA commented 6 years ago

Authorship: @arokem has made substantial contributions to the repository and is the sole author listed on the paper. A number of other contributors have made relatively minor contributions; I guess it is OK that these are not authors?

@gvwilson is also a substantial contributor to the repository - in fact by far the major contributor. At his point it is not clear to me which parts of the repository he contributed and whether he ought to be a co-author on the paper as well. Can @arokem and @gvwilson please clarify?

ThomasA commented 6 years ago

Example usage: as I see it, we can inspect this and several other aspects on two levels:
- Being a teaching module, one level is examples given to students of the module when taught.
- The other level is examples of using the teaching module for other potential teachers.
I assume the second level (meta-level) is the most important in this review procedure.

As such, I do not think this submission provides much guidance in terms of examples of how to actually use the module. Here I am thinking that it might not for example be immediately obvious to new adopters of the module that the content seems to be set up to generated through GitHub's jekyll and how to use that. In particular, the file instructors.md in the repository is empty - except for some headlines. Perhaps the module follows some common structure from Software Carpentry that has some generic usage documentation for instructors that could be referenced?

gvwilson commented 6 years ago

The content is all @arokem - my contributions were solely to the Jekyll template.

oliviaguest commented 6 years ago

@ThomasA have you seen the materials at the repo's URL? http://arokem.github.io/scipy-optimize/

ThomasA commented 6 years ago

@oliviaguest yes, I guess that can be seen as "getting started" advice for both learners and instructors alike, but I was thinking if there should be more "meta-instruction" on which practicalities are involved if you want to clone and modify the material for your own purposes? It could be a simple matter of making potential instructors aware that the material relies on GitHub jekyll for generation and referring to GitHub's documentation for that. Or maybe Software Carpentry has some generic instructions for their material that applies here?

ThomasA commented 6 years ago

Apart from my above comment on usage examples, that I would like to discuss, I consider my review complete and can recommend publication.

oliviaguest commented 6 years ago

Ah, I see what you mean. I agree that's a very useful idea.

labarba commented 6 years ago

I agree with @ThomasA. The Author Guidelines say:

Computational learning modules should be complete and immediately usable for self-learning or adoption by other instructors.

In the paper (and possibly also the documentation), JOSE authors should explain how an instructor might adopt the module or how an independent learner might use it.

Readers also want to know why they might adopt/use the module. This has to do with the approach to teaching a topic, and the learning scenario.

(Bear in mind, we're looking at the first few submissions to JOSE, and we are solidifying our genre as we hold these very conversations.)

arokem commented 6 years ago

Indeed, I used the Carpentries (then Software Carpentry) lesson template to set up the pages for this lesson.

I added a link to the Carpentries example lesson in the README in https://github.com/arokem/scipy-optimize/commit/f6b2ae9dbded8e2610900292a439bf6e369c9a8a

On Thu, Jun 28, 2018 at 5:53 AM Lorena A. Barba notifications@github.com wrote:

I agree with @ThomasA https://github.com/ThomasA. The Author Guidelines say:

Computational learning modules should be complete and immediately usable for self-learning or adoption by other instructors.

In the paper (and possibly also the documentation), JOSE authors should explain how an instructor might adapt the module or how an independent learner might use it.

Does that address this issue?

Readers also want to know why they might adopt/use the module. This has to do with the approach to teaching a topic, and the learning scenario.

I don't know what this means. Could you give an example (e.g., from another paper) demonstrating this?

(Bear in mind, we're looking at the first few submissions to JOSE, and we are solidifying our genre as we hold these very conversations.)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/openjournals/jose-reviews/issues/16#issuecomment-401024066, or mute the thread https://github.com/notifications/unsubscribe-auth/AAHPNoQyKKLiQwVerebnaazYNccCbtGyks5uBNHTgaJpZM4UqefQ .

labarba commented 6 years ago

I see that only two check-boxes remain unticked in the review checklists.

Are we waiting on a couple of improvements from the author, at this point?

ThomasA commented 6 years ago

I think linking to the Software Carpentry lesson introduction has helped http://carpentries.github.io/lesson-example/. The submission is OK by me now.

labarba commented 6 years ago

@oliviaguest Do you recommend acceptance now? (you have one more box to tick)

labarba commented 6 years ago

@arokem Tiny fix: SciPy should have a capital P (paper Summary section).

labarba commented 6 years ago

@arokem More fixes:

Summary: In the reference to Jones at al. 2001, we see the year twice in the citation.
Statement of need:
- "such as 'Software Carpentry'," --> place the comma inside the quote.
- "The target audience ... are researchers" --> is
Learning objectives: "In addition to these" --> the
Description of the module:
- "The core of the course are" --> is
- "to fit these functional form" --> forms (or the instead of these)
- "sum of square error objective function" --> sum-of-square-error (hyphens for compound adjective)

oliviaguest commented 6 years ago

Hi @labarba I'm ticking it on the proviso that this (https://github.com/arokem/scipy-optimize/issues/4) is all sorted, which I assume it is?

arokem commented 6 years ago

@whedon generate pdf

whedon commented 6 years ago

Attempting PDF compilation. Reticulating splines etc...

whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

arokem commented 6 years ago

@whedon generate pdf

whedon commented 6 years ago

Attempting PDF compilation. Reticulating splines etc...

whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

labarba commented 6 years ago

Great, @arokem — I see all the changes, and your paper is ready to accept!

Please make an archive now on your chosen repository, and tell us the DOI.

arokem commented 6 years ago

@labarba : do you understand why the year 2001 appears twice in the rendered pdf? It only appears once in the bib file

And if I remove that, I get no year at all... (see the recent compilation attempt). Maybe whedon doesn't know how to properly handle the "misc" bib category?

labarba commented 6 years ago

@oliviaguest, @ThomasA — Thank you both for volunteering to review this submission, and being part of the JOSE adventure!

arokem commented 6 years ago

Thanks all! Here is the Zenodo DOI for the archive: 10.5281/zenodo.1304473

labarba commented 6 years ago

@whedon set 10.5281/zenodo.1304473 as archive

whedon commented 6 years ago

OK. 10.5281/zenodo.1304473 is the archive.

labarba commented 6 years ago

@arfon, I wonder if you could help here. We're having a little problem with one of the references. See the comment by @arokem, above.

labarba commented 6 years ago

@arokem Why do you put two dashes after the year?

[UPDATE] I see that's how they write it in the SciPy website's page on citation format. But since it's causing trouble, you could try with the year "2001" only?

arfon commented 6 years ago

We had to this the other day with another bibtex file for an online entry type. I’m afraid I don’t know what the fix is here (we didn’t figure it out on the other submission)

On Tue, Jul 3, 2018 at 20:20, Lorena A. Barba notifications@github.com wrote:

@arfon https://github.com/arfon, I wonder if you could help here. We're having a little problem with one of the references. See the comment by @arokem https://github.com/arokem, above https://github.com/openjournals/jose-reviews/issues/16#issuecomment-402325346 .

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/openjournals/jose-reviews/issues/16#issuecomment-402327275, or mute the thread https://github.com/notifications/unsubscribe-auth/AAARgwzNO9aq-egfklvKhylesOTsVuOiks5uDApjgaJpZM4UqefQ .

arokem commented 6 years ago

@whedon generate pdf

whedon commented 6 years ago

Attempting PDF compilation. Reticulating splines etc...

whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

arokem commented 6 years ago

Yep, removing the dashes does remove the year duplication. Should I create a new archive for this change?

labarba commented 6 years ago

Can you just up the version of the archive on Zenodo? (keeps the DOI)

labarba commented 6 years ago

@arokem Note that Zenodo grabs the authors automatically from the GitHub repo. You need to manually change the author list there, since you get people listed that are not authors of this module.

whedon commented 6 years ago

:tada::tada::tada: Congratulations on your paper acceptance! :tada::tada::tada:

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

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

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://www.flipcause.com/secure/cause_pdetails/Mjk3ODA=

labarba commented 6 years ago

@arokem Your paper is now published, yippee!!!
Please sign up as reviewer 😁

@oliviaguest, @ThomasA — Thank you again for reviewer. Do sign up (if you haven't) to our official reviewer list, for future requests, and help us advertise JOSE!

arokem commented 6 years ago

Thank you! Yippee! On Wed, Jul 4, 2018 at 12:38 PM Lorena A. Barba notifications@github.com wrote:

@arokem https://github.com/arokem Your paper is now published, yippee!!! Please sign up as reviewer 😁

https://github.com/oliviaguest

I believe I already did!

@oliviaguest https://github.com/oliviaguest, @ThomasA https://github.com/ThomasA — Thank you again for reviewer. Do sign up (if you haven't) to our official reviewer list, for future requests, and help us advertise JOSE!

Thanks to you both for the review!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/openjournals/jose-reviews/issues/16#issuecomment-402548481, or mute the thread https://github.com/notifications/unsubscribe-auth/AAHPNp4gV4EyRohq4jIK22j6TrFHrwFOks5uDRm-gaJpZM4UqefQ .

openjournals / jose-reviews