[REVIEW]: A short course about fitting models with the `scipy.optimize` module about jose-reviews HOT 47 CLOSED

from jose-reviews.

You've gone about it precisely as we want 👍

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

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:

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

from jose-reviews.

Attempting PDF compilation. Reticulating splines etc...

from jose-reviews.

--> Check article proof 📄 <--

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

• 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?

from jose-reviews.

• 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?

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

from jose-reviews.

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?

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

@whedon generate pdf

from jose-reviews.

Attempting PDF compilation. Reticulating splines etc...

from jose-reviews.

--> Check article proof 📄 <--

from jose-reviews.

@whedon generate pdf

from jose-reviews.

Attempting PDF compilation. Reticulating splines etc...

from jose-reviews.

--> Check article proof 📄 <--

from jose-reviews.

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.

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

@whedon set 10.5281/zenodo.1304473 as archive

from jose-reviews.

OK. 10.5281/zenodo.1304473 is the archive.

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

from jose-reviews.

@whedon generate pdf

from jose-reviews.

Attempting PDF compilation. Reticulating splines etc...

from jose-reviews.

--> Check article proof 📄 <--

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

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

from jose-reviews.

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

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=

from jose-reviews.