The BLAST Databases
                    Last updated on October 2, 2008

This document describes the "BLAST" databases available on the NCBI 
FTP site under the /blast/db directory.  The direct URL is:
      ftp://ftp.ncbi.nih.gov/blast/db

1. General Introduction

NCBI BLAST home pages (http://www.ncbi.nih.gov/BLAST/) use a standard 
set of BLAST databases for Nucleotide, Protein, and Translated BLAST 
searches.  These databases are made available in the /blast/db directory as 
compressed archives (ftp://ftp.ncbi.nih.gov/blast/db/) in pre-formatted 
format. The FASTA databases reside under the /blast/db/FASTA directory.

The pre-formatted databases offer the following advantages:

    * The pre-formatted databases are smaller in size and therefore are
      faster to download;
    * Sequences in FASTA format can be generated from the pre-formatted
      databases by the fastacmd utility;
    * A convenient script (update_blastdb.pl) is available to download 
      the pre-formatted databases from the NCBI ftp site;
    * Pre-formatting removes the need to run formatdb;
    * Taxonomy ids are available for each database entry.

Pre-formatted databases must be downloaded using the update_blastdb.pl 
script or via FTP in binary mode. Documentation for the update_blastdb.pl
script can be obtained by running the script without any arguments (perl is
required).

The compressed files downloaded must be inflated with gzip or other decompress 
tools. The BLAST database files can then be extracted out of the resulting 
tar file using tar program on Unix/Linux or WinZip and StuffIt Expander 
on Windows and Macintosh platforms, respectively.  

Large databases are formatted in multiple 1 Gigabytes volumes, which 
are named using the database.##.tar.gz convention. All relevant volumes
are required. An alias file is provided so that the database can be called
using the alias name without the extension (.nal or .pal). For example, 
to call est database, simply use "-d est" option in the commandline 
(without the quotes). 

Certain databases are subsets of a larger parental database. For those 
databases, alias and mask files, rather than actual databases, are provided. 
The mask file needs the parent database to function properly. The parent 
databases should be generated on the same day as the mask file. For 
example, to use swissprot pre-formatted database, swissprot.tar.gz, one 
will need to get the nr.tar.gz with the same date stamp.

Additional BLAST databases that are not provided in pre-formatted 
formats are available in the FASTA subdirectory.  For genomic BLAST 
databases, please check the genomes ftp directory at:
    ftp://ftp.ncbi.nih.gov/genomes/


2. Contents of the /blast/db/ directory

The pre-formatted BLAST databases are archived in this directory. The 
name of these databases and their contents are listed below.
+----------------------+-----------------------------------------------+
|File Name             | Content Description                           |
+----------------------+-----------------------------------------------+
/FASTA                 | subdirectory for FASTA formatted sequences
    
README                 | README for this subdirectory (this file)

env_nr.*tar.gz         | Environmental protein sequences
env_nt.*tar.gz         | Environmental nucleotide sequences

est.*tar.gz            | volumes of the formatted est database
                       | from the EST division of GenBank, EMBL, 
                       | and DDBJ

est_human.tar.gz       | alias and mask files for human subset of the est
est_mouse.tar.gz       | alias and mask files for mouse subset of the est
est_others.tar.gz      | alias and mask files for non-human and non-mouse
                       | subset of the est database
                       | These alias and mask files need all volumes of
                       | est to function properly.

gss.*tar.gz            | volumes of the formatted gss database
                       | from the GSS division of GenBank, EMBL, and
                       | DDBJ

htgs.*tar.gz           | volumes of htgs database with entries0tifiers) in a 
        file.  One can obtain a list of gi's for a given Entrez query from
        http://www.ncbi.nlm.nih.gov/Entrez/batch.html.  This file should
        be in the same directory as the database, or in the directory that
        BLAST is called from.

  -U  Use lower case filtering of FASTA sequence [T/F]  Optional
    default = F

        This option specifies that any lower-case letters in the input FASTA file
        should be masked.  

Enhancements:

A new option has been added to search multiple queries at once for the
blastn and tblastn program options of blastall.

  -B Number of concatenated queries, for blastn and tblastn [Integer]
     Optional
     default = 0

This new feature similar in principle, but different in implementation
from the support for multiple queries already existing in megablast.
The combination of ungapped search (-g F)  and multiple queries
(-B N) is not supported. The argument to -B option must be equal
to the number of sequences in the FASTA input file.

Processing multiple query sequences in one run can be much faster than
processing them with separate runs because the database is scanned only 1
time for the entire set of queries. When the -B option is used, the
results may differ from the ones produced with individual queries. Usually
results  will be at least as good or better (in terms of score/evalue)
than the results of corresponding  individual queries; exceptions  occur
due to the heuristic nature of BLAST. Additional alignments may appear.
It is  guaranteed that matching sequences will
appear in the same order when they are tied in evalue
and are part of the output both with and without -B.
When the -B option is used, the summary statistics at the bottom
of the output are for the combined set of queries; at present,
the summary statistics are not tabulated for the individual
queries in a multiple-query input.
./usr/share/doc/blast2/blastclust.html0000644000000000000000000002022210303110051016604 0ustar rootroot
BLASTCLUST - BLAST score-based single-linkage clustering.

1. Clustering procedure.

BLASTCLUST automatically and systematically clusters protein or DNA sequences
based on pairwise matches found using the BLAST algorithm in case of proteins or 
Mega BLAST algorithm for DNA. In the latter case a single Mega BLAST search is
performed for all the sequences combined against a database created from the
same sequences. BLASTCLUST finds pairs of sequences that have statistically
significant matches and clusters them using single-linkage clustering. 

BLASTCLUST uses the default values for the BLAST and Mega BLAST parameters.
For protein sequences these are: matrix BLOSUM62; gap opening cost 11; gap
extension cost 1; no low-complexity filtering.
For DNA sequences: match reward 1, mismatch penalty -3, non-affine gapping costs 
(see README.mbl document for explanation), wordsize 28.
In both cases e-value threshold is set to 1e-6. 
For each pair of sequences the top-scoring alignment is evaluated according to
the following criteria: 

       x1                   x2      HSP length on seqX: Hx = x2-x1+1 
        |                    |      gaps in seqX: Gx
seqX ---======================----- seqX length: Lx
         \\|||||||||||||||||//      BLAST score: S 
seqY ----====================------ number of identical residues: N
         |                  |       seqY length: Ly
        y1                 y2       gaps in seqY: Gy
                                    HSP length on seqY: Hy = y2-y1+1 

coverage of seqX: Cx = Hx/Lx
coverage of seqY: Cy = Hy/Ly
coverage:         max(Cx,Cy) or min(Cx,Cy), depending on the value of -b option 
alignment length  Al = Hx+Gx = Hy+Gy
score density:    S/min(Hx,Hy) or N/Al*100%

If the coverage is above a certain threshold
 AND
the score density is above a certain threshold,

these two sequences are considered to be neighbored.

Thus determined neighbor relationships is considered symmetric and provides
the base for clustering by a single-linkage method (which puts a sequence
to a cluster if the sequence is a neighbor to at least one sequence in the
cluster).

2. Input formats.

The primary input format for BLASTCLUST is a FASTA-format sequence file.
Each sequence should have a unique identifier (as defined by formatdb).
BLASTCLUST formats this sequence set into a BLASTable database
(in the directory pointed to by the environment variable TMPDIR or in
the current directory), then removes the database.

Instead of a FASTA file, a database prepared by formatdb with -o option
set to TRUE can be supplied as an input.

Another type of input is a sequence hit-list previously saved by
BLASTCLUST (in this case BLASTCLUST will use pre-computed HSP data
instead of making de novo comparisons).

You can restrict clustering to a subset of your data by supplying an ID
list file (IDs separated by spaces, tabs, newlines, commas or semicolons).
This is supposed to be used for re-clustering subsets of sequences using
the previously computed hit-list file.

3. Output format.

BLASTCLUST prints out clusters of sequence IDs, sorted from largest to
smallest cluster (alphabetically by ID of the first sequence if of the
same size), separating clusters by a newline character. Sequence
identifiers within a cluster are space-separated and sorted from
longest to shortest sequence (alphabetically by IDs if of the same length).

4. Crash recovery.

If the program crashed because of system error you can restart it
using crash recovery mode. This works only if you were saving
hit-list during the clustering. Start the job with the same command
line as before, specifying the hit-list saving to the same file but
also set the "continue unfinished clustering" option to TRUE. The
process will restart from the last saved point and will append the
hit-list file.

5. Environment.

BLASTCLUST is supposed to work in a normal NCBI environment, in
particular:

BLOSUM62 matrix is available via .ncbirc or BLASTMAT environment
variable.

6. Program options

Input:

 -i <file> sequence file in the FASTA format (default = stdin)
 -d <file> sequence database name
 -r <file> name of a hit-list file saved by BLASTCLUST

 These three options are mutually exclusive.

 -l <file> a file with a list of IDs to restrict the clustering,
    applicable only when reclustering from a saved hit-list.
 
Thresholds:

 -S <threshold> similarity threshold
    if <3 then the threshold is set as a BLAST score density
    (0.0 to 3.0; default = 1.75)
    if >=3 then the threshold is set as a percent of identical
    residues (3 to 100)
 -L <threshold> minimum length coverage (0.0 to 1.0; default = 0.9)
 -b <T|F> require coverage as specified by -L and -S on both (T) or
    only one (F) sequence of a pair (default = TRUE)

Output:

 -o <file> file to save cluster list (default = stdout)
 -s <file> file to save hit-list (this file may be not portable across
    platforms)
 -p <T|F> protein (T) or nucleotide (F) sequences in the input
    (default = TRUE)

Misc:

 -C <T|F> continue unfinished clustering (crash recovery mode).
    (default = FALSE)
 -a <number> Number of CPU's to use in a multi-thread mode
    (default = 1).
 -v <logfile> Progress report destination (printed every 1000 sequences).
    Set to F to suppress report messages (default = stderr).
 -e <T|F> Enable sequence id parsing in database formatting. Set to F if 
    multiple sequences have identical ids (default = TRUE).
 -W Word size to use for initial matches (default = 0, translates to 3 for
    proteins and 32 for nucleotides). 
 -c <config file> Configuration file with advanced options, containing any 
    of the following options with their values, separated by whitespace:
    -r, -q, -G, -E - match, mismatch, gap open and gap extension scores 
respectively, 
    -e - e-value cut off,
    -y, -X - the dropoff values for the ungapped and gapped extension respectively, 
    -A - window size for two-hit version,
    -I - hitlist size,
    -Y, -z - effective search space and database length respectively, to be used for 
e-value and bit score calculations,
    -F - filter string,
    -s - raw score cut off for nucleotide search,
    -S - strand option.

7. Credits:

Ilya Dondoshansky (dondosha@ncbi.nlm.nih.gov)
Yuri Wolf (wolf@ncbi.nlm.nih.gov)

05 August, 2000

8. Questions, requests and/or bug reports:

blast-help@ncbi.nlm.nih.gov

APPENDIX A.
Format of the hit-list file.

The hit-list file consists of the following parts:

 - header
 - sequence ID list
 - sequence length list
 - hit list

The byte-by-byte layout is platform-dependent; field sizes given here
are true for most UNIX platforms.

A.1. Header.

        4-byte integer  IDtype  1 if numeric IDs; 0 if string IDs
        4-byte integer  ListSz  size of the ID list; if IDs are numeric this
                                is the number of SeqID records, otherwise this
                                is the length of the ID list (in bytes)

A.2. Sequence ID list.

If IDtype is 1 (numeric IDs) then the list is ListSz records of

        4-byte integer  SeqID   sequence ID (numeric)

If IDtype is 0 (string IDs) then the list is a list of records of

        var-length char SeqID   sequence ID (string)
        space (' ')             separator

(total length is ListSz bytes; the number of sequences is equal to the number
of spaces).

A.3. Sequence length list.

This is a list of

        4-byte integer  SeqLen  sequence length

A.4. Hit list.

The list consists of the following records going to the end of file:

        4-byte integer  N1      ordinal number of the 1st sequence
        4-byte integer  N2      ordinal number of the 2nd sequence
        4-byte integer  HSPL1   HSP length on the 1st sequence
        4-byte integer  HSPL2   HSP length on the 2nd sequence
        8-byte float    Score   BLAST score
        8-byte float    PercId  Percent of identical residues
./usr/share/doc/blast2/blastdb.html0000644000000000000000000003756311071170077016100 0ustar rootroot