The SPIDER Python Library

Table of Contents

Overview
Installation
Example functions: readdoc, writedoc, and makeSpiderFilename
The Spider Python Library : Spiderutils.py
Coding Examples
The Python Imaging Library
Displaying images with Tkinter
Array operations : Spiderarray.py
Spire compatibility : Spiderscripts.py

Overview

The SPIDER Python Library was developed to provide functions for handling SPIDER files in your Python programs. In particular, your scripts can read or write Spider document files in a single line. Data columns from doc files can be treated as arrays. The Python Imaging Library provides general image processing operations for SPIDER images, and lets you display them in Tkinter. Numerical array operations may also be applied to SPIDER images and volumes.

Note: The SPIDER Python Library does NOT let your scripts call SPIDER operations, as in
output = AP_MQ(input arguments...) For that, you need the Python Wrapper for SPIDER (under development).

Python vs SPIDER batch files

There are some differences to keep in mind:

• Perhaps the greatest novelty for programmers new to Python is the strict enforcement of indentation. Program blocks are defined by indentation, not labels and end statements, such as ENDIF or LB1.
• Filenames are strings in Python, and must be enclosed in quotes (either 'single' or "double"). Strings are a Python data type for sequences of characters.
• Unlike SPIDER batch files, filenames in Python scripts require the data extension.
  Therefore, use "file001.dat", not FILE001.
• As in Unix, uppercase vs lowercase matters.

There are a few Python tutorials out there: Instant Python, various Python tutorials, and the Python web site has a few pointers

The conventions below:

Function names are bold.
Function keywords are inside parentheses.
Keywords in square brackets are optional, and have default values. That means if the definition looks like:
readdoc (filename [, column=1, keys=0]),
you can use
readdoc(filename), and it assumes you mean readdoc(filename, column=1, keys=0).

The Python prompt, >>>, assumes you have started Python and imported the Spider Python Library:

% python
Python 2.3.3 (#9, May 25 2004, 10:53:39) [C] on irix6
>>> from Spider.Spiderutils import *
>>> # type python commands at the prompt

Installation

Download the file SpiderPythonLibrary-1.0.tar.gz from http://www.wadsworth.org/spider_doc/spider/download.
Extract the files:
       gunzip SpiderPythonLibrary-1.0.tar.gz
       tar xvf SpiderPythonLibrary-1.0.tar
       cd SpiderPythonLibrary-1.0
Run setup.py install (or just copy the Spider/ directory to your Python site-packages directory.)

readdoc, writedoc, makeSpiderFilename and getfilenumber

readdoc (filename [, column=1, keys=0])

Returns the contents of a Spider document file. The output is either a list or a dictionary (see Python documentation about these data types).
keys can be either 0, 1, or 'all' (in quotes)

• If keys=0 (default), it returns a list of column values (column=1 refers to the 1st Spider document file data column. column=0 refers to key column).
• If keys=1, it returns a dictionary indexed by keys. Each dictionary key is associated with the value from the specified column.
• If keys='all', it returns a dictionary indexed by keys. Each dictionary key is associated with a list of ALL the values for that key (the column keyword is ignored).

Examples:
The Spider document file shown below has four columns of data:

 ;spi/hcc   06-OCT-2004 AT 10:53:47   defocus.hcc
 ; /    MICROGRAPH   DEFOCUS      ASTIG.ANG   ASTIG.MAG
    1 5   1.0000       36797.       88.       196.0 
    2 5   7.0000       31989.      -77.       151.0 
    3 5   14.000       23748.       53.       85.0     
    4 5   16.000       21499.      -74.       496.0     
    5 5   27.000       14098.       33.       336.0
 
>>> readdoc('defocus.hcc') # same as readdoc('defocus.hcc', column=1)
[1.0, 7.0, 14.0, 16.0, 27.0]

>>> readdoc('defocus.hcc', column=2)
[36797.0, 31989.0, 23748.0, 21499.0, 14098.0]

>>> readdoc('defocus.hcc', column=2, keys=1)
{1: 36797.0, 2: 31989.0, 3: 23748.0, 4: 21499.0, 5: 14098.0}
>>> # the output is a Python dictionary - items are accessed by key:
>>> d = readdoc('defocus.hcc', column=2, keys=1)
>>> d[3]
23748.0  # for key=3: the value from column 2

>>> d = readdoc('defocus.hcc', keys='all')
>>> d[5]
[27.0, 14098.0, 33.0, 336.0] # all the values for key=5

NB: this function only works for document files from Spider version 11.0 or later (with data separated by spaces).

writedoc (filename, columns=None, lines=None [, headers=None, keys=None, mode='w'])

Writes data to a file in Spider document file format.
Data can be organized as a set of columns or a set of lines.
(or as a dictionary, for compatibility with readdoc)
The call to writedoc must use EITHER the columns OR lines keyword.
Data must be integer or float.
filename: must have the data extension.
columns: a list of lists; each doc file column is a list of numbers.
lines: a list of lists; each doc file line is a list of numbers.
headers: a list of strings for column headings.
keys: a list of integers. Default starts with first key = 1.
mode='w' (default): deletes previously existing file. mode='a' appends to file.

Examples:

>>> A = [1.0, 7.0, 14.0, 16.0, 27.0]  # create a list of numbers
>>> B = [36797, 31989, 23748, 21499, 14098]  # another list
>>> hdrs = ['mics', 'defocus']  # a list of strings for column headings
>>> writedoc('file001.dat', columns=[A,B], headers=hdrs)

produces the file, file001.dat:

 ;dat/dat   03-MAR-2006 AT 15:28:34   file001.dat
 ; /            mics     defocus
    1  2           1       36797
    2  2           7       31989
    3  2          14       23748
    4  2          16       21499
    5  2          27       14098

>>> writedoc('file002.dat', lines=[A,B])

produces the file, file002.dat:

 ;dat/dat   03-MAR-2006 AT 15:29:50   file002.dat
    1  5           1           7          14          16          27
    2  5       36797       31989       23748       21499       14098

Remember that columns (and lines) must refer to a list of lists.
columns=[10, 20, 30]      (1 set of brackets) will generate an error.
columns=[[10, 20, 30]]      (note 2 sets of brackets) will create a doc file with a single column.

makeSpiderFilename (filename, number)

Returns a filename with a number substituted for asterisks.
Substitutes the first set of asterisks it finds (i.e. leftmost).
If the number of asterisks is too small for the number of digits, the filename is extended.
Examples:

>>> makeSpiderFilename('mic***.dat', 123)
'mic123.dat'
>>> makeSpiderFilename('tmp/mic****.gtp', 23)
'tmp/mic0023.gtp'
>>> makeSpiderFilename('mic***.dat', 123456)
'mic123456.dat'

getfilenumber (filename)

Returns the number from a filename as a string with leading zeroes.
The file number must immediately precede the extension dot. Returns "" if no number found.
Examples:

>>> getfilenumber("mic0089.ext")
'0089'  # note, output is a string
>>> int(getfilenumber("mic0089.ext"))
89  # output converted to integer