[AstroPy] Practical Python for Astronomers web tutorial

[August (Gus) Muench]

Hi,


Sadly, Joe, despite all the docs work, the assertion that numpy docs
are clean of 'from numpy import *' excepts immediately.  A new user
following this reasonable link path has namespace garbage heaps before
they even get past example #1:

http://numpy.scipy.org/  => "NumPy Tutorial"
http://www.scipy.org/Tentative_NumPy_Tutorial => "The Basics: An example"
http://www.scipy.org/Tentative_NumPy_Tutorial#head-c5f4ceae0ab4b1313de41aba9104d0d7648e35cc

:)

I also think that audience matters a lot.  IRAF namespaces are
obfuscated away and its driven me crazy that CIAO/Sherpa are devoid of
namespace but if those users are in the audience then short of
preaching (which is always pedagogically inappropriate) what is one to
do?

[Heretic warning]  Finally, who cares if someone else can't read your
code? Its about audience.  The audience for my reduction script is me
(and maybe I should use namespaces so I can retrace what I did).  If I
wish to share it then I'm either going to be ignored on github, voted
down on stackoverflow or run into collaborators anger or experience
pedagogical problems if its crappy (and maybe even namespace free).


    - Gus






> Date: Tue, 24 May 2011 20:42:37 -0400
> From: Joe Harrington <jh at physics.ucf.edu>
> Subject: Re: [AstroPy] Practical Python for Astronomers web tutorial
> To: astropy at scipy.org
> Cc: jh at physics.ucf.edu
> Message-ID: <wl8wrhfk3uq.fsf at physics.ucf.edu>
>
>> http://python4astronomers.github.com/
>
> First, this is a great idea and I encourage your work in it!
>
> Second, I've been teaching a class in Python (the one for which I
> started the SciPy Doc Project).  Feel free to look at the class web
> site for additional ideas and demos.  The demos are in the lecture
> directories, organized as numbered subdirectories.  For solutions and
> large datasets, we can talk offline (I have to be careful about
> circulating solutions for obvious reasons).
>
> http://planets.ucf.edu/academics/ast5765/
> (Follow the tiny files link in the first block of normal type.)
>
> Third, comments on the workshops.
>
> 1. Don't use:
>
> from whatever import *
>
> or any shortcuts like 'ipython -pylab' that do that.  It's poor style
> and against the practice of the numpy community in all its docs and
> demos.  Remember that the numpy, scipy, and matplotlib developers can
> in the future put anything they want in their namespaces, and a new
> release could break your working code because of a namespace conflict
> that doesn't exist when you write it.  While that may not bite you for
> your workshops, it will eventually bite anyone who writes enough code
> like that.  Those problems can be hard to find.
>
> In my experience, the "import *" habit is a very tough one to break,
> so it's particularly important never to teach it.  I categorically do
> not use in my course any books or other resources that do "import *".
> Using:
>
> from whatever import foo, bar, baz
>
> is ok, though not great just because of the bookkeeping required at
> the top of every file.  But, it's a low-impact way of rescuing old
> code.
>
> 2. Unless you are specifically teaching how to use the features of
> ipython in a particular demo, make sure all demos run in plain python,
> so they can be used in programs.  At the very least, give exactly your
> startup options (e.g., "ipython -pylab") and imports so the user can
> run your demo.  Also make sure you test them with no startup files
> (see #5 below for bug report).
>
> 3. Provide the data you use in your demos as a hyperlink above the
> demo (referring to "Reading a table and plotting" demo).  In general,
> I've found it simpler just to generate data or embed a simple dataset,
> except when teaching how to read from a table.
>
> 4. The "Reading a table" demo is far too complicated for a first table
> demo.  Remember that most of your audience will want to copy the demo
> and edit for their own purposes, so give them something short, like a
> simple ASCII file with two columns, read with a numpy function and
> plot.  Then go for the asciitable, fancy histogram, real data
> thing.  They will be more impressed with the simplicity of plotting in
> 3 lines than with the fanciness of 23 lines.
>
> 5. In this demo, random.uniform() isn't imported by pylab:
>
> $ ipython -pylab
> Python 2.6.5 (r265:79063, Apr 16 2010, 13:57:41)
> Type "copyright", "credits" or "license" for more information.
>
> IPython 0.10 -- An enhanced Interactive Python.
> ?         -> Introduction and overview of IPython's features.
> %quickref -> Quick reference.
> help      -> Python's own help system.
> object?   -> Details about 'object'. ?object also works, ?? prints more.
>
>  Welcome to pylab, a matplotlib-based Python environment.
>  For more information, type 'help(pylab)'.
>
> In [1]: n = 100
>
> In [2]: x = random.uniform(-10., 10., n)
> ---------------------------------------------------------------------------
> AttributeError                            Traceback (most recent call last)
>
> /home/jh/<ipython console> in <module>()
>
> AttributeError: 'builtin_function_or_method' object has no attribute 'uniform'
>
> In [3]:
> Do you really want to exit ([y]/n)? y
>
> 6. In the "Curve fitting with SciPy", don't forget the "2" in the
> denominator of the Gaussian exponent.  In your example, sigma should
> be sqrt(2), not 2 (since 2 * sigma^2 = 4 in the input).  Add a comment
> that you're passing a function in the fit and that it queries the
> function for how many args there are after the x data to find out how
> many parameters to fit.
>
> 7. In "Synthetic images", put a note in the for loop that there are
> more efficient, vector-based ways to do this without loops or
> conditionals (e.g., with np.where() or making a bigger image and then
> cropping it).  Why make a FITS rather than a matplotlib image?
>
> 8. In "Running existing compiled codes", put in a note that there are
> straightforward ways to get compiled code to execute directly as
> Python functions, which is what most people call "glue".  Why write
> the data to a file at all?  It would be simpler to write the output to
> a file with shell redirection and then read the file, if you must deal
> with a file here.  Close the file either way.
>
> Far as I got...
>
> Btw, I use that xkcd in my class as well.  Note that it is the one ON
> THE GROUND who says the other guy is flying.  So it's not a
> medicine-cabinet-induced hallucination!
>
> Also, the title of each workshop has the first word on the end of a
> breadcrumb trail and the rest on a second line.  Maybe put in a line
> break before the title.
>
> Alsoalso, in the table of workshops, give an estimate of the time each
> takes.
>
> Again, this is a fantastic resource, nicely put together!
>
> --jh--
>
>

>
> Message: 7
> Date: Wed, 25 May 2011 05:35:29 +0000
> From: Vicki Laidler <laidler at stsci.edu>
> Subject: Re: [AstroPy] Practical Python for Astronomers web tutorial
> To: Tom Aldcroft <aldcroft at head.cfa.harvard.edu>, "jh at physics.ucf.edu"
>        <jh at physics.ucf.edu>
> Cc: "astropy at scipy.org" <astropy at scipy.org>
> Message-ID:
>        <173C0F068F6E49449797E90DF0B59EF8B67373 at EXCHMAIL1.stsci.edu>
> Content-Type: text/plain; charset="us-ascii"
>
> Hi Tom,
>
> I'm going to second Joe's emphatic prohibition on "from whatever import *", for two reasons:
> not only as a matter of purity, but also as a practical matter. Using pylab specifically, I have
> more than once clobbered a few of my own variables when I did "from pylab import *" after
> doing a bunch of data analysis. Or, conversely, I accidentally clobber a pylab function with
> one of my own variables.
>
> I recommend the idiom "import pylab as P". I use this with our local
> scientists all the time, explaining to them that this sets P as an abbreviation for pylab.
> Then we use P.plot and so on. Prepending a "P." in front of the pylab commands is really
> very low typing overhead and visual clutter, and I haven't heard or seen any resistance to it.
> We import numpy in a similar way.
>
> (...and while we're on the subject of visual clutter, I may be the only person in the world who
> utterly loathes iPython, but I'd like to second the request to make sure your demos work
> in plain vanilla python as well.)
>
> I do agree that pylab is very valuable for this kind of tutorial and for astronomers' Python use
> in general. In real life I do "from pylab import *" for quick&dirty interactive work, but I would
> never teach with it and I don't do it in a session where I'm doing any non-trivial amount of
> data manipulation because I've been burned.
>
> cheers,
> Vicki Laidler
>
>

>
> Message: 8
> Date: Wed, 25 May 2011 03:01:07 -0300
> From: Taro Sato <ubutsu at gmail.com>
> Subject: Re: [AstroPy] Practical Python for Astronomers web tutorial
> To: Vicki Laidler <laidler at stsci.edu>
> Cc: "astropy at scipy.org" <astropy at scipy.org>,    "jh at physics.ucf.edu"
>        <jh at physics.ucf.edu>
> Message-ID: <BANLkTikO0ZEd0g1NE=5oJVe2wiwfQZ3t8g at mail.gmail.com>
> Content-Type: text/plain; charset=UTF-8
>
> Hi there.  I also hope whoever will be writing tutorials and teaching
> materials actually try to preach good practices.  Namespace is there
> for a reason as are other conventions and coding standards.  I
> recently had to customize codes written by astronomers and it was an
> absolute nightmare dealing with all the global variables defined in
> different include files....  Yes the code worked but why don't you
> make them break the rules only after they know what they are doing?
>
> Taro
>
>



-- 
August Muench
Astrophysicist & Friend of the Virtual Observatory
Smithsonian Astrophysical Observatory
gmuench at cfa.harvard.edu
(617) 495-7979
@augustmuench