NAME

fasfilter -- Select sequences by numerical values of name,value pairs

SYNOPSIS

fasfilter [OPTION]... [RANGES] [MULTIFASTA-FILE]...

RANGE SPECIFICATION

RANGES : { RANGE | RANGE,RANGES }
RANGE  : { POINT | BOUND>SEP<UBOUND }
>SEP<  : {    ..     |       :       |       -      }
POINT  : a number, as defined in perlnumber 
BOUND  : a number, as defined in perlnumber, or the empty string 
UBOUND : a number >= BOUND, as defined in perlnumber, or the empty string 

DESCRIPTION

fasfilter takes sequence or alignment data on input, and outputs only sequence records that have numerical data within specific value ranges. By default, entire sequence identifiers are compared, assuming they are numbers. Optionally, fasfilter may be directed to other parts of sequence records including entire descriptions, fields in descriptions, the values of tagged (name,value) pairs in descriptions, or the values of regex captures on identifiers or descriptions.

More specifically, fasfilter tests whether specific numerical data of sequence records falls within one of more RANGES specified by its only mandatory argument. If one record's value falls within one of the RANGES, the sequence will be printed to output. If a sequence record does not have the specified component, or its value falls outside all specified ranges, the sequence will not be printed to output. Range bounds are inclusive. Ranges are not simplified with respect to one another (e.g. through taking their union).

If the first range begins with a negative number, you should terminate option processing with "--".

Options specific to fasfilter: -d, --description filter on description -f, --field=<int> filter on field in description -t, --tag=<string> filter on value of a (tag,value) pair in the description -x, --regex=<regex> filter on value of a regex capture -S, --split-on-regex=<regex> split description for field-based filtering using regex -v, --negate print records whose values fall outside of all specified ranges

Options general to FAST: -h, --help print a brief help message --man print full documentation --version print version -l, --log create/append to logfile -L, --logname=<string> use logfile name <string> -C, --comment=<string> save comment <string> to log --format=<format> use alternative format for input --moltype=<[dna|rna|protein]> specify input sequence type -q, --fastq use fastq format as input and output

INPUT AND OUTPUT

fasfilter is part of FAST, the FAST Analysis of Sequences Toolbox, based on Bioperl. Most core FAST utilities expect input and return output in multifasta format. Input can occur in one or more files or on STDIN. Output occurs to STDOUT. The FAST utility fasconvert can reformat other formats to and from multifasta.

DEFAULT AND OPTIONAL FILTERING BEHAVIOR

By default, fasfilter tests identifiers of sequence records. Options described below modify which parts of sequence records get tested. These options take effect as follows with decreasing priority: -t > -xd > -x > -f > -d

OPTIONS

-d, --description

Filter sequence records by their descriptions. If used in combination with the -x, --regex option, filters records by values of a regex capture applied to their descriptions.

-f [int], --field=[int]

Filter sequece records by a specific field in their descriptions. With this option, the description is split into fields using strings of white space as field delimiters (the default Perl behavior for splitting lines of data into fields).

This option takes a mandatory integer option argument giving the index for which field to filter on. One-based indexing is used, so the first field after the identifier has index 1. As standard in Perl, negative indices count backwards from the last field in the description; field "-1" is the last field, "-2" is the second-to-last etc.

In fasta files, the identifier occurs between the record separator (">") and the first whitespace on the identifier line, and the description is everything after the first string of white space on the identifier line. Therefore the identifier is counted as the 0th field, which is what fasfilter tests by default.

-S [regex], --split-on-regex=[regex]

Use regex <regex> to split the description for the -f option instead of the perl default (which splits on one or more whitespace characters). Special characters must be quoted to protect them from the shell. The regex is often helpfully enclosed by single-quote (') or double-quote (") brackets but never by forward slashes (/).

-t [string], --tag=[string]

Filter sequence records by values of a named tag in the description. Name-value pairs in the description are expected to have the format "name:value" as generated by FAST tools (such as faslen) or "name=value" as common in General Feature Format. The "name" must contain only characters from the set [a-zA-Z0-9_-]. The "value" is any string of non-whitespace characters. Sequence records for which the specified tag does not exist will not be written to output. Currently only the first (left-most) occcurence of a tag is compared.

-x [regex], --regex=[regex]

Filter sequence records by values of a regex capture applied to identifers (by default) or descriptions (in combination with the -d option). The format of the regex is a perl regular expression that must contain exactly one "capture buffer" specified by a pair or parentheses. The value captured in this buffer is tested. Sequence records that do not match the regex will will not be written to output. Currently only the first (left-most) match is tested. Special characters must be quoted to protect them from the shell. The regex is often helpfully enclosed by single-quote (') or double-quote (") brackets but never by forward slashes (/).

-v, --negate

Output sequences that do not meet the specified numerical criteria.

-h, --help

Print a brief help message and exit.

--man

Print the manual page and exit.

--version

Print version information and exit.

-l, --log

Creates, or appends to, a generic FAST logfile in the current working directory. The logfile records date/time of execution, full command with options and arguments, and an optional comment.

-L [string], --logname=[string]

Use [string] as the name of the logfile. Default is "FAST.log.txt".

-C [string], --comment=[string]

Include comment [string] in logfile. No comment is saved by default.

--format=[format]

Use alternative format for input. See man page for "fasconvert" for allowed formats. This is for convenience; the FAST tools are designed to exchange data in Fasta format, and "fasta" is the default format for this tool.

-m [dna|rna|protein], --moltype=[dna|rna|protein]

Specify the type of sequence on input (should not be needed in most cases, but sometimes Bioperl cannot guess and complains when processing data).

-q --fastq use fastq format as input and output.

EXAMPLES

Output sequences with gi number identifiers between 200 million and 500 million

fasfilter -x "gi\|(\d+)" 2e8..5e8 t/data/P450.fas

Output sequences with length greater than or equal to 515

faslen t/data/P450.fas | fasfilter -t length 515..

SEE ALSO

man perlre

perldoc perlre

Documentation on perl regular expressions.

man FAST

perldoc FAST

Introduction and cookbook for FAST

The FAST Home Page"

CITING

If you use FAST, please cite Lawrence et al. (2015). FAST: FAST Analysis of Sequences Toolbox. and Bioperl Stajich et al..