Home
About
Requirements
Screenshots
Download
Docs
Links
Contact

Getting Started Tutorial

Introduction

This aim of this tutorial is to provide the reader with adequate background to start using the PyStripchart widget set. The intended audience for this tutorial includes both Open Source software developers and members of the scientific community. Suggestions for the tutorial are most welcome. Please send your suggestions to Jonathan Merritt (email address is on the Contact Page).

Requirements

PyStripchart is developed under the Linux operating system (see, for example, www.linux.org), and for now this tutorial is designed for Linux users. So, the first requirement is a well-equipped Linux box with X-Windows, etc. If you have trouble setting this up, consult your local Linux guru.

GTK+ 2.4.0

First, you'll need GTK+ 2.4.0 installed. GTK+ is the widget set that PyStripchart is built upon. GTK+ is used for many Linux applications, including The Gimp. To check that you have the correct version of GTK+ installed, you can use the program pkg-config. Open up a Linux command shell and try the following:
[jsm@Reptile]$ which pkg-config
/usr/local/bin/pkg-config
[jsm@Reptile]$ pkg-config --version
0.15.0
[jsm@Reptile]$ pkg-config --modversion gtk+-2.0
2.4.0
(Note that [jsm@Reptile]$ is the shell prompt.) pkg-config may not be installed in the /usr/local/bin directory as shown above; the which command is used just to make sure you have pkg-config installed. If pkg-config reports that you have version 2.4.0 (or later) of GTK+ installed then you're OK. Otherwise, go fetch and install it.

Python 2.3.3

PyStripchart is written in Python, so naturally you need Python installed to use it. To check if you have Python set up correctly, you can try opening an interactive python session. Try the following in your shell:
[jsm@Reptile]$ python
Python 2.3.3 (#1, Jan 25 2004, 10:17:37) 
[GCC 3.3.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>
If you can successfully open an interactive session like this, and the version indicated is 2.3.3 (or later) then Python is installed. (Note: You can quit the Python session by pressing [Ctrl]-D.) If you don't have this version or newer of Python then go fetch and install it. Now would be a good time to read the Python Tutorial if you're new to Python.

PyGTK 2.2.0

The link between Python and GTK+ is achieved via PyGTK. This is a wrapper library, which wraps the GTK+ set of widgets and makes then accessible to Python. To check that you have PyGTK 2.2.0 (or newer) installed, try the following from the shell:
[jsm@Reptile]$ pkg-config --modversion pygtk-2.0
2.2.0
[jsm@Reptile]$ python
Python 2.3.3 (#1, Jan 25 2004, 22:25:46) 
[GCC 3.3.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import gtk
>>> gtk.gtk_version
(2, 4, 0)
pkg-config should report version 2.2.0 (or newer) of PyGTK. If you import the gtk module into Python as shown then its gtk_version variable should tally with the version of GTK+ that you have installed (as determined above). Note that there are a PyGTK Tutorial and FAQ available. You should familiarize yourself with the contents of these.

Download and Installation

You can download PyStripchart from the Download page. Currently, only the source code is available. Extract the package using the tar program (tar -xzf <filename>). This will extract the source code into a directory called pystripchart-x.x.x, where x are the version numbers. From within the extracted directory, you should be able to install PyStripchart by doing the following:
[jsm@Reptile]$ su
Password: <root password>
[root@Reptile]# python setup.py install
              ...
  <lots of installation information>
              ...
[root@Reptile]# exit
exit
[jsm@Reptile]$ ./runtests.py
Running PyUnit tests for pystripchart...
.............................................
----------------------------------------------------------------------
Ran 45 tests in 1.458s
 
OK
... PyUnit tests were successful! :-)
Running doctest tests for pystripchart...
... doctest tests completed.
You should see the installation complete successfully and see the tests complete without failure. There may be different numbers of tests performed, but there should be no errors during this process.

Example Code

PyStripchart has some examples in the demo directory of the distribution.  This tutorial will examine the code in the file striptableaudemo.py in detail.  You should be able to execute this file and experiment with it to begin with. You'll see something like this:



The two individual channels can be expanded by clicking on their buttons in the toolbar, and contracted by clicking on the close buttons next to the channel name.

Example Usage

This example refers to code within the file striptableaudemo.py, which is included in the distribution.

Suppose that you have acquired data about the air speed of swallows (this is a Monty Python joke - references to Monty Python are encouraged in Python examples). You have data about the speed of both an unladen swallow and a swallow that is carrying a coconut (unlikely though this may seem). PyStripchart is to be used to display this data retrospectively after it has been acquired. This is probably not the best use for the package: it's better suited for real time display than for retrospective display, but this scenario has been chosen for simplicity.

The speed data for both swallows has been acquired at 25 Hz, for 8 seconds (therefore 200 samples for each swallow). This data has been stored as columns in the file swallows.dat, which is included in the distribution. The read_data() function loads this data into two array objects, one for the unladen swallow and one for the coconut-carrying swallow.

In the create_GUI() method, a standard, top-level GTK window is created for the application. This window is then populated with a menu bar, a toolbar, and a StripTableau widget. The StripTableau widget is part of the PyStripchart distribution, and is a good widget to use for those starting with the package. The StripTableau widget is created within the create_StripTableau() function in the demo.

To create the StripTableau widget, the code inside create_StripTableau() reads as follows:
                hadj = gtk.Adjustment(0, 0, 8, 0.1, 1, 1)
                sel  = gtk.Adjustment(-1)
                self.striptableau = stripchart.StripTableau(hadj, sel)
                self.striptableau.metawidth  = 120
                self.striptableau.gradewidth = 100
                self.vbox.pack_end(self.striptableau.widget, gtk.TRUE,
                        gtk.TRUE)
In the first part:
                hadj = gtk.Adjustment(0, 0, 8, 0.1, 1, 1)
                sel  = gtk.Adjustment(-1)
A pair of gtk.Adjustment objects are created: one for controlling the horizontal range displayed on the StripTableau widget and one for controlling the selection capability of the widget. The horizontal range of the widget behaves like any other range widget, and may be connected to other widgets by assigning them the same gtk.Adjustment object as the data model.

Then:
                self.striptableau = stripchart.StripTableau(hadj, sel)
                self.striptableau.metawidth  = 120
                self.striptableau.gradewidth = 100
The widget is created, and its metawidth and gradewidth instance variables are set. These variables control the width of the "metadata" and "grade" parts of the widget respectively. The metadata region is on the right where the name of the channel is displayed and the grade region is on the left where the graduated scale is shown.

Now, both data channels are added to the widget. The code used to do this, for example for the unladen swallow, is the following:
                vadj_unladen = gtk.Adjustment(-10, -20, 20, 0, 0, 20)
                unladen_item = self.striptableau.addChannel(self.unladen,
                        vadj_unladen)
                unladen_item.name = "Unladen"
                unladen_item.meta = self.create_text(
                        "Air speed of an unladen swallow.")
                unladen_item.period = 1./25
First, a gtk.Adjustment is is created:
                vadj_unladen = gtk.Adjustment(-10, -20, 20, 0, 0, 20)
This controls the vertical range that is shown for this particular channel. Next, the addChannel() function is called on the StripTableau widget to add the data to the widget:
                unladen_item = self.striptableau.addChannel(self.unladen,
                        vadj_unladen)
This function returns a TableauItem widget, which packages the data in a GUI format for display, and this returned widget gets assigned to unladen_item.

The code then sets the name instance variable, which sets the name displayed on the channel in the metadata region. The meta instance variable is set next, which is an optional component that can be displayed in the region below the name of the channel:
                unladen_item.name = "Unladen"
                unladen_item.meta = self.create_text(
                        "Air speed of an unladen swallow.")
In this case, meta is set to a text view that displays some extra information about the channel. Finally, the period instance variable is set, which specifies the sampling period for the original data:

Our data was sampled at 25Hz, hence the sampling period is 1/25 s.
                unladen_item.period = 1./25

And that's it! This produces a functioning StripTableau widget which contains and displays the pair of channels for the swallow data.


Page Last Updated: 2004-03-28

Project hosted by:
SourceForge.net Logo