/ 
FAST-1.06
River stage zero No dependents
/ fasgrep

NAME

fasgrep - print sequence records matching a pattern

SYNOPSIS

fasgrep [OPTION]... [PERL-REGEX] [MULTIFASTA-FILE]...

DESCRIPTION

fasgrep takes sequence or alignment data as input, and outputs sequence records whose data match a perl regular expression (regex) argument. By default, the regex is tested for matching against sequence identifiers. fasgrep takes one argument, a perl regular expression. Regex arguments may require quoting to protect special characters from interpretation by the shell.

Options specific to fasgrep: -s, --sequence match on sequence -d, --description match on description -f, --field=<int> match on field <int> in description -t, --tag=<string> match on tagged value in description -S, --split-on-regex=<regex> use regex to split description for fields -v, --negate output sequences that do not match -i, --insensitive match case-insensitively -e, --iupac-expand-nuc expand IUPAC ambiguities for DNA/RNA in query -r, --revcom-iupac-expand-nuc reverse complement query and expand IUPAC -p, --iupac-expand-prot expand ambiguities for protein in query

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

fasgrep 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 MATCHING BEHAVIOR

By default, fasgrep tests regex matching on the identifiers of sequence records. Options described below modify which parts of sequence records get tested for regex matching. These options take effect as follows with decreasing priority: -t > -f > -d > -s

OPTIONS

-s, --sequence

Print records whose sequence data match the regex. Default: [query identifiers]

-d, --description

Print records whose descriptions match the regex. Default: [query identifiers]

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

Split descriptions into fields, and print records for which a specific numbered field matches the regex. With this option, the description is split into fields using strings of white space as field delimiters (the Perl default).

This option takes a mandatory integer option argument giving the index for which field the regex should query. 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 fasgrep matches by default.

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

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

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

-v, --negate

Output sequences that do not match the regular expression argument.

-i, --insensitive

Match data case-insensitively.

-e, --iupac-expand-nuc

Expand IUPAC ambiguity symbols in the regex argument for DNA/RNA sequence matching (implies -s, matching on sequence data). For example, the symbol "B" in the regex is equivalent to "[CGTU]". This option, -e, has priority over -p.

-r, --revcom-iupac-expand-nuc

Reverse complement the regular-expression and expand IUPAC ambiguity symbols for DNA/RNA sequence matching (implies -s, matching on sequence data). For example, the symbol "B" in the regex is equivalent to "[ACG]". This option, -r, takes priority over -e or -p. priority.

-p, --iupac-expand-prot

Expand IUPAC ambiguity symbols in the regex argyment for protein sequence matching (implies -s, matching on sequence data).

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

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

-q B,--fastq> Use fastq format as input and output.

EXAMPLES

Print all sequences with "-DNA" in the ID:

    cat data.fas | fasgrep "-DNA" > data.dna.fas

Print all seqs with "mammal", "Mammal" or "MAMMAL" in the description:

    fasgrep -di "mammal" < data.fas > mammal.fas

Print all sequences with the motif MSDQ in them:

    fasgrep -s "MSDQ" < data.fas > MSDQ.fas

Print all sequences that don't start with S or R:

    fasgrep -v "^[SR]" < data.fas > sub.fas

Print all sequences matching purine-purine-pyrimidine:

    fasgrep -sem dna "RRY" < data.fas > RRY.fas

    fasgrep -se "RRY" < data.fas > RRY.fas

    fasgrep -s "[AG][AG][CT]" < data.fas > RRY.fas

    fasgrep -s "[AG]{2}[CT]" < data.fas > RRY.fas

Print sequence records containing characters that are not IUPAC nucleotide ambiguities:

    fasgrep -is '[^ACUTGRYWSMKBDHVN]'

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