Ribbons Data File Formats

*.model file

A display model, some-name is made known to the program by an ASCII file, some-name.model , in the current directory named with the following format:

       single-string-name-for-menu  x.center  y.center  z.center

Note: C format: ` %s %f %f %f ', so NO BLANKS allowed in the name string (use underscores or caps to convey multiple words).

*.atoms and *.bonds and *.texts files

These are ASCII files consisting of lists of filenames, one to a line. Each filename refers to a *.sph or *.cyl for atoms or texts and bonds respectively. These files provide groups of atoms, text or bonds whose graphical attributes may be modified.

Note: ONE filename per line. The files must be explicitly named `molecule.atoms', `molecule.texts', or `molecule.bonds' to correctly match with the `molecule.model'.

*.ribbons and *.coords files

These are ASCII files consisting of lists of filenames, one to a line. There must be a one-to-one correspondence between the *.pdb coordinate files and the *.ss secondary structural files that define a continuous polymer chain of each ribbon to be displayed. The lines of the *.coord file have the format:

       chain1.pdb  optional-string

The `chain1.pdb' is the filename of a coordinate file assumed to be one continuous chain with unique residue numbers. The `optional-string' defaults to protein coordinates; the program expects amino acids with standard atom names (one CA per residue must be present). An optional-string beginning with the letter `N' (or `n') signifies nucleic acid coordinates; the program expects nucleotide residues with standard atom names. (one P per residue must be present).

The lines of the *.ribbon file have the format:

       molecule.ss  optional-file.color

If no *.color file is present, default assignments are used: `$RIBBONS_HOME/data/protein.color' or `nucleic color'.

There must be a file `name.coords' and a file `name.ribbons' to draw ribbons with model `name.model'. There must be a one-to-one correspondence between the *.pdb files and the *.ss files. The same *.ss or *.color file may be used with any number of *.pdb files.

*.pdb file

The *.pdb extension for atomic coordinate files is not required, but is recommended. The Protein Data Bank files have the following format:

ATOM      1  N   MET     1      27.340  24.430   2.614  1.00  9.67      1UBQ  71
             ^   ^       ^^       ^       ^       ^      ^     ^

The programs generally skip all input lines that do not begin with the `ATOM' keyword. The atom name, residue name, residue number (combines the integer with the alt.code, if present), x, y, z, occupancy and B-factor are returned. The occupancy and temperature factor are generally optional.

Note: Ribbon drawings require each subunit or contiguous chain to be in a separate file. Only amino acid residues should be present. An N-terminal `ACE' group will cause problems. Each amino acid residue must have an atom named `CA' and each nucleic acid residue must have an atom named `P'. Each residue should have a unique `residue number'. Alternative residue numbering schemes, e.g., `36A', `36B', as found in the serine protease family are OK. The chain code identifier is ignored.

FORTRAN format: (`ATOM',2X,I5,2X,A4,A4,1X,I4,A1,3X,3F8.3,2F6.2) as in FRODO, BUT the residue number is expected to be an integer.

*.sph file

The *.sph extension for sphere files is not required, but is recommended. Sphere files consist of 5 required (and an optional 6th) fields. The fields are blank-separated in the following format:

       x  y  z  radius  colorindex  name

For example:

   17.047 14.099 3.625 1.94 4 n_1_T

Note: C format: ` %f %f %f %f %d %s ', x,y,z,r must have a decimal, colorindex is 1..16. The special `name' in my format is required for the surface routines. If it is used for `*.texts' files, the radius is required by ignored. Here `name' may have embedded blanks and is the string displayed. This name is also displayed if a sphere is picked.

*.cyl file

The *.cyl extension for cylinder files is not required, but is recommended. Cylinder files are similar to sphere files, consisting of eight required (and an optional 9th) fields. The fields are blank-separated in the following format:

       x1 y1 z1  x2 y2 z2  radius  colorindex  name

For example:

   17.047 14.099 3.625  16.967 12.784 4.338  0.16 7

Note: C format: ` %f %f %f %f %f %f %f %d %s ', x,y,z's, r must have a decimal, colorindex is 1..16. name is displayed if picked.

*.ss file

The *.ss extension for secondary structure files is not required, but is recommended. The *.ss files are the most complicated. They control both the coloring and the overall shape of the ribbon. These files should be generated automatically by `pro-ss', then edited or modified to the desired effect. The *.ss file consists of a 1-line title, a 1-line header, and one line of data for each residue. The 1-line header consists of blank-separated strings --- the ss-residue-key strings (currently a maximum of 20). The files have the following format:

 arbitrary text title
 res#    seq      ss      option-1  option-2 ... option-20
 resi-1 seq-char ss-char option-char-1 ... option-char-20
 resi-2 ... (repeat for all residues) ... 
 resi-N seq-char ss-char option-char-1 ... option-char-20
 

For example:

 Calmodulin.  courtesy of babu.
 res# seq  ss  hb range sspp rama om
    5   T   c   O   7    c   ?   ?
    6   E   H   O   8    H   r   T
    7   E   H   O   8    H   R   T
  ... ... ... ...  ...
  144   M   H   H   5    H   R   T
  145   M   H   H   5    H   r   T
  146   T   H   H   5    H   R   T
  147   A   H   H   5    c   ?   ?
 

The program processes the second line to determine how many coloring keys are available for the ribbon (There are 5 in the example above). The residue header keys are single strings. The first three keys must literally be `res#', `seq', and `ss' in that order. Any others may be defined by the user.

The residue information is then scanned in for each residue. This information consists of as many blank separated fields as there are coloring keys. Note: The actual residue codes must be single characters.

The `ss-char' is the most special and literal code. Each residue in the chain is classified as Sheet, Helix, or Coil. Sheets are specified with the characters `S' (not `s') or `A'. The `A' designation creates an `arrow' in the renderings. Helices are specified with the characters `H' for right-handed alpha-helices, `L' for left-handed helices, or `3' for 3/10 helices. Coils are specified with the character `c'. Any other character defaults to coil. Note: All the operations involving Sheet, Helix, or Coil in the Ribbon Control Panels are based on this assignment.

Any of the columns of single character codes may be used to determine the coloring of the corresponding portion of the ribbon. Any ASCII character (`A' different than `a') may be used. The characters `1',`2',...`9', correspond directly to the color-indices 1...9. For example, suppose you want to color the entire chain white (default color 7 = White) except for a small number of critical residues to be orange (default color = 8). A *.ss file could be edited as follows: 1) add an identifying string, eg, `critical' to the end of the second line; 2) add `(one-or-more-blanks) 7' to the end of all lines except the first two ( vi command --- :3,$s/$/(one-or-more-blanks) 7/ ); 3) change the `7' to `8' for all of your critical residues.

*.polys and *.ndots files

These are ASCII files consisting of lists of filenames, one to a line. Each filename refers to a *.tri or *.dot for polygons (triangles only) and dots requiring normals respectively. These files provide groups of triangles or dots whose graphical attributes may be modified.

Note: The files must be explicitly named `molecule.polys' and/or `molecule.ndots' to correctly match with the `molecule.model'.

*.dot file

The *.dot extension for surface dot files is not required, but is recommended. Dot files consist of 8 required fields. The fields are blank-separated in the following format:

     colorindex  x y z  atom#  nx ny nz

For example:

     6 28.932 24.204 2.064 1 0.937 -0.133 -0.324

Note: C format: ` %d %f %f %f %d %f %f %f ', colorindex is 1..16, x,y,z are the coordinates, atom# is currently not used (but required), nx,ny,nz are the normal vector.

*.tri file

The *.tri extension for triangle files is not required, but is recommended. Tri files consist of 4 lines per triangle with 10 required fields. The fields are blank-separated in the following format:

        colorindex
        x1 y1 z1 nx1 ny1 nz1 [color1]
        x2 y2 z2 nx2 ny2 nz2 [color2]
        x3 y3 z3 nx3 ny3 nz3 [color3]

For example:

    6
    20.752 31.122 0.602  -0.0597 0.7278 -0.6832 4
    21.160 30.823 0.318  -0.1210 0.2642 -0.9569 6
    20.186 31.133 0.626  -0.2602 0.3571 -0.8971 6

Note: C format: ` %f %f %f %f %f %f %d ', colorindex is 1..16 and applies to entire triangle, unless the vertices are given individual colors. The x,y,z are the coordinates and nx,ny,nz are the normal vectors for each vertex. If individual vertex colors are give, colors are blended. Vertices must be defined in a counterclockwise direction to set `outside' correctly.

*.color file

The *.color extension for color mapping files is not required, but is recommended. There are actually several formats for various types of *.color files referenced in the manual, depending on whether you need to color ribbons, spheres, or ranges of residues, or ranges of scalar values, like B-factors or electrostatics. See examples in $RIBBONS_HOME/data/*.color.

ribbons color file

The files consist of groups of three lines, repeated for as many secondary structure keys as needed in the following format:

       ss-residue-key-string  arbitrary-text
       resi-char-1 resi-char-2 ... resi-char-N
       color-int-1 color-int-2 ... color-int-N

For example:

      ss    color codes for secondary structure
       H   S   A   c   T   3
       6   2   2   8   1   4
      seq    amino acid class coloring
       A  C  D  E  F  G  H  I  K  L  M  N  P  Q  R  S  T  V  W  Y
       2  3  1  1  2  6  4  2  4  2  3  5  6  5  4  8  8  2  7  8

In the example above, the color-coding by sequence `seq' is set so that `C' and `M' both correspond to the index `3' (default color 3 = Yellow ). Thus all sulfur containing residues will be yellow if coloring by the key `seq' is chosen with Sequence Color from the Ribbon Style Panel .

Note: The first string read must literally match a residue key in the corresponding *.ss file. The second line consists of the blank-separated 1-character codes associated with the residues of the *.ss key. The third line consists of blank-separated integer color indices. There is a one-to-one correspondence between the second and third lines. There must be as many characters in line two as there are integers in line three. White is the default color for any 1-character code not explicitly set.

atom/residue sphere color file

The files consist of three lines only, in the same format as above. except the first line is completely arbitrary, eg:

     amino acid residue coloring
       A  C  D  E  F  G  H  I  K  L  M  N  P  Q  R  S  T  V  W  Y
       2  3  1  1  2  6  4  2  4  2  3  5  6  5  4  8  8  2  7  8

range of scalars color file

The files consist of 3 lines. The first is a header that must begin with an integer N. The program then expects N increasing floating point range values on the next line, and N+1 color integer codes on the last line. The example maps temperature factors from deep blue to red. Values less than 7.3 are color 10 and values greater than or equal 33.4 are red.

 5  !! set colors and range for pdb-bf-sph N, N ranges, N+1 colors
   7.3  11.5  16.0  24.7  33.4
 10    6     2     3     8     1

residue range file

The files consist of lines of an inclusive residue range and a colorInt (or a colorChar if you are working with a *.ss file). The example colors the first 89 residues color 3, and the rest color 4:

   1  89  3
  90 153  4

*.rgb file

All images are saved in the SGI `*.rgb' format, which has become more or less a standard (along with *.gif, *.tiff, etc). This is a binary file. Use the SGI tool 'imgworks' to crop/scale/enhance or change format of the image. Usage: imgworks image.rgb

*.orient file

*.matter file

*.defaults file