BlobToolKit Viewer Taxonomy Display#

Overview#

The BlobToolKit viewer colors assembly scaffolds/contigs by a single active category axis — typically a taxonomic rank field such as bestsumorder_phylum. This axis is stored in Redux state as plot.cat and drives both the scatter plot coloring and the summary table category column.

plot.cat: The Single Active Category Axis#

plot.cat is a string field ID stored in the Redux plot slice (e.g., "bestsumorder_phylum"). It is initialized from the dataset's metadata at import time and synced to/from the URL query string via catField.

Redux state: The plot reducer 1 holds an axes object (x, y, z, cat). getCatAxis 2 and getMainPlot 3 are the canonical reselect selectors for reading it.

URL ↔ store sync: In querySync.jsx, catField maps to the axes.cat slot 4. When catField appears in the query string, it is dispatched as an EDIT_PLOT action 5, which also triggers an EDIT_FIELD action to mark that field as active. The viewer reads window.plot.cat as a fallback default 6.

Default value set at parse time: In hits.py, after applying the taxrule, the parse() function sets meta.plot["cat"] to "{prefix}_phylum" (e.g., "bestsumorder_phylum") unless plot.cat is already set 7. This is the mechanism by which a phylum-level view is the out-of-the-box default.

BLAST/Diamond Hits → Rank-Specific Category Fields#

The Python-side pipeline (hits.py) converts raw BLAST/Diamond tabular output into per-rank Category fields:

1. Parse hits — parse_blast() 8 reads tabular BLAST output, extracting subject, score, start, end, and taxid per hit.
2. Bin hits — bin_hits() 9 partitions hits along each sequence into windows (chunks).
3. Apply taxrule — apply_taxrule() 10 iterates over all taxonomic ranks returned by taxdump.list_ranks(). For each bin, apply_taxrule_to_bin() 11 looks up each hit's taxid against the taxonomy dump to resolve a rank-specific name (e.g., phylum name), accumulating scores per category. The category with the highest aggregated score in each bin wins.
4. Across-bin consensus — apply_taxrule_across_bins() 12 selects the most-frequent (then highest-scored) category across all bins for that sequence.
5. Sequences with no hits receive the label "no-hit" 13.
6. Unresolvable ranks produce "undef" or "{parent}-undef" labels 14.

Field naming convention: One Category field is created per rank per taxrule prefix, following the pattern {prefix}_{rank} (e.g., bestsumorder_phylum, bestsumorder_genus). 15. Companion sub-fields {prefix}_{rank}_score and {prefix}_{rank}_cindex are also created 16.

Viewer: Binding plot.cat to Visualization#

Selectors#

Table#

TablePlot.jsx passes plot.cat.meta.id as plotCategory to generateColumns() 21. The column for the active category axis renders color-coded CategoryLabel cells 22, while other category columns render plain text labels.

Color assignment#

getBinnedColors 23 maps each category index (from bins) to a palette color, so every downstream consumer (scatter plot, table, legend) uses a consistent color for the same taxon name.

Key Files#