pygrace

About

The pygrace project is a set of tools that were designed to act as an interface between the Python programming language and the Grace plotting tool. The pygrace package is a combination of two previously distinct projects:

• PyGrace, developed by members of the Amaral Lab. The functionality of the old PyGrace package is now in the new package under the name of templates.
• pygrace, developed by Mike McKerns. The functionality of the previous pygrace package is available in the new package under the name session.

Templates allow users to create complex Grace files from within Python; they are intended to:

• assist in the automated creation of many figures for use in large-scale exploratory data analysis.
• encourage code reuse, by offering an object-oriented structure.
• reduce the time required to create figures for scientific journal articles.

A pygrace session offers bindings to xmgrace as an alternative to the Grace console. This provides users with a powerful 2D scientific visualization platform that can be used as an alternative to MATLAB or Mathematica.

pygrace sessions were created by Mike McKerns, and pygrace templates were created by Dean Malmgren, Mike Stringer, and members of the Amaral Lab. Mike M., Dean M., and Mike S. are the maintainers of the pygrace project on SourceForge.

To get started with pygrace, see the tutorial.

Timeline

Tutorial

Important note: As of August 2009, the pygrace package is in a time of transition. As such, the following tutorial will be out of date very soon, but will be replaced by a more comprehensive one. The following tutorial applies to the pygrace/trunk version of the project.

Visualizing data may be an integral part of the data analysis process, however, pygrace templates are explicity intended to not perform any type of data analysis. Not even computing an average. Especially not performing a linear regression. This principle underlies much of the structure of pygrace templates, with the purpose discouraging users to adopt a “black box” approach to analysis. While visualizing data should be as painless as possible, the pain required to understand the analysis process is considered necessary, or even desirable (if you're into that sort of thing).

This tutorial is meant to help with installation of pygrace, and give new users an idea of how pygrace is structured. After reading this brief document, the next step for learning to use pygrace is to go through the examples that are located in the pygrace.templates Examples directory.

Installation

As pygrace is still young, the only method yet available to install it is to check out the source code from the Subversion repository at the SourceForge page. The next section describes how to do so.

Installing a development version

To check out the PyGrace repository, change to a directory where you want to put PyGrace, and type:

svn co https://pygrace.svn.sourceforge.net/svnroot/pygrace/trunk PyGrace

For now, it is important to use the “correct” capitalization of PyGrace (capital P and G). Then, make sure that the directory you are in is on the python path (the PYTHONPATH environment variable). One convenient way to do this is to add a line in your ~/.bashrc file that says:

export PYTHONPATH:\$PYTHONPATH:/path/to/your/pybrary/

Notice that, unlike the lame-o author of this documentation, it is not necessary to call the directory that PyGrace is located “the pybrary.” After the location of PyGrace is on the PYTHONPATH, import statements in python scripts will look in that directory (.../pybrary/) for modules, and since PyGrace is a package (it has an __init__.py file in the directory), the directory will act like a module. Now, make sure that you have executed the ~/.bashrc file by running.

source ~/.bashrc

That should do the trick. You can test that python can find the PyGrace package by opening an interactive python prompt and typing

import PyGrace

If no error is raised, then installation was succesful!

Getting started

PyGrace was designed so that, “anything you can do in Grace, you can do in PyGrace.” The best way to get started is to go through the examples in the Examples directory. Each example is fully commented. You may also find the following three documents helpful:

• PyGrace entity-relationship diagram The inheritance structure of PyGrace mirrors the file structure of Grace. This diagram uses “crow's foot” notation to indicate the relationship between different entities. One thing to note is that Drawing Objects can be associated with either a Grace or a Graph. This is important in cases where one want to, e.g., create a custom data symbol and have the symbol show up in the coordinate system of a graph.
• PyGrace Cheatsheet This handy cheatsheet shows the all of the methods and attributes of each PyGrace class. It can be generated for any custom template by calling the write_cheatsheet method.
• PyGrace attribute diagram This is a detailed diagram that shows all of the attributes of the standard PyGrace objects.

By refering to these diagram and going through the examples, you can develop a sense of how to use PyGrace. Remember to report bugs using the SourceForge page!

Screenshots

Here are some examples of the types of figures that you can create with pygrace templates. If you are interested in contributing a screenshot of a figure made in pygrace, contact us.

Publications

If you use pygrace in a scientific publication, please let us know and we will add a link to your publication on this page (where everybody will see it).

• Characterizing individual communication patterns Malmgren RD, Hofman JM, Amaral LAN, Watts DJ Proc. ACM SIGKDD 607-616 2009
• A Poissonian explanation for heavy tails in e-mail communication Malmgren RD, Stouffer DB, Motter AE, Amaral LAN Proc. Natl. Acad. Sci. USA 105(47): 18153-18158 2008
• Effectiveness of Journal Ranking Schemes as a Tool for Locating Information Stringer MJ, Sales-Pardo M, Amaral LAN PLoS ONE 3(2): e168 2008