Jump to: About windowing systems , Alternate Graphics
About graphics packages for the courseware
The courseware interfaces with your graphics environment only through the plotting routines in ClimateGraphics.py , which is imported by the ClimateUtilities module. Therefore, only ClimateGraphics.py needs to be modified according to the graphics environment you are using to produce plots. I currently support two graphics packages: PyNgl and MatPlotLib. I have more experience with PyNgl, but for most users MatPlotLib is probably the best choice, especially since it is installed as part of the Enthought distribution. For Windows users, MatPlotLib has the advantage that it doesn't require installation of an x11 windowing package (which would usually be CygWin). On a Mac, MatPlotLib uses the native windowing system, so it can't put up graphics across the network, but it does use x11 on Linux, and so can be used with a centralized courseware server. MatPlotLib is described under Alternate Graphics.
The ClimateGraphics module that comes with the courseware uses the PyNGL graphics module to produce graphical output, so you need to install this on your system. You can customize the ClimateGraphics module for use with some other graphics package if you like. Some users will find it easier to use MatPlotLib instead of installing PyNGL. Use of MatPlotLib is supported by the ClimateGraphicsMPL courseware module. See Alternate Graphics for details.
PyNgl is distributed through the Earth System Grid. It is available for various versions of Mac OSX, for Linux, and with a bit more trouble can also be made to run on Microsoft Windows. To obtain PyNGL, first go to Earth System Grid. The sofware you want is under the link to PyNGL under "Analysis and Visualization Software" near the bottom of the page. To download the software, you will need an Earth System Grid account. Anybody can get an account, and the process is simple and quick. To create an account, go to the "Login" tab and click the "Create New Account" under the Login window. Once you have an account set up, go back to the Earth System Grid home page and click the PyNGL link. The software is listed under "nested collections." As of 9/2010, the current release is Version 1.3.1, and you should click on this link. Then follow the link to the "precompiled binaries." There are two versions of these -- one with "cairo" support and one without. The one with "cairo" support allows output of graphics in png and various other formats, which you don't really need, but you might as well install this version as it can be convenient to be able to output graphics in png format for use on web pages. If you run into problems with the version with cairo support, you can fall back to the version without. Installation instructions for Mac OSX and Linux are nearly identical, except for a slight difference about the location of the directory where you have to put the files.
Once on the precompiled binaries page, you should click the link for "Download Files in this Collection." You may be asked to log in again at this point. After accepting the license agreement, you will get a list of files available for download. The distributions are all in the form of tar archive files, which can be unpacked by double-clicking on a Mac, or by using the command line equivalent on either Mac or Linux. If using Linux, download the version appropriate to your system. For Mac OSX, download the version PyNGL-1.3.1.macos-10.5-i386-py265-numpy130.tar.gz which is a 32-bit version working with Python 2.6 (the pre-built binaries of which are also generally 32-bit). The OS 10.5 32-bit version works fine on OS 10.6, and will probably work with later versions as well. The version PyNGL-1.3.1.macos-10.5-i386-py265-numpy141.tar.gz is similar, but was compiled to run with Version 1.4.1 of numpy, though mostly it seems that a lot of different versions of numpy will work fine with PyNGL. If you have decided to make the leap to 64 bits on your Mac, and have installed a 64-bit version of Python, then instead you should download one of the 64-bit builds of PyNGL, e.g. PyNGL-1.3.1.macos-10.6-x86_64-py265-numpy130.tar.gz . If you have one of the older PPC processor macs instead of one of the Intel-based macs, then instead you should download PyNGL-1.3.1.macos-10.5-ppc32-py265-numpy141.tar.gz.
Unlike Python and numpy, the Mac OSX distribution for PyNGL is not available as a single-click installer. You have to put the files in the right place more or less manually, just as you do under Linux. Under either system the most reliable way to do this is to first unpack the tar archives into whatever temporary holding directory you want. This will create a subdirectory with a name like the tarfile, but without the extension. Deep in this directory, following down the lib branch, is a directory called site-packages . You want to move the contents of this directory (not the directory itself) to the site-packages directory located in the lib directory in the place where the version of Python you are using was installed. If you used the disk image installer on the Mac, this will be a deep down subdirectory of /Library/Frameworks/Python.framework . For example, if you installed Python2.6, the full path of the directory to move the files to is:
You may also be able to locate the directory by using Spotlight to search for the phrase site-packages, but be careful, as you may have more than one such folder and also the Spotlight database might not be up to date and might not find them all. You can also do a which python and then do an ls -l on the result to find the root directory for your python installation.
On a Mac you can move the files by dragging in the Finder (you will be asked for administrator authorization). Alternately, from a terminal window you can use the linux command mv , though you will need to log in with superuser permission to do so. (Or use the command sudo mv ... , which will then ask you to log in with your password. This will work if you have administrator permission on your machine).
Under Linux, the procedure is the same -- just move the site-packages files from the PyNGL distribution to the site-packages directory for your Python distribution -- but the precise place where Python has been installed will vary from one Linux implementation to another. Just find the right Python root directory by doing which python and then ls -l on the result. The part of the directory path before the "bin" directory is where you want to search downward from to find lib/site-packages .
I will eventually find some way to simplify and automate this process, but the above procedure (while lengthy to explain) is simple and fairly foolproof.
PyNGL uses the x11 windowing system to display graphics, which is nice because that means it can display graphics across a network connection. On Mac and Linux you don't need to do anything further to use x11, because x11 comes shipped with Mac OS X (you can find it in the Applications->Utilities folder), and x11 is the native windowing system under Linux. For Microsoft Windows, you need to install CygWin if you want to use PyNGL.
Many climate datasets are stored in the netCDF file format, and if you can learn to read these files, it opens up a whole world of data analysis. There is a handy module, PyNio, which is distributed through the same site as PyNgl, and is installed using a similar procedure. None of the Workbook problems require reading netCDF datasets, but a very few of the plots in Chapter 7 (Seasonal cycles) and Chapter 9 (A peek at dynamics) are made from netCDF data. [**Note fix needed in order to use some versions of PyNio with Python 2.6]
Installation for Microsoft windows: [**Under Construction. Most Windows users would do better to use MatPlotLib, installed as part of the Enthought distribution. ]
[**x11. Native windowing systems. x11 is the native window system for Linux. When x11 is needed (mainly for Ngl on Mac). When using Ngl on Mac, how to let Python know to put display in an x11 window (happens automatically, even if starting from a double-click of idle).]
MatPlotLib is an outstanding graphics package available for Mac, Windows and Linux. It emulates Matlab-style graphics and is very powerful. MatPlotLib comes shipped with the Enthought Python distribution, but it can be installed on any Python of your choice.
ClimateGraphicsMPL.py provides MatPlotLib support, and is imported automatically if PyNgl isn't found on your system. You could also simply write your own plotting commands using the simple MatPlotLib commands, lucidly described at the link. MatPlotLib does not work very gracefully with idle because of the way it handles its interactive windows, but on a Mac or Linux if you start idle from the command line using
it works well enough. (I'm not yet sure what the corresponding procedure would be for running idle on Windows, but I will update this section once we get more experience with this issue on Windows).
If you want to use some other The only module that needs to be modified is
ClimateGraphics.py, since all references to graphics in the courseware go through the higher-level plotting interface in ClimateUtilities. If you are using a Windows machine, it is alost certainlysimpler to use MatPlotLib (especially with the Enthought distribution) than to install PyNgl, which also requires installation of CygWin to get the x11 windowing system used by PyNgl to display graphics.