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