README.kincontours Home Page: Richardsons' Laboratory J. Michael Word - 3/1999


On this page:



Introduction


The programs kin2Dcont and kin3Dcont produce contour plots from tables of values and their 2-D or 3-D coordinates. If the data is scattered in space, the programs can smooth it and produce what is essentially a histogram in two or three dimensions. Evenly sampled data values can also be contoured, as well as data which is periodic, for example when the dimensions are angles with 360 deg the same as 0 deg.

Both kin2Dcont and kin3Dcont are 'c' programs, designed for use in a UNIX or LINUX environment. They should be easy to port to various operating systems. The heart of the code is software based directly on the "contour tree" algorithm by Michael J. Zyda [1]. This has been extended with procedures to produce connected contours sorted by the contour level. Vector and Matrix creation routines were taken from Numerical Recipes [2].



Usage


Here is an example of using one of the contour routines:

kin3Dcont -g1.5 -s3 -l 2.5 sea atom.data >> atomcont.kin

It reads data in the file atom.data and generates a single 3D contour with a grid spacing of 1.5 and a filter stddev of 3.

Input is a series of value, x, y, [z] entries, each on a separate line. If the value comes after the position, use the -last flag.

The output is in kinemage format (kin2Dcont can produce PostScript output as an alternative). The programs write to standard output and can be appended to an existing kinemage file with the >> redirection symbol.

The flag -l (the letter L, not the number one) preceeds a set of level number, color name pairs. The color names should be kinemage colors: red, green, blue, cyan, yellow, magenta, white, pink, orange purple, sky, brown, gray, black, gold, yellowtint, sea, pinktint, bluetint, greentint, hotpink. A range of contour levels for a given color can be given with the -m flag.

The grid spacing, -g#.#, specifies how finely space is sliced to make the contours. The size of the output will increase with the square or cube as the grid spacing is made smaller. For data represented at atoms, a grid spacing of 1 Å is about as high as is neccessary.

The spot function, -s#.#, controls the smoothing. The value is the standard deviation of a gaussian filter and a bigger spot function smooths more. For scattered data, a -s often works well at a size of twice -g. For uniformly sampled data, -s is often best at the same size as -g.

Uniformly sampled data is often generated by sampling programs. For example, the following command creates a series of contours from score data that was sampled every 5 degrees for the chi1 and chi2 angles of a tyrosine sidechain.

kin2Dcont 1ah7y61.scores -kin -group -sampled -wrap 0 360 0 180 \
-g5 -s5 -m -200 -20 20 orange \
-l 0 grey -m 2 50 2 sea > 1ah7y61.cont.kin

The -sampled flag says the data is uniformly sampled. In addition, this data has periodic boundaries since 360° is the same as 0°. Periodic boundries are setup with the -wrap flag.

The -kin and -group flags used in the last example add the commands @kinemage and @group to the kinemage file, allowing it to operate as a stand alone kinemage. Other useful keywords for controlling the kinemage layout are: -name, -noaxis, -flat and -lens.

The commands kin2Dcont -help and kin3Dcont -help will display a description of the command line options for these programs.



Troubleshooting


If you don't have kin2Dcont and kin3Dcont or if you have an old copy, you can get the latest release from our web site; binary executable files are available for several operating systems along with source code. Make sure you download .exe or .tar files as BINARY. If you download the .exe files, you will probably wish to rename them to just "kin2Dcont" and "kin3Dcont". Put them into a directory which is listed in your PATH environmental variable. For UNIX or LINUX you will also have to make them executable with the command:

chmod +x kin2Dcont kin3Dcont

The source code should compile easily on almost all UNIX like systems. Check the "makefile" for any system specific issues and then type:

make kin2Dcont kin3Dcont


Inline Kin2Dcont Help


Syntax: kin2Dcont [-flags] [inputfilename | -] >> out.kin

Read x, y, value or value, x, y sample data and
place on a 2D grid using a gaussian spot function and
generate one or more 2D contour levels in kinemage format.

Flags:

(contour level specification)
  -Level #.# color [...]          contour at one or more levels
  -Multi #.# #.# #.# color [...]  contour From To By Color
     where [...] represents optional additional level specifications

(discrete lattice and spot filter)
  -Grain#.#         spacing between lattice points (default 1)
  -GXY #.# #.#      spacing between lattice points in each dim
  -Stddev#.#        spot filter stddev (default 2)
  -SXY #.# #.#      spot filter stddev in each dim
  -WRAP #.# #.# #.# #.#  bounds of rectangle where edges wrap
                         (4 numbers: xmin xmax ymin ymax)
  -SAMPled          input data is a uniform grid of samples

(input source)
  -FIRST            value in first column then x,y (default)
  -LAST             value in last column after x,y
  -                 a dash represents the standard input stream
  -INput filename   alternate way to identify the input file
  by default, input is read from standard input

(other)
  -KINemage         writes @kinemage in header
  -GROUP            writes @group in header
  -SUBgroup         writes @subgroup in header
 (-group and -subgroup are mutually exculsive.)
  -NAMe string      identifier for @group or @subgroup
  -DOMinant         add dominant keyword to @group or @subgroup
                    (supresses header when used with -dump)
  -LENS             add lens keyword to @group or @subgroup
  -NOAXIS           do not draw axis lines marking the box edges
  -PS               output in PostScript rather than kinemage format
  -FLAT             make the contour levels flat on the 2D plane
  -T_               Use _ as the field separator character(s).
                    For example -t@ would separate on at-signs.
                    In the input, multiple consecutive separators count as one.
(The default delimiters are: blank, tab, newline, return, comma and colon)
  -Span#.#          spot filter span in stddev (default 2)
  -SCALE#.#         Z dimension scale factor (default 1)
  -DUMPlattice      output lattice data for debugging

  -Verbose          displays extra info about the calculation
  -Quiet            suppresses extra output

  -Help             prints this help message

Example: kin2Dcont -g5 -s10 -l 125 sea mydata >>my.kin
generates a single 2D contour with a spacing of 5 and a filter stddev of 10

kin2Dcont: version 1.4 3/6/99, Copyright 1999, J. Michael Word


Inline Kin3Dcont Help


Syntax: kin3Dcont [-flags] [inputfilename | -] >> out.kin

Read x, y, z, value or value, x, y, z sample data and
place on a 3D grid using a gaussian spot function and
generate one or more 3D contour grids in kinemage format.

Flags:

(contour level specification)
  -Level #.# color [...]          contour at one or more levels
  -Multi #.# #.# #.# color [...]  contour From To By Color
     where [...] represents optional additional level specifications

(discrete lattice and spot filter)
  -Grain#.#         spacing between lattice points (default 1)
  -GXYZ #.# #.# #.# spacing between lattice points in each dim
  -Stddev#.#        spot filter stddev (default 2)
  -SXYZ #.# #.# #.# spot filter stddev in each dim
  -WRAP #.# #.# #.# #.# #.# #.#  bounds of box where edges wrap
                     (6 numbers: xmin xmax ymin ymax zmin zmax)
  -SAMPled          input data is a uniform grid of samples

(input source)
  -FIRST            value in first column then x,y,z (default)
  -LAST             value in last column after x,y,z
  -                 a dash represents the standard input stream
  -INput filename   alternate way to identify the input file
  by default, input is read from standard input

(other)
  -KINemage         writes @kinemage in header
  -GROUP            writes @group in header
  -SUBgroup         writes @subgroup in header
 (-group and -subgroup are mutually exculsive.)
  -NAMe string      identifier for @group or @subgroup
  -DOMinant         add dominant keyword to @group or @subgroup
                    (supresses header when used with -dump)
  -LENS             add lens keyword to @group or @subgroup
  -NOAXIS           do not draw axis lines marking the box edges
  -T_               Use _ as the field separator character(s).
                    For example -t@ would separate on at-signs.
                    In the input, multiple consecutive separators count as one.
(The default delimiters are: blank, tab, newline, return, comma and colon)
  -Span#.#          spot filter span in stddev (default 2)
  -DUMPlattice      output lattice data for debugging

  -Verbose          displays extra info about the calculation
  -Quiet            suppresses extra output

  -Help             prints this help message

Example: kin3Dcont -g1.5 -s3 -l 125 sea mydata >>my.kin
generates a single 3D contour with a spacing of 1.5 and a filter stddev of 3

kin3Dcont: version 1.4 3/6/99, Copyright 1999, J. Michael Word


References & Further Information


[1] A Decomposable Algorithm for Contour Surface Display Generation, Michael J. Zyda, ACM Transactions on Graphics, Vol. 7, No. 2, April 1988, Pages 129-148.

[2] Numerical Recipes in C, 2nd ed, Press, Teukolsky, Vetterling, and Flannery, 1992, Cambridge University Press.

We hope this helps you get started working with contours. To find the latest version of kin2Dcont and kin3Dcont, see http://kinemage.biochem.duke.edu.

e-mail:
J. Michael Word or
David C. Richardson
URL: http://kinemage.biochem.duke.edu
Biochemistry Department
Duke University
Durham, NC USA 27710