Licensed Ribbons Software Distribution

Ribbons 3.32 'UNIX' ReadMe

Last update: Apr 12, 2008

Dear Ribbons License Holder,

To install the ribbons 'unix' (meaning anything but Windows) distribution:
(there is a separate Read.Me for the Windows PC distribution)


1) Create your official ribbons home.

Suggest you name it something like "ribbons" or "ribbons332": 

    mkdir /somewhere/on/your/machine/ribbons
Go there: 

    cd /somewhere/on/your/machine/ribbons
Make sure you have enough space with the unix command to report available kilobytes available on your local disk: 

    df -lk
There are nearly 13 megabytes for all the compressed archive files. The minimal required configuration requires about half that. The software will be extracted from these compressed files (below). The minimal required configuration requires about 10 megabytes, the complete (un-cleaned) installation over 18 megabytes.


2) Get the archives from our web server.

Browse: http://www.cbse.uab.edu/ribbons/

Select from the options under "Licensed Downloads". Will assume you select "Base Distribution", notes on the "...Executables" appears later.

Login with the "user"/"password" that you were given.

The files have been split into many pieces, to make life easier for those across the seas.

These are the base distribution files required for any 'unix' box:

Get the next 5 files for local help directory, else the browser will serve the pages from this website.

Get these executables for a Linux PC:

There are several pre-built binary distributions available also. Get any of them if you need to. They will overwrite the BINARY executables of 'rib_binu.tgz' and 'rib_binx.tgz'.
But, be sure to get the 'rib_bins.tgz' and 'rib_boas.tgz' anyway,
as they contain executable shell scripts used on all machines:

If you need (or want) to rebuild the software for another system, get the files below as well as those in the required base distribution):


3) Uncompress and extract the information.

Issue the following command: 

  csh unzip332.csh  ( Should see many file names scroll by )
                    ( Make sure there are no errors!! )
Issue the following command to see if you got it all: 

  ls -F    ( -F flags directories by adding trailing '/' )
           ( Should see 4-21 directories, depending... )
           ( Must at least see: bin/ data/ elmo/ boas/ )
At this point, you may remove all the *.tgz archives and untar332.csh (unless you want to make a backup in this form).

Do you have an SGI? For cuteness on SGI's, (as superuser): 

  cp  $RIBBONS_HOME/help/ribbons.icon /usr/lib/images
If you are running Linux Fedora Core 2, or have installed the pre-built binaries for your machine, you are ready to see if it works (below).

Else, you must be able to rebuild the code. You should have unpacked the source code archives above. 

  cd install     ( read the file: "Read.Me" )
  configure      ( under development - must create 'Makefiles' )
  make clobber   ( destroy any old binaries )
  make           ( compile everything )
  make install   ( move executables to $RIBBONS_HOME/bin )

4) Set your environment.

All ribbons users must:
  • set the environment variable: RIBBONS_HOME
  • set the environment variable: RIBBONS_HELP
  • set the environment variable: RIBBONS_SPEED
  • set the path to include: $RIBBONS_HOME/bin Instructions below for doing this are for 'csh' (what i use).

    To set the environment variable interactively, go to your directory "ribbons", type: 

      setenv RIBBONS_HOME `pwd`
    The 'RIBBONS_HELP' variable is the local command you run to surf the internet and view HTML documents, eg: 

      setenv RIBBONS_HELP firefox
    The 'RIBBONS_SPEED' variable is machine specific, to slow down fast new machines in various 'motion' modes. Suggest: 

      setenv RIBBONS_SPEED 1     ##  old SGI O2
  setenv RIBBONS_SPEED 10    ##  Mac G4
  setenv RIBBONS_SPEED 20    ##  Linux with hot video card
    To add to your command path interactively, (after doing the "setenv"), type: 

      set path = ( $path $RIBBONS_HOME/bin )
  rehash
    Suggest you put all of this in your .login or .cshrc file per local convention so it all works automatically on logging in. This is from my .login file: 

      setenv RIBBONS_HOME /wmc/ribbons
  setenv RIBBONS_HELP firefox
  set path = ( $path $RIBBONS_HOME/bin )
    If you use 'bash' under linux, you are on your own, but the comparable 'profile' commands look something like this: 

      RIBBONS_HOME=$HOME/projects/ribbons332
  PATH=$PATH:$RIBBONS_HOME/bin
  export PATH RIBBONS_HOME
  RIBBONS_HELP=firefox
  export RIBBONS_HELP
  RIBBONS_SPEED=20
  export RIBBONS_SPEED


    5) See if it works.

    Issue the following commands:

    A) Run the interactive demo: 

        ribbons-demo -n his

 Notes:
      A window is opened after initialization,
      with a small ball&stick model.
      LeftMouse controls scaling, MiddleMouse XY rotations,
      RightMouse XY translations.
      The workings are supposed to be intuitive.
      "Help" selected from the MenuBar brings up HTML screens.
    B) Run with your data:

    Ribbons requires PDB (Protein Data Bank) files for input. Ribbons works by making a database of lots of little ascii files for display. It requires each macromolecular chain for a ribbon drawing to be in a separate file for best results. Lots of utilities exist to massage the data, and these may be driven by the GUI interface 'ribbons-data'. For illustrations of your favorite molecule, mol.pdb, suggest your create a new directory, go there, copy (or link) your coordinates, then: 

       ribbons-data mol

 Notes:
      The workings are again supposed to be intuitive.
      Suggestion:  Click "Create Default Drawing"
      (if it beeps at the keyboard, just accept defaults for now)
      Then click:  "Execute Command" to invoke 'ribbons'
      The various help buttons should offer you guidance.
     *** Python version 2.4 must be installed on your system.
    C) Read The Friendly Manual!

    Read the overview of the program, and the first link "Required Files", and look at some sample images and the steps required to create them.
    All available from: 

       ribbons-help

    6) Let me know !!!

    E-mail after you get and test it, especially if you had any problems. Note I can't answer PC or linux questions, but would like to know if it works or not, or if there were any libraries you had to add. If you must rebuild the code on a new platform, I'll try to help. And, if you make a great image suitable for the image of the month gallery, please send it to me!

    -mike (carson@uab.edu)