blast client

Program Option for Netblast (blastcl3)

Tao Tao, Ph.D.
User Service
NCBI, NLM, NIH

TOC

1. Introduction
2. Installation and setup
3. Firewall settings
4. Options and their accepted values
5. Practical usage examples
6. Trouble shooting and technical assistance
- 6.1 Errors and warnings
- 6.2 Technical assistance

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 (www.ncbi.nlm.nih.gov/BLAST/). 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:

ftp.ncbi.nlm.nih.gov/blast/executables/LATEST/

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 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 Address	Port Number
130.14.29.112	5861
130.14.29.112	5862
130.14.29.112	5863
Note Please refer to '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.

[NCBI]
DATA=/home/johndoe/netblast-2.2.12/data

[CONN]
FIREWALL=TRUE

[NET_SERV]
SRV_CONN_MODE=SERVICE

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:

www.ncbi.nlm.nih.gov/blast/Doc/urlapi.html

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
Option	-p
Function	Specifies which program to run
Default	None, mandatory
Input Format	String
Example	To run blastn program use: -p blastn
Note	Program string options and type of search they specify
	Program	Query	DB
	blastn	nucleotide	nucleotide
	blastp	protein	protein
	blastx	nucleotide, translated	Protein
	tblastn	protein	nucleotide, translated
	tblastx	nucleotide, translated	nucleotide, translated

Table 4.2
Option	-d
Function	Specifies database(s) to be searched
Default	nr
Input Format	String
Example	One can search against multiple databases can be specified in command line. To search nr and est at together use: -d "nr est"
Note	Be conservative. Search against large databases may not complete due to CPU time limit, which is set at one hour.

Table 4.3
Option	-i
Function	Specifies input query file
Default	stdin
Input Format	String, mandatory
Example	To use sequences from query.txt as query, use -i query.txt
Note	One should use the complete file name WITH its extension. To use stdin default, omit the -i and redirect using: < mito.txt

Table 4.4
Option	-e
Function	Specifies Expect value cutoff
Default	10
Input Format	Real
Example	To make the search more stringent, one can use: -e 0.001
Note	Accepted formats are integer, fraction, decimal, exponential and scientific notation. To set the cutoff to 2×10-20, use -e 2e-20

Table 4.5
Option	-m
Function	Specifies alignment view option
Default	0
Input Format	Integer
Example	To display the result in XML form use: -m 7
Note	Option values and the output formats they specify
	0	Pairwise
	1	query-anchored showing identities
	2	query-anchored no identities
	3	flat query-anchored, show identities
	4	flat query-anchored, no identities
	5	query-anchored no identities and blunt ends
	6	flat query-anchored, no identities and blunt ends
	7	XML Blast output
	8	tabular (not post processing)
	9	tabular with comment lines (post-processed, sorted)
	10	ASN, text
	11	ASN, binary

Table 4.6
Option	-o
Function	Specifies result output file
Default	stdout (print to screen)
Input Format	String [file name]
Example	To 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
Option	-F
Function	Specifies which filter(s) to use to mask query sequence
Default	T (DUST for nucleotide, SEG for protein)
Input Format	String
Example	To filter low complexity and lookup table only, use: -F "m L"
Note	Accepted 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
Option	-G
Function	Cost to open a gap
Default	0
Input Format	[Integer]
Example	To increase the gap open penalty to 10, use: -G 10
Note	Zero 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
Option	-E
Function	Cost to extend a gap
Default	0
Input Format	[Integer]
Example	To increase the gap extension penalty to 4, use: -E 4
Note	Zero 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
Option	-X
Function	X dropoff value for gapped alignment (in bits)
Default	0
Input Format	[Integer]
Example	To increase the gapped alignment dropoff to 40, use: -X 40
Note	Gapped Alignment Dropoff Default Setting (in bits)
	Program	blastn	megablast	tblastx	others
	Value	30	20	0	15

Table 4.11
Option	-I (capital i)
Function	Show GI in definition line
Default	F
Input Format	[T/F]
Example	To activate the GI display use: -I T
Note	Sample display: T: gi\|223046\|prf\|\|0410468A... F: prf\|\|0410468A...

Table 4.12
Option	-q
Function	Penalty for a nucleotide mismatch
Default	-3
Input Format	[Integer]
Example	To set penalty to -2, use: -q -2
Note	For blastn only, different -r/-q ratios are optimal for aligning sequences with different percentage of similarities.

Table 4.13

Option

-r

Function

Reward for a nucleotide match

Default

Input Format

[Integer]

Example

To increase the reward to 2, use: -

1. Introduction