| README.kincontours | Home Page: Richardsons' Laboratory | J. Michael Word - 3/1999 |
On this page:
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].
Here is an example of using one of the contour routines:
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.
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.
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:
The source code should compile easily on almost all UNIX like systems. Check the "makefile" for any system specific issues and then type:
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
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
[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