This section is meant to help users on well-supported platforms and common Python environments get started using Chaco as quickly as possible. If your platform is not listed here, or your Python installation has some quirks, then some of the following instructions might not work for you. If you encounter any problems in the steps below, please refer to the Installing and Building Chaco section for more detailed instructions.
There are several different ways to get Chaco:
Install the Enthought Python Distribution. Chaco and the rest of the Enthought Tool Suite are bundled with it. Go to the main Enthought Python Distribution (EPD) web site and download the appropriate version for your platform. After running the installer, you will have a working version of Chaco.
Enthought Python Distribution is free for academic and personal use, and fee-based for commercial and government use.
(Windows, Mac) Install from PyPI using easy_install (part of setuptools) from the command line:
(Linux) Install distribution-specific eggs from Enthought’s repository. See the ETS wiki for instructions for installing pre-built binary eggs for your specific distribution of Linux.
(Linux) Install via the distribution’s packaging mechanism. We provide .debs for Debian and Ubuntu and .rpms for Redhat. (TODO)
Download source as tarballs or from Subversion and build. See the Installing and Building Chaco section.
Chaco requires Python version 2.5.
Depending on how you installed Chaco, you may or may not have the examples already.
If you installed Chaco as part of EPD, the location of the examples depends on your platform:
If you downloaded and installed Chaco from source (via the PyPI tar.gz file, or from an SVN checkout), the examples are located in the examples/ subdirectory inside the root of the Chaco source tree, next to docs/ and the enthought/ directories.
If you installed Chaco as a binary egg from PyPI for your platform, or if you happen to be on a machine with Chaco installed, but you don’t know the exact installation mechanism, then you will need to download the examples separately using Subversion:
ETS 3.0 or Chaco 3.0:
svn co https://svn.enthought.com/svn/enthought/Chaco/tags/3.0.0/examples
ETS 2.8 or Chaco 2.0.x:
svn co https://svn.enthought.com/svn/enthought/Chaco/tags/enthought.chaco2_2.0.5/examples
Almost all of the Chaco examples are stand-alone files that can be run individually, from any location.
All of the following instructions that involve the command line assume that you are in the same directory as the examples.
Run the simple_line example:
This opens a plot of several Bessel functions and a legend.
You can interact with the plot in several ways:
To pan the plot, hold down the left mouse button inside the plot area (but not on the legend) and drag the mouse.
To zoom the plot:
- Mouse wheel: scroll up to zoom in, and scroll down to zoom out.
- Zoom box: Press “z”, and then draw a box region to zoom in on. (There is no box-based zoom out.) Press Ctrl-Left and Ctrl-Right to go back and forward in your zoom box history.
- Drag: hold down the right mouse button and drag the mouse up or down. Up zooms in, and down zooms out.
- For any of the above, press Escape to resets the zoom to the original view.
To move the legend, hold down the right mouse button inside the legend and drag it around. Note that you can move the legend outside of the plot area.
To exit the plot, click the “close window” button on the window frame (Windows, Linux) or choose the Quit option on the Python menu (on Mac). Alternatively, can you press Ctrl-C in the terminal.
You can run most of the examples in the top-level examples directory, the examples/basic/ directory, and the examples/shell/ directory. The examples/advanced/ directory has some examples that may or may not work on your system:
For detailed information about each built-in example, see the Annotated Examples section.
While all of the Chaco examples can be launched from the command line using the standard Python interpreter, if you have IPython installed, you can poke around them in a more interactive fashion.
Chaco provides a subpackage, currently named the “Chaco Shell”, for doing command-line plotting like Matlab or Matplotlib. The examples in the examples/shell/ directory use this subpackage, and they are particularly amenable to exploration with IPython.
The first example we’ll look at is the lines.py example. First, we’ll run it using the standard Python interpreter:
This shows two overlapping line plots.
You can interact with the plot in the following ways:
To pan the plot, hold down the left mouse button inside the plot area and dragging the mouse.
To zoom the plot:
- Mouse wheel: scroll up zooms in, and scroll down zooms out.
- Zoom box: hold down the right mouse button, and then draw a box region to zoom in on. (There is no box-based zoom out.) Press Ctrl-Left and Ctrl-Right to go back and forward in your zoom box history.
- For either of the above, press Escape to reset the zoom to the original view.
Now exit the plot, and start IPython with the -wthread option:
This tells IPython to start a wxPython mainloop in a background thread. Now run the previous example again:
In : run lines.py
This displays the plot window, but gives you another IPython prompt. You can now use various commands from the chaco.shell package to interact with the plot.
Import the shell commands:
In : from enthought.chaco.shell import *
Set the X-axis title:
In : xtitle("X data")
Toggle the legend:
In : legend()
After running these commands, your plot looks like this:
The chaco_commands() function display a list of commands with brief descriptions.
You can explore the Chaco object hierarchy, as well. The chaco.shell commands are just convenience functions that wrap a rich object hierarchy that comprise the actual plot. See the Exploring Chaco with IPython section for information on more complex and interesting things you can do with Chaco from within IPython.
There have been several presentations on Chaco at previous PyCon and SciPy conferences. Slides and demos from these are described below.
Currently, the examples and the scipy 2006 tutorial are the best ways to get going quickly. (See http://code.enthought.com/projects/files/chaco_scipy06/chaco_talk.html)
Some tutorial examples were recently added into the examples/tutorials/scipy2008/ directory on the trunk. These examples are numbered and introduce concepts one at a time, going from a simple line plot to building a custom overlay with its own trait editor and reusing an existing tool from the built-in set of tools. You can browse them on our SVN server at: https://svn.enthought.com/enthought/browser/Chaco/trunk/examples/tutorials/scipy2008
The API docs for Chaco 3.0 (in ETS 3.0) are at: http://code.enthought.com/projects/files/ETS3_API/enthought.chaco.html
The API docs for Chaco2 (in ETS 2.7.1) are at: http://code.enthought.com/projects/files/ets_api/enthought.chaco2.html