coloRNA version 1.0 readme file-------------------------------This is written to help use the colorRNA Python program. The colorRNA program displays the secondary structure graphs included in the UTexas (www.rna.icmb.utexas.edu) or other PostScript files. It also reads a .pdb file and colors the residues from the secondary structure file according to either the B column data of 3D distance for each phosphate. The program can also differentiate user-defined groups of residues  using a user-controlled color. The base can be shown as a letter (A,T,G,C,U), keyboard character(%), or symbol. Normal Start:-------------1)Start program with the command "python colorRNA.py &", or whatever filepath is appropriate.2)Press the "Load Files" button, then press either "Select pdb file" or the "Select residue xy file" button. Within the pop-up window, navigate to the appropriate file and either double-click it or select the file and press the "Open" button. Repeat for all files you wish to use. Finally, select the green "Load files" button. NOTE: This program is expecting one chain in the pdb file. If your pdb file has multiple chains, make a copy of the pdb and crop out everything except the chain of interest. Also, on a slow machine the .pdb will load MUCH faster if only the Phosphates are included, a command like "grep ' P  ' infile.pdb > outfile.pdb" can accomplish this. Also, be advised that reading the .pdb file may take a minute, depending on the speed of your computer. 3)When the xydata file has been read, the secondary structure will appear in black. If the .pdb file has been loaded as well, the residues will be colored according to their B column values. If no xydata file is used, then nothing will be displayed. 4)Use controls to display the information accordingly. Controls:---------Under 'Load Files':    'Select pdb file'- a pop-up window will appear, navigate and select your desired pdb file.    'Select residue xy file'- same as above, for secondary xy structure data.     'Select rigid body file' - to input the file that will separate the secondary structure into regions. Each line in the file is an entry. For a region that is one (large) stem loop, the entry is: "| FirstResidue - LastResidue #". For a region that is discontinous, the entry is: "| FirstResidueSide1 - LastResidueSide1 | LowerResidueSide2 - HigherResidueSide2 # ".    'Select left/right file' - names a file that stores what "side" of a region, defined by rigid body file, is larger. The User should not need to modify this.     'Select colored group file" - Stores the x & Y points for every vertex of the colored region. The color of each region can be controled by modifying its "header". The color information is stored in standard RGB hexadecimal format (#99FFFF).    'Ignore changes'- do not load selected files. Close window with no action done.     'Load files'- if any files were changed, new files loaded.     Under 'Residue Options':    'Shape of existing residue'-if the residues are being shown as symbols, the shape a base that has a pdb entry will be displayed.    'Shape of non-existing residue'-if the residues are being shown as symbols, the shape a base that does not have a pdb entry will be displayed.    'Symbol size'- size of all residue symbols in the graph    'Letter to display for non-existing residue'- if residues are shown as letters, the letter a base without pdb information will be shown as. If left blank, the base will show it's own letter in black.     'Letter display size'-size of all residue letters in the graph.     'How to display residues above/below  max./min. threshold.'- controls how residues that do have pdb information and are above/below the two thresholds will be displayed. The two thresholds are controlled by sliders on the main window.        'Do not display' -the affected residues will not be shown on the graph.        'Display' -the affected residues will be shown exactly as other residues with pdb information would be displayed, except colored black.        'Display as other' - the affected residues will be shown in black as letters if unaffected residues are symbols, or vice versa.     'Ignore changes'- all changes made will be ignored. Close window with nothing done.     'Change residues' - any changes made will be performed when the window closes.     'Current residue' - Displays the residue number and type (A,C,T,G,U) that the mouse is currently over. 'Current value' - Displays the value, either B column value or distance from current Home residue, of the current residue. 'Selected residue' - Displays the residue number and type of curretn Home residue used for 3D distance calculations. The Home residue can be changed by clicking on a new one with the mouse.    Min. Threshold - this slider affects residues that have an entry in the pdb. The display of all residues with a B column value/distance less than what this is set to will be controlled by the 'How to display residues below min. threshold.' variable entry discussed in the Residue Options. This slider runs from the lowest B column value found to Max. Threshold setting.Max. Threshold - similar to Min. Threshold above. Residues as letter/symbols - controls how residues are 'normally' displayed. This setting controls residues with and without pdb information. If the 'Display as other' setting is selected in Residue Options, the residues above/below the thresholds will be switched as well. Under 'Key Options':   'Shape of key entries' - controls the shape of the colored region of the key.    'Number of key entries' - describes the number of colors/values in the key. Set this to 0 or 1 for no key.    'Size of key entries' - controls the size of the colored regions of the key, as well as the value size if displayed.    'Spacing of key entries' - controls the amount of vertical space between each key shape/value. If this is less the the size of a key entry, a continuous key can be constructed.    'Length of key value' - describes the length of the numerical value next the key color area. This length includes a period. Set to zero for colored key regions only.    'Use threshold for key min/max?' - If this option is selected, the min/max values of the key will be controlled by the threshold sliders.    'Ignore changes'- all changes made will be ignored. Close window with nothing done.    'Change residues' - any changes made will be performed when the window closes.   Under 'Rigid Body & Tick marker Options':   'Display rigid body regions?' - If this is checked, and a rigid body file has been uploaded, the delineations will be drawn.    'Display regions as outlines/open lines/polygons' - Select one of the three to determine how the delineations will be drawn. Outlines will highlight the region using a colored line that surrounds the region. Open lines is similar to Outlines, except that the line will be open between the first and last residue in the group. Polygons will highlight the region using a filled outline placed "behind" the residues and bonds.    'Distance from bases to edge of region' - controls the distance that colored region extends from the secondary structure.    'Thickness of line for outlines' - controls the width of line for colored regions.    'Display tick markers?' - If this box is checked, tick marks will be drawn for every tenth base.    'Length of tick mark' - Determines the actual length of the black tickmark. duh   'Tickmark thickness' - Determines the thickness of the tickmark.    'Shade of all tickmarks' - Controls the darkness of the tickmarks. A setting of Zero is black, and 255 is equal to white. Note that with a setting of 255 tickmarks are still being drawn, but white. This can be seen if colored regions/rigid body delineations are used.    B column or Distance display - Determines how residues are colored if a PDB is loaded. If B column is chosen, residues are colored based on the B column entry for their phosphates. If distance is chosen, residues are colored based on their 3D distance from a "Home" residue. The Home residue can be selected by clicking on it with the mouse while in this mode. 'Save Screen' - This button allows the User to save the contents of the canvas, white display region, to an EPS file that many graphics programs can read. Please note that it will only save what is currently visible on the screen. If some of the secondary structure is cut off, that will not be saved in the file. Also note that due to differences between Python and EPS graphics, the EPS file may not appear exactly as it does in coloRNA. Currently, all settings are optimized for EPS output. Under 'Advanced Options':   'Select arrows existance/color' - The arrows that highlight the Home base in Distance display mode will be colored based on the color scheme used by the key, if this is set to zero, one, or anything in between. If this is set to anything greater than one, the arrows will be colored black. If this value is set to less than zero, then no arrows will be displayed.    'Select arrows thickness' - Adjusts the thickness of the arrow, and the arrow head. Independent settings/different ratios should be possible, if you change the code.    'Select arrows distance' - Adjusts the distance between the Home residue and the point of the arrow.    'Select arrows length' - Changes the length of the arrow itself.    'Resolution of threshold sliders' - This settings changes the numerical position where rounding takes place. By default this is set to the tenths (1) position. If this is not accurate enough, depending on your B column entries, this could be moved to the hundred thousandths (5) position.    'Shade of all bonds' - Similar to shade setting for tickmarks. Value of 0 makes all bonds appear black, setting of 255 draws white bonds. Once again, these white bonds will be apparent if rigid body coloring is used.    'X & Y adjustments for ...' - These settings adjust various graphical elements in relation to each other. For instance, if the display looks good, except all the bonds are too far to the left, adjust the fourth slider from the bottom to the right (increasing). Note: Python considers the point (0,0) to be in the upper left hand corner of the white region. Seeing as this agrees well with SPIDER, I saw no reason to change it.    Converting file types:---------------------All xy data files used in this program are modified versions of the PostScript files from the Comparative RNA website (www.rna.icmb.utexas.edu). There are Python programs written to extract the information from modified versions of these files. They are not user friendly at the moment. Acknowledgments:----------------This software and readme file written by Jamie LeBarron. For a copy of this software, contact Dr. Joachim Frank:Joachim Frank, Ph.D. Howard Hughes Medical Institute Investigator, Professor, Department of Biochemistry and Molecular Biophysics, and Department of Biology, Columbia University, 650 W. 168th Street, P&S Black Building 2-221 New York, NY10032 (T) 212 305-9510 (F) 212 305-9500 (E) jf2192@columbia.edu http://franklab.cpmc.columbia.edu  http://www.hhmi.org/research/investigators/frank.html