alterlab-blast

$npx mdskill add AlterLab-IEU/AlterLab-Academic-Skills/alterlab-blast

Runs local NCBI BLAST+ and DIAMOND sequence searches from command line.

  • Builds local BLAST databases and runs blastn/blastp/blastx/tblastn searches.
  • Requires NCBI BLAST+ 2.17.0 binaries; DIAMOND optional for large protein searches.
  • Selects correct BLAST task and taxonomic scoping based on query type.
  • Outputs tabular results in outfmt 6/7 for easy parsing by downstream tools.

SKILL.md

.github/skills/alterlab-blastView on GitHub ↗
---
name: alterlab-blast
description: "Runs NCBI BLAST+ 2.17.0 sequence searches from the command line: makeblastdb (with -parse_seqids), blastn/blastp/blastx/tblastn with tabular -outfmt 6/7 for parsing, correct -task choice (megablast vs blastn vs blastn-short), -taxids/-negative_taxids taxonomic scoping, and -mt_mode multithreading; plus a DIAMOND blastp --ultra-sensitive path for large protein searches. Warns that -max_target_seqs is a heuristic keep-count, not a top-N best-hits filter. Use when the user wants command-line BLAST, makeblastdb, a local BLAST database, blastn/blastp/blastx/tblastn searches, or DIAMOND protein search. For the Bio.Blast web NCBIWWW API prefer alterlab-biopython; for quick one-liner database lookups prefer alterlab-gget. Part of the AlterLab Academic Skills suite."
license: MIT
allowed-tools: Read Write Edit Bash(python:*) Bash(makeblastdb:*) Bash(blastn:*) Bash(blastp:*) Bash(blastx:*) Bash(tblastn:*) Bash(blastdbcmd:*) Bash(diamond:*)
compatibility: "Requires NCBI BLAST+ 2.17.0 binaries on PATH (conda: `bioconda::blast`; or Homebrew `blast`); no API key or account needed for local searches. DIAMOND (`bioconda::diamond`) is optional and only used for the large-protein fast path. Parsing/QC helper runs under `uv run python` with the standard library only."
metadata:
    skill-author: AlterLab
    version: "1.0.0"
---

# BLAST+ — Command-Line Sequence Search

Run local NCBI **BLAST+ 2.17.0** searches end-to-end: build a database with
`makeblastdb`, search it with `blastn` / `blastp` / `blastx` / `tblastn`, emit
machine-parseable tabular output, and scope by taxonomy. For very large protein
searches, hand off to **DIAMOND** `blastp --ultra-sensitive` (100x–10,000x the
speed of BLAST, per the DIAMOND project). This is the **CLI / local-database**
skill; it is deliberately distinct from the Biopython web API and the gget
one-liner (see routing table below).

> Bulk DB builds and large searches are CPU/IO-heavy and fully offline — good
> candidates to run on local compute rather than burning API calls.

## When to Use This Skill

Use this skill when the request involves any of:

- "BLAST these sequences", "run blastn/blastp/blastx/tblastn", "command-line BLAST"
- "build a local BLAST database", "makeblastdb", "index this FASTA for BLAST"
- "search my reads against a local nt/nr database", "get tabular BLAST hits I can parse"
- "scope the BLAST search to a taxon" (`-taxids` / `-negative_taxids`)
- "BLAST is too slow on millions of proteins" → DIAMOND `blastp`
- retrieving sequences out of a BLAST DB (`blastdbcmd`, requires `-parse_seqids`)

### Does NOT Trigger

Route adjacent requests to the right sibling skill instead of forcing BLAST+:

| The request is really about… | Route to |
|------------------------------|----------|
| The **web** BLAST API (`Bio.Blast.NCBIWWW.qblast`), or scripting BLAST inside a Python pipeline with `Bio.Blast` parsing | `alterlab-biopython` |
| A **quick one-liner** BLAST/database lookup (`gget blast`, gene/structure/enrichment lookups) | `alterlab-gget` |
| Unified programmatic access to many bio web services (UniProt, KEGG, Ensembl REST, NCBI eUtils) | `alterlab-bioservices` |
| Building/searching a **phylogenetic tree** from sequences, not a similarity search | `alterlab-phylogenetics` |
| Read alignment to a reference genome (BWA/minimap2 → BAM) and SAM/BAM handling | `alterlab-pysam` |
| FASTQ→VCF variant calling pipeline | `alterlab-nf-core-sarek` |
| Transcript-level RNA-seq quantification (salmon/kallisto) | `alterlab-rnaseq-quant` |
| 16S/ITS amplicon classification (QIIME 2) | `alterlab-qiime2-amplicon` |
| Protein **structure** prediction / embeddings (ESM, AlphaFold) | `alterlab-esm` |

If the user explicitly says "web BLAST", "NCBIWWW", or "without installing
anything", they want `alterlab-biopython`, not this skill.

## Quick Start

```bash
# 1. Build a protein DB (‑parse_seqids enables blastdbcmd retrieval + DIAMOND reuse)
makeblastdb -in proteins.fasta -dbtype prot -parse_seqids -out mydb -title "my proteins"

# 2. Search, tabular output you can parse, std 12 columns
blastp -query query.faa -db mydb -outfmt 6 -evalue 1e-5 -out hits.tsv

# 3. QC / summarize the tabular output (stdlib only)
uv run python scripts/parse_blast_tab.py hits.tsv --best-hit
```

`-outfmt 6` is the canonical machine-readable format; its default columns are
the `std` set: `qseqid sseqid pident length mismatch gapopen qstart qend sstart
send evalue bitscore`. Use `-outfmt 7` for the same columns plus comment lines.

## Choosing the Right Program

| Query | Subject DB | Program |
|-------|-----------|---------|
| nucleotide | nucleotide | `blastn` |
| protein | protein | `blastp` |
| nucleotide (translated) | protein | `blastx` |
| protein | nucleotide (translated) | `tblastn` |

`-dbtype` for `makeblastdb` is `nucl` for nucleotide subjects, `prot` for protein.

## The Five Things People Get Wrong

1. **`-max_target_seqs` is NOT a "top N best hits" filter.** It is the number of
   aligned sequences to *keep*, applied during the search as a heuristic cutoff;
   ties are broken "by order of sequences in the database", not by score. Setting
   `-max_target_seqs 1` does **not** reliably return the single best hit. To get
   the best hit, keep a generous value and pick the top row *after* sorting by
   bitscore (see `scripts/parse_blast_tab.py --best-hit`). Default is 500.
2. **Wrong `-task` for `blastn`.** `megablast` (default) is for highly similar
   sequences; use `blastn` for cross-species / more divergent hits and
   `blastn-short` for queries < ~30 nt (primers, sgRNAs). `dc-megablast` is the
   discontiguous option for inter-species comparison.
3. **Forgetting `-parse_seqids` at DB-build time.** Without it you cannot pull
   sequences back out with `blastdbcmd -entry`, and DIAMOND cannot reuse the
   sequence IDs cleanly. You cannot add it later without rebuilding.
4. **Quoting the `-outfmt` custom column list for DIAMOND.** BLAST+ wants the
   spec quoted (`-outfmt '6 qseqid sseqid pident evalue'`); **DIAMOND wants it
   unquoted** (`--outfmt 6 qseqid sseqid pident evalue`). Mixing these up is a
   common silent error.
5. **Multithreading.** Use `-num_threads N`. For *many small queries*, set
   `-mt_mode 1` (split by query) so all threads stay busy; `-mt_mode 0` (default,
   split by database volume) suits few large queries. BLAST+ 2.15+ can choose
   automatically, but set it explicitly when in doubt.

Full option reference, taxonomy scoping, and DB-prep details:
[`references/blast_cli.md`](references/blast_cli.md).

## Taxonomic Scoping

Restrict a search to (or away from) clades by NCBI taxid:

```bash
blastn -query q.fna -db nt -taxids 9606 -outfmt 6 -out human_only.tsv
blastp -query q.faa -db nr -negative_taxids 2 -outfmt 6 -out no_bacteria.tsv
```

Scoping by taxid requires a taxonomy-aware database (one built/downloaded with
its `*.taxid` mapping, e.g. NCBI's pre-formatted `nt` / `nr`). See
[`references/blast_cli.md`](references/blast_cli.md#taxonomy).

## DIAMOND — Fast Path for Large Protein Searches

When `blastp` / `blastx` against millions of proteins is too slow, DIAMOND is a
drop-in for protein-space search:

```bash
diamond makedb --in nr.faa -d nr_diamond
diamond blastp -d nr_diamond -q query.faa -o hits.tsv \
  --ultra-sensitive --outfmt 6 qseqid sseqid pident length evalue bitscore
```

Sensitivity ladder (fast → most sensitive): `--fast`, `--mid-sensitive`,
`--sensitive`, `--more-sensitive`, `--very-sensitive`, `--ultra-sensitive`.
Use `--ultra-sensitive` when you need BLAST-comparable recall; default fast mode
trades sensitivity for speed. DIAMOND's `--outfmt 6` is compatible with the
BLAST+ tabular parser below. Details and tradeoffs:
[`references/diamond.md`](references/diamond.md).

## Recommended Workflow

1. **Pick the program** from the query/subject table above.
2. **Build the DB** with `makeblastdb -parse_seqids` (or download a pre-formatted
   NCBI DB). For >~1M proteins, build a DIAMOND DB instead.
3. **Search** with `-outfmt 6`, an explicit `-evalue` threshold, the right
   `-task` (blastn), and `-num_threads`. Add `-taxids` if scoping.
4. **Parse & QC** with `scripts/parse_blast_tab.py` — it sorts by bitscore,
   extracts best-hit-per-query, applies identity/coverage/e-value filters, and
   flags the `-max_target_seqs` pitfall if the column count looks truncated.
5. **Retrieve** any hit sequence with
   `blastdbcmd -db mydb -entry <id>` (needs `-parse_seqids`).

## Verify Before Reporting

- Confirm `blastn -version` / `diamond version` actually ran — never report hits
  you did not produce.
- State the program, `-task`, `-evalue`, and DB used; results are meaningless
  without them.
- If you used `-max_target_seqs`, confirm best-hit selection was done by
  *post-hoc bitscore sort*, not by trusting the keep-count as a top-N.
- For DIAMOND results, note the sensitivity level used.

## References

- [`references/blast_cli.md`](references/blast_cli.md) — full BLAST+ 2.17.0 option
  reference: programs, `makeblastdb`, `-outfmt` columns, `-task`, taxonomy
  scoping, `-mt_mode`, `blastdbcmd` retrieval, and the `-max_target_seqs` caveat.
- [`references/diamond.md`](references/diamond.md) — DIAMOND DB build, sensitivity
  modes, output formats, and when to choose it over BLAST+.
- NCBI BLAST+ manual: https://www.ncbi.nlm.nih.gov/books/NBK569856/
- DIAMOND: https://github.com/bbuchfink/diamond

Part of the AlterLab Academic Skills suite.

More from AlterLab-IEU/AlterLab-Academic-Skills

SkillDescription
alterlab-abm-mesaBuilds agent-based models of social systems with Mesa 3 — the current AgentSet API (model.agents.shuffle_do('step'), auto-assigned unique_id, mandatory super().__init__(seed=...)), cell spaces (mesa.discrete_space OrthogonalMooreGrid / classic mesa.space grids), the DataCollector, batch_run parameter sweeps, and SolaraViz — for emergence, segregation, diffusion, opinion dynamics, and cooperation models. It uses the Mesa 3.x API (the old mesa.time schedulers like RandomActivation are removed) and treats the model as a generative theory to be validated, not just run. Use when the request mentions an agent-based model, Mesa, simulating interacting agents, or emergent macro behavior from micro rules. For discrete-event (queueing/process) simulation prefer alterlab-simpy; for reinforcement learning prefer alterlab-stable-baselines3. Part of the AlterLab Academic Skills suite.
alterlab-academic-careerPrepares academic career documents and professional-development materials for faculty and researchers. Use when drafting academic CVs, research statements, teaching philosophies, diversity statements, faculty-position cover letters, tenure dossiers, promotion narratives, academic portfolios, or mentorship statements, and when planning conference-networking strategy, building academic web presence, setting up ORCID profiles, or understanding impact metrics. Part of the AlterLab Academic Skills suite.
alterlab-accreditation-aolScaffolds program-level Assurance-of-Learning (AoL) documentation for AACSB (2020 Standard 5) and ABET (Criterion 3 Student Outcomes, Criterion 4 Continuous Improvement) accreditation — program learning outcomes / competency goals, curriculum-to-outcome mapping matrices, direct- and indirect-assessment plans, rubric design, and closing-the-loop continuous-improvement narratives — and validates the structure of an outcome-mapping matrix with scripts/aol_matrix.py. Use when the user needs AACSB or ABET assurance-of-learning material, a program-learning-outcomes set, a curriculum/outcome map or coverage matrix, a direct/indirect assessment plan, a closing-the-loop report, or accreditation self-study text. For single-course design or course rubrics prefer alterlab-teaching-design; for post-award grant reports prefer alterlab-grant-reporting. Part of the AlterLab Academic Skills suite.
alterlab-adaptyvSubmits and tracks protein-testing experiments on the Adaptyv Bio Foundry cloud lab (wet-lab validation), and optimizes protein sequences before submission with computational tools (NetSolP, SoluProt, SolubleMPNN, ESM). Use when designing proteins that need wet-lab validation - binding/affinity screening, expression testing, thermostability, or fluorescence assays - or when submitting experiments to the Foundry API, browsing the target catalog, tracking experiment status, retrieving results, or pre-screening sequences for solubility/expression. Triggers on "Adaptyv", "Foundry API", "cloud lab", "biolayer interferometry / BLI", "wet-lab validation". Part of the AlterLab Academic Skills suite.
alterlab-aeonRuns time series machine learning with the aeon library — classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search via scikit-learn compatible APIs. Use when working with temporal data, sequential patterns, or time-indexed observations (univariate or multivariate) that need specialized algorithms beyond standard ML approaches. Part of the AlterLab Academic Skills suite.
alterlab-akademik-tesvikComputes the annual Turkish academic-incentive (akademik teşvik) score for Devlet (state) university öğretim elemanı (academic staff) from a classified activity list, applying the verified Akademik Teşvik Ödeneği Yönetmeliği (2018/11834) Faaliyet Hesaplama Tablosu headline puanları (Proje 20, Araştırma 15, Yayın 30, Patent 30, Atıf 30, Tebliğ 20, Ödül 20) with the k (author-count), p (Q1 1/Q2 0.8/Q3 0.5/Q4 0.25), and r (project-role) coefficients via türü puanı = Σ(faaliyet oranları) × headline (MADDE 8/2), then enforcing the per-type headline ceilings, the 100 cap (MADDE 8/3), and the net-30 payment gate (MADDE 10/3) in a deterministic scripts/tesvik_score.py. Use when the user wants to calculate akademik teşvik puanı, check the en az 30 (net-30) threshold, apply TABLO 4 ceilings, or estimate teşvik eligibility; keeps its coefficients separate from doçentlik scoring. For doçentlik point eligibility prefer alterlab-docentlik-eligibility. Part of the AlterLab Academic Skills suite.
alterlab-alpha-vantageAccesses real-time and historical stock market data, forex rates, cryptocurrency prices, commodities, economic indicators, and 50+ technical indicators via the Alpha Vantage API (requires a free API key from alphavantage.co). Use when fetching stock prices (OHLCV), company fundamentals (income statement, balance sheet, cash flow), earnings, options data, market news/sentiment, insider transactions, GDP, CPI, treasury yields, gold/silver/oil prices, Bitcoin/crypto prices, forex exchange rates, or calculating technical indicators (SMA, EMA, MACD, RSI, Bollinger Bands). Part of the AlterLab Academic Skills suite.
alterlab-alphafoldPredict protein 3D structures with AlphaFold2 via ColabFold — MMseqs2-accelerated MSAs, monomer and AlphaFold2-Multimer complex folding, and confidence-based validation (pLDDT, pTM/ipTM, PAE). Use when folding a protein sequence or complex from FASTA, generating a predicted structure with confidence metrics, ranking models, or checking self-consistency of a design. For co-folding a protein WITH a small-molecule ligand or predicting binding affinity prefer alterlab-boltz; for antibody–antigen or one-FASTA multi-entity complexes prefer alterlab-chai; to LOOK UP an already-computed structure prefer alterlab-alphafold-db; for ESM embeddings or inverse folding prefer alterlab-esm. Part of the AlterLab Academic Skills suite.
alterlab-alphafold-dbAccess the AlphaFold DB of 200M+ AI-PREDICTED protein structures — retrieve models by UniProt accession, download PDB/mmCIF files, and analyze prediction confidence metrics (pLDDT, PAE). Use when a UniProt ID needs a computationally predicted 3D structure or when no experimental structure exists, for homology modeling, protein engineering, or structure-based drug discovery; for EXPERIMENTALLY determined structures (X-ray, cryo-EM, NMR) prefer alterlab-pdb, and for protein sequences, annotations, or accession ID mapping prefer alterlab-uniprot instead. Part of the AlterLab Academic Skills suite.
alterlab-anndataBuild, slice, concatenate, read, and write AnnData annotated data matrices (obs, var, X, layers, obsm, uns) — the scverse data STRUCTURE, not an analysis pipeline. Use when creating or wrangling .h5ad/zarr files, managing cell and gene annotations, concatenating batches, or handling layers/obsm/backed-mode; for the QC, normalization, clustering, UMAP, and differential-expression analysis pipeline prefer alterlab-scanpy instead, and for RNA velocity from spliced/unspliced layers prefer alterlab-scvelo instead. Part of the AlterLab Academic Skills suite.