/bio-local-blast

<!--

COPYRIGHT NOTICE

This file is part of the "Universal Biomedical Skills" project.

Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>

All Rights Reserved.

#

This code is proprietary and confidential.

Unauthorized copying of this file, via any medium is strictly prohibited.

#

Provenance: Authenticated by MD BABU MIA

-->

--- name: bio-local-blast description: Run local BLAST searches using BLAST+ command-line tools. Use when running fast unlimited searches, building custom databases, performing large-scale analysis, or when NCBI servers are slow or unavailable. tool_type: cli primary_tool: BLAST+ measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes. allowed-tools:

• read_file
• run_shell_command

---

Local BLAST

Run BLAST searches locally using NCBI BLAST+ command-line tools.

Installation

# macOS
brew install blast

# Ubuntu/Debian
sudo apt install ncbi-blast+

# conda
conda install -c bioconda blast

# Verify installation
blastn -version

BLAST+ Programs

| Command | Query | Database | Description | |---------|-------|----------|-------------| | `blastn` | DNA | DNA | Nucleotide-nucleotide | | `blastp` | Protein | Protein | Protein-protein | | `blastx` | DNA | Protein | Translated query vs protein | | `tblastn` | Protein | DNA | Protein vs translated DB | | `tblastx` | DNA | DNA | Translated vs translated | | `makeblastdb` | - | - | Create BLAST database |

Creating BLAST Databases

makeblastdb - Create Database

# Create nucleotide database
makeblastdb -in sequences.fasta -dbtype nucl -out my_db

# Create protein database
makeblastdb -in proteins.fasta -dbtype prot -out my_proteins

# With title and parse sequence IDs
makeblastdb -in sequences.fasta -dbtype nucl -out my_db \
    -title "My Reference Database" -parse_seqids

**Key Options:** | Option | Description | Values | |--------|-------------|--------| | `-in` | Input FASTA file | Path | | `-dbtype` | Database type | `nucl`, `prot` | | `-out` | Output database name | Path prefix | | `-title` | Database title | String | | `-parse_seqids` | Enable ID-based retrieval | Flag | | `-taxid` | Assign taxonomy ID | Integer | | `-taxid_map` | Taxonomy ID mapping file | Path |

Database Files Created

my_db.nhr  # Header file (nucl) / .phr (prot)
my_db.nin  # Index file (nucl) / .pin (prot)
my_db.nsq  # Sequence file (nucl) / .psq (prot)
my_db.ndb  # Alias file (optional)
my_db.not  # ID index (if parse_seqids)
my_db.ntf  # Index (if parse_seqids)
my_db.nto  # Index (if parse_seqids)

Running BLAST Searches

Basic Usage

# BLASTN
blastn -query query.fasta -db my_db -out results.txt

# BLASTP
blastp -query proteins.fasta -db my_proteins -out results.txt

# BLASTX (translate query, search protein DB)
blastx -query genes.fasta -db nr -out results.txt

Common Options

| Option | Description | Example | |--------|-------------|---------| | `-query` | Query FASTA file | `-query seq.fa` | | `-db` | Database name | `-db nt` | | `-out` | Output file | `-out results.txt` | | `-outfmt` | Output format | `-outfmt 6` | | `-evalue` | E-value threshold | `-evalue 1e-5` | | `-num_threads` | CPU threads | `-num_threads 8` | | `-max_target_seqs` | Max hits | `-max_target_seqs 100` | | `-max_hsps` | Max HSPs per hit | `-max_hsps 1` | | `-word_size` | Word size | `-word_size 11` | | `-dust` | Filter low complexity (nucl) | `-dust yes` | | `-seg` | Filter low complexity (prot) | `-seg yes` |

Output Formats (-outfmt)

| Value | Format | |-------|--------| | `0` | Pairwise (default) | | `1` | Query-anchored with identities | | `5` | BLAST XML | | `6` | Tabular | | `7` | Tabular with comments | | `10` | CSV |

Tabular Output Fields (-outfmt 6)

Default columns: `qseqid sseqid pident length mismatch gapopen qstart qend sstart send evalue bitscore`

Custom columns:

blastn -query query.fa -db my_db -outfmt "6 qseqid sseqid pident length evalue stitle"

**Available Fields:** | Field | Description | |-------|-------------| | `qseqid` | Query ID | | `sseqid` | Subject ID | | `pident` | Percent identity | | `length` | Alignment length | | `mismatch` | Mismatches | | `gapopen` | Gap openings | | `qstart` | Query start | | `qend` | Query end | | `sstart` | Subject start | | `send` | Subject end | | `evalue` | E-value | | `bitscore` | Bit score | | `stitle` | Subject title | | `qcovs` | Query coverage | | `qcovhsp` | Query coverage per HSP |

Code Patterns

Create Database and Search

#!/bin/bash
# Create database from reference sequences
makeblastdb -in reference.fasta -dbtype nucl -out ref_db -parse_seqids

# Run BLAST
blastn -query query.fasta -db ref_db -out results.txt \
    -outfmt 6 -evalue 1e-10 -num_threads 4

# View results
head results.txt

BLAST with Tabular Output

#!/bin/bash
blastn -query query.fasta -db my_db \
    -outfmt "6 qseqid sseqid pident length mismatch gapopen qstart qend sstart send evalue bitscore stitle" \
    -evalue 1e-5 \
    -max_target_seqs 10 \
    -num_threads 8 \
    -out results.tsv

Filter and Sort Results

# Get hits with >90% identity
awk -F'\t' '$3 >= 90' results.tsv

# Sort by E-value
sort -t$'\t' -k11 -g results.tsv

# Get best hit per query
sort -t$'\t' -k1,1 -k11,11g results.tsv | sort -t$'\t' -k1,1 -u

Batch BLAST Multiple Files

#!/bin/bash
for query_file in queries/*.fasta; do
    base=$(basename "$query_file" .fasta)
    echo "Processing $base..."

    blastn -query "$query_file" -db my_db \
        -outfmt 6 -evalue 1e-5 -num_threads 4 \
        -out "results/${base}_blast.tsv"
done

Python Wrapper

import subprocess
import os

def make_blast_db(fasta_file, db_name, db_type='nucl'):
    cmd = ['makeblastdb', '-in', fasta_file, '-dbtype', db_type, '-out', db_name, '-parse_seqids']
    subprocess.run(cmd, check=True)

def run_blast(query, db, output, program='blastn', evalue=1e-5, thr