Skip to content

Add a script that builds the local BLAST ortholog database from taxonomy IDs - #27

Merged
AnthonyGarza124 merged 5 commits into
refactor-v2from
local-blast-db-script
Oct 15, 2026
Merged

AnthonyGarza124 merged 5 commits into
refactor-v2from
local-blast-db-script

Conversation

@AnthonyGarza124

@AnthonyGarza124 AnthonyGarza124 commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

Add a script that builds the local BLAST ortholog database from taxonomy IDs

A new user starts with nothing. Given the NCBI taxonomy IDs of the species they want orthologs from, scripts/make_blast_db.sh downloads each RefSeq reference proteome with the NCBI datasets CLI, combines them, builds a BLAST database with -parse_seqids, verifies retrieval, and prints the species names to use as species_map keys.

LocalBlastSearcher fetches each hit's complete protein with blastdbcmd -entry, which fails on any database built without -parse_seqids. Both of our existing lab databases were built that way and return no orthologs under V2.

The script can also build from a protein FASTA the user already has (-i), or extract taxa from an existing taxonomy-enabled database such as nr (-n). The README section is rewritten as the three steps a user follows: install the tools, run the script, point LocalBlastSearcher at the result.

Tested from scratch with yeast plus fruit fly: download, build, and verify took six seconds, blastp returns correct hits, and per-accession retrieval works.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Taxonomy extraction fails when the output directory does not already exist.

1 open finding
What changed in this PR

Adds a helper script for building local protein BLAST databases compatible with Lverage V2.

Changes:

  • Builds with -parse_seqids and checks first-record retrieval.
  • Supports extracting selected taxa from an existing database.
  • Replaces manual README commands with script examples.
File Description
scripts/​make_blast_db.sh Adds database extraction, building, and retrieval verification.
README.md Documents script-based database setup.

🧠 Review effort: Balanced


💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread scripts/make_blast_db.sh Resolved
…omy IDs

A new user starts with nothing. Given the NCBI taxonomy IDs of the species
they want orthologs from, scripts/make_blast_db.sh downloads each RefSeq
reference proteome with the NCBI datasets CLI, combines them, builds a
BLAST database with -parse_seqids (LocalBlastSearcher fetches each hit's
complete protein with blastdbcmd -entry, which fails without it), verifies
retrieval, and prints the species names to use as species_map keys.

It can also build from a protein FASTA the user already has (-i), or
extract taxa from an existing taxonomy-enabled database such as nr (-n).

Rewrite the README section as the three steps a user actually follows:
install the tools, run the script, point LocalBlastSearcher at the result.
The README is for users; how to construct LocalBlastSearcher in code
belongs in the API docs. Step 3 now just says what to keep from the
script's output and why.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Missing executable permission blocks documented commands, and truncated species reporting can leave valid ortholog species unmapped.

2 open findings
1 resolved since last review

🧠 Review effort: Balanced

Comment thread scripts/make_blast_db.sh Resolved
Comment thread scripts/make_blast_db.sh Resolved
@AnthonyGarza124 AnthonyGarza124 changed the title Add a script that builds a V2-compatible local BLAST database Add a script that builds the local BLAST ortholog database from taxonomy IDs Oct 15, 2026
The file was committed as 644 because this clone has core.filemode off,
so the documented invocation failed with permission denied. Also drop the
20-line cap on the species report, since users copy species_map keys
from it.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Shared RefSeq accessions can cause database creation to fail for valid multi-species inputs.

2 open findings
1 resolved since last review

🧠 Review effort: Balanced

Comment thread scripts/make_blast_db.sh Resolved
RefSeq reuses WP_ accessions for identical proteins across related
bacteria, and makeblastdb -parse_seqids refuses duplicate ids (two
Bacillus reference proteomes share 803). When a downloaded record's id was
already added by an earlier species, suffix it with the taxid and keep the
description; accessions are untouched otherwise. For -i input, fail early
with the duplicate ids listed instead of makeblastdb's error.

Also fix the final report: piping blastdbcmd -info into head raised
SIGPIPE under pipefail, so the script exited before printing the species
list and ready line. Use sed, which reads to the end.

README: bacterial proteomes label many records with only a genus, so map
every printed name.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Duplicate identifiers can abort builds, and inconsistent or ambiguous species labels can discard or misclassify hits.

2 open findings
1 resolved since last review
Previously missed (2)

In code that hasn't changed since last review

Medium severity Disambiguate shared bracketed organism labels across species

scripts/​make_blast_db.sh:95

When two downloaded species share a bracketed group label such as [Bacillus], suffixing their accessions leaves their species indistinguishable. LocalBlastSearcher assigns taxonomy from that label alone (src/lverage/blast.py:69–84), so following README lines 89–91 and mapping the printed label to one taxid misclassifies proteins from the other species. Preserve source-specific organism labels and print their taxid mappings, or reject labels shared across source taxa. Update the README to explain that ambiguous group labels cannot safely be mapped to a single species.

Medium severity Use consistent organism extraction between builder and BLAST parser

scripts/​make_blast_db.sh:124

This prints the last bracketed field, but _parse_blast_hits (src/lverage/blast.py:69) reads the first. For >id NADH dehydrogenase [ubiquinone] subunit [Homo sapiens], the script recommends Homo sapiens, while the searcher looks up ubiquinone and skips the hit when only the recommended species key is configured. Use a consistent organism-extraction rule in the builder and searcher; printing the first field instead would incorrectly treat protein annotations as species.

🧠 Review effort: Balanced

Comment thread scripts/make_blast_db.sh Resolved
Track every id emitted so far, not only those from earlier species, and
pick a collision-free suffix when a proteome repeats an accession or the
suffixed name already exists.

README: two species of the same genus share genus-level labels in RefSeq
and cannot be told apart by species_map.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Printed species-map keys can disagree with the searcher's header parsing, causing valid hits to be skipped.

0 open findings

2 resolved since last review
Previously missed (1)

In code that hasn't changed since last review

Medium severity Align organism extraction between BLAST builder and searcher

scripts/​make_blast_db.sh:129

This prints the last bracketed field, but LocalBlastSearcher uses the first (src/lverage/blast.py:69–76). For a header such as [acyl-carrier-protein] S-malonyltransferase [Escherichia coli], the script prints Escherichia coli, while the searcher looks up acyl-carrier-protein and skips the hit with an unresolved-species warning. Align the searcher's organism extraction with the builder's trailing species field, and add a regression case with brackets in the protein description. Printing the first field instead would incorrectly treat a protein-description fragment as a species.

🧠 Review effort: Balanced

@AnthonyGarza124
AnthonyGarza124 merged commit ae7cdf4 into refactor-v2 Oct 15, 2026
2 checks passed
@AnthonyGarza124
AnthonyGarza124 deleted the local-blast-db-script branch October 15, 2026 18:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants