IaGraph: A Python Package for Quick Interactive Graphing

>>> plot(x, y)

 >>> contour(data, x, y)

(Click here for a list of more examples.)

Introduction

This is a package of interactive graphing tools, built upon the Climate Data Analysis Tools (CDAT) package (v4.0). IaGraph will create line plots, scatter plots, and contour plots. The current version of the package is 0.3.1.1.

Although I've used these routines in my own research, I cannot guarantee that they will work for your purposes. More disclaimers and other fine print is below.

If you email me your email address, however, I'll let you know of any major bugs that are found in this package.

The page is subdivided into these categories:

If you don't find the information you're looking for on this page, see the manual.


Package Description

General

The routines in this package allows you to make quick plots of atmospheric sciences data with a single line of Python code. I try to emulate IDL syntax, but there are substantial differences. Perhaps 30% of the time, the plot generated will also be suitable for publication, and procedures in this package will allow you to write those plots to a Postscript or GIF file. The other 70% of the time, however, you will want a more complex plot for publication, which this package cannot make.

Because IaGraph is designed to be simple as opposed to powerful, this web page and the examples it links to should be enough for most users. If you'd like more information about the structure of the package, troubleshooting, etc., see the manual.

Importing the Package

All procedures are the same name as the module they are contained in (and there is only one non-private procedure in that module). Thus, the plot function, which makes an x-y plot, in the plot module.

Normally if you import a package via a plain import you have to specify the entire package/module path in order to access a function (e.g. IaGraph.plot.plot). Since the purpose of this package is to allow you to do quick and dirty graphing, I recommend you put the following lines in your .pythonrc.py file, which starts up automatically each time you do an interactive session:

import IaGraph
from IaGraph import *

The first import line gives you access to the package's system variables (this is optional; you don't need to do this import if you are not planning to change any of the settings stored in the system variables). The second import line allows you to access all key package procedures (see the "Module Listing" section below) by procedure name, without needing the package and module names.

Making a Plot and Writing to a File

To plot an x-y line plot of vectors x and y on screen just type:

>>> plot(x, y)

To make a contour plot on screen of data, where the columns of data are indexed by vector x and the rows of data are indexed by vector y, type:

>>> contour(data, x, y)

In plots of quantities on the Earth, usually x is longitude and y is latitude, where data has rows of constant latitude. When you execute a plot or contour command, any preexisting plot in the active canvas is replaced by the new plot. Thus, the package currently can only make one plot at a time.

To write the last plot made (i.e. the plot specified by the IaGraph "active canvas" system variable) to the Postscript file plot.ps, type:

>>> active2ps("plot.ps")

Writing GIF to a file is done similarly:

>>> active2gif("plot.gif")

Overplotting additional plots is done using the oplot and ocontour commands, for overplotting line and contour plots, respectively.

By default, the active canvas is in window 0. To change the active canvas to a new window (window 1), use:

>>> window(1)

Subsequent plotting commands will be directed to the new window. Note that the old window is not closed and still remains in memory for later editing.

Summary of Bug Fixes, Updates, and Version History

A summary list of bugs and fixes, updates to the package, and a summary of the version history (with links to gzipped tar files of previous releases of the package) is found here.

[Back up top to the Introduction.]


Help and Examples

For more information on any command, type help(cmd), where cmd is the name of the command (e.g. plot). The command docstrings give detailed information regarding keyword options and settings.

By looking through a few examples, you'll find out 90% of all you need to know about this package:

Use help to list the codes for the available symbol codes, linestyles, etc. for each routine. Finally, here are some web pages that provide quick summaries of additional topics:

For more information see the concise package description and the manual.

[Back up top to the Introduction.]


Module Listing

All modules in the package are listed below. Only "key" commands are made available by the from IaGraph import * command; all other modules need to be imported by the full package/module name. The "Module Name" column provides links to the module source code. The "Pydoc" column provides links to documentation produced from the module docstrings by the pydoc tool. The "Key?" column notes whether the module contains key package commands or not (key commands are made readily available via a from IaGraph import * statement).

Module Name Pydoc Key? Function
__init__.py HTML Y Lists all modules in package, define system variable class, and set initial values for the system variables.
active2gif.py HTML Y Writes the active VCS canvas to a GIF file.
active2ps.py HTML Y Writes the active VCS canvas to a Postscript file.
contour.py HTML Y Plot contour plot to screen and save as active VCS canvas.
IaGraph_version.py HTML N Gives the version number for the package.
loadct.py HTML Y Load a specified color table into a given VCS canvas.
ocontour.py HTML Y Overplot a contour plot to screen onto the active VCS canvas.
oplot.py HTML Y Overplot an x-y plot to screen onto the active VCS canvas.
plot.py HTML Y Plot x-y plot to screen and save as active VCS canvas.
plotct.py HTML Y Plot a given color table to screen and save as active VCS canvas.
wavelen2rgb.py HTML N Given a wavelength of visible light (nm), returns an RGB triple that describes that color.
window.py HTML Y Set the active canvas to a specified window number.

[Back up top to the Introduction.]


Downloading and Installing the Package

Platforms

I've only tested IaGraph on a GNU/Linux system, though it should work on any Unix platform that runs CDAT.

Since I'm distributing the package as a gzipped tar file, if you're using Windows email me about getting the source code or download the modules one at a time from the module listing section above.

Dependencies

Python: IaGraph has been tested on and works on v2.2.2. and 2.3.3.

Full functionality of IaGraph requires the following packages and modules be installed on your system and findable via your sys.path:

Both cdms and vcs are part of the Climate Data Analysis Tools (CDAT). Numeric and MA are part of the Numerical Python (Numpy) package.

Installation of Numpy is trivial. Installation of CDAT, on the other hand, is more difficult (see their web site for details). Nonetheless, without the CDAT packages, IaGraph cannot do much (only plot will work without CDAT, and even then in only a limited way).

Package IaGraph itself is written entirely in the Python language.

Downloading and Installing

First, get the following file:

Expansion of the tar file will create the directory IaGraph-0.3.1.1. This directory contains the source code, the full documentation (HTML as well as images), a copy of the license, and example scripts.

To unzip and expand the tar file, execute at the command line:

gunzip IaGraph-0.3.1.1.tar.gz
tar xvf IaGraph-0.3.1.1.tar

There are a few ways you can install the package. For all these methods, first go into the IaGraph-0.3.1.1 directory:

You can append entries to your path by:

import sys
sys.path.append('newpath')

Where 'newpath' is the full path of the location you're appending to your Python path. Thus, if the directory IaGraph is in a directory /home/jlin/lib/python, 'newpath' is '/home/jlin/lib/python'. You can automate this by making the proper settings in a user customized .pythonrc.py file.

That's it!

Installing a Local Copy of the Documentation

The IaGraph-0.3.1.1 directory contains a complete copy of the documentation for the package, including images. Keep this directory around (you can rename it) if you'd like to have a local copy of the documentation. The front page for all documentation is the Doc/index.html file in IaGraph-0.3.1.1. The most recent copy of the documentation is located online here.

[Back up top to the Introduction.]


Copyright and Licensing

Software License

Unless otherwise stated, the Python routines described on this page or which reference this page are copyright © 2003-2004 by Johnny Lin and constitute a library that is covered under the GNU Lesser General Public License (LGPL):

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

You can contact Johnny Lin via this email or at the University of Chicago, Department of the Geophysical Sciences, 5734 S. Ellis Ave., Chicago, IL 60637, USA.

A copy of the GNU LGPL can be found here. Please note that these disclaimers of warranty supercede any implied or explicit warranties or claims found in the text of the routine source code themselves.

Documentation License

The referring web page is part of the documentation of the IaGraph package and is copyright © 2003-2004 Johnny Lin. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found here. The Transparent copy of this document is located at http://www.johnny-lin.com/py_pkgs/IaGraph/Doc/index.html.

[Back up top to the Introduction.]

Acknowledgements: Thanks to Dean Williams for lots of help! This work was carried out partially at the University of Chicago Climate Systems Center, funded by the National Science Foundation (NSF) Information Technology Research Program under grant ATM-0121028. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author and do not necessarily reflect the views of the NSF.

Return to Johnny Lin's Python Library.
Return to Johnny Lin's Home Page.

Valid HTML 4.01! Valid CSS! Updated: May 11, 2004 by Johnny Lin <email address>. License.