rib_bone Homepage


Among other uses, rib_bone is a set of tools to make H-bonds for Ribbons (Mike Carson) using Alwyn Jones's program O as a graphical interface.

Download version 0.1

Just "tar xf" this file from within (into) your working O directory.


How To rib_bone


============================================================
==                rib_bone Version 0.01                   ==
============================================================
==    A package for designating bonds and ranges of a     ==
==              molecular structure in O.                 ==
============================================================
==              (c) James C. Stroud, 2004                 ==
==        Provided under the GNU Public License           ==
============================================================


I. What is rib_bone?

rib_bone is the second generation incarnation of the perl
package formerly known as "rbbnd". The reason for the name
change should be obvious: the name "rbbnd" sucks.  Rib_bone
allows a user to use Alwyn Jones's program O as a graphical
front end for assigning hydrogen bonds, picking ranges, or
annotating structures. Atoms can be picked with various
commands with real-time graphical feedback in O.  rib_bone's
original intent was to allow a user to create a file that
described hydrogen bonds.  This file was then read into
another program that created the hydrogen bonds for Mike
Carson's program Ribbons. This is still one of the best uses
of the package, but I have added features that make it now
more generally useful. Besides creating an O drawing script,
called ".bonds.o" in the working O directory and
automatically displaying this drawing in O real-time,
rib_bone creates a file describing either bonds or ranges as
the user works. The real-time feed back is provided through
an O graphical object called "bonds" in the Object_menu.
The "bonds" object is described in the O data block
".bonds_draw".

Bonds and ranges are designated with the @bond and @range
commands, respectively.  Bonds and ranges can be
conveniently removed by deselecting with the @bond and
@range commands, respectively. Thus, @bond and @range are
toggles.  It is worthwhile to note that a bond is different
than a range, so a bond can not be toggled off by selecting
it with the @range command or vice-versa (this would be
analogous to trying to make a bond using the @range command
instead of the @bond command).


II. The rib_bone selection file: "bonds.txt"

This rib_bone selection file, called "bonds.txt", is created
in the O working directory. It contains lines that look like
the following:

    hnn k 286 nh1 : hnn m 533 o

This line has 9 parts separated by spaces. The first four
describe the NH1 atom that of residue 286 in chain K that
belongs to molecular structure "HNN". The colon (":") is the
"bond operator" that means the entry describes a bond.  As
you may have guessed the second atom is the main chain O of
residue 533 in chain M, also of molecular structure "HNN". 

There is a subtle logic to the description of an atom in
"bonds.txt", going from its most general affiliation to its
most specific (big to little). Namely,

    molecular_structure chain_id residue_number atom_name

Currently, the other operator is a range operator,
specifying a range of residues. The range operator is a dash
("-"). Thus, a line specifying a range would look something
like this:

    hnn m 535 cb - hnn m 638 ca

This line specifies a range of residues from 535 to 638 of
chain M.  The "bonds.txt" file reflects my penchant for the
lowercase.

The file "bonds.txt" can also contain blank lines and
comments.  Comment lines begin with a "#" (pound character).
Thus, a "bonds.txt" file might look like this:

    ####################################
    # beginning of "bonds.txt"
    ####################################

    # some bonds
    hnn k 286 nh1 : hnn m 533 o
    hnn g 166 oe1 : hnn k 286 nh2

    # some ranges
    hnn k 282 c - hnn k 411 c
    hnn g 200 c - hnn g 313 c

    ####################################
    # end of "bonds.txt"
    ####################################

If authoring your own rib_bone "bonds.txt" file, make sure
the selection lines contain all 9 (and only 9) elements and
are left justified.


III. rib_bone and Ribbons

rib_bone was originally designed to be used with Ribbons to
make hydrogen (or any other type of) bonds in illustrations
since this process is intensely tedious if done manually.
Presently, the way to use rib_bone with Ribbons for bonds is
by designating hydrogen bonds graphically in Ribbons using
the @bond command. The generated "bonds.txt" file can then
be used with the appropriate pdb file to create the bonds
for reading into Ribbons. The command would look something
like this:

    make_rb bonds.txt pdbfile.pdb > bondfile.cyl

By default, make_rb creates
dashed bonds, beautifully centered between the two atoms.
Solid bonds can be created with the -s option, e.g.:

    make_rb -s bonds.txt pdbfile.pdb > bondfile.cyl

The make_rb program comes originally in the "rib_bone/bin/"
sub-directory within the O directory in which rib_bone was
installed.

It is critical to note that the PDB file (above called
"pdbfile.pdb") should be the same one used for making the
original Ribbons model and have the same chain and residue
numberings as the PDB file read into O. Best is just to use
the same PDB file for all three (Ribbons, O, and make_rb) if
possible. If the coordinates are different between the
original Ribbons model and the make_rb PDB file, the bonds
will not be in the right place.


IV. rib_bone and extpdb

extpdb is a convenient little program (separate from
rib_bone) used to extract residues from PDB files and make
new PDB files with these residues. extpdb is used in the
following manner to produce a file ("part-of-1owr.pdb")
which contains a specific subset of atoms of another pdb
file ("1owr.pdb"):

    extpdb 1owr.pdb < ranges.txt > part-of-1owr.pdb

Extpdb uses a much simpler selection syntax than rib_bone
and only understands ranges, so the "bonds.txt" file must be
converted to an extpdb file with the program rb2ext.  The
above two lines

    hnn k 286 nh1 : hnn m 533 o
    hnn m 535 cb - hnn m 638 ca

converted with rb2ext will look like this:

    k 286 286
    m 533 533
    m 535 638 

Notice how the bond was converted to two ranges (a bond
isn't a range, after all--a range is a range and a bond just
connects two ranges of one residue each, as far as rb2ext is
concerned).

Since extpdb takes ranges of residues from one chain at a
time, rb2ext will make assumptions if a range that spans two
chains is designated.  Thus, when using rb2ext, be explicit
and make sure the residues are in the same chain, as the
example above demonstrates.

rb2ext and extpdb can be combined on a single line, so that
"bonds.txt" can be used by extpdb somewhat directly, e.g.:

    rb2ext bonds.txt | extpdb 1owr.pdb > part-of-1owr.pdb


V. rib_bone and ext-cb-rib

Ribbons (at least as of version 3.6) has a nice menu command
under :File:Export Ribbons Files:CB-bond: that writes bonds
from the C-beta atoms to the currently calculated ribbons.
These bonds are put into a file named by the user (e.g.
"CB-bond.cyl").  The limitation of this command is that it
outputs bonds for every residue in the PDB file. Usually,
the user will only want a subset of these bonds for a
particular figure. For this reason, I created the
ext-cb-rib. ext-cb-rib takes extpdb type ranges and cuts
bonds from the file created by the Ribbons "CB-bond"
command. ext-cb-rib is located in the rib_bone bin directory
of the insall folder. Execute the ext-cb-rib program to see
how to use it.


VI. Setup

To get started, just unpack the rib_bone.tar file into your
working O directory:

    cd my-o-folder/
    tar xf rib_bone.tar

Copy the files "make_rb", "rb2ext", and "ext-cb-rib" to some
place in your path. These files are in the newly created
rib_bone folder in the bin directory:

    my-o-folder/rib_bone/bin/

Get your O session started then do the following command in
your O text window:

    @mac/setup_rib_bone.mac

This will get four useful macros into your database: @bond,
@range, @addline, @comment, and @rbclear. @bond prompts the
user to pick two atoms and creates a bond between them.
@range is similar to @bond, except that a range is
designated. A range looks different than a bond in the
real-time graphical feed-back object "bonds".  @addline
simply adds a line to the file "bonds.txt".  @comment allows
you to add a comment to the "bonds.txt" file by typing into
the text window. @rbclear is a macro that renames
"bonds.txt" to "bonds.txt.old" and ".bonds.o" to
".bonds.o.old". It also deletes the "bonds" object from the
O database. You may want to edit your O User Menu to call
these macros (see the O documentation for how to edit your
User Menu. You will want to save your O database after
setting up rib_bone so you do not have to re-execute the
setup_rib_bone.mac macro in future sessions with the same
database.


V. Future

In the future, I plan these improvements/additions:

    1. Create an install script with user specifiable
       defaults, such as install location of various
       executables.
    2. Customizable appearance of graphical feed-back
    3. Combine @addline and @comment functions into rib_bone
       executable
    4. Extend the rib_bone language to include
       meta-information that can be used by make_rb to create
       more sophisticated ribbons files (bonds, atoms,
       h-bonds, ribbons).
    5. Create rib_bone converters to produce molscript, etc. 
    6. Essentially combine 4 and 5 to make rib_bone a    molecular
       drawing description language
    6. Create a more intuitive way to graphically represent a
       range
    7. Intelligible documentation