NAME

alignment-thin - Remove sequences or columns from an alignment.

SYNOPSIS

alignment-thin [OPTIONS] alignment-file

DESCRIPTION

Read an alignment, remove selected sequences or columns, and write the resulting alignment in FASTA format to standard output. The alignment filename is required; use - to read standard input. Diagnostics and --find-dups reports go to standard error.

Sequence filtering precedes column filtering. Length filters run first, followed by selection by name, removal of gappy sequences, and similarity thinning. Column filters therefore use the remaining sequences. Empty columns are retained unless a column filter removes them.

--protect, --keep, and --remove accept comma-separated names or @filename. In a names file, separate names with commas or newlines. Names are matched exactly. To supply an initial literal @, escape it as \@ and quote the argument for the shell.

Protected sequences survive all sequence filters. --keep also protects the listed sequences and retains any sequences named by --protect, even if a length filter would remove them. --keep and --remove cannot be given together.

To list sequence names or lengths, use alignment-info --show-names or alignment-info --show-lengths instead.

GENERAL OPTIONS

-h, --help

Print usage and options, then exit.

-V, --verbose

Output more log messages on standard error.

SEQUENCE FILTERING OPTIONS

-p names, --protect names

Protect the listed sequences from removal, without excluding other sequences.

-k names, --keep names

Keep only the listed sequences and any sequences named by --protect. These sequences are protected from subsequent sequence filters.

-r names, --remove names

Remove the listed sequences unless they are protected.

-l length, --longer-than length

Remove unprotected sequences with ungapped length less than or equal to length.

-s length, --shorter-than length

Remove unprotected sequences with ungapped length greater than or equal to length.

-c count, --cutoff count

Thin similar sequences using a strict cutoff of fewer than count directional mismatches. Count positions where the candidate has a present character other than a fully unknown state (such as DNA N) and the other sequence has a different symbol, including a gap. The count can differ when the two sequences are exchanged. Protected sequences are never removed.

-d count, --down-to count

Thin similar sequences toward count retained sequences. Earlier sequence removals count toward this target. Protection or the absence of a removable pair can prevent reaching it. When combined with --cutoff, the result can contain fewer than count sequences to satisfy the similarity cutoff.

--remove-gappy count

Remove up to count unprotected sequences with the fewest present characters at conserved columns. Conserved columns are recalculated among the remaining sequences after each removal.

--conserved fraction (=0.75)

For --remove-gappy, the minimum fraction of retained sequences with a present character needed to classify a column as conserved. Conservation here refers to occupancy, not identity.

COLUMN FILTERING OPTIONS

-K name, --keep-columns name

Protect columns occupied by the named sequence from --min-letters and --remove-unique. The sequence is looked up in the original alignment, even if removed by a sequence filter. Does not override --erase-empty-columns.

-m count, --min-letters count

Remove unprotected columns with fewer than count present characters among retained sequences.

-u length, --remove-unique length

Shorten runs of characters present in only one retained sequence to at most length characters, subject to --keep-columns protection. Internal runs are shortened from the middle; terminal runs are shortened from the outer end.

-e, --erase-empty-columns

Remove columns with no present characters after the other column filters. Gaps (-) and unknown calls (?) do not count as present; ambiguous non-gap states such as DNA N do.

OUTPUT OPTIONS

-S, --sort

Reorder columns to group similar gaps while preserving the character order within each sequence. Applied after filtering.

-F names, --find-dups names

For each input sequence outside the comma-separated target list, report its nearest target on standard error. The list must be nonempty; @filename is not supported for this option. Targets are chosen by mismatches at positions where both sequences have present characters other than fully unknown states such as DNA N. Reports use the original alignment, before filtering, and do not replace the alignment written to standard output.

EXAMPLES

Keep only selected sequences:

alignment-thin --keep=seq1,seq2 file.fasta > selected.fasta

Remove named sequences, or sequences of length 250 or less:

alignment-thin --remove=seq1,seq2 file.fasta > filtered.fasta
alignment-thin --longer-than=250 file.fasta > long.fasta

Thin to 30 sequences while protecting names listed in a file:

alignment-thin --down-to=30 --protect=@names.txt file.fasta > thinned.fasta

Thin sequences using a cutoff of five directional mismatches:

alignment-thin --cutoff=5 file.fasta > thinned.fasta

Remove up to ten sequences with poor coverage of conserved columns:

alignment-thin --remove-gappy=10 file.fasta > filtered.fasta

Keep columns with at least five present characters, retaining columns occupied by reference:

alignment-thin --min-letters=5 --keep-columns=reference file.fasta > columns.fasta

Remove empty columns from standard input:

alignment-thin --erase-empty-columns - < file.fasta > compact.fasta

Report each non-target sequence's nearest target, discarding the alignment output:

alignment-thin --find-dups=seq1,seq2 file.fasta > /dev/null

SEE ALSO

alignment-cat(1), alignment-info(1)

REPORTING BUGS

BAli-Phy online help: http://www.bali-phy.org/docs.php.

Please send bug reports to bali-phy-users@googlegroups.com.