The pygrace project is a set of tools designed to act as an interface between the Python programming language and the Grace plotting tool.

pygrace allows users to create complex Grace files from within Python.

It is 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.

pygrace was originally created by Dean Malmgren, Mike Stringer, and members of the Amaral Lab. When they decided to let pygrace die a slow death, its maintainance was taken over by Daniel Stouffer and the Stouffer Lab.

To get started with pygrace, see the installation guide.

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 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 git repository at the Github page. The next section describes how to do so.

Installing a development version

To clone the pygrace repository, change to a directory where you want to save the code and type:

git clone https://github.com/pygrace/pygrace.git

To install pygrace, all you need to do is enter into the pygrace directory you just created and run setup.py:

cd pygrace
python setup.py install

By default, Python will attempt to install pygrace in the global Python site-packages directory. If you don't have permissions to do this (or prefer not to install pygrace globally), you can install it locally by adding the --user option:

python setup.py install --user

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 templates entity-relationship diagram The inheritance structure of pygrace templates 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 wants to, e.g., create a custom data symbol and have the symbol show up in the coordinate system of a graph.
• pygrace templates Cheatsheet This handy cheatsheet shows the all of the methods and attributes of each pygrace templates class. It can be generated for any custom template by calling the write_cheatsheet method.
• pygrace templates attribute diagram This is a detailed diagram that shows all of the attributes of the standard pygrace templates objects.

By refering to these diagrams and going through the examples, you can develop a sense of how to use pygrace. Please let us know what you think and report bugs using the GitHub page.

TBD.

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 templates, contact us.

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).

• Evolutionary conservation of species' roles in food webs Stouffer DB, Sales-Pardo M, Sirer MI, Bascompte J Science 335(6075): 1489-1492 2012
• Strong contributors to network persistence are the most vulnerable to extinction Saavedra S, Stouffer DB, Uzzi B, Bascompte J Nature 478(7368): 233-235 2011
• Duality between time series and networks Campanharo ASLO, Sirer MI, Malmgren RD, Ramos FM, Amaral LAN PLoS One 6(8): e23378 2011
• The role of body mass in diet contiguity and food-web structure Stouffer DB, Rezende EL, Amaral LAN J. Anim. Ecol. 80(3): 632-639 2011
• Compartmentalization increases food-web persistence Stouffer DB, Bascompte J Proc. Natl. Acad. Sci. USA 108(9): 3648-3652 2011
• The role of mentorship in protégé performance Malmgren RD, Ottino JM, Amaral LAN Nature 465(7298): 622-626 2010
• On universality in human correspondence activity Malmgren RD, Stouffer DB, Campanharo ASLO, Amaral LAN Science 325(5948): 1696-1700 2009
• 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