ssu-draw(1)

NAME
ssu-draw - draw secondary structure diagrams of SSU rRNA

SYNOPSIS

Draw structure diagrams for all alignments created by ssu-align in directory <dir>:

ssu-draw [options] dir

Draw structure diagrams for a single alignment file <aln>:

ssu-draw -a [options] aln

DESCRIPTION

ssu-draw reads alignments created by ssu-align, calculates per-consensus-column statistics on them and creates secondary structure diagrams that display those statistics using "heat map"-like color schemes. The statistics are also printed in tabular format to output text files for easy parsing. ssu-draw can also draw secondary structure diagrams of individual sequences in the alignment with the --indi option.

Alignment masks, which define a subset of consensus positions to exclude from an alignment for purposes such as phylogenetic inference, can be displayed on the structure diagrams. Positions excluded by the mask will be drawn as open circles. Consensus columns are those which have a non-gap (non-'.') character in the reference annotation for the alignment. The reference annotation appears in lines beginning with "#=GC RF". ssu-draw will automatically display masks created by ssu-mask if they exist in the same directory as the alignments.

An important caveat of ssu-draw is that only consensus positions of the SSU models models are drawn. Inserted residues (i.e. any target residue that does not align to a consensus alignment position) are not drawn. Another important limitation is that ssu-draw cannot draw diagrams for alignments created by ssu-align using models other than the default ones (with the -m option to ssu-align ) unless the motivated user creates their own template postscript file for the models being used. For more information on this, see the ssu-esl-ssdraw manual page.

OUTPUT
The secondary structure diagrams created by ssu-draw are either pdf or postscript files. If the executable program ps2pdf exists in the user's path, the files will be pdf. If not, they will be postscript. The --ps2pdf and --ps-only options, described below, can be used to modify this default behavior.

By default, a single pdf or postscript that contains nine pages will be drawn for each alignment. The nine pages are alignment summary diagrams and display the alignment consensus sequence, information content, mutual information, insert frequency, average insert length, deletion frequency, internal deletion frequency, average posterior probability and fraction of sequences that span each position, respectively. The consensus sequence can be displayed on these alignment summary diagrams if the --cnt option is used. Additionally, the alignment statistics that are displayed in the structure diagrams are printed in tabular format to output text files ending with the ".drawtab" suffix to allow easy parsing.

OPTIONS

-h  Print brief help; includes version number and summary of all options.

-a  Specify that the single command-line argument is a Stockholm alignment file, not a directory.

-f  Force; override the limitation that structure diagram files file, not a directory.

-d  Display the pre-calculated, default SSU-ALIGN v0.1 masks on the secondary structure diagrams. Positions excluded by the mask will appear as open circles.

-s <f>
    Display the pre-calculated mask in file <f>. This option will only work on a single alignment, so either -a must be used, or <dir> must only contain a single alignment. The path and file specified by <f> must exist either with respect to the current working directory or SSUALIGNDIR (environment variable)..

-k <s>
    Display pre-calculate masks in files called <modelname>.<s>.mask on the secondary structure diagrams for alignments created by ssu-align with models named <modelname>. If ssu-align was used with the default CM file, <modelname> will be 'archaea', 'bacteria' or 'eukarya'. The mask files must exist in either the current working directory, the directory that includes the alignments being masked, or SSUALIGNDIR.

-m <f>
    Specify that the CM file <f> was used by ssu-align to create the alignment(s) being masked with a command like ssu-align -m <s> foo.fa foo. <f> must be a path that exists with respect to either the current working directory or SSUALIGNDIR.

-t <f>
    Specify that the template postscript file to use for drawing secondary structure diagrams is file <f>. If not used, the default v0.1 template file will be used. <f> must be a path that exists with respect to either the current working directory or SSUALIGNDIR.

-i  Specify that the -i option was used by ssu-align to create the alignments being masked.

MISCELLANEOUS INPUT/OUTPUT OPTIONS:

--ps2pdf <s>
    Specify that an executable named <s> in your PATH can be used for converting postscript files to pdf files with the usage: <s> foo.ps foo.pdf

--ps-only
    Specify that postscript output is preferable to pdf. No postscript to pdf conversion will be attempted.

--ifile <f>
    Insert information for the alignment, created by ssu-align, is in file <f>. This option only works in combination with -a.

--key-out <s>
    Include the string <s> as part of all output file names from ssu-draw, immediately before the suffix. For example, foo.archaea.<s>.pdf would be created instead of foo.archaea.pdf.

--no-mask
    Do not display masks on the structure diagrams. By default, ssu-draw will display masks created by ssu-mask if they exist in the same directory as the alignments.

--mask-key <s>
    Specify that the mask files created by ssu-mask include the string <s> before the ".mask" suffix. This will be true if the --key-out <s> option was used when ssu-mask was run.

OPTIONS FOR ONE PAGE ALIGNMENT SUMMARY DIAGRAMS:
In addition to the default nine page diagram displaying all available alignment statistics, each of the nine statistics can be drawn on single page diagrams using the following options. The output files will be named automatically based on the alignment file name.

--prob
    Draw a single page diagram displaying average posterior probability per consensus position for each alignment to a file.

--ifreq
    Draw a single page diagram displaying frequency of inserts after each consensus position for each alignment to a file.

--iavglen
    Draw a single page diagram displaying average insert length after each consensus position for each alignment to a file.

--dall
    Draw a single page diagram displaying the fraction of sequences that have a gap (deletion) at each consensus position for each alignment to a file.

--dint
    Draw a single page diagram displaying the fraction of sequences that have an internal gap (internal deletion) at each consensus position for each alignment to a file. An internal gap for a sequence is one that occurs after (3' of) the first aligned nongap residue in the sequence and before (5' of) the final aligned nongap residue in the sequence.

--span
    Draw a single page diagram displaying the fraction of sequences that span each consensus position for each alignment to a file. A sequence s spans consensus position 'x' that is actual alignment position 'a' if s has at least one non-gap residue aligned to a position 'b' <= 'a' and at least one non-gap residue aligned to a position 'c' >= 'a'

--info
    Draw a single page diagram displaying the information content of each consensus position for each alignment to a file.

--mutinfo
    Draw a single page diagram displaying the mutual information per basepaired position for each alignment to a file.

--cnt
    Draw consensus nucleotides on all alignment summary diagrams

--no-aln
    Do not draw the default nine page diagram displaying all available statistics.

OPTIONS FOR DRAWING STRUCTURE DIAGRAMS FOR INDIVIDUAL SEQUENCES:
Structure diagrams for individual sequences can be drawn, one sequence per page. For each sequence, an additional page displaying the posterior probability for the sequence will be drawn. To draw all sequences in the alignment, use the --indi option. The resulting pdf or postscript files will be large for large alignments. For pdfs, the file size will be about 1 Mb for every 20 sequences. For postscript file, the size will be about 1 Mb for every 2 sequences. If you only want to draw individual diagrams for a subset of the sequences in the alignment, use ssu-mask with the --seq-r or --seq-k options to create an alignment of the subset of sequences you want to draw, and then run ssu-draw on that alignment with the -a option. See the ssu-mask manual page for more information.

--indi
    Draw sequence and posterior probability diagrams for all sequences in each alignment.

--rf
    Draw a single page diagram displaying the model's reference sequence/structure to a file. The sequence displayed will be the exact sequence from the #=GC RF annotation of the alignment file.

--cons
    Draw a single page diagram displaying the alignment consensus sequence to a file. The consensus sequence is defined as the most frequent nucleotide at each position. Nucleotides that occur in at least 75% of the sequences that do not have a gap at the position will be uppercase; others will be lowercase.

--no-pp
    With --indi, do not draw posterior probability diagrams, only draw individual sequence diagrams.

--no-bp
    With --indi, --rf, or --cons, do not color nucleotides based on their basepair type.

--no-ol
    With --indi, do not outline nucleotides that are not the most common nucleotide in the alignment at their respective consensus position.

OPTIONS FOR OMITTING SECTIONS OF STRUCTURE DIAGRAMS:

--no-leg
    Omit the legend from all structure diagrams.

--no-head
    Omit the header from all structure diagrams.

--no-foot
    Omit the footer from all structure diagrams.

SEE ALSO
See ssu(1) for a master man page with a list of all the individual man pages for programs in the SSU-ALIGN package.

For complete documentation, see the user's guide that came with your SSU-ALIGN distribution (Userguide.pdf).

COPYRIGHT
Copyright (C) 2016 Howard Hughes Medical Institute.
Freely distributed under the BSD open source license.

AUTHOR
Eric Nawrocki
HHMI Janelia Farm Research Campus
19700 Helix Drive
Ashburn VA 20147 USA
http://eddylab.org/