Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
whedon opened this Issue Jun 16, 2018 · 47 comments

Comments

Projects
None yet
7 participants
@whedon
Copy link
Collaborator

whedon commented Jun 16, 2018

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

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:

  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://jose.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @labarba know.

Review checklist for @oliviaguest

Conflict of interest

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

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

Review checklist for @ThomasA

Conflict of interest

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

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

This comment has been minimized.

Copy link
Collaborator Author

whedon commented Jun 16, 2018

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 🎉.

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

watching

  1. 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

This comment has been minimized.

Copy link
Collaborator Author

whedon commented Jun 16, 2018

Attempting PDF compilation. Reticulating splines etc...
@whedon

This comment has been minimized.

Copy link
Collaborator Author

whedon commented Jun 16, 2018

@labarba

This comment has been minimized.

Copy link
Member

labarba commented Jun 16, 2018

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

This comment has been minimized.

Copy link
Collaborator

oliviaguest commented Jun 23, 2018

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: arokem/scipy-optimize#4

@labarba

This comment has been minimized.

Copy link
Member

labarba commented Jun 23, 2018

You've gone about it precisely as we want 👍

@ThomasA

This comment has been minimized.

Copy link
Collaborator

ThomasA commented Jun 28, 2018

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

@ThomasA

This comment has been minimized.

Copy link
Collaborator

ThomasA commented Jun 28, 2018

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

@ThomasA

This comment has been minimized.

Copy link
Collaborator

ThomasA commented Jun 28, 2018

  • 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

This comment has been minimized.

Copy link
Collaborator

ThomasA commented Jun 28, 2018

  • 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

This comment has been minimized.

Copy link

gvwilson commented Jun 28, 2018

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

@oliviaguest

This comment has been minimized.

Copy link
Collaborator

oliviaguest commented Jun 28, 2018

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

@ThomasA

This comment has been minimized.

Copy link
Collaborator

ThomasA commented Jun 28, 2018

@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

This comment has been minimized.

Copy link
Collaborator

ThomasA commented Jun 28, 2018

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

@oliviaguest

This comment has been minimized.

Copy link
Collaborator

oliviaguest commented Jun 28, 2018

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

@labarba

This comment has been minimized.

Copy link
Member

labarba commented Jun 28, 2018

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

This comment has been minimized.

Copy link
Collaborator

arokem commented Jul 2, 2018

@labarba

This comment has been minimized.

Copy link
Member

labarba commented Jul 2, 2018

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

This comment has been minimized.

Copy link
Collaborator

ThomasA commented Jul 2, 2018

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

This comment has been minimized.

Copy link
Member

labarba commented Jul 3, 2018

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

@labarba

This comment has been minimized.

Copy link
Member

labarba commented Jul 3, 2018

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

@labarba

This comment has been minimized.

Copy link
Member

labarba commented Jul 3, 2018

@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

This comment has been minimized.

Copy link
Collaborator

oliviaguest commented Jul 3, 2018

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

arokem added a commit to arokem/scipy-optimize that referenced this issue Jul 3, 2018

@arokem

This comment has been minimized.

Copy link
Collaborator

arokem commented Jul 3, 2018

@whedon generate pdf

@whedon

This comment has been minimized.

Copy link
Collaborator Author

whedon commented Jul 3, 2018

Attempting PDF compilation. Reticulating splines etc...
@whedon

This comment has been minimized.

Copy link
Collaborator Author

whedon commented Jul 3, 2018

@arokem

This comment has been minimized.

Copy link
Collaborator

arokem commented Jul 4, 2018

@whedon generate pdf

@whedon

This comment has been minimized.

Copy link
Collaborator Author

whedon commented Jul 4, 2018

Attempting PDF compilation. Reticulating splines etc...
@whedon

This comment has been minimized.

Copy link
Collaborator Author

whedon commented Jul 4, 2018

@labarba

This comment has been minimized.

Copy link
Member

labarba commented Jul 4, 2018

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.

@labarba labarba added the accepted label Jul 4, 2018

@arokem

This comment has been minimized.

Copy link
Collaborator

arokem commented Jul 4, 2018

@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

This comment has been minimized.

Copy link
Member

labarba commented Jul 4, 2018

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

@arokem

This comment has been minimized.

Copy link
Collaborator

arokem commented Jul 4, 2018

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

@labarba

This comment has been minimized.

Copy link
Member

labarba commented Jul 4, 2018

@whedon set 10.5281/zenodo.1304473 as archive

@whedon

This comment has been minimized.

Copy link
Collaborator Author

whedon commented Jul 4, 2018

OK. 10.5281/zenodo.1304473 is the archive.

@labarba

This comment has been minimized.

Copy link
Member

labarba commented Jul 4, 2018

@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

This comment has been minimized.

Copy link
Member

labarba commented Jul 4, 2018

@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

This comment has been minimized.

Copy link
Member

arfon commented Jul 4, 2018

@arokem

This comment has been minimized.

Copy link
Collaborator

arokem commented Jul 4, 2018

@whedon generate pdf

@whedon

This comment has been minimized.

Copy link
Collaborator Author

whedon commented Jul 4, 2018

Attempting PDF compilation. Reticulating splines etc...
@whedon

This comment has been minimized.

Copy link
Collaborator Author

whedon commented Jul 4, 2018

@arokem

This comment has been minimized.

Copy link
Collaborator

arokem commented Jul 4, 2018

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

@labarba

This comment has been minimized.

Copy link
Member

labarba commented Jul 4, 2018

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

@labarba

This comment has been minimized.

Copy link
Member

labarba commented Jul 4, 2018

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

@labarba labarba closed this Jul 4, 2018

@whedon

This comment has been minimized.

Copy link
Collaborator Author

whedon commented Jul 4, 2018

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

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:

DOI

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:

@labarba

This comment has been minimized.

Copy link
Member

labarba commented Jul 4, 2018

@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

This comment has been minimized.

Copy link
Collaborator

arokem commented Jul 5, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.