.nr pp 11
.nr sp 11
.nr tp 11
.nr fp 10
.nr fi 0n
.sz 11
.if t \{
.po 1i
.he 'FASTA3.DOC''Release 3.5, June, 2008'
.fo ''- % -''
\}
.if n \{
.po 0
.na
.nh
\}
.ll 6.5i
.ce
\fBCOPYRIGHT NOTICE\fP
.lp
Copyright 1988, 1991, 1992, 1994, 1995, 1996, 1999 by William
R. Pearson and the University of Virginia.  All rights reserved. The
FASTA program and documentation may not be sold or incorporated into a
commercial product, in whole or in part, without written consent of
William R. Pearson and the University of Virginia.  For further
information regarding permission for use or reproduction, please
contact: David Hudson, Assistant Provost for Research, University of
Virginia, P.O. Box 9025, Charlottesville, VA 22906-9025, (434)
924-6853
.uh "\s+2The FASTA program package\s0"
.uh "Introduction"
.pp
This documentation describes the version 3 of the FASTA program
package (see W. R. Pearson and D. J. Lipman (1988), "Improved Tools
for Biological Sequence Analysis", PNAS 85:2444-2448 [.wrp881.]; W. R.
Pearson (1996) "Effective protein sequence comparison"
Meth. Enzymol. 266:227-258;[.wrp960.] Pearson et. al. (1997) Genomics
46:24-36;[.wrp971.]  Pearson, (1999) Meth. in Molecular Biology
132:185-219.[.wrp000.]  Version 3 of the FASTA packages contains many
programs for searching DNA and protein databases and one program
(prss3) for evaluating statistical significance from randomly shuffled
sequences.
.pp
This document is divided into three sections: (1) A summary overview of
the programs in the FASTA3 package; (2) A guide to using the FASTA
programs; (3) A guide to installing the
programs and databases.  In addition to this file, the
\fCchanges_v35.html\fP and \fCchanges_v34.html\fP list functional changes to the
programs.  The \fCreadme.v30..v35\fP, files provide a more complete
revision history of the programs, including bug fixes.
.pp
The programs are easy to use, so if
you are using them on a machine that is administered by someone else,
you can focus on sections (1) and (2) to learn how to use
the programs.  If you are installing the programs on your own
machine, you will need to read section (3) carefully.
.sh 1 "An overview of the \f(CBFASTA\fP programs"
.pp
Although there are a large number of programs in this package, they
belong to three groups: (1) 
"Conventional" Library search programs:
FASTA35, FASTX35, FASTY35, TFASTX35, TFASTY35, SSEARCH35, GGSEARCH35, GLSEARCH35;
(2)
Programs for searching with short fragments:
FASTS35, FASTF35, TFASTS35, TFASTF35, FASTM35;
(3)
A program for finding non-overlapping local alignments: LALIGN35.
Programs that start with \f(CBfast\fP search protein
databases, while \f(CBtfast\fP programs search translated DNA databases.
Table I gives a brief description of the programs.
.lp
(Earlier FASTA3 releases included \f(CBprss3\fP and
\f(CBprfx3\fP. With FASTA version 35, these programs have been
incorporated into \f(CBssearch35\fP and \f(CBfastx35\fP.  FASTA
version 35 programs now automatically estimate statistical parameters
by shuffling - the function of \fCprss\fP and \fCprfx\fP, when
searching for libraries with fewer than 500 members.)
.lp
.(z
.TS
center;
c s
c s
= =
l lw(5.5i).
\d\fBTable I. Comparison programs in the FASTA35 package\fP\u

\fCfasta35\fP	T{
Compare a protein sequence to a protein sequence 
database or a DNA sequence to a DNA sequence database using the FASTA 
algorithm.[.wrp881,wrp960.]  Search speed and selectivity are 
controlled with the \fIktup\fP(wordsize) parameter.  For protein 
comparisons, \fIktup\fP = 2 by default; \fIktup\fP =1 is more sensitive 
but slower.  For DNA comparisons, \fIktup\fP=6 by default; \fIktup\fP=3 or 
\fIktup\fP=4 provides higher sensitivity; \fIktup\fP=1 should be used for 
oligonucleotides (DNA query lengths < 20).
T}

\fCssearch35\fP	T{
Compare a protein sequence to a protein sequence 
database or a DNA sequence to a DNA sequence database using the 
Smith-Waterman algorithm.[.wat815.]  \fCssearch3\fP is about 10-times 
slower than FASTA35, but is more sensitive for full-length protein 
sequence comparison.
T}

\fCfastx35\fP/ \fCfasty35\fP	T{
Compare a DNA sequence to a protein
sequence database, by comparing the translated DNA sequence in three
frames and allowing gaps and frameshifts.  \fCfastx35\fP uses a
simpler, faster algorithm for alignments that allows frameshifts only
between codons; \fCfasty35\fP is slower but produces better alignments
with poor quality sequences because frameshifts are allowed within
codons.
T}

\fCtfastx35\fP/ \fCtfasty35\fP	T{
Compare a protein sequence to a DNA sequence
database, calculating similarities with frameshifts to the forward and
reverse orientations.
T}

\fCfastf35/tfastf35\fP	T{
Compares an ordered peptide mixture, as would be obtained by
Edman degredation of a CNBr cleavage of a protein, against a protein
(\fCfastf\fP) or DNA (\fCtfastf\fP) database.
T}

\fCfasts35/tfasts35\fP	T{
Compares set of short peptide fragments, as would be obtained
from mass-spec. analysis of a protein, against a
protein (\fCfasts\fP) or DNA (\fCtfasts\fP) database.
T}
=	=
.TE
.)z
.sh 1 "Using the FASTA Package"
.sh 2 "Introduction/Overview"
.pp
All the FASTA sequence comparison programs use similar command line
options and arguments.  The simplest arguments are:
the name of a query sequence file, a library file, and
(possibly) the \fIktup\fP parameter.  If command line options are
provided, they \fImust\fP preceed the standard query-file and
library-file arguments.
.pp
All of the programs can accept arguments
on the command line; if a query-file and library-file are not
specified on the command line, they will prompt for the file names (and
\fIktup\fP value, if appropriate).
.lp
To use FASTA, simply type:
.(l
.ft C
\f(CBfasta35\fP
and you will be prompted for :
.in +0.5i
the name of the test sequence file
the name of the library file
and whether you want ktup = 1 or 2. (or 1 to 6 for DNA sequences)
(ktup of 2 is about 5 times faster than ktup = 1)
.ft R
.)l
The program can also be run by typing
.(l
.ft C
fasta35 -q test.aa /lib/bigfile.lib \fIktup\fP (1 or 2)
.ft R
.)l
.lp
Included with the package are several test files.
To check to make certain that everything is working, you can try:
.(l
.ft C
fasta35 -q musplfm.aa prot_test.lib
.)l
and
.(l
tfastx35 mgstm1.aa gst.nlib
.ft R
.)l
.sh 3 "Sequence files I"
.pp
The \fCfasta35\fP programs can read query and library files in many
standard formats.  (Unlike some earlier versions of FASTA, and like
\fCBLAST\fP, version 35 can compare a file with multiple query
sequences to a sequence database, performing an independent search
with each sequence in the query file.)  The default file format for
query and library files -- the format that will be used if no
additional file format information is provided -- is \fCFASTA\fP format.
.pp
FASTA format files consist of a description line, beginning
with a '>' character, followed by the sequence itself:
.(l
.ft C
>sequence name and description 1
A F A S Y T .... actual sequence.
F S S       .... second line of sequence.
>sequence name and description 2
PMILTYV ... sequence 2
.ft R
.)l
All of the characters of the description line are read, and special
characters can be used to indicate additional information about the
sequence. In general, non-amino-acid/non-nucleotide sequences in the
sequence lines are ignored.
.pp
FASTA format files from major sequence distributors, like the NCBI and
EBI, have specially formatted description lines, e.g.:
.(l
.ft C
>gi|54321|ref|np_12345| example NCBI refseq sequence
.ft P
.)l
or
.(l
.ft C
>sw:gstm1_human P01234 glutathione transferase GSTM1 - human
.ft P
.)l
Included with the FASTA distribution are several sample test files,
\fCseq/*.aa\fP and \fCseq/*.seq\fP, as well as two small sequence
libraries, \fCseq/prot_test.lib\fP and \fCseq/gst.nlib\fP.
.pp
You can build your own library by concatenating several sequence
files.  Just be sure that each sequence is preceded by a line
beginning with a '>' with a sequence name/description.  Sequences
entered with word processors should use a "text" mode, e.g. "Save as
text" with MS-WORD, with end of line characters and no special
formatting characters in the file.  The FASTA program cannot read
Microsoft Word .DOC files, or rich text (.RTF) files; query and
library sequence files should contain only sequence descriptions,
sequences, and end-of-line characters.
.sh 3 "Running the programs"
As mentioned earlier, the FASTA programs can be run either
interactively, by typing the name of a FASTA program (and possibly
command line options) and the <return>
key, or from the command line, entering command line options, and the
query and library file names.  For searches of large databases that
may take several minutes (or longer), it is probably more convenient
to run searches from the command line, e.g.:
.(l
.ft C
fasta35 -q query.file library.file > output.file
.ft P
.)
The command line shown above could be typed in a Unix or MacOSX
terminal window, or from the MS-Windows command line interface
(command.exe).  In the command above, the \fC-q\fP ensures that the
program will not pause to ask for additional information; the \fC>
output.file\fP sends all of the output from the program to
\fCoutput.file\fP.  The command line syntax shown above works for all
the FASTA programs, e.g.:
.(l
.ft C
lalign35 -q mchu.aa mchu.aa > mchu.laln
fastx35 -q mgstm1.seq prot_test.lseg > mgstm1.fx_out
ssearch35 -q mgstm1.aa xurtg.aa > mgstm1_xurtg.ss
.ft P
.)l
.pp
\fICommand line options\fP -- The FASTA programs provide a variety of
command line options that modify the default scoring matrix
(\fC-sBL62\fP) and gap penalties (\fC-f -11\fP, \fC-g -1\fP), other
algorithm parameters, the output options (\fC-E 0.1\fP, \fC-d 20\fP,
\fC-m 9i\fP), and statistical procedures (\fPz -2\fP).  A complete
list of command line options is shown near the end of this document.
Unlike the \fCBLAST\fP programs, all \fCFASTA\fP command line options
must preceed the query file name and library file name (and there are
no command line options available to specify the query and library
file names).  Thus, a FASTA command like:
.(l
.ft C
ssearch35 -q query.file library.file -s BL62
.ft P
.)
that seeks to change the scoring matrix to BLOSUM62, would at best
ignore the \fC-s BL62\fP option (it might fail altogether).
In general, FASTA programs run from the command line should always
start:
.(l
.ft C
fasta_pgm -q
.ft P
.)l
However, one can provide command line options (e.g. to change the
scoring matrix or gap penalties) without a query file or library file,
and the program will use the options but prompt for the necessary
files. The program will not prompt, however, if the \fC-q\fP option is
provided; it will fail lacking a query and library sequence.
.sh 3 "Interpreting the results"
.pp
After a FASTA program runs, it typically provides a histogram of the
similarity scores (no histogram is displayed if there are fewer than
20 sequences in the library), a list of sequence descriptions and
scores, and a set of alignments.  Fig. 1 shows a summary of an
\fCssearch35\fP comparison of \fCseq/mgstm1.aa\fP against a small
protein database. Shown is the output after the histogram and before
the first alignment.  Below the statistical summary is information
about the algorithm (Smith-Waterman, with SSE2 acceleration), 
scoring matrix (BLOSUM62), and gap penalties (-11 to open a gap, -1 to
extend, thus -12 for a one residue gap, -13 for a 2 residue gap, etc.)
The numbers in parenthesis after the scoring matrix name
\fC(11:-4)xS\fP report the highest (11) and lowest (-4) values in the
matrix; the \fCxS\fP indicates that lower case (low complexity)
residues in the sequences were scored as 'X' in the initial alignments.
.(z
.ft C
5201128 residues in 13351 sequences
Statistics:  Expectation_n fit: rho(ln(x))= 4.1460+/-0.00039; mu= 6.3087+/- 0.022
 mean_var=21.2574+/- 3.982, 0's: 6 Z-trim: 29  B-trim: 27 in 1/61
 Lambda= 0.278176
 Kolmogorov-Smirnov  statistic: 0.0061 (N=29) at  32
Algorithm: Smith-Waterman (SSE2, Michael Farrar 2006) (6.0 Mar 2007)
Parameters: BL62 matrix (11:-4)xS, open/ext: -11/-1
 Scan time:  0.420

The best scores are:                            s-w bits E(13351)
sp|P08010|GSTM2_RAT Glutathione S-transf ( 219)  966 392.6 4.3e-110
sp|P09211|GSTP1_HUMAN Glutathione S-tran ( 211)  256 107.6 2.5e-24
sp|P04906|GSTP1_RAT Glutathione S-transf ( 211)  231 97.6 2.6e-21
sp|P00502|GSTA1_RAT Glutathione S-transf ( 222)  164 70.7 3.4e-13
sp|P14942|GSTA4_RAT Glutathione S-transf ( 223)  109 48.6 1.5e-06
sp|P12653|GSTF1_MAIZE Glutathione S-tran ( 214)   78 36.2   0.008
sp|P04907|GSTF3_MAIZE Glutathione S-tran ( 222)   77 35.8   0.011
sp|P20432|GSTT1_DROME Glutathione S-tran ( 210)   68 32.2    0.13
sp|P11277|SPTB1_HUMAN Spectrin beta chai (2138)   70 32.5       1
sp|P10138|RL15_MYCCT 50S ribosomal prote ( 146)   52 25.8     7.1
sp|P02664|CS2LB_MOUSE Alpha-S2-casein-li ( 144)   51 25.4     9.2
sp|P11413|G6PD_HUMAN Glucose-6-phosphosp ( 515)   56 27.2      10
.ft P
.sp
.ce
Figure 1 - \fCssearh35\fP results
\l'6.5i'
.)z
.pp
Four numbers after the description of each library sequence are shown;
the first (in parentheses) is the length of the library sequence; the
other three are the raw Smith-Waterman score for the alignment, the
\fIbit\fP score, and the expectation (E()), or statistical
significance, of the alignment score.  The E() value is given in the
context of the size of the database searched, in this case, 13,351
sequences.  The bit score shown here is equivalent to a BLAST bit
score; together with the length of query and library sequences, it can
be used to calculate the significance of the alignment.  Bit scores
are convenient because they provide a matrix independent score that
can be compared with other searches performed with other matrices and
gap penalties against other databases.  However, the E()-value, or
expectation, provides the most direct measure of the statistical
significance of the match; in this example the \fCGSTM\fP, \fCGSTP\fP,
and \fCGSTA\fP proteins from human and rat clearly share significant
similarity (better than { E() < 1.5 times 10 sup {-6} } ), and the
\fCFASTF1_MAIZE\fP sequence shares marginally significant similarity.
While percent identity is often used to characterize the quality of an
alignment and the likelihood that it reflects homology, the E()-value
is a much more reliable value.  Many sequences that share less than
25% identity will share very significant similarity (in the example
above \fCmgstm1.aa\fP and \fCGSTA_RAT\fP, with E() < 1.5e-6, are 23.3%
identical).  The expectation value captures information about
conservative replacements, identities, and alignment length to provide
a \fIsingle\fP value that captures the significance of the alignment.
.pp
The statistical routines assume that the library contains a large
sample of unrelated sequences.  With version 35, if the library
constains fewer than 500 (MAX_RSTATS) sequences, then the library
sequences will be shuffled to produce 500 random scores, from which
lambda and K will be estimated. If the library contains a large number
of \fIrelated\fP sequences, then the statistical
parameters can be estimated by using the \fC\-z 11\-15\fP, options.
\fC\-z\fP options greater than 10 calculate a shuffled similarity score
for each library sequence, in addition to the unshuffled score, and
estimate the statistical parameters from the scores of the shuffled
sequences.
.pp
For protein searches, library sequences with E() values < 0.001 for
searches of a 10,000 entry protein database are almost always
homologous. Some sequences with E()-values from 1 - 10 
may also be related, but unrelated sequences ( 1 \- 10 per search) will
have scores in this renage as well. Remember, however, that these E()
values also reflect differences between the amino acid composition of
the query sequence and that of the "average" library sequence.  Thus,
when searches are done with query sequences with "biased" amino-acid
composition, unrelated sequences may have "significant" scores because
of sequence bias.  \fCSSEARCH35\fP can address this problem by calculating
similarity scores for random sequences with the same length and amino
acid composition. 




.sh 1 "Options"
.pp
Command line options are available to change the scoring parameters
and output display. \fBCommand line options must preceed other program
arguments, such as the query and library file names.\fP
.sh 2 "Command line options"
.ip "-a"
(fasta35, ssearch3 only) show both sequences in their entirety.
.ip "-A"
force Smith-Waterman alignments for fasta3 DNA sequences.  By default,
only fasta3 protein sequence comparisons use Smith-Waterman alignments.
.ip "-B"
Show normalized score as a z-score, rather than a bit-score in the list
of best scores.
.ip "-b #"
Number of sequence scores to be shown on output.  In the absence of
this option, fasta (and ssearch) display all library
sequences obtaining similarity scores with expectations less than
10.0 if optimized score are used, or 2.0 if they are not. The -b
option can limit the display further, but it will not cause additional
sequences to be displayed.
.ip "-c #"
Threshold score for optimization (OPTCUT).  Set "-c 1" to
optimize every sequence in a database.
.ip "-E #"
Limit the number of scores and alignments shown based on the
expected number of scores.  Used to override the expectation value of 10.0
used by default.  When used with -Q, -E 2.0 will show all library sequences
with scores with an expectation value <= 2.0.
.ip "-d #"
Maximum number of alignments to be displayed.  Ignored if "-Q" is not
used.
.ip "-f"
Penalty for the first residue in a gap (-12 by default for proteins,
-16 for DNA, -15 for FAST[XY]/TFAST[XY]).
.ip "-F #"
Limit the number of scores and alignments shown based on the expected
number of scores. "-E #" sets the highest E()-value shown; "-F #" sets
the lowest E()-value. Thus, "-F 0.0001" will not show any matches or
alignments with E() < 0.0001.  This allows one to skip over close
relationships in searches for more distant relationships.
.ip "-g"
Penalty for additional residues in a gap (-2 by default for proteins,
-4 for DNA, -3 for FAST[XY]/TFAST[XY]).
.ip "-h"
Penalty for frameshift (fastx3/y35, tfastx3/y3 only).
.ip "-H"
Omit histogram.
.ip "-i"
Invert (reverse complement) the query sequence if it is DNA.  For
tfastx35/y35, search the reverse complement of the library sequence
only.
.ip "-j #"
Penalty for frameshift within a codon (fasty3/tfasty3 only).
.ip "-l file"
Location of library menu file (FASTLIBS).
.ip "-L"
Display more information about the library sequence in the alignment.
.ip "-M low-high"
Range of amino acid sequence lengths to be included in the search.
.ip "-m #"
Specify alignment type: 0, 1, 2, 35, 4, 5, 6, 8, 9, 10
.(l I
.ft C
    \-m 0        \-m 1          \-m 2          \-m 3        \-m 4
.ft C
MWRTCGPPYT   MWRTCGPPYT    MWRTCGPPYT                 MWRTCGPPYT
::..:: :::     xx  X       ..KS..Y...    MWKSCGYPYT   ----------
MWKSCGYPYT   MWKSCGYPYT
.ft P
.)l
.ip 
\fC\-m 5\fP provides a combination of \fC\-m 4\fP and
\fC\-m 0. \fC\-m 6 provides \fC\-m 5\fP plus HTML formatting.
.ip "-m 8"
provides BLAST tabular format output (a tab delimited line with the
query name, library name, percent identity, and other alignment
information). "\fC-m 8C\fP" provides some additional information
provided by the BLAST tabular with comment lines.
.ip "-m 9"
provides coordinates and scores with the best score information.
A simple "\fC -m 9\fP" extends the normal best score information:
.(l
.ft C
The best scores are:                                      opt bits E(14548)
XURTG4 glutathione transferase (EC 2.5.1.18) 4 -   ( 219) 1248 291.7 1.1e-79
.ft P
.)l
to include the additional information (on the same line, separated by
a <tab>):
.(l
.ft C
%_id  %_gid   sw  alen  an0  ax0  pn0  px0  an1  ax1 pn1 px1 gapq gapl  fs
0.771 0.771 1248  218    1  218    1  218    1  218    1  219   0   0   0
.ft P
.)l
\fC -m 9c\fP provides additional information: an encoded alignment string.  Thus:
.(l I
.ft C
       10        20        30        40        50          60         70  
GT8.7  NVRGLTHPIRMLLEYTDSSYDEKRYTMGDAPDFDRSQWLNEKFKL--GLDFPNLPYL-IDGSHKITQ
       :.::  . :: ::  .   .:::         : .:    ::.:   .: : ..:.. :::  :..:
XURTG  NARGRMECIRWLLAAAGVEFDEK---------FIQSPEDLEKLKKDGNLMFDQVPMVEIDG-MKLAQ
               20        30                 40        50        60        
.ft P
.)l
would be encoded:
.(l
.ft C
=23+9=13-2=10-1=3+1=5
.ft P
.)l
The alignment encoding is with repect to the alignment, not the
sequences.  The coordinate of the alignment is given earlier in the
"\fC -m 9c\fP" line.
.ip "-m 10"
\fC\-m 10\fP is a new, parseable format for use
with other programs.  See the file "readme.v20u4" for a more complete
description. 
.ip
As of version "fa34t23b2", it has become possible to combine independent
"\fC\-m\fP" options.  Thus, one can use "\fC\-m 1 -m 6 -m 9\fP".
.ip "-M low\-high"
Include library sequences (proteins only) with lengths between low and
high.
.ip "-n"
Force the query sequence to be treated as a DNA sequence.  This is
particularly useful for query sequences that contain a large number of
ambiguous residues, e.g. transcription factor binding sites.
.ip "-O"
Send copy of results to "filename."  Helpful for environments without
STDOUT (mostly for the Macintosh).
.ip "-o "
Turn off default optimization of all scores greater than OPTCUT. Sort
results by "initn" scores (reduces the accuracy of statistical
estimates).
.ip "-p"
Force query to be treated as protein sequence.
.ip "-Q,-q"
Quiet - does not prompt for any input.  Writes scores and alignments
to the terminal or standard output file.
.ip "-r"
Specify match/mismatch scores for DNA comparisons.  The default is
"+5/-4". "+3/-2" can perform better in some cases.
.ip "-R file"
Save a results summary line for every sequence in the sequence
library.  The summary line includes the sequence identifier,
superfamily number (if available) position 
in the library, and the similarity scores calculated.  This option can
be used to evaluate the sensitivity and selectivity of different
search strategies.[.wrp951,wrp981.]
.ip "-s file"
Specify the scoring matrix file.  \fCfasta35\fP uses the same scoring
matrices as Blast1.4/2.0.  Several scoring matrix files are included
in the standard distribution.  For protein sequences: \fCcodaa.mat\fP
- based on minimum mutation matrix; \fCidnaa.mat\fP - identity matrix;
\fCpam250.mat\fP - the PAM250 matrix developed by Dayhoff et
al.;[.day787.]  \fCpam120.mat\fP - a PAM120 matrix.  The default
scoring matrix is BLOSUM50 ("-s BL50"). Other matrices available from
within the program are: PAM250/"-s P250", PAM120/"-s P120", PAM40/"-s
P40", PAM20/"-s P20", MDM10 - MDM40/"-s M10 \- M40" (MDM are modern
PAM matrices from Jones et al.,[.tay925.]), BLOSUM50, 62, and 80/"-s
BL50", "-s BL62", "-s BL80".
.ip "-S"
Treat lower-case characters in the query or library sequences as
"low-complexity" ("seg"-ed) residues.  Traditionally, the "seg"
program [.woo935.] is used to remove low complexity regions in DNA
sequences by replacing the residues with an "X".  When the "-S" option
is used, the FASTA33 (and later) programs provide a potentially more
informative approach.  With "-S", lower case characters in the query
or database sequences are treated as "X"'s during the initial scan,
but are treated as normal residues during the final alignment display.
Since statistical significance is calculated from the similarity score
calculated during the library search, when the lower case residues are
"X"'s, low complexity regions will not produce statistically
significant matches.  However, if a significant alignment contains low
complexity regions, their alignmen is shown.  With "-S", lower case
characters may be included in the alignment to indicate low complexity
regions, and the final alignment score may be higher than the score
obtained during the search.
.ip
The \fCpseg\fP program can be used to produce databases (or query
sequences) with lower case residues indicating low complexity regions
using the command:
.(l I
\fCpseg database.fasta -z 1 -q  > database.lc_seg\fP
.)l
(\fCseg\fP can also be used with some post processing, see readme.v33tx.)
.ip
The \fC-S\fP option should always be used with \fCFASTX/Y\fCP and
\fCTFASTX/Y\fP because out of frame translations often generate
low-complexity protein sequences.  However, only lower case characters
in the protein sequence (or protein database) are masked; lower case
DNA sequences are translated into upper case protein sequences, and
not treated as low complexity by the translated alignment programs.
.ip "-t #"
Translation table - fastx35, tfastx35, fasty35, and
tfasty3 now support the BLAST tranlation tables.  See
\fChttp://www.ncbi.nlm.nih.gov/Taxonomy/Utils/wprintgc.cgi\fP.
.ip
In addition, "\-t t" or "\-t t#" turns on the addition of an implicit termination
codon to a protein:translated DNA match.  That is, each protein
sequence implicitly ends with "*", which matches the termination codes
for the appropriate genetic code.  "\-t t#" sets implicit termination
and a different genetic code.
.ip "-U"
Treat the query sequence an RNA sequence.  In addition to selecting a
DNA/RNA alphabet, this option causes changes to the scoring matrix so
that 'G:A' , 'T:C' or 'U:C' are scored as 'G:G'.
.ip "-V str"
It is now possible to specify some annotation characters that can be
included (and will be ignored), in the query sequence file.  Thus, One
might have a file with: \fC"ACVS*ITRLFT?"\fP, where "*" and "?"  are
used to indicate phosphorylation.  By giving the option \fC\-V '*?'\fP,
those characters in the query will be moved to an "annotation string",
and alignments that include the annotated residues will be highlighted
with the appropriate character above the sequence (on the number line).
.ip "-w #"
Line length (width) = number (<200)
.ip "-W #"
 context length (default is 1/2 of line width -w) for alignment,
like fasta and ssearch, that provide additional sequence context.
.ip "-x #match,#mismatch"
Specify the penalty for a match to an 'X', and mismatch to 'X',
independently of the PAM matrix.  Particularly useful for
\fCfastx3/fasty35\fP, where termination codons are encoded as 'X'.
.ip "-X \"off1 off2\""
Specifies offsets for the beginning of the query and library sequence.
For example, if you are comparing upstream regions for two genes, and
the first sequence contains 500 nt of upstream sequence while the
second contains 300 nt of upstream sequence, you might try:
.(l I
\fCfasta -X "-500 -300" seq1.nt seq2.nt\fP
.)l
If the -X option is not used, FASTA assumes numbering starts with 1.
(You should double check to be certain the negative numbering works
properly.)
.ip "-y"
Set the width of the band used for calculating "optimized" scores.
For proteins and ktup=2, the width is 16.  For proteins with ktup=1,
the width is 32 by default.  For DNA the width is 16.
.ip "-z -1,0,1,2,3,4,5"
\fC\-z -1\fP turns off statistical calculations. \fCz 0\fP estimates
the significance of the match from the mean and standard deviation of
the library scores, without correcting for library sequence length.
\fC\-z 1\fP (the default) uses a weighted regression of average score
vs library sequence length; \fC\-z 2\fP uses maximum likelihood
estimates of
.if t \(*l
.if n Lambda
and \fIK\fP; \fC\-z 3\fP uses Altschul-Gish
parameters;[.alt960.] \fC\-z 4 \- 5\fP uses two variations on the
\fC\-z 1\fP strategy. \fC\-z 1\fP and \fC\-z 2\fP are the best methods,
in general.
.ip "-z 11,12,14,15" 
estimate the statistical parameters from shuffled copies of each
library sequence.  This doubles the time required for a search, but
allows accurate statistics to be estimated for libraries comprised of
a single protein family.
.ip "-Z db_size"
set the apparent size of the database to be used when calculating
expectation E() values.  If you searched a database with 1,000
sequences, but would like to have the E()-values calculated in the
context of a 100,000 sequence database, use '-Z 100000'.
.ip "-1"
sort output by init1 score (for compatibility with FASTP - do not
use).
.ip "-3"
translate only three forward frames
.sp
.lp
For example:
.(l
\fCfasta -w 80 -a seq1.aa seq.aa\fP
.)l
would compare the sequence in seq1.aa to that in seq2.aa and display the
results with 80 residues on an output line, showing all of the residues
in both sequences.  Be sure to enter the options before entering the file
names, or just enter the options on the command line, and the program will
prompt for the file names.
.sp
.pp
(November, 1997) In addition, it is now possible to provide the fasta
programs with the query sequence (fasta, fasty, ssearch, tfastx), or
two sequences (prss, lalign, plalign) from the unix "stdin" stream.  This
makes it much easier to set up FASTA or PRSS WWW pages.  To specify
that stdin be used, rather than a file, the file name should be
specified as '-' or '@' (the latter file name makes it possible to
specify a subset of the sequence).
Thus:
.(l
cat query.aa | fasta -q @:25-75 s
.)l
would take residues 25-75 from query.aa and search the 's' library
(see the discussion of FASTLIBS).
.sh 2 "Environment variables"
.pp
Because the current version of the program allows the user to set
virtually every option on the command line (except the \fIktup\fP,
which must be set as the third command line argument), only the
\fCFASTLIBS\fP environment variable is routinely used.
.ip "FASTLIBS"
specifies the location of the file which contains the list of library
descriptions, locations, and library types (see section on finding
library files).
.sh 1 "Frequently Asked Questions (FAQs)"
.np
\fIWhich program should I use?\fP See Table I.
.np
\fIHow do I search with both DNA strands with\fP \fCfasta3\fP \fIand\fP
\fCfastx3\fP? With version 32 of the FASTA program package, all
searches that use DNA queries (e.g. \fCfasta3\fP, \fCfastx3/y3\fP)
examine both strands. To revert to earlier FASTA behavior - only
looking at the forward or reverse strand - use \fC\-3\fP to search only
the forward strand and \fC\-i -3\fP to search only the reverse strand.
.np
\fIWhen I search Genbank - the program reports:\fP \fC0 residues in 0
sequences\fP.  This typically happens because the program does not
know that you are searching a Genbank flatfile database and is looking
for a FASTA format database.  Be certain to specify the library type
("1" for Genbank flatfile) with the database name.
.np
What is the difference between \fCfastx3\fP and \fCfasty3\fP (or
\fCtfastx3\fP and \fCtfasty3\fP).  \fC[t]fastx3\fP uses a simpler
codon based model for alignments that does not allow frameshifts in
some codon positions (see ref. [.wrp971.]).  \fCtfastx3\fP is about
30% faster, but \fCtfasty3\fP can produce higher quality alignments in
some cases.
.np
\fIWhen I run\fP \fCfasta3 -q\fP, I don't see any (or very little)
output, but I get lots of scores when I run interactively. With the
\fC\-Q\fP option, the number of high scores displayed is limited by the
\fC\-E #\fP cutoff, which is 10.0 for protein comparisons, 2.0 for DNA
comparisons, and 5.0 for translated DNA:protein comparisons.  In
interactive mode (without \fC\-Q\fP), by default you see 20 high
scores, regardless of \fCE()\fP value.
.np
\fIWhat is ktup\fP \- All of the programs with \fCfast\fP in their
name use a computer science method called a lookup table to speed the
search.  For proteins with \fIktup\fP=2, this means that the program
does not look at any sequence alignment that does not involve matching
two identical residues in both sequences.  Likewise with DNA and
\fIktup\fP = 6, the initial alignment of the sequences looks for 6
identical adjacent nucleotides in both sequences.  Because it is less
likely that two identical amino-acids will line up by chance in two
unrelated proteins, this speeds up the comparison.  But very distantly
related sequences may never have two identical residues in a row but
will have single aligned identities.  In this case, \fIktup\fP = 1 may
find alignments that \fIktup\fP=2 misses.
.np
\fISometimes, in the list of best scores, the same sequence is shown
twice with exactly the same score.  Sometimes, the sequence is there
twice, but the scores are slightly different.\fP When any of the
\fCfasta3\fP programs searches a long sequence, it breaks the sequence
up into \fIoverlapping\fP pieces.  The length of the piece depends on
the length of the query and the particular program being used (it can
also be controlled with the -N #### option).  Since the pieces overlap
by the length of the query sequence (or 3*query_length for fastx/y35
and tfastx35/y35), if the highest scoring alignment is at the end of
one piece, it will be scored again at the beginning of the next piece.
If the alignment is not be completely included in the overlap region,
one of the pieces will give a higher score than the other.  These
duplications can be detected by looking at the coordinates of the
alignment.  If either the beginning or end coordinate is identical in
two alignments, the alignments are at least partially duplicates.
.sh 1 "Installing FASTA and the sequence databases"
.sh 2 "Obtaining the libraries"
.pp
The FASTA program package does not include any protein or DNA sequence
libraries.  Protein and DNA sequence databases are available 
via anonymous FTP from the NCBI (\fCftp.ncbi.nih.gov\fP) and EBI (\fCftp.ebi.ac.uk\fP).
.sh 3 "The GENBANK DNA sequence library"
.pp
Because of the large size of DNA databases, you will probably want to
keep DNA databases in only one, or possibly two, formats.  The FASTA3
programs that search DNA databases - \fCfasta35\fP, \fCfastm35\fP, and  \fCtfastx/y35\fP can read DNA databases in Genbank flatfile (not
ASN.1), FASTA, GCG/compressed-binary, BLAST1.4 (\fCpressdb\fP), and
BLAST2.0 (\fCformatdb\fP) formats, as well as EMBL format.  If you are
also running the GCG suite of sequence analysis programs, you should
use GCG/compressed-binary format or BLAST2.0 format for your
\fCfasta35\fP searches.  If not, BLAST2.0 is a good choice.  These
files are considerably more compact than Genbank flat files, and are
preferred.  The NCBI does not provide software for converting from
Genbank flat files to Blast2.0 DNA databases, but you can use the
Blast \fCformatdb\fP program to convert ASN.1 formated Genbank files,
which are available from the NCBI \fCftp\fP site.
.pp
The NCBI also provides the \fCnr\fP, \fCswissprot\fP, and several EST
databases that are used by BLAST in FASTA format from:
\fCftp://ncbi.nlm.nih.gov/blast/db\fP.  These databases are updated
frequently.
.sh 3 "The NBRF protein sequence library"
.pp
You can obtain the PIR protein sequence database
[.pir980.] from:
.(l
National  Biomedical Research Foundation
Georgetown  University  Medical  Center
3900 Reservoir Rd, N.W.
Washington, D.C. 20007
.)l
or via ftp from \fCnbrf.georgetown.edu\fP or from the NCBI
(\fCncbi.nlm.nih.gov/repository/PIR\fP). The data in the \fCascii\fP
directory is in PIR Codata format, which is not widely used.  I
recommend the PIR/VMS format data (libtype=5) in the \fCvms\fP
directory.
.sh 3 "The EBI/EMBL CD-ROM libraries"
.pp
The European Bioinformatics Institute (EBI) distributes both the EMBL
DNA database and the SwissProt database on CD-ROM,[.apw961.] and they
are available from:
.(l
EMBL-Outstation  European Bioinformatics Institute
Wellcome Trust Genome Campus,
Hinxton Hall
Hinxton,
Cambridge CB10 1SD
United Kingdom
Tel: +44 (0)1223 494444
Fax: +44 (0)1223 494468
Email: DATALIB@ebi.ac.uk
.)l
In addition, the SWISS-PROT protein sequence database is available via
anonymous FTP from \fCftp://ftp.expasy.ch/databases/swiss-prot/\fP
(also see \fCwww.expasy.ch\fP).
.sh 2 "Finding the libraries: FASTLIBS"
.pp
The major problem that most new users of the FASTA package have is in
setting up the program to find the databases and their library type.
In general, if you cannot get \fCfasta35\fP to read a sequence
database, it is likely that something is wrong with the \fCFASTLIBS\fP
file.  A common problem is that the database file is found, but either
no sequences are read, or an incorrect number of entries is read.
This is almost always because the library format (\fClibtype\fP) is
incorrect.  Note that a type 5 file (PIR/VMS format) can be read
as a type 0 (default FASTA) format file, and the number of entries
will be correct, but the sequence lengths will not.
.pp
All the search programs in the FASTA3 package use the environment
variable \fCFASTLIBS\fP to find the protein and DNA sequence libraries.  The
\fCFASTLIBS\fP variable contains the name of a file that has the actual
filenames of the libraries.  The \fCfastlibs\fP file included with the
distribution on is an example of a file that can be referred to by
FASTLIBS. To use the \fCfastlibs\fP file, type:
.(l
\fCsetenv FASTLIBS /usr/lib/fasta/fastgbs\fP (BSD UNIX/csh)
or
\fCexport FASTLIBS=/usr/lib/fasta/fastgbs\fP (SysV UNIX/ksh)
.)l
Then edit the \fCfastlibs\fP file to indicate where the protein and DNA
sequence libraries can be found.  If you have a hard disk and your
protein sequence library is kept in the file \fC/usr/lib/aabank.lib\fP and
your Genbank DNA sequence library is kept in the directory:
\fC/usr/lib/genbank\fP, then \fCfastgbs\fP might contain:
.ne 8
.(l
.ft C
NBRF Protein$0P/usr/lib/seq/aabank.lib 0
SWISS PROT 10$0S/usr/lib/vmspir/swiss.seq 5
GB Primate$1P@/usr/lib/genbank/gpri.nam
GB Rodent$1R@/usr/lib/genbank/grod.nam 
GB Mammal$1M@/usr/lib/genbank/gmammal.nam
^   1    ^^^^       4                   ^     ^
          23                             (5)
.ft R
.)l
The first line of this file says that there is a copy of the NBRF
protein sequence database (which is a protein database) that can be
selected by typing "P" on the command line or when the database menu
is presented in the file \fC/usr/lib/seq/aabank.lib\fP.
.pp
Note that there are 4 or 5 fields in the lines in \fCfastgbs\fP.  The first
field is the description of the library which will be displayed by
FASTA; it ends with a '$'.  The second field (1 character), is a 0 if
the library is a protein library and 1 if it is a DNA library.  The
third field (1 character) is the character to be typed to select the
library.
.pp
The fourth field is the name of the library file.  In the example
above, the \fC/usr/lib/seq/aabank.lib\fP file contains the entire
protein sequence library.  However the DNA library file names are
preceded by a '@', because these files (\fCgpri.nam, grod.nam,
gmammal.nam\fP) do not contain the sequences; instead they contain the names
of the files which contain the sequences.  This is done because the
GENBANK DNA database is broken down in to a large number of smaller
files.  In order to search the entire primate database, you must
search more than a dozen files.
.pp
In addition, an optional fifth field can be used to specify the format
of the library file.  Alternatively, you can specify the library
format in a file of file names (a file preceded by an '@').  This
field must be separated from the file name by a space character ('\ ')
from the filename.  In the example above, the \fCaabank.lib\fP file is
in Pearson/FASTA format, while the \fCswiss.seq\fP file is in PIR/VMS format
(from the EMBL CD-ROM). Currently, FASTA can read the following formats:
.(l I
.ft C
0 Pearson/FASTA (>SEQID - comment/sequence)
1 Uncompressed Genbank (LOCUS/DEFINITION/ORIGIN)
2 NBRF CODATA (ENTRY/SEQUENCE)
3 EMBL/SWISS-PROT (ID/DE/SQ)
4 Intelligenetics (;comment/SEQID/sequence)
5 NBRF/PIR VMS (>P1;SEQID/comment/sequence)
6 GCG (version 8.0) Unix Protein and DNA (compressed)
11 NCBI Blast1.3.2 format  (unix only)
12 NCBI Blast2.0 format  (unix only, fasta32t08 or later)
.ft R
.)l
In particular, this version will work with the EMBL and PIR VMS
formats that are distributed on the EMBL CD-ROM. The latter format
(PIR VMS) is much faster to search than EMBL format.  This release
also works with the protein and DNA database formats created for the
BLASTP and BLASTN programs by SETDB and PRESSDB and with the new NCBI
search format.  If a library format is not specified, for example,
because you are just comparing two sequences, Pearson/FASTA (format 0)
is used by default. To specify a library type on the command line,
add it to the library filename and surround the filename and library
type in quotes:
.(l
.ft C
fasta3 query.file "/seqdb/genbank/gbpri1.seq 1"
.ft P
.)l
.pp
You can specify a group of library files by putting a '@' symbol
before a file that contains a list of file names to be searched.  For
example, if @gmam.nam is in the fastgbs file, the file "gmam.nam"
might contain the lines:
.(l
.ft C
</seqdb/genbank
gbpri1.seq 1
gbpri2.seq 1
gbpri3.seq 1
gbpri4.seq 1
gbrod.seq 1
gbmam.seq 1
.ft R
.)l
In this case, the line beginning with a '<' indicates the directory
the files will be found in.  The remaining lines name the actual
sequence files.  So the first sequence file to be searched would be:
.(l
.ft C
/usr/lib/genbank/gbpri.seq
.ft R
.)l
The notation "\fC<PIRNAQ:\fP" might be used under the VAX/VMS operating
system. Under UNIX, the trailing '/' is left off, so the library
directory might be written as "\fC</usr/seqlib\fP".
.pp
The FASTA programs can search a database composed of different files
in different sequence formats.  For example, you may wish to search
the Genbank files (in GenBank flat file format) and the EMBL DNA
sequence database on CD-ROM.  To do this, you simply list the names
and filetypes of the files to be searched in a file of filenames.  For
example, to search the mammalian portion of Genbank, the unannotated
portion of Genbank, and the unannotated portion of the EMBL library,
you could use the file:
.(l I
.ft C
</usr/lib/DNA
gbpri.seq 1
\&#  (this '#' causes the program to display the size of the library)
gbrod.seq 1
\&...
gbmam.seq 1
\&...
gbuna.seq 1
\&...
unanno.seq 5
\&#
.ft R
.)l
.(l I F
You do not need to include library format numbers if you only use the
Pearson/FASTA version of the PIR protein sequence library.  If no
library type is specified, the program assumes that type 0 is being
used.
.)l 
.pp
Test the setup by running FASTA.  Enter the sequence
file '\fCmgstm1.aa\fP' when the program requests it (this file is
included with the programs).  The program should then ask you to
select a protein sequence library.  Alternatively, if you run the
TFASTX35 program and use the mgstm1.aa query sequence, the program
should show you a selection of DNA sequence libraries.
Once the fastgbs file has been set up correctly, you can
set FASTLIBS=fastgbs in your AUTOEXEC.BAT file, and you will not need to
remember where the libraries are kept or how they are named.
.ne 8
.lp
As always, please inform me of bugs as soon as possible.
.sp
.nf
William R. Pearson
Department of Biochemistry
Jordan Hall Box 800733
U. of Virginia
Charlottesville, VA

wrp@virginia.EDU

.sh 1 "References"
.[
$LIST$
.]

