Using ASGL

ASGL commands

#EPSF -- produce encapsulated PostScript

Command:

#EPSF [ .ps | .eps ]

Description:

If the very first line in the steering file starts with the above in the first column, ASGL will create a PS file that conforms to the Encapsulated PostScript standard. In this case, only one page graphics per file can be produced. Optionally, you can also specify the extension for the PS filename. It is usually .eps for the Encapsulated PostScript, but you may want to keep it as .ps if you depend on it in some other programs. The default is .ps. You can only specify the extension when #EPSF is the first line. If you produce an EPSF file you can include it properly in the L^ATEX document using:

SET STAMP_TEXT -- stamp the page

Command:

SET STAMP_TEXT = $\langle{\tt string:1}\rangle$ [ DEFAULT | NONE your text], STAMP_SIZE = $\langle{\tt real:1}\rangle$

Description:

If set to DEFAULT the page will be stamped at the bottom right corner with the ASGL version, date, time, filename, and page number. The default value is DEFAULT for PostScript and NONE for Encapsulated PostScript. The command is not allowed in Encapsulated PostScript.

READ_TABLE -- read the Table array of data

Options:

Description:

This command will read a text file containing a rectangular array of values. The columns represent vectors that can be later used for plotting as X and Y coordinates. This array will be referred to as the Table array. If ADD_DATA[1] = ON new columns will be appended to the right of the existing columns. The new number of data points is the number of rows in the new file. If ADD_DATA[2] = ON new rows will be appended to the end of the existing rows. The new number of columns is the number of columns in the new file. The command will only read the points whose index satisfies $\mbox{mod}(i-1, {\sf POINT\_MODULUS}\index{POINT\_MODULUS@{\sf POINT\_MODULUS}}) = 0$ and is within boundaries of ROW_RANGE. ROW_RANGE can be 0 or -999 to indicate that it is to be ignored. The total number of points read is approximately for a factor of POINT_MODULUS smaller than the total number of points between selected rows in a file. This option is useful for plotting very large files. The line can start with `#', in which case it will be ignored as far as the points are concerned. There can be string columns in the file that can contain data for point labelling by PLOT2D. Number/string column identification is achieved in one of the two ways: If there is a comment line `#COLUMNS' before any non-comment line, then that line is used for identification. The comment line must contain a series of `N' for number columns and `S' for string columns, in the correct order. Otherwise, the items from the first non-comment line are interpreted as numbers or strings. A string is everything that cannot be interpreted as a number. If you want blanks in strings, quote them in single quotes '. The last line starting with `#CAPTION_TEXT' is assigned to CAPTION_TEXT, which is useful for automated production of titles. Similarly for `#PRINT_TEXT' and `#DESCRIPTION'.

WRITE_TABLE -- write the Table array of data

Options:

Description:

It will write a text file containing an array of values, where columns are selected from the Table array using the NO_XY_SCOLUMNS and XY_SCOLUMNS variables. See WORLD for explanation of these variables.

READ_DPLOT -- read the Density array of data

Options:

Description:

It will read a text file containing the Density array of data. Two formats are possible. In free format (DPLOT_FORMAT=OFF), a text file must contain two integer dimensions (NX,NY) followed by data NX * NY values. The first line can contain NX and NY, at most. The following lines can contain a single row of an array, at most. The order of reading the elements is:

read(ioinp,*)NX,NY
do i = 1, NX
read(ioinp,*) (array(i,j),j=1,NY)
end do

This array can then be plotted using DPLOT command. The array(1,1) element will appear at the coordinate system origin, in the lower left corner of the coordinate system. When formatted input is used (DPLOT_FORMAT=ON), a text file contains any number of lines in the form:

I, J, number_1 number_2, ..., number_DPLOT_COLUMN, ...

These lines are read and the Density array is filled in on the fly as specified by the I and J indices and the value in column DPLOT_COLUMN. All other numbers in a line are ignored. The elements of the Density array not assigned explicitly are set to DPLOT_FILL.

With the formatted input, when DPLOT_SYMMETRIZE = ON, the array is also symmetrized, array(j,i)=array(i,j) for each line that is read in.

If the DPLOT_ORIENTATION is YX, instead of XY, the X and Y axes are swapped during reading in the data.

WRITE_DPLOT -- write the Density array of data

Options:

Description:

It will write a text file containing the Density array of data. Two formats are possible. In free format (DPLOT_FORMAT=OFF), the text file will contain two integer dimensions (NX,NY) followed by data NX * NY values. The first line will contain NX and NY, at most. The following lines will contain a single row of an array, at most. The order of writing the elements is:

read(ioinp,*)NX,NY
do i = 1, NX
read(ioinp,*) (array(i,j),j=1,NY)
end do

When formatted output is used (DPLOT_FORMAT=ON), the text file will contain a number of lines in the form:

I, J, ARRAY

If the DPLOT_ORIENTATION is YX, instead of XY, the X and Y axes are swapped during writing out the data.

WORLD -- define the extent of your data

Options:

Description:

This command has to be called before any plotting is done. It calculates the extent of the plot and initializes the Plot coordinate system -- it determines its position on a paper. If you selected automatic World bounds setting, you should have your data already read by the READ_TABLE, READ_DPLOT, or READ_PDB commands.

When plotting a PDB structure, the PERSPECTIVE, EYE_TO_SCR, and SCR_TO_TOP have to be set up at the time of drawing with the BALL_STICK command to properly scale the plot.

PAPER_WINDOW defines the position and orientation of a window on the paper. The format is (XMIN YMIN XMAX YMAX ORIENTATION). The origin for rotation is the origin of the Base PostScript coordinate system which is in the lower left corner of a paper. Units are cm and degrees. This window on the paper will contain the data from WORLD_WINDOW. Any data points outside this area will be clipped. If orientation of the window is 90 ${}^{\scriptstyle\circ}$ then the plot will be printed in the landscape mode.

In POSITION, if the first element is different from 0 then the PAPER_WINDOW is defined automatically using the position codes (1-37) irrespective of the value of PAPER_WINDOW. The following convention is used:

1 - 8

small 1-4, left column; 5-8, right column (8 plots / page)

9 - 11

medium small (3 plots / page)

12 - 13

medium (2 plots / page)

14

medium large (1 plots / page)

15

large, landscape (1 plots / page)

16 - 37

tiny, portrait (32 plots / page)

If the second element is 0, the aspect ratio between X and Y is set to 1.3333 (horizontal rectangle), if it is 1 the aspect ratio is 1.0 (square), if it is 2 the aspect ratio is 3.9 (very extended horizontal rectangle).

WORLD_WINDOW defines the coordinate axes in the World of the data to be plotted. These ranges will correspond to the PAPER_WINDOW window. However, if any of the four values is -999 (by default this is the case), the program will try to calculate that value from the data read in by the last data input command (READ_TABLE, READ_DPLOT, or READ_PDB).

WORLD_FRACTION defines the fraction of the number of the central points that are used to get the WORLD_WINDOW when calculated automatically. By default, this is 1. This is useful when there are a small number of outliers that you do not want to plot because the large scale would observe the relationship between the remaining points.

NO_XY_SCOLUMNS defines the numbers of selected columns in the Table array that are to be examined for the maximal and minimal values of X and Y, respectively, when calculating the real World extent of the graph. If any of the numbers is 0 then NO_XY_SCOLUMNS and XY_SCOLUMNS are set to reflect the values in XY_COLUMNS. Use this variable when automatic boundaries are required for multi-line plots and it is not clear which data vector should be used for bounds setup.

In multi-plot plots, do not forget that undefined NO_XY_SCOLUMNS and
XY_SCOLUMNS are set automatically in the first WORLD command and will stay defined until reset with SET or RESET commands.

XY_SCOLUMNS defines the columns for the range searching (see also above). The first NO_XY_SCOLUMNS(1) integers define the X-columns in the Plotting array for X range and the last NO_XY_SCOLUMNS(2) integers are the Y columns for the Y range.

If A4_WINDOW_MARGIN is ON a line around the Bounding Box of the Base PostScript coordinate system is drawn, A4 paper is bounded.

AXES2D -- draw coordinate axes, ticks, and labels

Options:

Description:

It will plot the axes of the coordinate system.

TICK_FONT sets the font size for labeling the ticks.

X_LABEL_STYLE and Y_LABEL_STYLE select the labelling regime:

1

labels for X,Y-ticks supplied explicitly to the routine.

2

labels calculated automatically.

3

labels not displayed at all.

X_TICK and Y_TICK define, in World coordinates, the position of the first tick on the X,Y-axes, the spacing between the ticks, and the rightmost tick position.

X_LABEL_SHIFT and Y_LABEL_SHIFT shift the X/Y-axes labels. Shifts are specified in the Plot coordinates.

X_TICK_LABEL and Y_TICK_LABEL set the index of the X/Y-axes ticks that are numbered first, and also every which tick from the first one on is numbered.

X_TICK_DECIMALS and Y_TICK_DECIMALS set the number of decimal places used in the automatic calculation of the X/Y-axes tick labels. If 0, only a dot will appear after an integer. If $-1$ only an integer will appear.

If Y_SCALE is RIGHT it will plot the Y-axis ticks and their numbers on the right side of the plot. Default is LEFT.

CAPTION_XLEFT and CAPTION_XRIGHT are returned by AXIS2D for later use by the CAPTION command in placing the captions next to the Y-axis. If these automatic values are not good you can correct them manually (rarely needed).

X_AXIS_FACTOR is used to scale the X-label ticks before the label is written out. If EXPONENT is ON then `En' is added to the tick label where $n = \mbox{nint}[\log10(\mbox{{\sf X\_AXIS\_FACTOR}\index{X\_AXIS\_FACTOR@{\sf X\_AXIS\_FACTOR}}})]$. If EXPONENT is OFF then `En' is not added and could be included in the axis label with the CAPTION CAPTION_POSITION = 4 or 5 command.

PLOT2D -- draw a 2D line or scatter plot

Options:

Description:

This command will plot a line and/or the points defined by the selected columns in the Table array.

PLOT2D_SYMBOL_TYPE defines the symbol to be plotted for every point. If 0 nothing is plotted. If set to $-1$, then the centered integer indices are plotted for each point.

PLOT2D_LINE_TYPE defines a line type to be plotted between successive points in the Table array. If 0 no line is plotted -- used for scatter plots.

XY_COLUMNS selects X and Y columns in the Table array. If any of the two columns is not defined, it is substituted by a vector $1,2,\ldots,N$.

POINT_FONT selects the font for the point symbol in the case where
PLOT2D_SYMBOL_TYPE = $-1$.

If LABEL_COLUMN is a string column, then the labels in that column are drawn for each point. If LABEL_LOCATION is 1, the label is centered on the point, if 2 the label is to the right of the point. LABEL_FONT is the font type for the labels.

If COLOR_COLUMN is defined, it is used to color the symbols from red, yellow, green to blue in the range from COLOR_RANGE[1] to [2]. The HSB color convention is used (hue from 0.0 to 0.5). If COLOR_STYLE is GRAY, gradual coloring is done; if BLACK, the values within the range are of color 0 (red), and those outside the range are color 0.5 (blue).

SPECTRUM -- draw a bar code plot

Options:

Description:

This command plots an energy spectrum looking like a vertical bar code.

PLOT2D_LINE_TYPE defines the line type to be used for horizontal energy levels.

XY_COLUMNS selects the Y column in the Table array that specifies energy levels. Note that Y column is plotted, not X column. This is to be consistent with the WORLD command.

BAR_XSHIFT specifies the starting X of the energy levels in the World coordinates.

BAR_WIDTH defines a relative width of the bars in the World coordinates.

HIST2D -- draw a 2D histogram

Options:

Description:

This command plots a histogram of X and Y columns in the Table array.

BAR_GRAYNESS defines the grayness of the bar on the scale from 0.0 (black) to 1.0 (white).

BAR_WIDTH defines a relative width of the bars where 1.0 would make two neighbouring bars touch each other. If less than 1 there is empty space between bars.

BAR_LINE_TYPE defines a linetype used to border the bar in the $\Pi$ shaped way. If linetype is 0 bordering is not done.

In NO_XY_SCOLUMNS, the first element has to be 1 because there can only be one X-column. The second element is the number of Y-columns. It is 1 for normal histograms and more than 1 for a histogram where bars are stacked on top of each other to get a stacked bar at a single X value.

XY_SCOLUMNS specifies X-column and Y-columns in the Table array for the histogram. The dimension of XY_SCOLUMNS has to be NO_XY_SCOLUMNS(1) + NO_XY_SCOLUMNS(2). The default values for NO_XY_SCOLUMNS and XY_SCOLUMNS (when the inputs are 0) are obtained from XY_COLUMNS. If the X-column is not defined, it is substituted by a vector 1,2,...,N. The X coordinate of the bar specifies its mid-point (not the left edge, for example). X-interval corresponding to one bar is always calculated automatically as the difference between the first and last X divided by the number of bars less 1. This works well when you have equal spacing between the points on X axis. If not you can always correct the bar width using BAR_WIDTH.

XY_COLUMNS is used only when default values for XY_SCOLUMNS are required.

BAR_XSHIFT shifts the bars for this amount along the X-axis. This is to allow the plotting of several bars at the same X without modifying the data files.

DPLOT -- draw a density plot

Options:

Description:

This command will do a density plot of the Density array read in by the
READ_DPLOT command.

If BAR_LEGEND is ON it will plot a gray scale code to the right of the plot.

BAR_LEGEND_PLACES sets the number of pre- and post-decimal point places for the labelling of the bar legend.

DPLOT_GRAYNESS defines the grayness of the smallest and largest value to be plotted, respectively. If you want small to be white, set the first element larger than the second one.

DPLOT_LINE_TYPE defines the line type for the mesh plotted on the density plot.

DPLOT_PART selects the part of the Density array to be plotted.

DPLOT_BOUNDS sets the real World bounds on the values of the Density array corresponding to the DPLOT_GRAYNESS interval.

DPLOT_STYLE selects whether the DPLOT_BOUNDS range is to be colored with various degrees of gray (GRAY), or every cell within the range is to be coloured by the first bound of DPLOT_GRAYNESS and all other cells by the second bound of DPLOT_GRAYNESS.

If NUMBER_DENSITY_PLOT is set to ON the number is plotted for each cell instead of the gray rectangle. This number shows the height of the function. You can use the same mechanism as for GRAY to show only numbers in certain range.

NUMBER_PLACES sets the number of spaces before and after the decimal point when NUMBER_DENSITY_PLOT = ON.

POINT_FONT sets the font type for the numbers when NUMBER_DENSITY_PLOT = ON.

PRINT_FONT sets the font type for the numbers for the bar legend.

PRINT_DXY will offset the X and Y of the number printed in each cell (in World coordinates).

CAPTION -- place a caption next to an axis

Options:

Description:

This command puts text at pre-specified positions around the plot.

The sequence of CAPTION commands for the same type of a caption is important. The captions will be placed around the graph starting with the position closest to the graph. Therefore, a subtitle should be done before the title, but the X-title should be done before the X-subtitle. CAPTION_XLEFT is the X-position in the Plot coordinates of the leftmost part of the Y-captions (by default -0.15). AXES2D returns the precise values for CAPTION_XLEFT, so use CAPTION after AXES2D without specifying CAPTION_XLEFT. CAPTION_XRIGHT is a similar variable that is used when Y_SCALE = RIGHT.

The following positions with respect to the graph are available:

1

above graph, centered

2

below graph, centered

3

left of graph, centered,

4

below graph, right

5

left of graph, top

6

right of graph, center

7

right of graph, top

8

left, top corner of graph

9

right, top corner of graph

10

right, bottom corner of graph

11

left, bottom corner of graph

12

center, top of graph

RESET_CAPTIONS -- reset caption positioning

Command:

RESET_CAPTIONS

Description:

Resets the positions for the subsequent captions. This command has to be executed after the WORLD and before the AXES2D commands.

LINE2D -- draw a line

Options:

Description:

Plots a line specified in World coordinates. It uses LINE2D_LINE_TYPE if defined (i.e. in 1..LINTYPS, where LINTYPS is the number of line types read from file `psgl1.ini'), otherwise it uses LINE2D_WIDTH and LINE_GRAYNESS. If LINE2D_WIDTH_SCALING is X (case insensitive), the line width is specified in the units of the X-axis, otherwise in the units of the Y-axis. If CLIP is off, the line can occur outside the plot area, otherwise it is clipped.

SET_RECORD -- sets RECORD to selected Table elements

Options:

Description:

This command puts the selected elements in the first line of the Table data into the RECORD variable. RECORD can then be used in captioning the plot or plots.

This command is useful in combination with the SELECT_DATA command in order to produce many different captions in one set of plots, from one data file.

PRINT -- print a text

Options:

Description:

Prints text positioned in World (COORDINATES = WORLD) or Plot (COORDINATES = PLOT) coordinates at PRINT_XY (PRINT_MODE = XY). Alternatively, if PRINT_MODE = POINT, the coordinates of the point PRINT_POINT in the columns XY_COLUMNS are used. If point index is out of range, the last point is used. In either case, (X,Y) is translated for PRINT_DXY. PRINT_ANGLE is a rotation of the text, PRINT_HORIZ is 1 for left justified, 2 for centered and 3 for right justified, PRINT_VERT is 1 for bottom aligned, 2 for center aligned and 3 for top aligned.

For all text printing, including the one submitted to the CAPTION command, the following conventions hold:

• Superscript: embedded in _
• Subscript : embedded in $\wedge$
• Greek char : embedded in @

Multi-level embedding is allowed.

Special characters can be printed by using the PostScript character codes. For example, to print the character, use `
305'.

NEW_PAGE -- start a new page

Command:

NEW_PAGE NO_COPIES $\langle{\tt integer:1}\rangle$

Description:

Advances to the next page: the next plot will be on the new page. It can only be used when Encapsulated PostScript (EPSF) is not selected.

ARROW -- draw an arrow

Command:

ARROW [options]

ARROW_POSITION = $\langle{\tt real:4}\rangle$	X1 Y1 X2 Y2
ARROW_SHAPE = $\langle{\tt real:3}\rangle$	tail thickness, arrow width, arrow length

Description:

Draws an arrow from (X1,Y1) to (X2,Y2) (tail to tip), in World coordinates (COORDINATES = WORLD) or in Plot coordinates (COORDINATES = PLOT). The elements of ARROW_SHAPE are tail thickness, arrow width, arrow length in Plot coordinates.

POSTSCRIPT -- write a PostScript command

Command:

POSTSCRIPT POSTSCRIPT_TEXT = $\langle{\tt string:1}\rangle$

Description:

Takes the POSTSCRIPT_TEXT string as a literal PostScript command and writes it to the output PS file.

TRANSFORM -- transform Table or Density array data

Options:

Description:

Transforms the columns of the Table array selected by XY_SCOLUMNS array. If NO_XY_SCOLUMNS are both 0, it transforms the Density array instead. You must be careful with labelling the ticks (AXES2D) and scaling (WORLD) when using this option since it transforms the data itself not only plotting of them.

TRF_PARAMETERS sets any parameters that may be required for the transformation.

TRF_TYPE selects the type of transformation:

LOGARITHMIC1:

$Y = \ln[\mbox{TRF\_PARAM(1)} + (Y-YMIN) \cdot \mbox{TRF\_PARAM(2)}]$

LOGARITHMIC2:

$Y = \ln[\mbox{TRF\_PARAM(1)} + Y \cdot \mbox{TRF\_PARAM(2)}]$

LOGARITHMIC3:

$Y = \mbox{log10}[\mbox{TRF\_PARAM(1)} + (Y-YMIN) \cdot \mbox{TRF\_PARAM(2)}]$

LOGARITHMIC4:

$Y = \mbox{log10}[\mbox{TRF\_PARAM(1)} + Y \cdot \mbox{TRF\_PARAM(2)}]$

CUMULATIVE:

$Y_i = \sum_{k=1,i} Y_k$

LINEAR:

$Y = \mbox{TRF\_PARAM(1)} + Y \cdot \mbox{TRF\_PARAM(2)}$

INVERSE:

$Y = \mbox{TRF\_PARAM(1)} + \mbox{TRF\_PARAM(2) / Y}$

EXPONENTIAL:

$Y = \mbox{TRF\_PARAM(1)} + \exp[\mbox{TRF\_PARAM(2)} + \mbox{TRF\_PARAM(3)}]$

NORMALIZE:

$Y = Y / \sum_i Y_i$

YMIN is the smallest value in all selected columns of the Table array or the smallest value in the Density array, as appropriate. CUMULATIVE is not available for transformation of the Density array.

Any transformation that is undefined (for example, a logarithm of a non-positive argument, or a division by zero) is assigned a value TRF_UNDEFINED.

RESET -- reset TOP

Command:

RESET

Description:

Reads in the top.ini file again. Resets all parameters to its default values. Use RESET before plotting the second, third, plot in the same TOP program to prevent surprises resulting from the non-default values of arguments such as X_TICK, XY_COLUMN, which were possibly set automatically when producing the first plot.

GET_BARS -- calculate histogram bars

Options:

Description:

Transforms the current X vector into a histogram by counting how many X coordinates fall in a certain interval. The interval size must be specified explicitly by the real World range BAR_DX. The centers of these intervals are returned in X and the heights of the bars in Y. Note that the current data in the Table array is erased, histogram coordinates are copied to the current X and Y. Only XMIN and XMAX are used to determine the X-range. If any of these two is undefined (-999) default values are supplied as the largest and smallest X in the data with an added DX on both sides. XMAX is corrected so that XMAX = XMIN + (N+1)*BAR_DX where N is the number of points (bars) in the new Table array. The first bin starts at XMIN+0.5*DX and the last bin ends at XMAX-0.5*DX. For example, if you have points with X-coordinates ranging from 0 to 100, you could set WORLD_WINDOW to -5 0 105 0 and BAR_DX to 10, which will create bins 0-9.999, 10-19.999, ..., 90-100.0; they will be centered on 5, 15, 25, etc. There will also be half of the bin width on each side of the histograms when it is plotted (from $-5$ to 105 on the X-axis).

XY_COLUMNS selects the X and Y columns. If Y column exists before the call, this routine also calculates the average and standard deviaton of the Y-values in each bin. These are returned in the two columns after the currently existing columns.

GET_DENSITY -- calculate Density plot data

Options:

Description:

Transforms the current X and Y vectors into a density plot (3D histogram) by counting how many X and Y coordinates fall in a certain interval. The interval sizes must be specified explicitly by the real parameters BAR_DX and BAR_DY. The heights of the density plot are returned in the Density array. All four values in WORLD_WINDOW are used to determine the X-range. If any of them is undefined (-999) default values are supplied as the largest and smallest X and Y in the data with an added DX/DY on all sides. This makes the WORLD exactly superposable to the world from the 1 .. NBARX, 1..NBARY density plot. This world goes from 0,0 to NBARX+1,NBARY+1. The center of the first bin is at XMIN+DX,YMIN+DY and the center of the last bin is at XMAX-DX,YMAX-DY. This gives a 0.5*DX, 0.5*DY margin around the plotted bins. XMAX (and YMAX) is corrected so that XMAX = XMIN + (N+1)*BAR_DX where N is the number of points (bars) in the new Density array. XY_COLUMNS selects the X and Y columns.

SHUFFLE_DPLOT -- re-organize the Density plot data

Options:

Description:

The transpose operation only has sense for square matrices. The other two commands invert the order of the points along the X and Y coordinates, respectively. To exchange the orientation of the X and Y axes as they appear on the plot, you should use the DPLOT_ORIENTATION option of the READ_DPLOT command.

DENSITY_TO_XY -- Density to XY data

Command:

DENSITY_TO_XY

Description:

Copies the current density array to the XY table.

XY_TO_DENSITY -- XY to density data

Command:

XY_TO_DENSITY

Description:

Copies the current XY table to the density array.

LEGEND -- draw a legend

Options:

Description:

Plots the legend for objects (curves, points, and bars). The legend is in the form 'symbol symbol_description'. Successive LEGEND commands print legends one per line, starting at the top. RESET_LEGEND has to be issued before LEGEND. Note that you can use this command to place text right to the plot if you specify invisible object types (0). The value of the SYMBOL keyword determines the type of the object symbol in the legend (POINT, LINE, or BAR). DESCRIPTION is the text describing the symbol. LEGEND_POSITION can have the same values as CAPTION_POSITION.

RESET_LEGEND -- reset legend positioning

Command:

RESET_LEGEND

Description:

Resets the starting Y position of the next legend to the initial value at the top of the plot.

PLOT_ERROR_BARS -- draw error bars

Options:

Description:

This command plots error bars. It relies on X and Y columns selected by the XY_COLUMNS argument (as in the PLOT2D command), and on the ERROR_COLUMN argument which selects the column in the Table array that contains the error in Y-coordinate for each (X,Y) point. The graphical attributes are the same as those used for the PLOT2D command. The error-bar is a vertical line with two short horizontal caps on top and bottom. The error line extends for `error' units below the central point and for `error' units above the central point; thus, the total height of the error bar is twice the error. PLOT2D_SYMBOL_TYPE selects the symbol type used to plot at the center of the error bar. If
PLOT2D_SYMBOL_TYPE is $-1$ then POINT_FONT font is used to print the points indices instead of point symbols. PLOT2D_LINE_TYPE selects the line type used for plotting the error bars. IF ERROR_SIGN contains word UP, the error value will be added to the y-value. If it contains DOWN, the error value will be subtracted from the y-value. ERROR_SIGN contains both by default, UP DOWN.

SELECT_DATA -- select some rows in Table array

Command:

SELECT_DATA SELECT_COLUMN = $\langle{\tt integer:1}\rangle$, SELECT_RANGE = $\langle{\tt real:2}\rangle$

Description:

This command selects the lines of the Table array that have a value in a specified column in a specified range. This is useful when you want to plot only a subset of data, for example make a (X,Y) plot at a fixed Z.

SWITCH_PS -- open a new PostScript file

Command:

SWITCH_PS FILE = $\langle{\tt string:1}\rangle$

Description:

This command will close the current PS file and open another one for subsequent output.

FIT -- non-linear least-squares fit of data

Options:

Description:

This command does a non-linear least-squares fitting of the (X,Y) data in columns XY_COLUMNS to the model selected by FIT_MODEL. The standard errors of the data points can be specified in column ERROR_COLUMN. If this column index is undefined, all errors are set to 1. FIT_PARAM_INITIAL specifies the initial estimates for all the parameters. FIT_PARAM_INDICES specifies the indices of parameters to be actually varied in the fitting. FIT_CUTOFFS specifies the convergence criterion: when the absolute and relative change in the chi-square is smaller than specified in two consecutive cycles, the fitting exits. If FIT_WORLD is OFF, the Y-column contains the function values for the corresponding X. If FIT_WORLD is ON, the X column is changed to NO_SPLINE_POINTS points that equidistantly span WORLD_WINDOW X-range and Y-column is filled with the function values calculated at these new X-points. Note that Xmin and Xmax of the World are specified as the first and third element of WORLD_WINDOW.

FIT2 -- non-linear least-squares fit of data

Command:

FIT2 [options]

Description:

Downward compatible with FIT, except that it can also do multidimensional least-squares fitting. Should replace FIT with time.

SMOOTH_TABLE -- smooth the Table array data

Options:

Description:

Smoothes data in the Table array using one of the two methods selected by SMOOTH_TYPE: the cubic spline or running average method. The main appearance difference between the two methods is that spline smoothing goes through the original points (if they were evenly distributed), whereas window averaging changes the original points.

In the spline method, NO_SPLINE_POINTS is the number of points to be calculated by spline smoothing. It is returned in PLOT_POINTS. Columns X and Y are selected by XY_COLUMNS; note the difference with the running average method.

In the running average method, the weight of point $j$ is proportional to $({\sf HALF\_WINDOW}\index{HALF\_WINDOW@{\sf HALF\_WINDOW}}-\vert i-j\vert+1)$ where $i$ is the central point and HALF_WINDOW is the number of points left and right of point $i$ that are in the window. Only the columns specified by NO_XY_SCOLUMNS and XY_SCOLUMNS are smoothed; note the difference with the spline method. PLOT_POINTS is not changed.

READ_PDB -- read a Brookhaven molecular structure

Command:

READ_PDB FILE = $\langle{\tt string:1}\rangle$, PDB_FORMAT = $\langle{\tt string:1}\rangle$

Description:

Reads in the PDB file according to the format specified. Format can be PDB or XYZ. The former is the Brookhaven Protein Databank format. The latter consists only of x,y,z for one atom per line.

WRITE_PDB -- write a Brookhaven molecular structure

Command:

WRITE_PDB FILE = $\langle{\tt string:1}\rangle$

Description:

Writes out the PDB file.

MAKE_BONDS -- make a list of bonds

Options:

Description:

Constructs the bonds between the currently selected bonding set of atoms and either adds them to the list of existing bonds or creates this list from scratch, depending on the logical variable ADD_BONDS.

BOND_COLOR sets the color of the current bonds. The coloring scheme is from PostScript: 0 for black and 1 for white; intermediate values select various shades of gray.

COVALENT_BOND defines the distance cuttoff between which the atom pair is recognized as bonded to each other. If any of the two values is undefined (i.e. -999), then the covalent bond exists when a distance between the two atoms is less than 0.55 times the sum of the two van der Waals radii and more than half of that value. The radii are obtained from the PDB atom names by first recognizing an extended atom type in the residue, and then looking into the radii library file for all atom types in all residue types. Hydrogen atoms are treated separetely -- they are just recognized as such directly and their radii assigned accordingly.

BOND_LINE sets the line type for drawing the current bonds. If the line type is negative than only the line of the type -BOND_LINE is drawn, not the polygon with caps.

BOND_WIDTH_FACTOR sets the bond width. If too large (approx 1), bond coordinates may be undefined.

BOND_TAPER is a factor that is multiplied by the delta Z of the bond and its width to increase the width of the nearer end, and decrease the width of the further end. It should be 0 or larger than 0.

LABEL_ATOMS -- label the selected atoms

Options:

Description:

Labels the currently selected labelling set of atoms with the currently selected labelling style. Labelling style is a string and can be any sequence of the items listed above, in any order.

DEFAULT_ATOM_COLOR -- color all the atoms

Command:

DEFAULT_ATOM_COLOR

Description:

Assigns default attributes to all the atoms: atom color and atom lines. Useful to do after SELECT_ATOMS which assigns a specific color and line; if you need generic coloring for different atom types.

SELECT_ATOMS -- select atoms in a molecule

Options:

Description:

Adds atoms to, removes atoms from, or initializes the ASGL atom sets selected by FOR. SELECTION_STATUS determines whether the selected atoms are added (ADD), removed (REMOVED), or a set is initialized and then the selected atoms are added (INITIALIZE). There are three sets of atoms in ASGL: (1) the atoms that are selected for display (BALL_STICK), (2) the atoms that are selected for calculation of bonds (MAKE_BONDS) and (3) the atoms that are selected for labelling (LABEL_ATOMS). The FOR variable is a scalar string that can contain any combination of the three selections: The selection of atoms is a hierarchical process: First, FROM specifies which of the three atom sets are used for scanning; if FROM = ALL, all atoms in the input pdb file are used for scanning. ATOM_TYPE and RES_TYPE constrain scanning to specified atom and residue types, respectively. They can contain several atom and residue types in one quoted string. SELECTION_MODE determines whether only an atom satisfying all search criteria is to be selected or all atoms in a residue of a found atom are to be selected.

The SEARCH_STRING specifies SEGMENT or SPHERE search; this determines the other possible arguments.

The SEGMENT search scanns only a single segment specified by the beginning and ending residue number (as found in the input atom file), SEGMENT_RANGE. The value of the residue number can be X, which implies the first or last residue, as appropriate. SELECTION_STEP is a step in the residue index used in scanning for the atoms. This is useful in labelling only every 5-th CA atom, for example.

The SPHERE search scanns only over those atoms that are closer than SPHERE_RADIUS to the SPHERE_CENTER atom, after the center atom was translated by (xtrans, ytrans, ztrans) specified in SLAB. If the first element of SPHERE_CENTER is INDEX then the second element is an atom index of the center atom; otherwise, the first and second element are the residue number (as in the input atom file) and the atom type, respectively. SLAB specifies the interval on Z-axis relative to Z of the translated central atom that imposes another condition on the selected atoms: $Zcen+dz1 < Z+ztrans < Zcen+dz2$. This is useful to make less crowded plots. Larger Z is on front, so dz1 specifes the plane that is further away than the dz2 plane. To get any atoms, $dz1 < dz2$.

The radii of the currently selected display set of atoms is set to RADIUS * RADIUS_FACTOR. If the final atom radii is 0, the atom is not drawn. If RADIUS is undefined (-999) then the van der Waals radius of that atom type is used.

ATOM_COLOR sets the color of the currently selected display set of atoms. The coloring scheme is from PostScript: 0 for black and 1 for white; intermediate values select various shades of gray.

ATOM_LINE sets the line type for drawing the currently selected display set of atoms.

BALL_STICK -- draw a molecule

Options:

Description:

Plots a ball-and-stick plot of the currently selected display set of atoms and of the selected bonds.

ROTATE_MOL -- rotate the molecule using rotation matrix

Command:

ROTATE_MOL ROTATION_MATRIX = $\langle{\tt real:9}\rangle$

Description:

Rotates the whole molecule according to the rotation matrix.

ROTATE_MOL_AXIS -- rotate the molecule around the axis

Command:

ROTATE_MOL_AXIS AXIS $\langle{\tt real:3}\rangle$, DEGREES = $\langle{\tt real:1}\rangle$

Description:

Rotates the whole molecule around the axis AXIS for DEGREES degrees.

TRANSLATE_MOL -- translate the molecule

Command:

TRANSLATE_MOL SHIFT = $\langle{\tt real:3}\rangle$

Description:

Translates the whole molecule for SHIFT Ångstroms.

CENTER_MOL -- center the molecule

Command:

CENTER_MOL

Description:

Center the whole molecule.