Review of lesson 2—it is a big jump from lesson 1; we need to fill the gap

[labarba]

I've read over the (currently) Lesson 2 draft, and I think that this made a large, uncomfortable leap from Lesson 1. In fact, this material might be appropriate for a much later lesson. The basic objective was to introduce custom functions, but there's a lot more going on.

1. it uses magics to run a separate python script (with no explanation);
2. the function definition is introduced with an abstract example where 'turn right' and 'go forward' are messages printed out, and nothing is computed;
3. the lesson imports the custom function 'gorover' with no explanation;
4. the function 'student_func' is then passed as an argument to the 'gorover' function; what does that mean to our novice students working through the lesson?
5. it uses a JSAnimation with no explanation.

Basically, I think that this lesson will be full of mysteries and somewhat frustrating for a novice. As a general rule, my "design guide" for these lessons is that each one should introduce one major new concept, and ideally it should do so while reinforcing or repeating something that was already done in a previous lesson. This gives a sense of confidence to the novice and reduces cognitive load.

In summary, this lesson is nice, although it can be improved, but I see it as a lesson 4 or 5 or even 6 … definitely not 2.

[ahmadia]

Thanks for the review, just a quick couple of notes in response:

I've read over the (currently) Lesson 2 draft, and I think that this made a large, uncomfortable leap from Lesson 1. In fact, this material might be appropriate for a much later lesson. The basic objective was to introduce custom functions, but there's a lot more going on.

1. it uses magics to run a separate python script (with no explanation);

The magics can be removed/hidden.

1. the function definition is introduced with an abstract example where 'turn right' and 'go forward' are messages printed out, and nothing is computed;

Of course something's being computed here. A command is being computed. The logic is simple, but it could be reduced to a True/False or other output. I don't think arithmetic is needed for a function to be understandable.

1. the lesson imports the custom function 'gorover' with no explanation;

This should be explained, good point.

1. the function 'student_func' is then passed as an argument to the 'gorover' function; what does that mean to our novice students working through the lesson?

It means that functions are also variables. This shouldn't be a mysterious or frightening concept. Just in the same way that I can write down a recipe and give it to somebody else, I can also pass a function to another function. This might deserve a sentence of explanation.

1. it uses a JSAnimation with no explanation.

Also deserves a sentence of explanation, basically just that we are using their web browser to visualize the rover actions.

Basically, I think that this lesson will be full of mysteries and somewhat frustrating for a novice. As a general rule, my "design guide" for these lessons is that each one should introduce one major new concept, and ideally it should do so while reinforcing or repeating something that was already done in a previous lesson. This gives a sense of confidence to the novice and reduces cognitive load.

In summary, this lesson is nice, although it can be improved, but I see it as a lesson 4 or 5 or even 6 ... definitely not 2.

Seeing this lesson written out, I agree that it shouldn't be 2. I'd suggest numbering this lesson 3, and adding a lesson 2 that introduces simple functions and function chaining. Then the only major concept being introduced in this lesson would be flow control (if tests).

[labarba]

Just to clarify, my main point was that too many things are being introduced in this one lesson, not that any of these in and of itself would not be understandable, if properly explained. So no need to explain to me that functions are also variables, for example. The issue is that by the time the novice student gets to here, cognitive load is hitting red and they won't parse it.

[ahmadia]

:) Agreed, let's split it down by at least one lesson, and if it still looks (or reviews) like too much, we can keep splitting.

[gforsyth]

I agree that we probably need a "custom functions" lesson as a standalone.

I have a few ideas for motivations/exercies:

1. creating functions to calculate taylor expansion of sine and cosine up to a given nth value, compare to numpy built-in calculation as an example of the kind of repeated action you would write a function to address.
2. function to calculate roots of quadratic given a, b, c -- also shows how functions can return multiple values. add a conditional to throw an exception if the roots are complex
3. fibonacci sequence (?). just because?
4. end with rover control function to lead into the next lesson

On Sun, Mar 9, 2014 at 4:48 PM, Aron Ahmadia notifications@github.comwrote:

:) Agreed, let's split it down by at least one lesson, and if it still looks (or reviews) like too much, we can keep splitting.

Reply to this email directly or view it on GitHubhttps://github.com/barbagroup/JITcode-MechE/issues/19#issuecomment-37138575 .

[ahmadia]

@gforsyth - I like your ideas :)

[labarba]

I found the notebook that plotted temperature anomalies this winter on top of a world map. I'm thinking this could make a good example for lesson 2: it builds from lesson 1, with new data, and it would only introduce function definitions on top of that. I'm thinking of using Matplotlib not plotly for this. As much as I looked in the repository, I did not find a copyright or licensing notice for this: http://nbviewer.ipython.org/gist/etpinard/9278679

[ahmadia]

I want to raise a caution against writing a lesson with a hard plot.lydependency. They're a commercial service and have only been around for a year. I would feel much more comfortable if we were using an open stack like the EarthPy example http://earthpy.org/interpolation_between_grids_with_basemap.html

On Sun, Mar 9, 2014 at 7:41 PM, Lorena A. Barba notifications@github.comwrote:

I found the notebook that plotted temperature anomalies this winter on top of a world map. I'm thinking this could make a good example for lesson 2: it builds from lesson 1, with new data, and it would only introduce function definitions on top of that. I'm thinking of using Matplotlib not plotly for this. As much as I looked in the repository, I did not find a copyright or licensing notice for this: http://nbviewer.ipython.org/gist/etpinard/9278679

Reply to this email directly or view it on GitHubhttps://github.com/barbagroup/JITcode-MechE/issues/19#issuecomment-37144139 .

[labarba]

When I said "I'm thinking of using Matplotlib not plotly for this," I really meant rewriting the whole code to … umm, not use plotly.

[ahmadia]

Sorry! I totally missed that :(

On Monday, March 10, 2014, Lorena A. Barba notifications@github.com wrote:

When I said "I'm thinking of using Matplotlib not plotly for this," I really meant rewriting the whole code to ... umm, not use plotly.

Reply to this email directly or view it on GitHubhttps://github.com/barbagroup/JITcode-MechE/issues/19#issuecomment-37161533 .

[labarba]

The winter 2014 temperature-anomaly study could possibly be a lesson 3, and we could do an even more fundamental lesson 2 that introduces function definitions via a unit-conversion example. Here is an example with temperature conversions: http://thelivingpearl.com/2014/01/02/temperature-conversation-application-in-python/ Within a notebook, we could do away with the main() function that includes a while loop, and simply have the individual conversion functions, demonstrating them with both scalar and data-set (array) inputs.

[ahmadia]

Okay, that sounds good.

On Mon, Mar 10, 2014 at 7:22 AM, Lorena A. Barba notifications@github.comwrote:

The winter 2014 temperature-anomaly study could possibly be a lesson 3, and we could do an even more fundamental lesson 2 that introduces function definitions via a unit-conversion example. Here is an example with temperature conversions:

http://thelivingpearl.com/2014/01/02/temperature-conversation-application-in-python/ Within a notebook, we could do away with the main() function that includes a while loop, and simply have the individual conversion functions, demonstrating them with both scalar and data-set (array) inputs.

Reply to this email directly or view it on GitHubhttps://github.com/barbagroup/JITcode-MechE/issues/19#issuecomment-37172535 .

[gforsyth]

I'm going to go ahead and close this -- I think the new lesson 2 in the windspeed branch covers most of the issues raised.