Mmm... the other reason for introducing the aliases is that instructors and learners are typing this stuff as they go along, and some of them won't have editors that tab-complete.

A large number of instructors don't use the Notebook (at least not
initially).

On Fri, Apr 10, 2015 at 04:26:57AM -0700, Greg Wilson wrote:

A large number of instructors don't use the Notebook (at least not
initially).

Do they use IPython's command line interface? Or do they switch
between an editor and a terminal for running scripts?

On Fri, Apr 10, 2015 at 02:59:22AM -0700, Greg Wilson wrote:

Mmm... the other reason for introducing the aliases is that
instructors and learners are typing this stuff as they go along, and
some of them won't have editors that tab-complete.

And this commit only requires:

• Six ‘np.’ → ‘numpy.’ edits
• Two ‘plt.’ → ‘matplotlib.pyplot.’ edits

in the core topics (not counting the code/readings-*.py, since they're
readings ;). And five of the ‘np.’ → ‘numpy.’ edits are in
08-cmdline.md, where folks are most likely editing a single
cell/script and won't need to retype ‘numpy.’ at every place it shows
up in the notes.

I agree with @gvwilson on this one. When we tab complete what we are doing is invisible to our students

On Fri, Apr 10, 2015 at 09:13:16AM -0700, Azalee Bostroem wrote:

I agree with @gvwilson on this one. When we tab complete what we are
doing is invisible to our students

And when we introduce new syntax we're loading our learner's short
term memory ;). I'm not saying there are no negative effects to this
change, I'm just saying that I think the benefit of covering only a
single import syntax outweighs the cost of typing out ‘numpy.’ twice
and ‘matplotlib.pyplot.’ once. There's definitely room for discussion
in there, though. Do you think the extra typing is a large cost? Is
explaining tab-completion a large cost (we'd already covered that in
the shell lesson by the time we hit this content at UW)? Do you think
covering the different posible syntaxes for imports is a small cost?

I think a handful of additional characters is a really good deal for not having to introduce a concept we would rather avoid having to talk about in the first exposure to Python.
How about whoever teaches next tries this version and reports back if the students did, in fact, have troubles typing the longer version?

This issue seems controversial and with good arguments for either side. I think the only fair way to settle this is with a good old fashioned vote. Register your +1 for either A) dropping import aliases or B) keeping import aliases. We'll give it several days, or until there's an obvious consensus.

I'm +1 for keeping them.

On Mon, Apr 20, 2015 at 06:33:30AM -0700, Trevor Bekolay wrote:

I'm +1 for keeping them.

I'm +1 for dropping them (obviously ;).

To help me understand your preference for dropping them, do you think
there's something I'm missing in my cost/benefit list 1? Or do you
just disagree with my weighting of the various terms? Both are valid
options (I'm certainly not omniscient, and my weightings are
subjective), but so far I haven't seen any suggestions for
alternatives.

Just the weighting; I think the "folks will see this in the wild" and "my fingers hurt from typing" outweigh the short term memory demand. Many novices that I have taught are slow at editing text; they type at a leisurely pace, and when they make a mistake at the start of a line, they may not realize it for a while. Once they realize it, they'll backspace back to where they made the error, and start typing from that point. Not that big a deal for numpy, but matplotlib.pyplot is super easy to confuse ("matplotlib" has a lot of hard consonants that sound similar when said quickly). I don't think novices are really thinking that deeply about the syntax in class either; they're primarily copying out what we present to them, and will inspect them deeply later. Making a mistake in typing can set them back twenty seconds or so, which we have to wait for; if we continue pressing forward and students fall behind, they quickly get discouraged.

On Mon, Apr 20, 2015 at 09:56:21AM -0700, Trevor Bekolay wrote:

Many novices that I have taught are slow at editing text…

Agreed. More typing isn't free.

… but matplotlib.pyplot is super easy to confuse …

Also agreed, but with this change they only have to type it out twice
more. If that takes them a minute or two more, it's still less time
than we spent at UW explaining the ‘import … as …’ syntax and the
magical namespacing you get out of the ‘%pylab inline’ magic we used
(I prefer ‘%matplotlib inline’ 1 to avoid flooding the local
namespace). It looks like the official lessons dropped the inline
call back in ee83592 (Extracting grids and reformatting lesson,
2014-12-03), so I'm not sure how figures are displayed now, or how
much time folks are taking to explain imports with the current lesson.
But I'd be surprised if you can add the extra syntax in much under the
minute or two of typing you're saving ;).

As an aside on the inline business, UW was mostly taught from an older
version of this lesson. Now that we've dropped the inline magic, how
are figures displayed? Is everyone launching an external viewer?

I vote +1 for dropping "import as".

I think that import numpy as np sets a problematic example in the respect that np is (or appears like) an ad-hoc identifier and I'd argue that the practice of using reasonably readable variable names should also be applied to import aliases. Using a few terse aliases is convenient initially but can become a problematic habit in more extensive "real life" work (e.g. merging / harmonising / reusing code where different aliases have been used for the same package is definitely not a nice job). From a didactic perspective, possibly having different students using variations of aliases (e.g. import numpy as np, import numpy as npy, import numpy as num) can well confuse students as well as instructors.

On a related issue, I'd also favour import matplotlib.pyplot to from matplotlib import pyplot, regardless of whether it's followed by an as clause, in order to minimise the amount of syntax variations.

Personally I think that import ... as should be used sparingly (if at all), and from ... import even more so. While I have sympathy for the idea of designing materials to be realistic by incorporating language elements "encountered in the wild", I think the best examples to show are not just commonly encountered, but also examples of good practice -- and with import aliasing and from ... import I'm not convinced the latter is the case.

I'm +1 for using the following:

import numpy as np
from matplotlib import pyplot
(optional as plt)
%matplotlib
(optional in line)

These are all very common syntaxes in on line documentation and I think exposure to it is important for our students

I agree that it is important to show the import ... as. syntax at some point in the workshop. But I don't think it should be the first python command that they see. Hence I vote for not using import ... as in novice-inflammation.
I do vote for introducing import ... as in the second python lecture / day 2.
But since this vote is only about novice-inflammation, again, my +1 is for dropping the syntax.

I would also like to reiterate that it would be great if we found a way for a more data-driven discussion (i.e. experiment with either model), instead of only relying on (very valuable, but nevertheless) anecdotal evidence and personal opinions.

I agree with @abostroem (import ... as is common in documentation, almost the default, see [1]) and with @tbekolay (novices tend to type it wrong). In my opinion, the first is more important than the second.

The problem with tab completion is that no matter how many times you say they should use it, some people don't do it and prefer trust their typing. I guess non-programmers never have to use tab, so it's a really strange key for them.

[1] http://www.scipy.org/getting-started.html

On Mon, Apr 20, 2015 at 12:13:33PM -0700, Bernhard Konrad wrote:

I do vote for introducing import ... as in the second python
lecture / day 2.

What lesson do you teach for the second Python lecture?

On Mon, Apr 20, 2015 at 12:16:33PM -0700, Ivan Gonzalez wrote:

(import ... as is common in documentation, almost the default, see [1])

I think this is just so frozen into the numpy community that it's hard
for them to transition out of it ;). But I hardly ever see ‘import …
as …’ outside of the numpy ecosystem. And going back to @gvwilson's
initial “other 90%” rule (quoted in the initial comment here), I
personally think getting to practical use cases with as little syntax
discussion as possible is more important than covering “here's
something you might see after the workshop” code. There's just not
enough time to go down those rabbit holes (which is why I'd also like
to avoid the ‘from … import …’ syntax).

On Mon, Apr 20, 2015 at 12:13:33PM -0700, Bernhard Konrad wrote:

I would also like to reiterate that it would be great if we found a
way for a more data-driven discussion (i.e. experiment with either
model), instead of only relying on (very valuable, but nevertheless)
anecdotal evidence and personal opinions.

+1. Until then, we can bikeshed over the central phrasing, and then
instructors who disagree strongly enough can adjust the lesson for
their own workshops ;). It's much more fun when there's an objective
measure to settle disagreements, but such measures have eluded us so
far :p.

I think this is just so frozen into the numpy community that it's hard
for them to transition out of it ;). But I hardly ever see ‘import …
as …’ outside of the numpy ecosystem.

Maybe, but this is where we are :-)

In any case, maybe a good compromise would be to add to your PR an extra sentence (maybe in a callout or something in the extra files) explaining import ... as as an alternative syntax and that is commonly use within some fields.

On Mon, Apr 20, 2015 at 12:36:36PM -0700, Ivan Gonzalez wrote:

In any case, maybe a good compromise would be to add to your PR an
extra sentence (maybe in a callout or something in the extra files)
explaining import ... as as an alternative syntax and that is
commonly use within some fields.

No ‘import … as …’ in the main flow with a short ‘import … as …’
callout box (that instructors can skip or not as they see fit) works
for me.

FWIW, I'm +1 for dropping import ... as .... There's a part of the Python community that thinks it's just wrong, even while that part might recognise that subcommunities like numpy practically make a badge of it.

I don't think import ... as ... adds such a big cognitive load. Consistency with code "in the wild" is important imho since especially beginners mostly work with copy & paste.

Either way I think the examples and exercises have to be consistent i.e. I'm -1 on introducing the syntax later since that will really confuse people.

@kynan in my experience import ... as ... is one of those things that incur a negligible cognitive load to those of us with a cognitive system sufficiently conditioned for and by coding, but it can be a considerable issue for beginners. To elaborate on my earlier remark that merging code that uses different aliases for the same module is a rotten job, to someone who realises in seconds that np is an identifier of an object of type module with the canonical name numpy, such merging jobs are just dull and unnecessary, but I've seen beginners despairing over trying to figure out why some alias works for their buddy (who they're copying & pasting code from) but not for them.

As a cognitive science speculation I think this is a variant of object permanence [1]: While seasoned coders have a reasonably complete mental model of the context relevant to their code (and are quick to figure out where they may have their model wrong), beginners tend to be aware of the code on the screen only. Once code grows to a size where the import statements at the top are no longer in view, the difficulty learners have to resolve troubles resulting from missing / variant import statements quite noticeably jumps up.

[1] http://en.wikipedia.org/wiki/Object_permanence

As of now, I count 5 in favour of dropping, 4 in favour of keeping, and 1 neutral (as long as it's consistent). It's not a strong consensus, but in the interest of moving forward I'm going to merge this and add a note about it to discussion.md as an FAI (Frequently Argued Issue).

On Thu, Apr 30, 2015 at 06:35:23AM -0700, Trevor Bekolay wrote:

As of now, I count 5 in favour of dropping, 4 in favour of keeping,
and 1 neutral (as long as it's consistent).

That sounds close enough that the callout middle ground might be
useful 1.

Ah, I missed that callout suggestion. I'll add it to #76.