##############################################################################
##############################################################################

Note: non interactive mode: requires one of -p, -cg -png, or -jpg or
-ss from the command line. 
Example: sir_graph -p file where file.ct is a ct file will generate
a postscript file.

______________________________
|1.  sir_graph Documentation |
|____________________________|

sir_graph

##############################################################################
##############################################################################

________________________
|II. Brief Instructions|
|______________________|

Example ct files:  mdv1_1.ct, mdv1_2.ct, etc.
Below, assume that file.ct is a valid ct file.

To generate a circle graph as postscript output:

sir_graph -cg file

To generate a structure based on a circle graph as postscript:

sir_graph -p file

To generate a structure based on a circle graph as postscript with
automatic fixing of loops:

sir_graph -fix -p file

To generate a structure based on a circle graph as jpg output:

sir_graph -jpg test_1

To generate a structure based on natural angles as postscript:

sir_graph -p -n test_1

To view a structure in interactive mode based on a circle graph:

sir_graph test_1

To view a structure in interactive mode based on a circle graph  with
automatic fixing of loops:

sir_graph -fix test_1

-jpg, -png create jpeg and png output.
jpg and png can be used interchangably throught this documentation.


###########################################################################
###########################################################################


__________________________
| III. Input             |
|________________________|


For ct files, the .ct is optional, but the program tries to
open the file as given before appending the .ct.

Files starting with MFOLD in the data with be treated as GCG format,but
others will be treated as ct files.



For using this program to edit and save results for future editing:

Save the file with:    Create ss output

When editing the file "name".ct, this creates a file "name".new.ss
When editing the file "name".ss this creates a file "name".new.ss


To use any ss file as input with sir_graph,

Use the complete file name.  The .ss at the end will indicate to the
program to treat it like a ss file.

(Some ss files contain extra lines at the end specifying
font sizes, colors, line widths, etc.  This program 
should should ignore these lines.)

The program does not generate circle graph output for .ss files.

############################################################################
############################################################################
__________________________________
|IV. Interactive Mode Information|
|________________________________|

When -p, -png, -jpg and -cg are omitted from the command line,
sir_graph begins with an interactive editing mode.
Example:  sir_graph test_1


______________
| Windows:   |
|____________|

1.  Edit window,  Allows editing, and zooming of structure.
2.  Main window,  This small window shows the entire structure.
                  It has a box that can be resized and moved to
                  indicate what portion of the structure is shown in
                  the edit window.

3.  Information Window, Shows the current domain, or base as selected
                        in the edit window, and the function of the mouse
                        within the edit window.  Domain drawing information
                        is given such as clockwise, counter-clockwise, with 
                        loops automatically fixed, and with regularized angles.

4.  Input Window,      Pops up to ask for file names for saving.

All windows are resizable.

_____________________
|Key Usage:         |
|___________________|

For Edit Window

<Cursor Left>   Moves structure Left
<Cursor Right>  Moves structure Right
<Cursor UP>     Moves structure UP
<Cursor Down>   Moves structure Down



<Page UP>       Zooms in to magnify Structure.
<Page Down>     Zooms out to make structure smaller.

For the Main Window


<Cursor Left>         Moves box Left (Moves structure right in Edit window)
<Cursor Right>        Moves box Right
<Cursor UP>           Moves box UP
<Cursor Down>         Moves box Down
<Page UP>             Zooms in to magnify Structure in Edit window.
<Page Down>           Zooms out to make structure smaller in Edit window.


For the Input Window
 <Backspace>    Should be functional.
                 (Cursor keys are not functional.)


________________________________________________________
|Menu options: (Not all options appear in each window) |
|______________________________________________________|

Undo:     The program stores the current state and two previous states
          of the image as it is edited.  This option cycles back through
          these three states.

Mouse:    The right button brings up a menu in all windows.
          For the Main window, clicking on left button of the Main window
          selects the portion of the structure to show in the edit window.
 
          For the Edit window
          zoom     : the spot clicked becomes the center of the window.
                     The left button zooms in, the middle button
                     zooms out on the spot.
          Edit     : The left button identifies a base or base pair in
                     the information window.
                     This button will also drag a single
                     stranded base while pressed. 
                     For a double stranded base, the left botton
                     will move a helix if the base pair is the first
                     of a helix.  It will rotate the helix for any
                     other base pair.  Simply, press the button the
                     base pair, drag the mouse, and release the button.
                     For -f or -fa, see tutorial part II.

          Loop Stretch:  With the left button,
                         click on any base in a loop, and drag the
                         base away, or toward the center of the loop
                         to adjust the radius of the loop.

          Loop Natural:  click on a loop to redraw the loop with
                         natural angles using the left button.

          Loop Regularize: When a loop is clicked on,
                           each helix angle is rounded off
                           based on the value from Set Regularize Angle.
                           This works the same as Regularize All Angles,
                           except it applies to only one loop.

          Loop Fix:        For Circle graph angles, bases around
                           a loop are spread out so that they are
                           not drawn on top of each other.

          Single Strand Stretch:  With the left button,
                                  click on the middle base of a 
                                  single stranded region and drag
                                  the base away or toward the center
                                  of its loop.  The strand should
                                  move away or toward the center of the loop.
                                  (Does not work with -f or -fa below)

          Single Strand Linear:  Similar to above, but click on any base
                                 of a single stranded region. The base
                                 can be moved and other bases of the
                                 single stranded region will be spaced
                                 equidistant between it and the helix
                                 on either side.  It is most useful
                                 for a single stranded region at the
                                 end of a sequence. It can place the
                                 single stranded bases in a line and
                                 make the exterior loop look less like
                                 circular RNA/DNA. 
                                  (Added June 16, 2000)

Base Pair Lines/Dots:  Switch the connections between base pairs
                       from lines to dots, and back.

Outline Mode On/Off:   When on, letters representing bases are not drawn.

Loop Labels On/Off:    Draws a label for each loop.  The exterior loop is 1.

Base Labels:  Select the frequency of labeled bases.

Rotate Structure:   Selected an angle to rotate the structure.
                    Negative angles correspond to a clockwise rotation.

Clockwise/Counter Clockwise:  Any redrawing of the structure, or
                              any domain will be drawn as selected.
                              It is possible to draw some portions
                              of the structure clockwise, and others
                              counter clockwise.
                              If a structure is drawn clockwise, but
                              a particular domain is drawn counter-
                              clockwise, it will be drawn inside the
                              loop and may look strange.  This can be
                              done intentionally and is sometimes
                              useful.
                              If a .ss file is read in, this may need
                              to be set properly before editing
                              works as desired.

Annotation On/Off:   Select annotation type.
                     For selecting the name, .ann or .ss-count is appended
                     to the input file name. .ann is used for p-num and
                     probability annotation.
                     This option does not work in outline mode.

                     The -af option can be used to specify the file.

Annotation Options:  Bases, Dot, Both 
                     

Scale to fit window:


Some editing expands or shifts the structure.
This option scales and shifts the structure to center it in the
main window.
It also adjusts the zoom on the Edit window to show the full image.
The option is called automatically when some options are performed such
as creating jpg, png, or postscript output for the Main window.



Draw with Natural angles:  Redraws the entire structure with natural angles.

Draw with circle graph angles:  Redraws the entire structure with circle
                                graph angles.

Draw with Z value circle graph angles: Redraws the entire structure with
                                       circle graph angles;
                                       The Z value indicates how to
                                       space the bases around the circle graph.
                                       For Z = .01, bases outside a multiloop
                                       are spaced at .01 of the space between
                                       baseswithin a multiloop.
                                       This is an attempt to space bases
                                       better in multiloops.
                                       Look at some circle graphs with various
                                       Z values.

Use degrees of circle for above two:  Using more degrees usually spaces out the
                                      graph more.  Using fewer
                                      draws the structure more like a line.
 
Set Regularize Angle:  This sets the angle for the option below and
                       for Mouse Function: Loop Regularize.
                       Domains drawn with circle graph angles will
                       use this value.
                       The current value appears as Reg = value
                       in the information window.
                       

Regularize all angles: For a given loop, each helix is drawn at an
                       angle relative to the loop.  This option rounds
                       off each angle based on the value from 
                       Set Regularize Angle.
                       Problems may occur when two helices happen to
                       be drawn at the same angle. The angle is
                       measured relative to the helix that closes
                       the domain.  This regularizing is done for
                       all loops within the structure. The fix loops
                       option does not apply to this option.

Fix Loops On/Off:     When on, any domain drawn with circle graph
                      angles will have loops adjusted.  Each loop
                      is adjusted so that bases are not drawn on
                      top of each other.
                      When on, Fix appears in the information window.

Draw included domain with:  This redraws the structure based on the domain
                            indicated in the information window.

     Natural_angles:       Draws the loop with Natural angles;
     Circle graph Angles:  Draws the domain as it would be if
                           the entire structure were drawn with 
                           circle graph angles.

                        For other angles, More degrees draws the domain
                        with more separation between helices.  Fewer
                        degrees results in generally less overlap.

Draw excluded domain with:   Peforms the same as included domain, except
                             it works on the complementary portion of the
                             structure.

Create Postscript:  Creates a postscript image of the structure.
                    From the Main window, this draws the entire structure,
                    From the edit window, it draws the shown portion.

Create jpg, png:  Creates a jpg/png image of structure.
                  From the Main window, this draws the entire structure,
                  From the Edit window, it draws the shown portion.

The creation of jpg and png images of structures requires:
  1. libgd and the include files: gd.h, gdfontg.h, gdfontl.h,
     gdfontmb.h, gdfonts.h, gdfontt.h
     Having these will permit the creation of gif images.
  2. In addition:
     i.  If libjpeg is found, then jpg output can be created.
     ii. If libpng or libpng12 are found, then png output can be created.

Create ss output:   Creates an ss file.  This file can be used as input by
                    sir_graph or XRNA.
                    The positions of bases are preserved, but not colors
                    or fonts.  Most XRNA features are not supported.

Run sir_graph on Included Domain, Whole:
                     For the domain listed in the information window,
                     start a new version of sir_graph that draws
                     this domain using the entire circle for this domain to
                     determine angles.  Many options previously set
                     should be preserved in the new structure. Most editing
                     will not be preserved. To preserve the editing,
                     save the file as an ss file, and run sir_graph on
                     the domain.

Run sir_graph on Included Domain, Partial:
                     Same as above except use the fraction of the
                     circle corresponding to the domain.  This option
                     matches the current execution of sir_graph,
                     but the Whole option should spread the structure out
                     more.

Run sir_graph on Excluded Domain, Whole:
                     (Similar to above)
                     Draws the external domain using the whole circle
                     to determine angles.


Exit:               Exits.



##############################################################################
##############################################################################

 _____________________________
| V.  Command Line switches: |
|____________________________|



Use:       sir_graph 'name'.ct                          
    Where 'name'.ct is a ct file, to create a structure
    based on circle graph angles.  The .ct suffix is optional.  
    (Entering a name ending in .ss indicates to treat  
    the file as an XRNA ss file.                     
                                                           

-a                  Output list of angles of tangents and       
                    perpendiculars (in degrees)                

-ab                 Annotates only bases for -pnum, -prob, -ss-count
                                            
-ad                 Annotates dots for -pnum, -prob, -ss-count                 
                             
-aj                 Title bar of windows shows name, energy from
                    ct file. Default is energy, name.

-af file            Specify file for annotation                  
                    default is 'name'.ann for -pnum        
                               'name'.ss-count for -ss-count
                               'name'.ann or 'name_k'.ann for -prob
-ar                 Rotate structure to avoid landscape mode 

-c                  For circular rna, default is linear
                    The exterior loop is drawn slightly differently.

-cc                 Draw counter-clockwise, defaults is clockwise

-cg                 Draw a circle graph. No structure is produced.

-col file_name      Read user supplied colors from file_name

-col_ann file_name2 Read user supplied colors from file_name2

-d diam             Diameter of circle in inches, max is 6 inch

-e base i base j    Draw circle graph or structure for
                    this excluded domain.            
                     1<=base_i<base_j<=length        

-ew base i base j   Same as -e except use the whole circle
                    for the domain

-f                  Draw the exterior loop flat           
                    Default to use circle graph angles on the 
                    rest, or use -n for natural angles  
                    Use with -i or -iw to flatten any other loop
                    -e, -ew, -z  are not valid

-fa                 Same as -f, but alternate helices between 
                    clockwise and counter-clockwise (up & down)

-fix                For drawing with circle graph angles,
                    this option spreads out bases around each loop 
                    so that they are not drawn on top of each other. 

-force force_file   Draw forced base pairs from force_file  
                    as diamonds rather than a dot.  
                    force_file must contain 1 or more  lines of the form:
                     F 167 174 1
                     F 162 178 2
                    The F is required, the next values specify the base pair.
                    The last value specifies how many consecutive base pairs to
                    highlight.
                    The above draws three diamonds for the base pairs:
                      (167,174)  (162,178) (163,177)
                    Use at most 99 of these base pairs.
                 
-i base i base j    Draw circle graph or structure for
                    this included domain.   
                      1<=base_i<base_j<=length

-iw base i base j   Same as -i except     
                    use the whole circle for the domain
               
-jpg wid            Make jpg, not postscript, output of structure
                    width= wid  Height= wid*11/8.5, 
                    default: width=612, Height=792 
                       50 < wid < 3200  

-D                  Use dots, not lines, for structure base pairs

-lab n              Label every nth base of structure, 0 for none

-lij r c            Force labels on r and c     (can only use one time.)
         

-loop               Label loops of structure        

-m                  Show midpoints of arcs in circle graph

-mo                 Show only Midpoints of arcs in circle graph          

-n                  Generate structure based on natural angles

-ni                 With -png, make a non-interlaced png structure
                     (Jpg files are not specified as interlaced from the program, because 
                      problems arose when they were.)

-o out_file    Specify name of output file        
                default is 'name'_cir.ps or 'name'.ps

-outline       Do not show bases in structure      

-p             Output a structure 'name'.ps 

               
-png wid       Make png, not postscript, output of structure
               width= wid  Height= wid*11/8.5, 
               default: width=612, Height=792 
                    50 < wid < 3200  

-pnum          Use p-num annotation  from .ann file  

-prob          Use probability annotation from .ann file

-r deg         Use deg degrees of the circle        
                 0<deg<359    Default: 356       
-reg deg        On loops, round angles to deg degrees for a  
                structure from circle graph angles  5<=deg<=120  
                (Must be integer) 
                Performs similar to the Regularize All angles Menu option.     

-rot deg       Rotate structure deg degrees counterclockwise

-s             Color connecting lines based on bases   
                GC or CG    red                   
                AU or UA    blue                 
                GU or UG    green                
                  other     yellow  in circle graph

-ss          Create 'name'.new.ss output for Xrna
                 (does not generate circle graph)
            

-ss-count    Use ss-count annotation from .ss-count flie

-tab_ann_html Create HTML format table for annotation
                Works with -pnum, -prob, -ss-count   
                Name:   'name'.'annotation-type'.col.html

-x            Create 'name'.png2bp as a list of base pair locations
              for png or jpg to use for the image map that identifies
              base pairs when they are clicked on from the web server.
              First line is a distance in base pairs within which
              a user must click on a base pair.
              Other lines are x y  b1 b2 for a base pair (b1,b2)
              at x,y where 0,0 is top left corner of image.
              x increase across, y increases downward.

-z val       circle graph angle for bases not in multiloop
              0<=val<=2.0; default 1.0,                 
              Use .1 to advance non multiloop bases 10% 
              of the advance given to multiloop bases  

-zoom s x y   Zooms about point x,y at magnification s
               x,y is a jpg/png coordinate, (0,0) is top left.  
               (612,792) is bottom right corner at default resolution.
              s=1.0 is normal size, s=5.0 magnifies image 5 times larger.
              s=.5 makes image half as big.
              This option applies only to postscript, jpg and png structure
              output.  
              x,and y are positive integers and are coordinates from
              an unzoomed jpg/png image. The resolution during the
              zoom must match the resolution from the original image.
              s is a real number greater than 0.
              This option does not apply to interactive mode.
                    
               

-zoom_ps s x y  Zooms about point x,y at magnification s  
                x,y is a postscript coordinate from an unzoomed structure
                image where  (0,0) is bottom, left. (612,792) is top
                right.
                s=1.0 is normal size, s=5.0 magnifies image 5 times larger.
                s=.5 makes image half as big
                This option applies only to postscript structure output.
                Image size is 72 points per inch, 8.5 inches wide, 11 tall.
                s is a real number greater than zero. x,y are integers.
                This option can be used to zoom in on specific place
                based on its coordinates in the postscript image.
                This option does not apply to interactive mode.


Note:         -pnum and -ss-count are used to color bases
              in structures, but they color the connecting
              arcs in circle graphs based on the average of
              base pair values              


Typing sir_graph with no options will provide the above menu.

For using the interactive mode  many switches have
equivalent menu options.

Note that some switches cannot be mixed, while others
switches are valid only in combination with another as given below:

Some switches apply only to the postscript circle graph with -cg option,
 and not to structures.
 (no interactive mode,  no -p, no -png, and no -jpg)

-d, -m, -mo, -s

Some switches apply only to structures and require interactive mode or 
, -p, -png,-jpg:

 -aj, -ar, -D, -lab, -lij, -loop, -af, -n, -outline,  -rot,
-ss, -f, -zoom -zoom_ps -x

Some switches work with both the circle graph and to structures.

-a, -c, -cc, -col, -col_ann,-ew, -e, -iw,-i, -o,-r,-z, -pnum, -ab, -ad,
 -prob, -ss-count, -tab_ann_html



For -f and -fa
 -n , -cc , -i, and -iw are valid options

For -f, draws exterior loop flat and each helix from it clockwise
Use -i or -iw to  flatten out any other loop.
-cc draws every helix counter-clockwise.
For clockwise, helices are drawn above the single strand of the loop.
For counter-clockwise with -cc, helices are drawn below the single
strand of the loop.


For -fa:
  Helices alternate between clockwise and counter-clockwise.
  This draws them alternating above and below the single strand of the
  loop.

For -fa and  -f
  When editing, (Mouse Function: Edit)
  To draw a helix above the single strand of the loop, redraw the
  domain  clockwise, use counter-clockwise to draw a helix below
  the single strand.
  Dragging the first basepair of a helix on the flattened loop will
  drag everything right of the helix to the right.
  Single stranded bases between this helix and the next left helix will be 
  spaced evenly between the two helices.

 

############################################################################
############################################################################
____________________________________________
|VI.  Definitions and General Information  |
|__________________________________________|

Natural Angles:


For a loop, each loop has a closing base pair.  This base pair is drawn
at the end of a helix.  This determines where and at what angle the loop
is drawn.  The number of bases on the loop is used to determine the radius
of the circle used to draw the loop.
The bases are then drawn equally spaced around the loop.  Each helix
coming out from the loop is drawn at the angle that its first base pair
naturally falls.  Bases on a loop that are base pairs are moved slightly
toward or away from the center of the helix to preserve the predefined
 distance between basepairs.

These special exceptions were made to improve the appearance.

Bulge loops with 1 or 2 single stranded bases are drawn straight,
not as natural angles.
The two helices on the loop are drawn straight across from each other.

Asymetric interior loops that have  one more unpaired base on one side
than the other are also drawn with 2 helices straight across from each other.

Exterior Loop: The loop containing the first and last base.  For non-circular
RNA/DNA this loop is somewhat artificial.  It is considered loop 1
when loops are labeled.


_____________________
| Pseudoknots       |
|___________________|

sir_graph cannot display structures for pseudoknots.
The -cg option will display the circle graph.  Pseudoknots should 
correspond to intersecting arcs.



_________________________
| annotation            |
|_______________________|

For structures, -pnum, -ss-count read annotation files
and color each base based on the value from the file.
For circle graphs, an arc representing a base pair is colored based
on the average of the values from the file for the two bases.


See http://www.ibc.wustl.edu/~zuker/rna/form1-doc.html#ANN
             for color annotation information.


________________________
| Circle Graph         |
|______________________|


A circle graph provides a way to visualize structures based on the information
provided in a ct file. It is defined by spacing the bases of a sequence
equally around a circle.  For each base pair, an arc is drawn between them
that is perpendicular to the circle at each base.  The line normal to the
arc that bisects the arc between the two bases provides an angle for drawing
the base pairs within a helix of a structure.  For base pairs of a helix,
the normal line is the same for all.  This line can also be drawn as a line
from the center of the circle to the point on the circle half way between the
two bases of the base pair.  Also notice that the connecting arcs only
intersect when a pseudoknot occurs.   

Each helix of the structure is drawn parallel to the line of the normal
line of the circle graph.  This angle provided by the circle graph
is what is used to draw the structure.
The angle can be viewed with the -a switch for each helix and is given as
perpendicular. It is perpendicular to each base pair.

To see why the circle graph is useful for structures:

Draw a dot on each arc where the normal line hits it.
Connect each of these normal lines for base pairs belonging to a helix.
None of the lines will intersect. 
This series of connections is a primitive structure.
The -m option for circle graphs connects the base pairs and also
connects helices within a loop to a common point.

__________________________________
|Structure from the Circle Graph |
|________________________________|

Continuing from above,
the final structure is made by
drawing the helices of the circle graph larger and drawing the unpaired bases
around loops between helices.  This final step  results in overlap in the
structure in some cases.  

The final structure makes each loop size depend on the number of bases
attached to it.  For each loop, helices are drawn away from the loop at the
same angle they are drawn in the circle graph.  They may overlap due to their
width. Unpaired bases between any two helices on a loop are spaced equally
between the two helices, which is not always visually pleasing.

The algorithm uses 2 main procedures:

1.  Draw a loop as a circle.
   A loop begins with a starting base pair, its location, 
   and an angle provided by 2. B
    A.  Traverse the loop counting the number of bases and
        finding the angle of each helix coming off it based on the
        angle from the circle graph.
    B.  Set the loop radius based on the number of bases around it.
        circumference=bases_around_loop*(distance between bases)=
              2*pi*radius
        radius=bases_around_loop*(distance between bases)/(2*pi)
    C.  Determine the loop center based on the starting base location,
        the angle from 2.B, and the loop radius.
    D.  Traverse the loop again drawing base pairs at the angle from part 1.A,
        and drawing unpaired bases spaced equally between any base pairs.

2.  Draw a helix.
    A.  The first base pair of a helix is drawn when the loop is drawn.
        Every other base pair is drawn a fixed distance, 1.0,
        from the previous base pair at the angle provided by the circle graph.
    B.  If a base pair is the  final base pair of a helix, draw a loop with #1
        based on the location of this base pair and its angle.

The algorithm begins by drawing the first exterior loop of the structure.
This uses #1. with a special case.  It traverses the first loop beginning
with the last base of the sequence, advances to the first base, then advances
to the last base again.  This way it can find an angle for each helix coming
off the first loop.  The center is set arbitrarily near (0,0).

Define:
Start_base:  First base of the sequence, (Usually 1)
End_base:    Last base of the sequence.

B            Current base;
B-P          Base B paired with base P.

Let B=Start_base;
While(B<=End_base)
{  If(B is Paired with something greather than B)
    { If(B is not the first base pair of a helix)
        { Draw the base pair B-P as in #2.A
        }
      If(B is the last base pair of a helix)
        {Follow #2.B
        }
    }
   B=B+1;
}



If an interior domain is specified rather than an entire sequence,
Start_base and End_base are set to the domain value.

If an exterior domain is specified with -e base_1 base_2,
then Start_base is 1, End_base is the last base of the sequence,
and the while loop begins with an extra line:
If( (B>base_1) and (B<base_2))
    B=base_2;

The structure is finally scaled and shifted to improve its appearance.

##############################################################################
##############################################################################
______________________________
| VII.  Tutorial             |
|____________________________|

Sample data files:

test* is test data.
test.seq was used as input for the mfold
server from http://www.ibc.wustl.edu/~zuker/ to generate test data.

test_gcg_1.ct is an example of gcg format for input.
test_1.ct is a normal ct file for input.
test_1.ss is an normal ss file for input.
test_1.force is a sample file for use with -force.
test.plot was used to generate test.ann, but
              is not used by sir_graph.
test.ann    Used for color annotation of sir_graph for test data.
            See http://www.ibc.wustl.edu/~zuker/rna/form1-doc.html#ANN
             for color annotation information.
test.ss-count Used for color annotation of sir_graph for test data.
              Values based on test_1.ct, test_2.ct to test_13.ct
sample.ann    Alternate pnum values for for test_1.ct
 

file.ct is a normal ct file for input.

Examples:

___________________________________
| Tutorial for PostScript output: |
|_________________________________|

1. Circle Graph

sir_graph -cg test_1

Draws a circle graph,test_1_cir.ps,  in postscript format of test_1.ct

2. Enhanced Circle Graph
   sir_graph -cg -s test_1

Same as #1, but connecting arcs are colored depending on
the type of basepair. (A-U is blue, G-C is red.)

3.  Enhanced circle graph

sir_graph -cg -s -m test_1

Same as #2, but now basepairs of a helix are drawn as
dots at the center of the arcs, and they are connected to each other.


Helices on the same loop are also connected to form intersections at the
center of the loops. 
You should see some resemblance to the final structure in step #5.

4.  Circle graph much like a structure. 

sir_graph -cg -s -mo test_1

The connecting arcs have been removed.
This is close to the final structure of step #5.

5.  Structure based on the circle graph

  sir_graph -p test_1
    Creates a structure, test_1.ps.
    (sir_graph test_1 or sir_graph -jpg test_1 generate an on screen
     version, and jpg version respectively.)

6.  Structure based on the circle graph with labeled loops

  sir_graph -p -loop test_1
Same as #5, but the loops are labeled.
 

Compare the result to step #4 above. 

Each helix in the circle graph is drawn at a particular  angle.
(traveling down a helix toward the center of the circle.)
The helices are drawn at exactly the same angle in the structure.

The circle graph provides a way to draw helices in a way that they
do not overlap.

When the structure is drawn, the helices may overlap some
simply because they have a measurable width.  Bases drawn around a
loop may overlap because the circle graph does nothing to prevent this.

Notice that loop 3 of the structure corresponds to the intersecting
lines in the lower right portion of the circle graph.
The 4 helices coming off these 2 lines are the 4 helices drawn in the
structure.
(base pairs 12-304, 310-365, 370-408, 9-409) 

7. Structure based on Natural Angles


  sir_graph -n -p -loop test_1

Draws the structure using natural angles without reference to
the circle graph.

This method often produces structure with overlapping data.

8.  p-num annotated structure.

 sir_graph -p -pnum test_1

Generates test_1.ps annotated based on test.ann.

See color_table.ps and test.plot.

Red indicates a low p-num indicating a base is in few structures, 
that is well determined.

Black indicates a large p-num indicting a base is in many structures,
or poorly determined.

Colors range red,orange, yellow, green, cyan, blue, purple, black.

9.  ss-count annotated structure

  sir_graph -p -ss-count test_1


Generates test_1.ps annotated based on test.ss-count

Red indicates always single stranded, Black indicates always double
stranded.  

Colors range red,orange, yellow, green, cyan, blue, purple, black.

test.ss-count values depend on all structures test_1.ct test_2.ct
to test_13.ct



10.  Overlap.

The domain of bases 30 to 124 has  two helices overlapping in the
circle graph structure of #5.

The helix with base pair (93,102) of length 3, and
    the helix with base pair (72,89) of length 6 are particularly bad.


Try: 
sir_graph -lab 5 -p test_1 
 to label every 5th base.
 

To draw this domain specifically:

sir_graph -p -i 30 124 -o test_domain test_1

creates test_domain.ps

sir_graph -cg -m -i 30 124 -o test_domain -s test_1

creates the corresponding circle graph, test_domain_cir.ps





The two helices that overlap in the structure 
 are drawn at about the same angle in the circle graph.
(The helix near the 80, and the helix above and left of this one.)

sir_graph -m -cg -iw 30 124 -o test_domain -s -r 270 test_1

Uses 270 degrees of the circle for this domain.

Look at test_domain_cir.ps and notice that the 
two helices, now appearing near the top of the graph,
have been spread out.  They are no longer drawn at nearly the same angle.


sir_graph -p -iw 30 124 -o test_domain -r 270 test_1

produces test_domain.ps, an equivalent structure for the circle graph.




____________________________________
| Tutorial for Interactive Part    |
|__________________________________|

11.  Fix of problem in #10.

sir_graph test_1

Activates interactive window for editing.

A.  Turn ON loop labels by,
Selecting Menu option: Loop labels On/Off
(Right mouse button brings up menu.)

B.  Use Page UP, Page Down to zoom in/out to view structure in
EDIT window.
    Clicking (with left button) on Main window will alter the image in the
    window to match the part of the structure where clicking was done.

C.  Use Cursor Left, Cursor Right to view loop #9.

D.  Natural loop Fix:
     Select Menu option: Mouse, Loop Natural
    (Mouse: Loop Natural should appear in small information window.)

    click (left mouse button) on loop 9 to draw it with natural angles
      and remove overlap.
    click on loop 6 to draw this loop with natural angles.

    Zoom out to view entire structure.

    Use Menu option: Undo twice to return to original Image.

E.  Alternative to D.  (Equivalent to #10 above.)
    
    Select Menu option: Base Labels, 5
     This helps identify bases.
    Select Menu option: Mouse, Edit 

    Click on basepair, 30-124.
    This should select Domain: (30,124) in the small information window.
    
     Select Menu option: Draw included Domain with, Natural Angles

     Try also, 
            Menu optoin: Draw include Domain with, Circle Graph
            This sould be the same as the original.

     Try also,  
           Menu option: Draw include Domain with, Circle Graph 356
           This draws helices at angles based on using
            356 degrees of the circle graph for the domain 30 to 124.
           It thus spreads out the helices.

     Try also, 
        Menu option: Draw include Domain with, Circle Graph 270
        This does almost as much good as 356.
     Try also, 
        Menu option: Draw include Domain with, Circle Graph 45
        This draws the domain on 45 degrees and is similar to the original.

     Experiment to find something you like.
         I suggest the 270 degree option.


F.  Fix loops 15,14,18.

     Select Menu Option: Mouse: Loop Natural.

     click on loops 15,14,18 

     or


    Select Menu Option: Edit
    
     click on base pair  (133,260)
     Select Menu Option: Draw included Domain, Circle Graph 270
     click on base pair (136,175)
     Select Menu Option: Draw included Domain, Circle Graph 270

G.  Improve loop 3,

    Click on base pair (12,304)
    
    Select Menu Option: Draw included Domain, Circle Graph 270 

H.  Experiment with Mouse, Edit.

    Select Menu option: Mouse, Edit.

    Click (left mouse button) and hold on the first base pair of any helix,
    dragging will move the helix.
    Clicking on any other basepair and dragging will rotate the helix.

    Clicking and dragging on a single stranded base will move it.

I.  Experiment with loop stretch.

    Select Menu option: Mouse, Loop Stretch.
    
     click and drag on any base in a loop, This should expand or shring
      the loop as the pointer is moved away or toward the center of the
      loop.

J.   Experiment with strand stretch.
     
     Select Menu option: Mouse, Single Strand Stretch.
     
     Click on a single stranded base and drag it toward or away
     from the center of a loop to alter all bases on the strand.
     Clicking on the middle base of the strand should produce
     best behavior.


______________________________________________________________________
|Tutorial for Interactive part II   |
|___________________________________|
A.  For viewing an image clockwise with circle graph angles

Type
   sir_graph file


B.  Rotating the structure to improve appearance:
Try: Rotate Structure:  90 
     Rotate Structure:  -25

C.  Enlarging the image:
Press Page Up twice in Edit window.
Printing from the Edit window will produce the enlarged image.
Printing from the other window will produce the normal image with
a one inch margin.

D.  For Annotation:
Try: Annotation: p-num
Try: Annotation Options: dots
Try  Annotation: Off

E.  For Natural Angles:
Try: Draw with Natural Angles
Try  Rotate Structure: 90
     Rotate Structure: 5

Exit:

___________________________________________
|Tutorial for Flattening a loop           |
|_________________________________________|


F.  For flattening the exterior loop, clockwise appearance
Type 
   sir_graph -f file 
Exit:
(Try sir_graph file to see the differenct the -f makes)

G.  For flattening the exterior loop, clockwise/counter-clockwise
mixed appearance.

Type 
   sir_graph -fa file

H.  Dragging a helix attatched to a flat loop.
Select Mouse Function: Edit
Click and hold the base pair of a helix attached to the flattened loop. (Using
left mouse button)  move the mouse to drag the helix right, left, up or down.

The bases left of the helix and before the next helix should be spaced out
equally as the helix is moved.  Data to the right of the helix should
move exactly as the helix does.
Release the left button when the graph is correct.

Click on some other basepair of the helix will rotate it.
Click and drag on a single stranded base will move only it.

If a domain is selected for redrawing and it is attached to the flat loop;
it will be drawn above the flat loop if clockwise is selected, or
it will be drawn below the flat loop if counter-clockwise is selected.


Helices not attached to the exterior loop should be edited normally.

These options do not work with a flat loop:
   Mouse: Loop Stretch 
          Single Strand Stretch 


I.  To draw the exterior loop flat with natural angles on the helices 
coming off from it:
 sir_graph -fa -n file
 

J.  To flatten out some other loop, say the loop containing bases 162 to 215
Type from the command line:
  1.
     sir_graph -f -i 162 215 file

     Draws helices above the flat loop in clockwise fashion.

  2.
   sir_graph -f -i 162 215 file
   
   Draws helices below the flat loop in counter-clockwise fashion.


  3.
    sir_graph -fa -i 162 215 file
    Draws helices alternating  above/below the flat loop in
    alternating  clockwise/counter-clockwise fashion.

  4.
    sir_graph -fa -cc -i 162 215 file
    Draws helices alternating  below/above the flat loop in
    alternating  counter-clockwise/clockwise fashion.


##########################################################################
########################################################################## 
_____________________
| VIII. Update list |
|___________________|

 
############################################################################
############################################################################

___________________________________________
| IX. Example of each command line Switch |
|_______________________ _________________|

Most results can be compared to #1,#2, and #3 below to notice their effect.


1.   Create structure on the screen.

Switch:   (none)
Example 1a:     sir_graph file
Example 1b:     sir_graph test_1

Result: Produces structure on screen for file.ct

2. Create structure as a jpg


Switch:  -jpg


Example: sir_graph -jpg file

Result:  Produces jpg image 612 pixels wide x 792 pixels tall
named file.jpg.   The structure should be similar to #1, and #3.
(From #1 choose menu option: Create JPG: Resolution :Default 
to produce the same image.)

-jpg can be used in any command in place of -p when a jpg
is desired instead of postscript.

There is no jpg or png circle graph.


3.  Create structure as postscript

Switch: -p

Example: sir_graph -p file
Result:  Produces postscript file file.ps of the structure.
The structure should be similar to #1a, and #2.

(From #1 choose menu option Create Postscript: to produce
the same image.)

4. Create jpg of specified width

Switch:   -jpg wid
50<wid<3200,  height=11/8.5 * wid.

Example: sir_graph -jpg 400 file
Creates jpg image 400 pixels wide x 518 pixels tall of the structure.
(From #1 , use choose menu option: Create JPG: Resolution: and pick from the
 available resolutions.)

5. Label the loops.

Switch: -loop

Example: sir_graph -loop file
or sir_graph -loop -p file


Numbers the loops in the structure.
Loops start at 1 for the exterior loop.
(From #1, use menu option: Loop Labels On/Off)

6. List angles made by each helix.

Switch:  -a

Example: sir_graph -a file
or sir_graph -a -p file


With loops labeled:
sir_graph -a -loop file
or sir_graph -a -loop -p file



Lists each base according to what loop or helix it is on.
Loops can be labeled with -loop as in #5.
Each helix is numbered as the loop immediately preceding it.
The exterior loop and first helix are always numbered as 1.
The tangent angle is the angle made by the line connecting base pairs
of a helix.
The perpendicular is the angle traversed down the helix.



7.  Automaticly Rotate structure for better appearance.

Switch: -ar

Example: sir_graph -ar file
or sir_graph -ar -p file


The postscript output is assumed to be 8.5 inches wide and 11 inches tall.
Thus the paper's width is less than its height.

If an structure has greater width than height, it will be rotated 90 degrees
clockwise to make it fit better on the page.
When performed, the better fit of the image on the page allows it
to be magnified.

The switch works the same with screen and jpg output because they have
the same shape as a piece of paper.


8.  Rotate fixed amount.

Switch: -rot deg
           0 < deg < 359

Example: sir_graph -rot 63 file
or sir_graph -rot 63 -p file


Rotate the structure 63 degrees counter clockwise.

For combination -ar and -rot, try
sir_graph -ar -rot 180 file
or sir_graph -ar -rot 180 -p file


(For #1a, try Menu Option: Rotate Structure: 90 and
 Rotate Structure: -25 ) 

9.  Edit the jpg output.

10.  Annotation with pnum values from .ann file

switch: -pnum

Example: sir_graph -pnum test_1
or  sir_graph -pnum -p test_1


Uses test_1.ct and test.ann to color the bases based on pnum values
in test.ann.

color_table.ps lists the colors. Red is most certain. Black is least
certain.  The pnum value for base i is the the total
number of dots in the ith row and ith column of the plot file 
for the sequence.

(For #1, use menu option: Annotation: ON/OFF : p-num)


11.  Annotation with ss-count values from .ss-count file.

switch: -ss-count

Example: sir_graph -ss-count test_1
or  sir_graph -ss-count -p test_1



Uses test_1.ct and test.ss-count to color the bases based on ss-count values
in test.ss-count


color_table.ps lists the colors. Red is most often single stranded. Black least
often single stranded. The colors range over the values provided in the file.
The values in the file are the number of structures that a given base is 
single stranded. 

(For #1, use menu option: Annotation: ON/OFF : ss-count)



12.  Annotation with probabilities in .ann file.
(Not tested)

Switch: -prob

Example: sir_graph -prob test_1

Similar to #10, but values in test_1.ann are probabilities for
a given base pair.

(For #1, use menu option: Annotation: ON/OFF : Probability)


13.  Annotate character.
For #10, #11, #12 above, this annotates the base rather than using a colored
dot and a black or white base on top of it.

Switch: -ab


Example: sir_graph -ab -pnum test_1
or  sir_graph -ab -pnum -p test_1


(For #1, Use menu option: Annotation Options: Bases)

14.  Annotate Dot.
For #10, #11, #12 above, this colors a dot rather than a colored dot and
a black or white base on top of it.

Switch: -ad


Example: sir_graph -ad -pnum test_1
or  sir_graph -ad -pnum -p test_1


(For #1, Use menu option: Annotation Options: Bases)

15.  Specify file for annotation.

Switch:  -af file

Example:  sir_graph -af sample -pnum test_1
or sir_graph -af sample -pnum -p test_1
 



Searches for sample.ann and used it as an annotation file for test_1.ct
This switch should also work for -ss-count and -prob.

sample.ann defines the annotation slightly differently than test.ann of #10

16.  User supplied annotation colors.

Switch: -col_ann filename

Example: sir_graph -col_ann annotation.col -pnum test_1
or sir_graph -col_ann annotation.col -pnum -p test_1

This allow you to use something other than the red for well
determined and black for poorly determined color scheme.
The colors can be set as you like in the file, but the program
is particular about its format.

This should also work -ss-count and -prob.


#16 and #15 differ in that #16, -col_ann, defines the  40 annotation
colors with RGB values, but #15, -af, gives pnum, -prob, or -ss-count
information used to determine which of the 40 colors to use for each base.

17.  User supplied colors.

Switch: -col file_name

Example: sir_graph -col sir_graph.1.col test_1
or sir_graph -col sir_graph.1.col -p test_1

The file specified describes all colors except for annotation colors.
It can be edited, but its format must be maintained.

18.  Creating a html file to show pnum or ss-count information

Switch: -tab_ann_html

Example: sir_graph -tab_ann_html -pnum test_1
or sir_graph -tab_ann_html -pnum -p test_1


Creates test.ann.col.html

The -pnum is required.  It works similarly with -ss-count instead
of -pnum

The switch is ignored if the html file already exists.

19.  Specify circular RNA/DNA

Switch: -c

This should draw the exterior loop slightly different for circular
RNA/DNA.

The end bases are labeled 5' and 3' for non-circular RNA.
For circular RNA, they are labeled with the base number.

20  Draw the structure counter-clockwise rather the default
clockwise.
 
Switch: -cc

Example: sir_graph -cc test_1
     or sir_graph -cc -p test_1


21. Use dots, not lines, for base pairs.

Switch: -D

Example sir_graph -D file
or sir_graph -D -p file

22.  Outline mode.

Switch: -outline

Example: sir_graph -outline file
or sir_graph -outline -p file

Does not show bases in structure.

For jpg's, the program only draws the bases
when they are large enough to be seen even when this switch is omitted.

23. Create ss file for input to Xrna program.

Switch: -ss

Example: sir_graph -ss -p file


(For #1: Use: sir_graph file
         Edit the structure.
         Create the ss file with Create SS output)


24. Draw a flat loop.


Switch: -f or -fa

Example: sir_graph -f file
or sir_graph -f -p file

or 
Example: sir_graph -fa file
or sir_graph -fa -p file


See  Tutorial for flattening a loop above.

25. Draw a structure with natural angles.

Switch: -n

Example: sir_graph -n file
or sir_graph -n -p file


See definitions for how a natural angle structure differs from
a circle graph structure.

(For #1, Select Menu option: Draw with Natural Angles.)

26. Force labels on bases r and c

Switch: -lij r  c

Example: sir_graph -lij 221 226 file
 sir_graph -lij 221 226 -p file 


Places labels on the bases 221 and 226.

27.  Specify labeling of bases.

Switch -lab n

Example: sir_graph -lab 5 file.
or sir_graph -lab 5 -p file.


Labels every nth base.
Use -lab 0 for no labels.


28.  Specify the name of the output file.

Switch: -o out_file

sir_graph -o output -p file
creates output.ps

sir_graph -o output -jpg file
creates output.jpg

sir_graph -o output -cg file
creates output_cir.ps

sir_graph -o output file
will select a default name of output.ps or output.jpg when these
files are created from the menu.



29. Highlight specific base pairs as defined in a file.

Switch: -force force_file

sir_graph -force test_1.force -i 125 269 test_1 &
or
sir_graph -force test_1.force -i 125 269 -p test_1

This highlights the base pairs specified in the file by
drawing them as diamonds, not dots.
See -force above for the format of force_file.

__________________________________________________________________
|Circle graph command line switches  (with -cg )                 |
|________________________________________________________________|

30.  Create a postscript file of the circle graph

Switch: -cg 
Example: sir_graph -cg file
creates file_cir.ps


31.  Specify the diameter of the circle in the circle graph.
This has no effect on  the structre.

Switch: -d diam
0 < diam < 6.0 inches

Example sir_graph -cg -d 2.0 file 

Compare to #30.

32.  Color the connecting lines between bases of the circle graph
     based on the type of base pair.

     GC or CG    red
     AU or UA    blue
     GU or UG    green
     other

Switch: -s

Example: sir_graph -cg -s file

33.  Color the connecting lines between bases of the circle graph
based on the pnum or ss-count values.

Switch: -pnum or -ss-count
Example: sir_graph -cg -pnum test_1
or sir_graph -cg -ss-count test_1


34.  Specify an interior domain.
Draws the structure or circle_graph, but only shows base_1 to base_2.


Switch: -i base_1 base_2
base_1 < base_2

Example: sir_graph -i 16 300 test_1
or sir_graph -i 16 300 -p test_1

or for the circle graph
sir_graph -i 16 300  -cg test_1

This makes a region easier to see.
The domain is sometimes adjusted to show a little more of the
structure than is specified when base_1 and base_2 are not a base pair.

The structure for bases base_1 to base_2 is the same as it would be
without the -i switch.

35.  Specify an exterior domain

This draws the complement of #34.

Switch: -e base_1 base_2
base_1<base_2

Draws the structure or circle_graph, but only shows baes 1 up to base_1 and
base_2 to the last base.
The requires base_1 < base_2 and 
base_1 and base_2 must be a base pair.


This makes a region easier to see.

Example: sir_graph -e 16 300 test_1
or sir_graph -e 16 300 -p test_1

or for the circle graph
sir_graph -e 16 300  -cg test_1

Compare results for #34 and #35, and #1b to see the effect of -i and -e.


The visible portion of the structure is drawn the  same as it would be
without the -e switch.

36.  Draw an included domain using all of the circle.
This is similar to #34 but usually produces better results.

Switch: -iw base_1 base_2
base_1 < base_2

Example: sir_graph -iw 16 300 test_1
or sir_graph -iw 16 300 -p test_1

or for the circle graph
sir_graph -iw 16 300  -cg test_1

This makes a region easier to see.
The domain is sometimes adjusted to show a little more of the
structure than is specified when base_1 and base_2 are not a base pair.

The advantage over #34 is that the circle graph uses the entire circle
for bases base_1 to base_2,
and spreads helix angles out farther to make a better structure.

#34 Spreads the entire sequence over the circle and uses proportionally less
for the domain being viewed.

37.    Draw an excluded domain using all of the circle.
This is similar to #35 but usually produces better results.

Switch: -ew base_1 base_2

This requires base_1 < base_2 and base_1 and base_2 must be a base pair.


Draws the structure or circle_graph, but only shows base 1 to base_1 and
 base_2 to the last base.




Example: sir_graph -ew 16 300 test_1
or sir_graph -ew 16 300 -p test_1

or for the circle graph
sir_graph -ew 16 300  -cg test_1

This makes a region easier to see.

38.  A circle graph using only part of the circle.

Switch: -r deg

Example: sir_graph -r 180 file
or sir_graph -r 180 -p file
and
 sir_graph -r 180 -cg file
which use 180 degrees of the circle.

For normal
compare to sir_graph file
or sir_graph -p file
and sir_graph -cg file.
which uses 356 degrees of the cirle

Notice that the -r 180  squeezes the angles closer together.


Also try:

Example: sir_graph -r 90 file
or sir_graph -r 90 -p file
and
 sir_graph -r 90 -cg file
which uses 90 degrees of the circle and squeezes the
angles even closer together.

These results show that using fewer degrees for a structure
makes the angles closer together and harder to see.

Alternatively, for a domain, using more degrees  makes it
easier to see.

The editing from sir_graph allows a domain to be drawn with more
degrees than from the default circle graph and is thus easier to see
with some risk of overlap.

These also helps explain why -iw works better than -i.



39.  Spacing bases around a circle graph unequally.

Switch: -z val.
0<=val<2.0,   (1.0 gives equal spacing)



where val=(distance between bases outside a multiloop)/
           (distance between of a multiloop)

Example: sir_graph  -z .1 -cg file
produces file_cir.ps
Look at sir_graph -z .1 file

For some loops, the circle graph puts the bases too close together around the
multiloop.
This spacing adjustment was an attempt to fix the problem.
It works in some situations.

40.  Displaying the midpoints of arcs in a circle graph.

Switch: -m


Example:  sir_graph -cg -s -m file
(-s is optional)

This connects the midpoints of arcs in a helix.
The connections correspoind to consecutive base pairs in a helix.
The intersections of lines correspond to loops with helices coming
off from them.

Compare to #32.

41.  Displaying a circle graph without the connecting arcs.

Switch: -mo

Example:  sir_graph -cg -s -mo file
(-s is optional.
Without -s midpoints are colored red,
but with -s the colors are based on type of basepair.)

The connecting arcs from #40 are removed.
The result is similar to the structure of #1a.



42. For non-interlaced png's.
Switch: -ni

Example: sir_graph -png -ni file

png are interlaced by default.


Interlaced png appears different when it loads 
slowly into a browser. 
 
I am not sure interlaced, non-interlaced applies to jpg files.



__________________________________________________________________
|Tutorial for Fixing Loops                                       |
|________________________________________________________________|

43. Fixing all loops of a structure
sir_graph -fix test_1 
sir_graph -png test_1 
sir_graph -p   test_1

This should spread out all helices on every loop.

Alternate method for interactive part:
sir_graph test_1
Select Menu Function: Fix Loops On/Off
Select Draw with circle graph angles

44. Interactive Fixing of loops on a given domain:
sir_graph test_1
Select Menu Function: Fix Loops On/Off
Click on the base pair 30, 124
Draw includeded Domain with Circle Graph

45.  Interactive Fixing of a specific loop or loops:
sir_graph test_1
Select Menu Function: Mouse Function: Loop Fix
Click on a loop to fix it.
Loop 6 closed by base pair 38,116 is a good choice.
Click on several loops to see the difference.


__________________________________________________________________
|Tutorial for Regularizing angles of helices on Loops            |
|________________________________________________________________|
This will make some structures look better.
46.  


Note for mouse functions regularize and loop fix,
Only one of these can be on at a time, but
you can regularize a loop, and then fix it.



###############################################################################
###############################################################################
________________
| X. Appendix  |
|______________|


_________________________
|Changing Default Colors|
|_______________________|

Use -col file_name, where filename is an edited version of sir_graph.col

The colors in sir_graph.col match the default colors given in
sir_graph_color.h
Use -col sir_graph.1.col for colors based on a black background.


To specify your own annotation colors:
Use -col_ann file_name, where filename is an edited version of annotation.col
The colors in annotation.col match the default colors given in
sir_graph_color_ann.h

Do not change the number of colors.
Specifying RGB values in the .col files that make colors look alike is 
permissible and could be used to make fewer annotation colors appear.

____________________________
|Default Labeling Frequency|
|__________________________|
When -lab is ommitted,
For size being the length of the sequence or domain.
Label every 50th base for size >= 500;
Label every 25th base for 100 <= size < 500;
Label every 10th base for 20 <= size < 100;
Label every 5th base for size < 20;


________________________________________________________
| Automatic Fix of Loops drawn with circle graph angles|
|______________________________________________________|
The options: -fix, Mouse Function: Loop Fix, and Fix Loops On/Off
all attempt to spread out bases around loops drawn with circle graph angles.

Note that -fix can be used with -reg, but only one of the Mouse Function:
Loop Fix and Loop Regularize is enabled at one time.  However,
A loop can first be regularized, and then fixed.
Domains can be drawn with fix and a regularize angle set.


Basic algorithm: (clockwise)
First the loop is drawn with circle graph angles.
Then from the incoming helix, the loop is traversed clockwise
with each helix pushed away from the previous helix if necessary.
The helix is pushed to make room for no single stranded bases,
 1 single stranded base, 2 single stranded bases, or 3 single stranded bases.

If there is not room for 3 bases, but there are more than 3 of them,
they are drawn in a somewhat rectangle fashion between the helices.
For an odd number of bases, the odd one is placed at the end of
 the extending rectangle of bases.

      s
    s   s                s- s
    s   s                s  s
G*C-s   s-A*U or     G*C-s  s-G*U

If there is room for 3 bases and no helices are moved, but there is
not room for all of the single stranded bases, these bases are pushed
outward from the loop to make a curved or pointy extension from the loop
depending on the number of bases and their initial positons.






One big problem develops as the loop is traversed clockwise:
The last base pair on the loop may get pushed way from its initial position
and is no longer reasonable relative to the incoming helix.

It is repositioned correctly relative to the incoming helix.  All 
helices and interspaced single stranded bases within 90 degrees counter
clockwise from the incoming helix are shifted to match it, but their previous
positions relative to each
other are preserved.  This creates a new problem. Bases just beyond the 
last helix within 90 degrees counter clockwise of the incoming helix are
not correct relative to it.  They are moved outward so they do not
overlap it.  All base pairs and interspaced single stranded bases from 90
to 270 degrees from the incoming helix are moved outward from the
incoming helix by the same amount.
At this point the incoming helix and all helices within
90 degrees of it are correct relative to each other.
All helices from 90 to 270 degrees are correct relative to each other.
The region 90 degrees counter clockwise from the incoming helix
may be ragged, but it should not overlap.
It will be viewable, but on ugly on rare occasions.






___________________
|III. Source Files|
|_________________|

sir_graph.c           Main souce code, specific to drawing structures
                      within the windows.
sir_graph.doc         This file.
sir_graph_alloc.c     Allocates memory for arrays.
sir_graph_ann.h       Functions for color annotation for p-num, ss-count.
sir_graph_color.h     Sets main colors for structures and circle graphs.
sir_graph_color_ann.h Constants for sir_graph_ann.h
sir_graph_ct.c        Reads ct file
sir_graph_img.c       Creates jpg,png files
sir_graph_ps.c        Creates ps files
sir_graph_ss.c        Reads or creates ss files
sir_graph_core.c       Core features of sir_graph.(Added Sep 15, 2000)


For customizing colors:
sir_graph.col         Example color file with default colors for -col switch.
sir_graph.1.col       Example color file for black background for -col switch
annotation.col        Example annotation colors with default colors
                       for -col_ann switch


Sample input files:
  file.ct  
  test-gcg_1.ct
  test_1.ct
  test_1.ss

Sample annotation files:
test.ann               Provides p-num annotation for use with test_1.ct
test.ss-count          Provides ss-count annotation for use with test_1.ct
file.ann              Provides p-num annotation for use with file.ct
sample.ann             Alternate p-num vales for test_1.ct
 
Supplementary input files:
 file.ann             Annotation for file.ct
 test.ann              Pnum annotation for test_1.ct
 test.ss-count         Ss-count annotation for test_1.ct
 test_1.force          Used with -force and test_1.ct

Other: test.plot       Data used to produce test.ann
       test.seq        Data used as input to mfold server to generate
                       test data.
       color_table.ps  Listing of current annotation scheme.
                       Matches annotation.col and sir_graph_color_ann.h


Historical_numbering: The rightmost column of a ct file provides a historical
numbering of the bases.  The leftmost column begins with 1 and proceeds to
the length of the sequence.  For most features, the historical numbering
is used.   

_____________________________
| Known Bugs                |
|___________________________|


1.  -z with -i, -iw, has a few problems.
    -z with -e, -ew is not allowed.
2.  -e or -ew with some options ?
3.  Possible problem with historical numbering for some features.
    None noticed yet.

4. Output of ss file with historical numbering?