Help for 'plot2' program.

Date help created:  12 Jun 1994
Date last updated:  31 Oct 2001
'plot2' is used to contour 2-dimensional planes from n-dimensional data sets. It can also be used to draw 1-dimensional slices of the 2-dimensional planes, and to approximately phase these slices.

To run the program type

	plot2 [<plot2 script file>]

The script file is optional. For details of syntax, and an example, type

	plot2 help scripts

In the individual module help files script key words are identified by being inside angular braces <>.

The graphical interface is Motif/X11.

A non-graphical version of the program, called 'plot2_nog', is also available. This is obviously only useful if there is a script file and if output is saved to one or more files (so, for example, this is a convenient way to make hardcopy output for every plane in a data set).

This program is meant for looking at individual planes (although as many as desired can be placed on top of each other). For scrolling in the directions orthogonal to the planes in view, use a program such as Per Kraulis' ANSIG.

Two auxiliary files, .plot2 and .position, are created when the parameters are saved on exit. Generally these files should not be edited.

Each button of the toplevel window pops up a module with functionality as briefly specified below.

NOTE: with the Motif Window Manager (MWM) (the default for Silicon Graphics machines) a parent window cannot ever be raised above any of its child windows. This can be annoying (sorry, but hey, it's not my fault).

Since the interface is Motif, the program may not work as well with non-MWM window managers. And color is important but reasonable results are obtainable in black and white.

Each module (except two of the displays) has a help button, which explains the available functionality in more detail. The general format is that there is a listing of features as seen on the screen, each being inside curly braces {}. Further HTML references are given in square braces [].

Generally, changing parameters leads to no change in the displays until an {apply} button is hit. The exceptions to this rule are explicitly noted.

{extract}
The 2-dimensional planes must be extracted into memory from the n-dimensional data sets on disk in order that a suitable contouring speed is achieved. [plot2/extract]

{region}
Specifies the region to be contoured. Allows specified regions to be stored for recall. [plot2/region]

{levels}
Specifies the levels for the contours. Allows easy modification of these levels. [plot2/levels]

{data}
Specifies which extracted data sets (planes) are displayed. From this module the modules defining the global default set of properties and the detailed properties of each data set can also be reached, as well as a module to save individual data sets as files (i.e. on disk). [plot2/data, plot2/object, plot2/property, plot2/save]

{displays}
Pops up the displays. There are three displays. The first is a display for the (2-dimensional) contours. The second is a display for the (1-dimensional) slices. The third tracks which part of the entire plane is being contoured. The functionality for the displays is explained under the help for the tracking display. [plot2/tracking]

{slices}
1-dimensional slices of the 2-dimensional planes can be drawn, and there is allowed an (approximate) phasing (using a Hilbert Fourier transform) and/or a baseline correction of the selected slice. [plot2/rowcol, plot2/phase, plot2/baseline]

{output}
The plots can be output to a file in various formats. Currently this means PS, EPS and HPGL. [plot2/output]

{quit}
Quit the program, with the option of saving all the parameters (e.g. levels) as they are currently set.

{help}
Display this message.

scripts

Scripts have the following different types of key words: variables, strings, actions, a looping construct, and the inclusion of another script file.

The value for a given key is the remainder of the line up to a comment symbol, and stripped of leading and trailing space.

Variables consist of two characters, the first must be a '$' and the second identifies the variable.

	<variable> <value>

sets the value of the <variable> to be equal to <value>.

Strings are used to set the value of text fields and 'radio' buttons in the various modules. Strings have the syntax <module.string> for the key, and (most of) the choices are given in the individual module help files.

	<module.string> <value>

sets the value of the string to be equal to <value>. The <value> of strings corresponding to radio buttons must be an integer representing the choice of button (and buttons start counting at 0).

Strings that are not explicitly set by the script file take their value from the auxiliary file .plot2 (if one exists in the current working directory).

Actions are used for the selection of objects in lists, the action of pushing a button and also some miscellaneous ones. The first two have the syntax <module.action> for the key, and the choices are given in the individual module help files, with an additional choice being <module>.popup, which pops up the corresponding module. The third has the syntax <action> for the key.

	<module.action> <value>
	<action> <value>

carries out the action, using the given <value>.

Currently the miscellaneous actions are

	print <value>   ! prints the given value to the screen
	sleep <number of seconds>   ! pauses for the given time
	region_stats_open <file>    ! opens file for region stats
	region_stats_close          ! closes file for region stats

Loops are introduced by the key word 'loop' or 'loop2' and must be ended by the key word 'end_loop'. The syntax for 'loop' is

	loop <variable> <first> <last> <step>

for 'loop2' is

	loop2 <variable> <first> <last> <step> <ndecimals>

('loop' assumes <ndecimals> = 0) and for 'end_loop' simply

	end_loop

and this causes a loop of the lines between the two, starting with the variable set to <first>, using an increment in the variable of <step> every loop, until the variable exceeds <last>.

<step> can be positive or negative. If it is positive then the loop continues until the value of the variable is greater than <last>. If it is negative then the loop continues until the value of the variable is less than <last>. These are all floating point values, and ABS(<step>) must be > 1.0e-4.

<ndecimals> specifies the number of decimal places to use when evaluating the <variable>. This is forced to be between 0 and 4 (inclusive).

<first>, <last> and <step> (and <ndecimals> for 'loop2') are only evaluated when the loop is first entered.

Loops may be nested.

All values for the above key words may have variables nested inside, and these are substituted at the appropriate time.

Other script files may be included (and hence processed) using the 'include' key word. The syntax for this is

	include <script file>

An example of a script file (perhaps used for a movie) is

	loop $i 11 15 1                ! set i = (11, ..., 15)
	extract.plane_name plane$i     ! define plane name
	extract.point_on_plane 0 0 $i  ! define plane point
	print extracting plane #$i     ! print message to screen
	extract.load                   ! load plane
	end_loop                       ! end the loop

	data.all_off                   ! deselect all data sets
	data.select plane15            ! select data set plane15
	data.apply                     ! show 2D display 

	loop $i 11 15 1                ! set i = (11, ..., 15)
	print displaying plane #$i     ! print message to screen
	data.next                      ! select next data set
	sleep 2                        ! pause 2 seconds
	end_loop                       ! end the loop

In this case the contour levels, region, etc., are as defined in the .plot2 file.

Azara help: plot2 / W. Boucher / azara@bioc.cam.ac.uk