Back: Parameters Home: Table of Contents Next: Edit configuration

Spire Configuration files

Configuration project attributes
Main window attributes
Location of source Procedure files
Dialogs and Procedure files
Directories
Configuration Editor
Reading Configuration information from a text file

Configuration files are the key to Spire. They describe a common project template that multiple users utilize in reconstruction projects.

Although you can write your own XML, it is easier to use Spire's Configuration Editor.

Like HTML, XML uses tags (items enclosed in angle brackets) to describe content. There must always be a closing tag. In XML, upper case vs lower case matters. Configuration files must begin and end with Configuration tags. The main sections of a configuration file are enclosed in Main, Locations, Dialogs, and Directories tags, described in more detail below. The basic organization of a configuration file is:

<Configuration params="yes" database="yes" >
<Main> (attributes of Spire's main window) </Main>
<Locations> (path to search for source Spider Procedure files) </Locations>
<Dialogs> (organizes the GUI, linking buttons to Procedure files) </Dialogs>
<Directories> (the contents of each directory - i.e., subdirectories and Procedure files) </Directories>
</Configuration>

See a small example. (Warning: your browser may not support XML.)

Configuration attributes

The <Configuration> tag has two attributes, params and database.

params specifies whether or not the project uses a parameter doc file. Specifically, when a new project is started, a parameter form is automatically presented to the user. Setting params="no" turns off this behaviour.

database specifies whether or not the project uses an external database. Setting database="no" prevents database entry fields from appearing in the GUI.

NB: the default is for Spire to use both parameters and a database. Therefore
<Configuration params="yes" database="yes" > has the same effect as <Configuration> with no attributes set.

The main window image and title

Section tag:
<Main>
Element tags:
<title>, <image>, <help>

Each configuration file should have a single <Main> tag, which configures the Spire main window.
The <title> tag specifies the large title that describes the type of project/configuration.
The <image> tag specifies the gif image in the upper left corner of Spire's main window. The image should be about 100 x 100 pixels. The full path to the image may be specified. Some default images are provided in the $PYTHONPATH/site-packages/Spire/pics directory.
The <helpurl> tag specifies a URL to display when the user selects Project Help in Spire's Help menu.

Example: 
<Main>
   <title>3D Reconstruction of Single Particles using Reference Projections
</title>
   <image>pics/ribo1.gif</image>
   <helpurl>../../../docs/techs/recon/mr.html
</helpurl>
</Main>

Location of source Procedure files

Section tag:
<Locations>
Element tag:
<location>

Each <location> tag specifies a directory containing the source Procedure files, similar to a Unix PATH variable. First, Spire determines a list of required Procedure files by searching the <Directories> section. Then, for each Procedure file, the location directories are searched until it is found. Source Procedure files are loaded into the project directory once, when the project is first started. After that, SPIRE uses the Procedure files in the local project directory.

Example: 
<Locations>
   <location>/net/bali/usr1/spider/docs/techs/recon/newprogs
</location>
   <location>/mnt/common/spider/docs/recon/newprogs
</location>
   <location>/usr/local/spider/programs</location>
</Locations>

Dialogs and Procedure files

The Dialogs section tells Spire how to organize and present the project to the user. Procedure files and other programs are linked to buttons, with short descriptive labels. 

Section tag:
   <Dialogs>

Element tags:
   <dialog>: begin a new dialog
      <name>: short name for the dialog
      <title>: dialog title
      <directory>: directory containing these Procedure files
      <help>: help URL (optional)
      <button>: button tags contain the following elements:
         <label>: descriptive label
         <buttontext>: text on the button itself
         <proc>: SPIDER procedure to run
         <prog>: a non-SPIDER program to run
      <group>: for grouping together several buttons

For example, the following fragment of XML markup creates the dialog in accompanying figure. After the dialog heading, five buttons are specified. Each button has a brief description, a button label, and an associated Procedure file (denoted by the <proc> tag). A Procedure file such as refproj.spi is actually executed as spider bat/ext @refproj.

The second button is tied to a program (web) that is not a Spider Procedure file, denoted by the <prog> tag. Such programs are executed just as they appear within the <prog> tag, along with any arguments. Since this occurs within a Unix subshell, sometimes the program is not recognized unless the full path to the executable is given.

The third and fourth buttons are grouped together, using the <group> tag. This may be used to allow the user to choose between alternative or optional Procedure files.

The last button has 2 Procedure files within the <proc> tag. More than one Procedure file can be included this way; they are executed one after another unless an error is encountered. 

  <dialog>
  <name>Alignment</name>
  <title>Particle Alignment</title>
  <dir>Alignment</dir>

    <button>
      <label>Create references</label>
      <buttontext>refproj.spi</buttontext>
      <proc>refproj.spi</proc>
    </button>

    <button>
      <label>open web</label>
      <buttontext>web</buttontext>
      <prog>web</prog>
    </button>

    <group name="Get alignment parameters - choose one:">
      <button>
        <label>Align particles to references</label>
        <buttontext>apmq.spi</buttontext>
        <proc>apmq.spi</proc>
      </button>

      <button>
        <label>Align particles using PubSub</label>
        <buttontext>pub_apmq.spi</buttontext>
        <proc>pub_apmq.spi</proc>
      </button>
    </group>

    <button>
      <label>Create the aligned images</label>
      <buttontext>align.spi</buttontext>
      <proc>combine.spi, align.spi</proc>
    </button>
  </dialog>

Directories

Section tag:
<Directories>
Element tag:
<dir>

Project subdirectories are specified by the <dir> tag; the directory name is the tag attribute "name". Directories may contain filenames and other directories. If a directory has no contents, the empty tag must still be closed with a slash mark, as in <dir name="prj" />. The top-level project directory must be specified by ".". The example below shows the top-level directory has a single Procedure file, resizevol.spi. The subdirectory Alignment has two empty subdirectories (ali and prj) plus five Procedure files. Spire creates subdirectories for the project, then fetches Procedure files from the source specified by the <Locations> tags, and copies them into the project directories. 

<Directories>
   <dir name=".">resizevol.spi</dir>
   <dir name="Alignment">
      <dir name="ali"/>
      <dir name="prj"/>
      refproj.spi, refprojctf.spi, sel_by_group.spi, apsh.spi, apshctf.spi 
   </dir>
</Directories>