{"slug":"alterlab-blast","title":"alterlab-blast","summary":"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_mo","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-23T18:56:53.359704Z","repo":{"url":"https://github.com/AlterLab-IEU/AlterLab-Academic-Skills","stars":68,"forks":13,"license":"MIT","updatedAt":"2026-09-23T13:42:59Z"},"bodyHtml":"
\n

name: alterlab-blast\ndescription: \"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.\"\nlicense: MIT\nallowed-tools: Read Write Edit Bash(python:) Bash(makeblastdb:) Bash(blastn:) Bash(blastp:) Bash(blastx:) Bash(tblastn:) Bash(blastdbcmd:) Bash(diamond:)\ncompatibility: \"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.\"\nmetadata:\nskill-author: AlterLab\nversion: \"1.1.0\"\nlast_updated: \"2026-09-23\"

\n

BLAST+ — Command-Line Sequence Search

\n

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

\n
\n

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

\n
\n

When to Use This Skill

\n

Use this skill when the request involves any of:

\n\n

Does NOT Trigger

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
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 parsingalterlab-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 searchalterlab-phylogenetics
Read alignment to a reference genome (BWA/minimap2 → BAM) and SAM/BAM handlingalterlab-pysam
FASTQ→VCF variant calling pipelinealterlab-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
\n

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

\n

Quick Start

\n
# 1. Build a protein DB (‑parse_seqids enables blastdbcmd retrieval + DIAMOND reuse)\nmakeblastdb -in proteins.fasta -dbtype prot -parse_seqids -out mydb -title \"my proteins\"\n\n# 2. Search, tabular output you can parse, std 12 columns\nblastp -query query.faa -db mydb -outfmt 6 -evalue 1e-5 -out hits.tsv\n\n# 3. QC / summarize the tabular output (stdlib only)\nuv run python scripts/parse_blast_tab.py hits.tsv --best-hit\n
\n

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

\n

Choosing the Right Program

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
QuerySubject DBProgram
nucleotidenucleotideblastn
proteinproteinblastp
nucleotide (translated)proteinblastx
proteinnucleotide (translated)tblastn
\n

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

\n

The Five Things People Get Wrong

\n
    \n
  1. -max_target_seqs is NOT a \"top N best hits\" filter. It is the number of\naligned sequences to keep, applied during the search as a heuristic cutoff;\nties are broken \"by order of sequences in the database\", not by score. Setting\n-max_target_seqs 1 does not reliably return the single best hit. To get\nthe best hit, keep a generous value and pick the top row after sorting by\nbitscore (see scripts/parse_blast_tab.py --best-hit). Default is 500.
    2. \n
  2. Wrong -task for blastn. megablast (default) is for highly similar\nsequences; use blastn for cross-species / more divergent hits and\nblastn-short for queries < ~30 nt (primers, sgRNAs). dc-megablast is the\ndiscontiguous option for inter-species comparison.
    3. \n
  3. Forgetting -parse_seqids at DB-build time. Without it you cannot pull\nsequences back out with blastdbcmd -entry, and DIAMOND cannot reuse the\nsequence IDs cleanly. You cannot add it later without rebuilding.
    4. \n
  4. Quoting the -outfmt custom column list for DIAMOND. BLAST+ wants the\nspec quoted (-outfmt '6 qseqid sseqid pident evalue'); DIAMOND wants it\nunquoted (--outfmt 6 qseqid sseqid pident evalue). Mixing these up is a\ncommon silent error.
    5. \n
  5. Multithreading. Use -num_threads N. Since BLAST+ 2.15 the default\n-mt_mode 0 means BLAST picks the split for you from query and database\nsize, which NCBI recommends leaving alone. Override only deliberately:\n-mt_mode 1 = ThreadByQuery (many small queries), -mt_mode 2 =\nThreadByDatabase (few large queries, big DB).
    6. \n
\n

Full option reference, taxonomy scoping, and DB-prep details:\nreferences/blast_cli.md.

\n

Taxonomic Scoping

\n

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

\n
blastn -query q.fna -db nt -taxids 9606 -outfmt 6 -out human_only.tsv\nblastp -query q.faa -db nr -negative_taxids 2 -outfmt 6 -out no_bacteria.tsv\n
\n

Scoping by taxid requires a taxonomy-aware database (one built/downloaded with\nits *.taxid mapping, e.g. NCBI's pre-formatted nt / nr). See\nreferences/blast_cli.md.

\n

DIAMOND — Fast Path for Large Protein Searches

\n

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

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

Sensitivity ladder (fast → most sensitive): --fast, --mid-sensitive,\n--sensitive, --more-sensitive, --very-sensitive, --ultra-sensitive. With no\nsensitivity flag DIAMOND runs its default mode, which sits between --fast and\n--mid-sensitive. Use --ultra-sensitive when you need BLAST-comparable recall. DIAMOND's --outfmt 6 is compatible with the\nBLAST+ tabular parser below. Details and tradeoffs:\nreferences/diamond.md.

\n

Recommended Workflow

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

Verify Before Reporting

\n\n

References

\n\n

Part of the AlterLab Academic Skills suite.

\n","files":[{"path":"evals/evals.json","sizeBytes":6296,"isText":true},{"path":"references/blast_cli.md","sizeBytes":6522,"isText":true},{"path":"references/diamond.md","sizeBytes":3157,"isText":true},{"path":"scripts/parse_blast_tab.py","sizeBytes":6653,"isText":true},{"path":"SKILL.md","sizeBytes":9661,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-23T18:57:14.09428Z","sha256":"19E59EC43038161F8CA96206D207BF709856D90FCDF5DF0F21163C1764A5661F","sizeBytes":13960},"review":null,"source":{"repositoryUrl":"https://github.com/AlterLab-IEU/AlterLab-Academic-Skills","path":"skills/bioinformatics/alterlab-blast","license":"MIT","commit":"e4836c08a20da195a11f30f203a8cf23ec30aa95","subtreeSha":"3EF11EF4062140A472EA401F8C8BD9C8D1A0DAEF7DA634AB675EE9357B04ACF3","lastSyncedAt":"2026-09-23T18:56:52.297238Z"},"reviewedAt":"2026-09-23T18:57:50.325706Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/bioinformatics/alterlab-blast"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart"},{"target":"git","command":"git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git"}]}