Program Option for Netblast (blastcl3)
Tao Tao, Ph.D.
User Service
1. Introduction
NCBI BLAST web server provides a convenient and user friendly way for individuals to search their queries against different public sequence databases. This server, however, does have some limitation. For example, one will not be able to perform large scale batch searches from most of the BLAST pages and the program selection for some of the available databases is limited. BLAST client provides a way to circumvent those limitations.

The client bypasses web browser and interacts directly with the NCBI BLAST server that powers the NCBI web BLAST service ( It performs the batch search with multiple sequences by taking one query sequence from the input file (with multiple FASTA formatted sequences), formulating the search according to the command line, and sending the search through the internet connection to NCBI BLAST server for processing. The program receives the search result from blast server and saves it to a local file specified by the command line. The program loops through all the queries in the input file till all are searched.

This program has no graphic user interface (GUI) and must be executed from command line under a terminal window. Users control the program through command line options. Detailed list of command line options are in Section 4. For usages and situation examples, see Section 5.

2. Installation and setup
NCBI provides BLAST client as an archive separate from that of the standalone (blast initialed) or server blast (wwwblast initialed) package. This archive is available for common platforms as netblast initialed files. They can be found at:
For Linux or Unix environment, installation is straight forward. One can place the archive in a desired directory and extract the archive using the following command line:
tar zxvf netblast-##-**.tar.gz
The resulted netblast-## directory contains bin, doc, and data subdirectories. The program, blastcl3, is under the bin subdirectory. The matrices BLAST needs for protein alignments are under the data subdirectory, while the doc subdirectory contains netblast.html (this file) and netblast_firewall.html with more information on configuration under firewall settings.

The package for Windows can be extracted using WinZip. It does not have this directory structure.

3. Firewall settings
The setup for NCBI network clients has been greatly simplified. If you are not behind a firewall no further action is required. If you are behind a firewall, and already use Sequin or Entrez, or if your system administrator has already performed the setup, then you should be able to start performing searches immediately after installation. Otherwise, your will need to make sure that the following IP address/port combinations are open in the firewall configuration.

Table 3. Firewall Ports Needed by BLAST Client for NCBI Connection
IP AddressPort Number 5861 5862 5863
Note Please refer to 'netblast_firewall.html' included in the package for details.

In addition to this, you also need to create an .ncbirc file placed in the home directory to instruct blastcl3 how to make the connection to NCBI. For PC running Windows, the file is named ncbi.ini which should be placed under the windows directory. A sample .ncbirc file is provided in the text box below for your reference.



As an alternative to blastcl3, NCBI BLAST web server also supports URL API, which uses URL encoded command to interact with Blast.cgi directly to "Put" search requests or to "Get" search results. For details on the standard commands, please refer to the online document at:
4. Options and their accepted values
As mentioned before in Section 1, blastcl3 has no GUI and works only under a command terminal. Users execute the the program by issuing command lines, and controls the way blast search is done through options in the command line. The command line options for this program are listed here individually below. The options commonly adjusted during actual searches are: -i, - d, -p, -o, -e, -F, -u, -b, -v, -m, and -n. The first four are mandatory.

Table 4.1
FunctionSpecifies which program to run
DefaultNone, mandatory
Input FormatString
ExampleTo run blastn program use: -p blastn
NoteProgram string options and type of search they specify
blastxnucleotide, translatedProtein
tblastnproteinnucleotide, translated
tblastxnucleotide, translatednucleotide, translated

Table 4.2
FunctionSpecifies database(s) to be searched
Input FormatString
ExampleOne can search against multiple databases can be specified in command line. To search nr and est at together use: -d "nr est"
NoteBe conservative. Search against large databases may not complete due to CPU time limit, which is set at one hour.

Table 4.3
FunctionSpecifies input query file
Input FormatString, mandatory
ExampleTo use sequences from query.txt as query, use -i query.txt
NoteOne should use the complete file name WITH its extension. To use stdin default, omit the -i and redirect using: < mito.txt

Table 4.4
FunctionSpecifies Expect value cutoff
Input FormatReal
ExampleTo make the search more stringent, one can use: -e 0.001
NoteAccepted formats are integer, fraction, decimal, exponential and scientific notation. To set the cutoff to 2×10-20, use -e 2e-20

Table 4.5
FunctionSpecifies alignment view option
Input FormatInteger
ExampleTo display the result in XML form use: -m 7
NoteOption values and the output formats they specify
1query-anchored showing identities
2query-anchored no identities
3flat query-anchored, show identities
4flat query-anchored, no identities
5query-anchored no identities and blunt ends
6flat query-anchored, no identities and blunt ends
7XML Blast output
8tabular (not post processing)
9tabular with comment lines (post-processed, sorted)
10ASN, text
11ASN, binary

Table 4.6
FunctionSpecifies result output file
Defaultstdout (print to screen)
Input FormatString [file name]
ExampleTo save result in out.txt use: -o out.txt
Note-p, -i, -d, -o are the core options needed for a blastcl3 search.

Table 4.7
FunctionSpecifies which filter(s) to use to mask query sequence
DefaultT (DUST for nucleotide, SEG for protein)
Input FormatString
ExampleTo filter low complexity and lookup table only, use: -F "m L"
NoteAccepted strings: T, F, D, L, R, V, S, C, and m.
m in -F stands for masking for lookup table only, which enables blast to
display the masked region in the alignment. L stands for Low complexity,
D stands for DUST. R stands for human Repeats, V stands for Vector.

S stands for SEG, which has other user specifiable values:
-F "S 10 1.0 1.5" SEG filter: window=10; low cut=1; high cut=1.5.
C stands for COIL, which also has user specifiable values:
-F "C 28 40 32" COIL filter: window=22; cutoff=40; linker=32.

To run SEG and COIL filter together, use: -F "S; C"
To mask lookup table only, add m: -F m "S; C"

To mask repeat sequences use: -F R or -F "m R"
To combine all together, use: -F "m L;R"
To mask vector filter, use: -F V
To call rodent repeat filter, use: -F "R -d rodent.lib"

Table 4.8
FunctionCost to open a gap
Input Format[Integer]
ExampleTo increase the gap open penalty to 10, use: -G 10
NoteZero invokes default (5) for blastn. It varies for blastp, blastx, tblastn, and tblastx. In protein searches, only a controlled set of -G/-E value pairs are acceptable for a given scoring matrix.

Table 4.9
FunctionCost to extend a gap
Input Format[Integer]
ExampleTo increase the gap extension penalty to 4, use: -E 4
NoteZero invokes default or 2 for blastn. Varies for blastp, blastx, tblastn, and tblastx. In protein searches, only a controlled set of -G/-E value pairs are acceptable for a given scoring matrix.

Table 4.10
FunctionX dropoff value for gapped alignment (in bits)
Input Format[Integer]
ExampleTo increase the gapped alignment dropoff to 40, use: -X 40
NoteGapped Alignment Dropoff Default Setting (in bits)

Table 4.11
Option-I (capital i)
FunctionShow GI in definition line
Input Format[T/F]
ExampleTo activate the GI display use: -I T
NoteSample display:
T: gi|223046|prf||0410468A...
F: prf||0410468A...

Table 4.12
FunctionPenalty for a nucleotide mismatch
Input Format[Integer]
ExampleTo set penalty to -2, use: -q -2
NoteFor blastn only, different -r/-q ratios are optimal for aligning sequences with different percentage of similarities.

Table 4.13
FunctionReward for a nucleotide match
Input Format[Integer]
ExampleTo increase the reward to 2, use: -r 2
NoteFor blastn only. Others use external scoring matrix to determine this. See -M table in blastall for more details.

Table 4.14
FunctionNumber of database sequences to show one-line descriptions for
Input Format[Integer]
ExampleTo increase the descriptions displayed to 1000 use: -v 1000
NoteWeb counterpart is "Descriptions"

Table 4.15
FunctionNumber of sequences with alignments to show
Input Format250
ExampleTo increase the alignment displayed to 1000 use: -b 1000
NoteUpper limit is 200000. Web counterpart: "Alignments". This is NOT the total number of alignment segments or high scoring pairs (HSPs). Rather it is the number of database sequences with HSP(s) to the query.

Table 4.16
FunctionThreshold for extending hits
Input FormatInteger
ExampleTo increase this threshold to 15, use: -f 15
NoteDefault if set to zero, not used by blastn or megablast. Extension Threshold Default Settings

Table 4.17
FunctionPerform gapped alignment
Input Format[T/F]
ExampleTo do only ungapped alignment, use: -g F
NoteDefault is gapped alignment, not available with tblastx.

Table 4.18
FunctionQuery genetic code to use
Input Format[Integer]
ExampleTo set the genetic code (translation table) to 14, use: -Q 14
NoteThis determines which translation table to use on query in translated blastx and tblastx searches. Default is universal codon.

Table 4.19
FunctionDB Genetic code
Input Format[Integer]
ExampleTo set the genetic code (translation table) to 14, use: -D 14
NoteDetermines which translation table to use for the database in tblastn and tblastx search. See details at:

Table 4.20
FunctionNumber of processors to use
Input Format[Integer]
ExampleTo change this to two CPUs, use: -a 2
NoteFrom 1 up to the number of CPUs available.

Table 4.21
FunctionTo save SeqAlign object
Input FormatString [File Out]
ExampleTo save SeqAlign object to blast_seqalign, use: -O blast_seqalign
NoteUser can use the output to reformat the result into different format using NCBI toolkit function. See /blast/demo/ subdirectory for more information.

Table 4.22
FunctionBelieve the query definition line
Input Format[T/F]
ExampleTo set this to true, use: -J T
NoteDefault set to false since query file definition lines may not follow NCBI convention.

Table 4.23
FunctionProtein scoring matrix to use
Input Format[String]
ExampleTo change this to PAM30, use: -M PAM30
NoteAccepted value: BLOSUM45, BLOSUM62, BLOSUM80, PAM30, or PAM70.

Table 4.24
FunctionWord size
Input Format[Integer]
ExampleTo set word size to 32, use: -W 32
NoteWord size setting for different programs
Programblastnmegablastall others

Table 4.25
FunctionEffective length of the database
Input Format[Real]
ExampleTo set this to 10000000, use: -z 10000000
NoteUse zero for the actual database size.

Table 4.26
FunctionNumber of best hits from a region to keep
Input Format[Integer]
Example To keep 200 hits, use: -K 200
NoteThis selects the specified number of best hits for a given region of the query for further evaluation. Off by default, 100 recommended if used.

Table 4.27
FunctionUse multiple hit
Input FormatInteger
ExampleTo do single hit, use: -P 1
NoteZero is for multiple hit, 1 for single hit. Not applicable to blastn.

Table 4.28
FunctionEffective length of the search space
Input Format[Real]
ExampleTo set this to 10000000, use: -Y 10000000
NoteThis is the product of effective query length and effective database length - actual length corrected for edge effects. Use zero for actual size.

Table 4.29
FunctionStrands of the nucleotide query to use in the search
Input Format[Integer]
ExampleTo search with the reverse complement strand only, use: -S 2
Note-S Input Code And Meaning for blastn, blastx, and tblastx.
MeaningInputReverse complementBoth

Table 4.30
FunctionProduce HTML output
Input Format[T/F]
ExampleTo generate HTML formatted output, use: -T T
NoteWith -T T, if the database is from NCBI, BLAST will hot link matched subject sequences to their actual entries in Entrez.

Table 4.31
FunctionRestrict search of database to the subset satisfying the query
Input Format[Entrez Term] in quotes
ExampleTo restrict entries to mRNA use: -u "biomol_mrna[prop]"
NoteArgument is a set of Entrez query terms. BLAST server will use the terms to retrieve a list of GI numbers and restrict the BLAST search to entries specified by the list. Make sure valid terms are used. For example, it does not make sense to restrict a search to genomic sequences while searching against the est database. For details, see Entrez Help

Table 4.32
FunctionUse lower case filtering of FASTA sequence
Input Format[T/F]
ExampleTo turn lowercase filter on, use: -U T
NoteMake sure that the query sequences are in UPPERCASE and only the filtered portions are in lowercase.

Table 4.33
FunctionX dropoff value for ungapped extensions (in bits)
Input Format[Real]
ExampleTo increase the dropoff to 25, use: -y 25
NoteDefault setting for ungapped alignment X dropoff (-y, in bits)

Table 4.34
FunctionX dropoff value for final gapped alignment (in bits)
Input Format[Integer]
ExampleTo increase this dropoff to 60, use: -Z 60
NoteLarge dropoff value settings may help generate longer alignment. Default setting for ungapped alignment X dropoff (-Z, in bits)
Programblastnmegablasttblastxall others

Table 4.35
FunctionRun rpsblast search
Input Format[T/F]
ExampleTo run rpsblast search, use: -R T
NotePerforms rpsblast search against CDD database. Requires an appropriate -d input. See "Remote Accessible BLAST Databases" for more information.

Table 4.36
FunctionEnable megablast search
Input Format[T/F]
ExampleTo enable megablast search, use -n T
NoteInvokes megablast algorithm when set to T. -W will default to 28 and queries will be concatenated. This will help speed up the search at the expense of search sensitivities.

Table 4.37
FunctionLocation on query sequence
Input Format[String]
ExampleTo search with 100 to 400 of a query, use: -L "100,400"
NoteIn -L "100,400", 100 is the start and 400 the end.

Table 4.38
FunctionMultiple hits window size
Input Format[Integer]
ExampleTo increase the window size to 50, use: -A 50
NoteDefault -A setting for different programs
Programblastnmegablastall others

Table 4.39
FunctionFrame shift penalty
Default0 (no penalty)
Input Format[Integer]
ExampleTo set OOF penalty to 10, use: -w 10
NoteNon-zero invokes OOF (Out Of Frame) algorithm for blastx.

Table 4.40
FunctionLength of the largest intron allowed in tblastn for linking HSPs
Input Format[Integer]
ExampleTo allow linking of HSPs 10000 letter apart, use: -t 10000
NoteZero disables linking. Otherwise, the value specified will be used.

5. Practical usage examples
Before we get into the actual use, we need to discuss the format of the input query. The only query format blastcl3 recognizes is FASTA. In this format, the query begins with a "greater than" sign (>) initialed definition line, or defline as it is commonly known. This defline contains a basic description of the sequence, such as its source, the gene it represents, or ways to identify the sequence. It is terminated by a hard return. Actual sequence immediately follows the defline in one or more lines each terminated by a hard return. Multiple query sequences should be concatenated one after another. Sample query sequences are presented below for your reference.

>gi|4557757|ref|NP_000240.1| MutL protein homolog 1
>gi|68348711|ref|NP_001234.2| tumor necrosis factor receptor 8

Note that the file containing the query sequences has to be saved as a plain text file.

The program runs under a command or terminal window. On PC the command window can be launched using "Start ► Program ► Accessories ► Command Prompt". On Mac, the Terminal program icon usually is under the Utilities folder. Double click the grey icon will launch it.

In the terminal window, cd to the directory containing the blastcl3, then run the program from there. Type "blastcl3 -" without quotes and hit return should display the command line options on the screen. On Mac and Unix/Linux platform, type "./blastcl3 -" without quotes.

Since the list of available database has increased significantly, they are removed from this file. We will document this in a separate file at a later time.

     5.1 General nucleotide searches
The primary use of nucleotide BLAST search is to identify the input query by finding if exact match(es) are present in the database. This type of search also is used to identify the genomic counterpart of an input mRNA sequence or vice versa. Sometimes it is also used to search with primer pairs to identify the annealing target and possible secondary annealing sites of the primers.

For sequences from well studied model organisms, a good approach is to search against the refseq_rna or refseq_genomic database with Entrez limit. Alternatively, search against nr with or without limit to the target organism can also offer good lead.

The following example command lines search the input query file new_seq.txt against either the refseq_rna or nr database and save the result in n_refm.out and n_nr.out, respectively.

blastcl3 -p blastn -i n_seq -p blastn -d refseq_rna -o n_refm.out
blastcl3 -p blastn -i n_seq -p blastn -d nr -o n_nr.out
We can further restrict the search to the mouse entries in those two databases by using entrez limit and to speed up the search by invoking the megablast algorithm. The following two options will accomplish that:
-u "mouse[organism]" -n T
For easy parsing of the search result, we can request that the result be returned in either XML or "Hit Table" (tabular) format using "-m 7" or "-m 9" without quotes in the command line.

Seaching a genomic DNA against nucleotide database, we should invoke the repeat filter to mask the repeat region and prevent BLAST program from being inundated by spurious hits to those regions. For human, this can be invoked by adding the following filter option to the command line:

-F "m L; R"
Rodent specific repeat filter requires different filter call:
-F "R -d rodent.lib"

Combining these together, the following command line searches the n_seq input nucleotide query file against the human subset in the refseq_genomic database with low complexity and human repeat filter and megablast algorithm. The expect value cutoff is set to 2x10-10 and the output is saved in refg.output:

blastcl3 -i n_seq -p blastn -d refseq_genomic -u "human[orgn]" -n T -F "m L; R" -e 2e-10 -o refg.output
    5.2 General protein searches
A protein BLAST search can be used to identify the input query protein or its function through matching to other known proteins and their annotation. One such database is refseq_protein. The following command line searches protein sequences in my_query against this database using blastp. The result is saved in my_output.
blatcl3 -p blastp -i my_query -d refseq_protein -o my_output

For functional analysis, direct search against cdd database is more informative. Matches from cdd search will identify the conserved functional domain(s) present in the query. Defline and annotation from these matched domains will provide a better revelation on the function of the query. The following command line does such a search against the cdd database (-d cdd) using rpsblast (-R T):

blatcl3 -p blastp -R T -i my_query -d cdd -o my_output

Specific search against pdb database can be used to identify existing structures with matching sequences useful for structure modeling purposes. We do not support PSI-BLAST or PHI-BLAST searches through blastcl3.

     5.3 Translated BLAST searches
Translated searches can be very informative in revealing the possible function of the query since the search and alignment is performed at the protein level, which is more sensitive and biologically relevant.

         5.3.1. blastx
This program searches a nucleotide query against a protein database. It first translates the query in all six frames and then searches those protein translations against the specified protein database. It is useful in identify the potential protein product(s) the query may encode and may even be able to provide information on the functions of the protein(s) should a good match to a well characterized protein can be found.

In the example command line below, we are searching the nucleotide sequences in my_query against refseq_protein. The results are saved in my_oputput file.

blatcl3 -p blastx -i my_query -d refseq_protein -o my_output

         5.3.2 tblastn
This program function searches an input query protein sequence against a target nucleotide database to find other potential protein sequences that might be encoded by those nucleotide sequences. It is a good way to find out yet unidentified homolog/paralog of a give protein query. During the search, the nucleotide database entries are first translated in all six frames. The query protein is then compared against those potential products to identify the matches.

Example given below searches the input protein query file my_query against est_human database to try to identify human est entries that may encode proteins similar to the query. The result is saved to my_output:

blastcl3 -p tblastn -i my_query -d est_human -o my_output

         5.3.3. tblastx

This program function compares all six-frame translations of an input query nucleotide against those from a nucleotide database. Since this search is very computationally expensive, we strongly recommend that you use it with caution, employ an higher search stringency, and limit the search to a smaller more specific subset of the database using entrez limit.

The following command line searches the my_query against the human genomic entries in nt database. The result is saved in my_output.

blastcl3 -p tblastx -i my_query -d nt -u "human[orgn] AND biomol_genomic[prop]" -o my_output

Due to the heavy computation intensity, we also recommend that users set up local standalone blast to performing such searches if the search volume is large and/or the need is regular.

     5.4 Genome BLAST searches

Genome BLAST pages collect the genomic sequences and other sequences specific to an organism in one place for easy access. In addition, the matches from searching these databases often contain links to the graphic display on the Genome Mapviewer for that organims. Those organism specific genomic and other sequence databases are also available for search using blastcl3 with one major difference - there will be no link to the Map Viewer.

         5.4.1 Microbial Genomes and Other Eukaryote Genomes

Depending on the status of the genome, they can be finished with accompying protein data, wgs with accompanying protein data, or wgs without accompanying protein data. The database naming convention is "Microbial/Taxid". The example command line below searches the protein database for E.coli K-12 strain:

blastcl3 -p blastp -i my_query -d Microbial/83333 -o my_output
NCBI is terminating the support for BLAST searching unfinished microbial genomic sequences through the microbial genome blast page. The recommended way is to blast against the wgs database since most of their genomic sequences are submitted to NCBI as wgs entries. The following command line example searches the wgs entries of Bacillus anthracis:
blastcl3 -p blastn -d wgs -i my_query -o my_output -u "bacillus anthracis[orgn] AND wgs[prop]"

        5.4.2 Higher Genomes

Higher genomes related databases are grouped according to orgamisms, each group has it own unique database prefix. The genome assemblies are build-specific and they are updated when now assemblies are made available. For example, the human genome database and other human specific databases have the "hs_genome/" prefix. The following example command line searches against all the available human genome assemblies:

blastcl3 -p blastp -i my_query -d hs_genome/all_contig -o my_output
The default filter in the human genome blast page is "low complexity, human repeat, and masking lookup table only". To emmulate this, we can add -F "mL;R" into the command line.

6. Trouble shooting and technical assistance
    6.1 Errors and warnings

Problems encountered while using blastcl3 can be caused by firewall configuration, internet connection interruption, or NCBI server glitches, with the firewall configuration as the most common cause. A representative error message may contain "[CONN_Open] Cannot open connection", "<<< Re-establishing NETBLAST Service >>>", or something in that order.

Adding the following two lines in the .ncbirc file will increase the timeout setting and generate more informative messages that are useful in debugging the problem:

Search related errors from NCBI BLAST server typically are accompanied by RID for that search. Those RIDs should be kept and sent to NCBI blast-help for trouble-shooting.

    6.2 Technical assistance

If you encounter netblast problems, please report them to blast-help alias below. We recommend that you copy the error/warning messages displayed on the screen and provide detailed command line, and other relevant information. Questions or comments on this document and on BLAST in general should also be sent to blast-help alias.
Questions on other NCBI resources should be sent to: