/bio-blast-searches

<!--

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-blast-searches description: Run remote BLAST searches against NCBI databases using Biopython Bio.Blast. Use when identifying unknown sequences, finding homologs, or searching for sequence similarity against NCBI's nr/nt databases. tool_type: python primary_tool: Bio.Blast.NCBIWWW measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes. allowed-tools:

• read_file
• run_shell_command

---

BLAST Searches

Run BLAST searches against NCBI databases using Biopython's Bio.Blast module.

Required Import

from Bio.Blast import NCBIWWW, NCBIXML
from Bio import SeqIO

BLAST Programs

| Program | Query | Database | Use Case | |---------|-------|----------|----------| | `blastn` | Nucleotide | Nucleotide | DNA/RNA sequence similarity | | `blastp` | Protein | Protein | Protein sequence similarity | | `blastx` | Nucleotide | Protein | Find protein hits for DNA query | | `tblastn` | Protein | Nucleotide | Find DNA encoding protein-like | | `tblastx` | Nucleotide | Nucleotide | Translated vs translated |

Core Function

NCBIWWW.qblast()

Submit a BLAST query to NCBI servers.

from Bio.Blast import NCBIWWW

# Simple BLASTN search
result_handle = NCBIWWW.qblast('blastn', 'nt', sequence)

**Key Parameters:** | Parameter | Description | Example | |-----------|-------------|---------| | `program` | BLAST program | `'blastn'`, `'blastp'` | | `database` | Target database | `'nr'`, `'nt'`, `'refseq_rna'` | | `sequence` | Query sequence | String or SeqRecord | | `entrez_query` | Limit by Entrez query | `'Homo sapiens[organism]'` | | `hitlist_size` | Max hits to return | `50` | | `expect` | E-value threshold | `0.001` | | `word_size` | Word size | `11` for blastn | | `gapcosts` | Gap penalties | `'5 2'` (open, extend) | | `format_type` | Output format | `'XML'` (default), `'Text'` |

Common Databases

**Nucleotide:** | Database | Description | |----------|-------------| | `nt` | All GenBank + EMBL + DDBJ | | `refseq_rna` | RefSeq RNA sequences | | `refseq_genomic` | RefSeq genomic sequences |

**Protein:** | Database | Description | |----------|-------------| | `nr` | Non-redundant protein | | `refseq_protein` | RefSeq proteins | | `swissprot` | SwissProt (curated) | | `pdb` | Protein structures |

Parsing Results

NCBIXML Parser

from Bio.Blast import NCBIWWW, NCBIXML

# Run BLAST
result_handle = NCBIWWW.qblast('blastn', 'nt', sequence)

# Parse XML results
blast_record = NCBIXML.read(result_handle)
result_handle.close()

# Iterate hits
for alignment in blast_record.alignments:
    print(f"Hit: {alignment.title}")
    for hsp in alignment.hsps:
        print(f"  E-value: {hsp.expect}")
        print(f"  Score: {hsp.score}")
        print(f"  Identity: {hsp.identities}/{hsp.align_length}")

Alignment/HSP Attributes

# Alignment (hit) attributes
alignment.title          # Hit description
alignment.accession      # Accession number
alignment.length         # Subject sequence length
alignment.hsps           # List of HSPs

# HSP (High-scoring Segment Pair) attributes
hsp.score               # Raw score
hsp.bits                # Bit score
hsp.expect              # E-value
hsp.identities          # Number of identical positions
hsp.positives           # Number of positive-scoring positions
hsp.gaps                # Number of gaps
hsp.align_length        # Alignment length
hsp.query               # Aligned query sequence
hsp.match               # Match line (| for identity)
hsp.sbjct               # Aligned subject sequence
hsp.query_start         # Query start position
hsp.query_end           # Query end position
hsp.sbjct_start         # Subject start position
hsp.sbjct_end           # Subject end position
hsp.strand              # Strand (blastn)
hsp.frame               # Reading frame (blastx/tblastn)

Code Patterns

Basic BLASTN

from Bio.Blast import NCBIWWW, NCBIXML

sequence = '''ATGAAAGCAATTTTCGTACTGAAAGGTTGGTGGCGCACTTCCTGA'''

print("Running BLASTN (this may take a minute)...")
result_handle = NCBIWWW.qblast('blastn', 'nt', sequence)

blast_record = NCBIXML.read(result_handle)
result_handle.close()

print(f"\nFound {len(blast_record.alignments)} hits")
for alignment in blast_record.alignments[:5]:
    hsp = alignment.hsps[0]
    print(f"\n{alignment.title[:70]}...")
    print(f"  E-value: {hsp.expect:.2e}")
    print(f"  Identity: {hsp.identities}/{hsp.align_length} ({100*hsp.identities/hsp.align_length:.1f}%)")

BLASTP with Organism Filter

from Bio.Blast import NCBIWWW, NCBIXML

protein_seq = '''MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH'''

result_handle = NCBIWWW.qblast(
    'blastp',
    'nr',
    protein_seq,
    entrez_query='Mammalia[organism]',
    hitlist_size=20,
    expect=0.001
)

blast_record = NCBIXML.read(result_handle)
result_handle.close()

for alignment in blast_record.alignments[:10]:
    hsp = alignment.hsps[0]
    print(f"{alignment.accession}: E={hsp.expect:.2e} - {alignment.title[:50]}...")

BLAST from FASTA File

from Bio import SeqIO
from Bio.Blast import NCBIWWW, NCBIXML

record = SeqIO.read('query.fasta', 'fasta')

result_handle = NCBIWWW.qblast('blastn', 'nt', record.seq)
blast_record = NCBIXML.read(result_handle)
result_handle.close()

for alignment in blast_record.alignments[:5]:
    print(f"{alignment.accession}: {alignment.title[:60]}...")

Save Results to File

from Bio.Blast import NCBIWWW

result_handle = NCBIWWW.qblast('blastn', 'nt', sequence)

# Save XML for later parsing
with open('blast_results.xml', 'w') as out: