ssu-build(1)

NAME
ssu-build - build SSU rRNA covariance models

SYNOPSIS

Build models using a user-created Stockholm alignment:

ssu-build [options] alignment-file

Build models using default SSU-ALIGN seed alignment:

ssu-build -d [options] seed-name

DESCRIPTION

ssu-build reads a multiple alignment of SSU rRNA sequences from alignment-file, constructs a covariance model and saves the CM to a file.

The alignment file must be in Stockholm format, and must contain consensus secondary structure annotation.

Alternatively, with the -d option, ssu-build uses the default SSU-ALIGN seed alignment for family seed-name as the input alignment. Possible choices for seed-name are archaea, bacteria and eukarya. The -d option is expected to mainly be useful in combination with the --trunc <s> option, which specifies that a subset of the input alignment be used to construct a non-full length model of a SSU rRNA, such as within positions spanned by a specific set of primers designed to target a variable region. (See the description of the --trunc <s> option below for details on its usage.)

When the -d option is used in combination with the --trunc <s> option, ssu-build will create secondary structure diagrams that highlight the specific SSU rRNA region that the newly constructed model represents.

The --trunc <s> option requires the user to know the beginning and ending consensus position of the desired region. Running ssu-build with the --num option will cause it to reformat the input alignment such that its consensus columns are numbered to make it easier to determine the appropriate column range. Additionally, the secondary structure diagrams of the default seed models included in the User's Guide have consensus positions of the default models numbered which may help determine column ranges when -d is being used in combination with --trunc.

ssu-build uses the program cmbuild from the INFERNAL package to construct CMs. Interested and motivated users can use cmbuild directly to create models. The version installed with SSU-ALIGN is actually called ssu-cmbuild to distinguish it from any versions of the program distributed with INFERNAL on your system.

OPTIONS

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

-d  Specify that the command-line argument is the name of a SSU-ALIGN 0.1 seed alignment, either 'archaea', 'bacteria', or 'eukarya'.

-f  Allow overwriting of the CM file.

-o <s>
    Specify that the CM file be named <s>. Without this option, ssu-build will automatically name the CM file based on the input alignment file name and command-line options that are used.

-n <s>
    Specify that the CM itself be named <s>. Without this option, ssu-build will automatically name the CM based on the input alignment file name and command-line options that are used. The name of the CM is important because it will be included as part of all output file names for files created by other SSU-ALIGN scripts that use this CM.

--append <s>
    Append this CM to CM file <s> that already exists. This allows creation of multi-CM files that can be used for discriminating between SSU sequences from different phylogenetic clades, such as the default SSU-ALIGN 0.1 CM file, which contains 3 CMs, one for each of the three domains of life.

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

OPTIONS FOR BUILDING MODELS FROM A TRUNCATED VERSION OF THE ALIGNMENT:

--trunc <s>
    Specify the range of alignment consensus columns to use for building the model. Without this option, the full alignment will be used. The <s> string must not contain any whitespace and must be formatted as <start>-<end> where <start> is the first consensus position to include and <end> is the final one, separated by a single '-' character. This option can be useful for creating a model that matches a specific region of the SSU molecule. For example, running ssu-build -d --trunc 525-765 archaea will build a CM that matches the so-called hypervariable V4 region of the archaeal SSU molecule. See the --num option for how to create alignments with consensus columns numbered to facilitate choosing start and end positions.

OPTIONS FOR REFORMATTING INPUT ALIGNMENTS

--num
    Do not build a CM. Instead, create a new alignment that is identical to the input alignment (or default seed alignment if -d) but that has extra annotation numbering consensus positions. This option is meant to be helpful for determining start and end positions to use with the --trunc option.

-i  Output alignments in interleaved Stockholm format of a fixed width that may be more convenient for reading. Without this option, output alignments will contain one line per sequence, and thus may contain very long lines.

OPTIONS FOR DEFINING CONSENSUS COLUMNS

--rf
    Use reference coordinate annotation (#=GC RF line in the input Stockholm alignment) to determine which columns in the input alignment are consensus, and which are not. Any non-gap character indicates a consensus column. (For example, mark consensus columns with "x", and insert columns with "."). This is true by default if the -d option is used, in which case ssu-build will use the #=GC RF annotation in the default seed model. However, if -d is not used, the default is to determine which columns are consensus automatically; if the frequency of gap characters in a column is greater than a threshold, gapthresh (0.8 by default, but settable with the --gapthresh option), the column is not consensus.

--gapthresh <x>
    Determine which columns in the input alignment are consensus based on the frequency of gap characters in each column. If less than or equal to <x> then the column is defined as a consensus one. As discussed in the description of the --rf option, this is default unless the -d and/or --rf options are enabled, with an <x> of 0.8.

OPTIONS CONTROLLING OUTPUT OF STRUCTURE DIAGRAMS

--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 This executable will be used for creating a pdf diagram of the showing the location of a truncated model on the SSU molecule if the --trunc and -d options are used. By default, ssu-build will use the executable program named ps2pdf if it is in your PATH to do this conversion. If ps2pdf does not exist, a postscript file will be generated.

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

EXPERT OPTIONS FOR MODEL CONSTRUCTION

--eent
    Use the entropy weighting strategy to determine the effective sequence number that gives a target mean match state relative entropy. The default target mean match state relative entropy is 0.59 bits but can be changed to <x> with --ere <x>.

--ere <x>
    Set the target mean match state relative entropy as <x>. By default the target relative entropy per match position is 0.59 bits.

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/