The SPIDER Python Library

Table of Contents

Overview
Installation
Example functions: readdoc, writedoc, and makeFilename
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.

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

The Spider directory is installed in your Python site-packages directory when you install Spire, which itself is part of the full SPIDER download.

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

Changes to version 1.2
makeSpiderFilename has been replaced by makeFilename, which allows additional replacement characters.
fileWriteLines has been added.
readdoc now has the lines keyword, while the keys keyword has been deprecated.

readdoc, writedoc, makeFilename and getfilenumber

readdoc (filename [, column=1, columns=None, lines=None])

Returns the contents of a Spider document file. You can request doc file columns (the output is in list form) or doc file lines (returns a dictionary).
Only one of column, columns, or lines may be used. If none are used, the default is column=1

• If only the filename is used, it returns the first doc file column as a list.
  
• The column keyword requires an integer corresponding to the desired column. It returns a list.
• column=0 returns the doc file keys.
• The columns keyword (note plural) requires a list of integers corresponding to a set of columns. It returns a tuple of lists.
  
• The lines keyword requires a list of doc file keys or the string 'all'. It returns a dictionary whose keys are the doc file's keys, and each key accesses a list corresponding to that line in the doc file.
  

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', columns=[1,2])
([1.0, 7.0, 14.0, 16.0, 27.0], [36797.0, 31989.0, 23748.0, 21499.0, 14098.0])
>>> # the output is a tuple of lists

>>> d = readdoc('defocus.hcc', lines=[3,4])
>>> {3: [14.0, 23748.0, 53.0, 85.0], 4: [16.0, 21499.0, -74.0, 496.0]}
>>> # the output is a dictionary

>>> d = readdoc('defocus.hcc', lines='all')  # get the entire doc file
>>> d.keys()
[1, 2, 3, 4, 5]
>>> d
{1: [1.0, 36797.0, 88.0, 196.0], 2: [7.0, 31989.0, -77.0, 151.0], 3: [14.0, 23748.0, 53.0, 85.0], 4: [16.0, 21499.0, -74.0, 496.0], 5: [27.0, 14098.0, 33.0, 336.0]}
>>> d[2]  # see the line at key=2
[7.0, 31989.0, -77.0, 151.0]

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.

makeFilename (filename, number [, char='*'])

Returns a filename with a number substituted for asterisks (default char).
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.
The optional char keyword lets you use a different replacement character.
Examples:

>>> makeFilename('mic***.dat', 123)
'mic123.dat'
>>> fn = makeFilename('mic***_$$$.gtp', 23, char='$')
>>> fn
'mic***_023.gtp'
>>> makeFilename(fn, 44)
'mic044_023.gtp'
>>> makeFilename('tmp/mic***.dat', 123456)
'tmp/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.
Example:

>>> getfilenumber("mic0089.ext")
'0089'  # output is a string

filenumber (filename)

Returns the number from a filename as an integer.
Example:

>>> filenumber("mic0089.ext")
89  # output is an integer