ssu-mask(1)

NAME
ssu-mask - mask (remove columns from) SSU rRNA multiple sequence alignments

SYNOPSIS

Mask all alignments created by ssu-align in directory <dir>:

ssu-mask [options] dir

Mask single alignment file <aln>:

ssu-mask -a [options] aln

List sequences in alignments in <dir>:

ssu-mask --list [options] <dir>

List sequences in alignment file <aln>:

ssu-mask -a --list [options] <aln>

Convert Stockholm alignments in <dir> to aligned FASTA:

ssu-mask --stk2afa [options] <dir>

Convert Stockholm alignment <aln> to aligned FASTA:

ssu-mask -a --stk2afa [options] <aln>

Extract a subset of sequences from an alignment:

ssu-mask -a --seq-k <listfile> [options] <aln>

Remove a subset of sequences from an alignment:

ssu-mask -a --seq-r <listfile> [options] <aln>

DESCRIPTION

ssu-mask reads multiple sequence alignments created by ssu-align in the directory dir, removes some columns from them (i.e. masks them), and then outputs the masked alignments into the same directory.

The -a option specifies that the command line argument is a single alignment file to mask, not a directory.

By default, the alignment masks are automatically computed by ssu-mask based on alignment confidence estimates in the alignment files (posterior probabilities) and applied to remove columns from the alignments, as described below. Alternatively, pre-computed masks can be used to enable comparison across multiple datasets. To use the default SSU-ALIGN v0.1 mask, see the -d option.

The main purpose of masking is to remove the columns from an alignment that are most likely to contain alignment errors prior to using it as input for a phylogenetic inference program.

An alignment mask defines which columns will be kept and which will be removed. ssu-mask can either calculate an appropriate mask for each alignment based on alignment posterior probability values (confidence levels in the alignment) and/or gap frequencies, or use a pre-calculated mask from an input file. In all cases, all non-consensus columns (called insert columns) are automatically removed. Residues in these columns are not aligned. In ssu-align created alignments, 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".

By default, ssu-mask determines a mask based on the posterior probability (PP) annotation for aligned residues. PP annotation appears in #=GR PP lines in the alignments. Characters in Stockholm alignment PP annotation can have 12 possible values: the ten digits '0-9', '*', and '.'. If '.', the position corresponds to a gap in the sequence. A value of '0' indicates a posterior probability of between 0.0 and 0.05, '1' indicates between 0.05 and 0.15, '2' indicates between 0.15 and 0.25 and so on up to '9' which indicates between 0.85 and 0.95. A value of '*' indicates a posterior probability of between 0.95 and 1.0. Higher posterior probabilities correspond to greater confidence that the aligned residue belongs where it appears in the alignment.

By default, any consensus column in which greater than 95% of the sequences have a PP of 0.95 or better (i.e. have a PP value of '*') will be included by a PP-based masked. The 95% value can be changed to <x> with the --pf <x> option. And the 0.95 PP threshold can be changed to <y> with the --pt <y> option.

The frequency of gaps in each column will also be considered if the --gapthresh <x> option is used. Any consensus column in which more than <x> fraction of the sequences contain gaps will be removed. With --gapthresh, additional columns will also be removed based on PP as described above unless the --gaponly option is used, which specifies that gap frequency be the only determining factor for mask construction.

Alternatively, pre-existing mask files can be used to remove columns from the alignments by using the -d, -k, or -s options. See the description of those options below for details. A mask file defines which columns to keep/remove. The mask is a string that may only contain the characters '0' and '1'. A '0' at position x of the mask indicates that column x is excluded by the mask and should be removed during masking. A '1' at position x of the mask indicates that column x is included by the mask and should not be removed during masking. All lines in the maskfile that begin with '#' are considered comment lines and are ignored. All non-whitespace characters in non-comment lines are considered to be part of the mask. The length of the mask must equal the consensus length (number of consensus columns) of the alignment to be masked.

In addition to masking, ssu-mask can be also be used to list the names of sequences in alignments with the --list option, convert Stockholm formatted alignments to aligned FASTA format with the --stk2afa option, or remove a subset of sequences from an alignment with the --seq-k or --seq-r options, as described below in the OPTIONS section.

ssu-mask is a PERL script that uses the C programs esl-alimask, esl-alistat, esl-reformat, and esl-alimanip C programs from the EASEL package to mask alignments, list sequences, convert formats, and remove sequences, respectively. The versions of these programs installed with SSU-ALIGN are prefixed with 'ssu-' to distinguish them from any versions of the program distributed with INFERNAL or HMMER on your system. For example, the version of esl-alimask called by ssu-mask is actually called ssu-esl-alimask.

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.

-d  Use the pre-calculated, default SSU-ALIGN v0.1 masks. These masks were determined by applying the default 95%/0.95 PP-based masking strategy described above on very deep SSU alignments. See the User's Guide for details. The default masks are named archaea-0p1.mask, bacteria-0p1.mask, and eukarya-0p1.mask and are installed in SSUALIGNDIR (environment variable).

-s <f>
    Use 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.

-k <s>
    Use pre-calculated masks in files called <modelname>.<s>.mask for masking 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.

OPTIONS FOR CONTROLLING MASK CONSTRUCTION:

--pf <x>
    Specify that a consensus column is kept (included by mask) if the fraction of sequences with a non-gap residue in that column with a posterior probability of at least <y> (from --pt <y> ) is <x> or greater. All other consensus columns and all non-consensus (insert) columns are removed (excluded by mask). By default <x> is 0.95.

--pt <y>
    Specify that a column is kept (included by mask) if <x> (from --pf <x> ) fraction of sequences with a non-gap residue in that column have a posterior probability of at least <y>. All other consensus columns and all non-consensus (insert) columns are removed (excluded by mask). By default <y> is 0.95. See the DESCRIPTION section for more on posterior probability (PP) masking. Due to the granularity of the PP annotation, different <y> values within a range covered by a single PP character will be have the same effect on masking. For example, using --pt 0.86 will have the same effect as using --pt 0.94.

--rfonly
    Keep all consensus columns and remove all non-consensus (insert) columns. Do not remove any consensus columns based on posterior probabilities or gap frequencies.

--gapthresh <x>
    Remove all consensus columns for which the fraction of sequences in the alignment that have a gap ('.', '-', or '_') at that position is greater than <x> and all non-consensus (insert) columns. Other consensus columns may be removed based on posterior probabilities as well unless the --gaponly option is used.

--gaponly
    With --gapthresh <x>,only remove consensus columns based on gap frequencies. Do not remove any columns based on PPs.

MISCELLANEOUS OUTPUT OPTIONS:

--afa
    Output alignments in aligned FASTA (afa) format instead of Stockholm. Note that the output alignments will not be valid input to the ssu-draw or ssu-build programs.

--dna
    Output DNA alignments, not RNA ones. By default, RNA alignments are output, even if the input is DNA.

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

OPTIONS FOR CREATING SECONDARY STRUCTURE DIAGRAMS DISPLAYING MASKS:
If -d is used, ssu-mask will attempt to draw secondary structure diagrams displaying which consensus columns are kept and which are removed by the mask(s). The diagrams will initially be created as postscript files, but will be converted to pdf files if the program ps2pdf (or another program <s> specified by --ps2pdf <s> ) is installed and is in the user's PATH. Otherwise, the output diagrams will be postscript files.

--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.

--no-draw
    Do not draw any mask diagrams.

OPTIONS FOR ALTERNATIVES TO MASKING (LISTING, CONVERTING, OR REMOVING SEQUENCES):

--list
    For each alignment, create a file that simply lists each sequence in the alignment on a separate line. Masking is not performed.

--stk2afa
    Convert each Stockholm alignment to aligned FASTA format. Masking is not performed.

--seq-k <f>
    Remove all sequences except those listed in file <f>. The file must contain each sequence name on a separate line. All names in the file must exist in the alignment. This file must be used in combination with -a because it will only work on a single alignment. Masking is not performed.

--seq-r <f>
    Remove all sequences listed in file <f>. The file must contain each sequence name on a separate line. All names in the file must exist in the alignment. This file must be used in combination with -a because it will only work on a single alignment. Masking is not performed.

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/