MRG: add label output & input options to compare and plot, for better customization

[ctb]

Adds sourmash compare --labels-to and sourmash plot --labels-from to support better label customization.

Fixes #2452
Fixes #2915

sourmash compare --labels-to

This command will generate a 'labels-to' file. Running:

sourmash compare tests/test-data/demo/*.sig -o compare-demo \
    --labels-to compare-demo-labels.csv

will produce a file that looks like this:

file compare-demo-labels.csv:

order,md5,label,name,filename,signature_file
1,60f7e23c24a8d94791cc7a8680c493f9,SRR2060939_1.fastq.gz,,SRR2060939_1.fastq.gz,../tests/test-data/demo/SRR2060939_1.sig
2,4e94e60265e04f0763142e20b52c0da1,SRR2060939_2.fastq.gz,,SRR2060939_2.fastq.gz,../tests/test-data/demo/SRR2060939_2.sig
3,f71e78178af9e45e6f1d87a0c53c465c,SRR2241509_1.fastq.gz,,SRR2241509_1.fastq.gz,../tests/test-data/demo/SRR2241509_1.sig
4,6d6e87e1154e95b279e5e7db414bc37b,SRR2255622_1.fastq.gz,,SRR2255622_1.fastq.gz,../tests/test-data/demo/SRR2255622_1.sig
5,0107d767a345eff67ecdaed2ee5cd7ba,SRR453566_1.fastq.gz,,SRR453566_1.fastq.gz,../tests/test-data/demo/SRR453566_1.sig
6,f0c834bc306651d2b9321fb21d3e8d8f,SRR453569_1.fastq.gz,,SRR453569_1.fastq.gz,../tests/test-data/demo/SRR453569_1.sig
7,b59473c94ff2889eca5d7165936e64b3,SRR453570_1.fastq.gz,,SRR453570_1.fastq.gz,../tests/test-data/demo/SRR453570_1.sig

The label column in this file can be edited to suit the user's needs; the index column is order, and all other columns can be ignored or deleted or updated without consequence.

sourmash plot --labels-from

This command will load labels from a file. Running:

sourmash plot --labels-from compare-demo-new-labels.csv compare-demo

uses the label column from the CSV as labels, in the order specified by the order column (interpreted as integers and sorted from lowest to highest). All other columns are ignored.

Example in a Jupyter Notebook

Some example code for updating the labels is available here:

https://github.com/sourmash-bio/sourmash/blob/compare_labels/doc/plotting-compare.ipynb

TODO

• add test for args.labeltext and args.labels_from check
• check the notebook update

Future:

• Consider switching to LinearIndex in the signature loading code, as that would let us maintain the location in the code without the current machinations. Also worth thinking about enabling lazy loading, which some future Index-code based modification might support.
• consider if and how to validate --labels-from CSV file...

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (a128ee3) 86.65% compared to head (b3369c1) 92.84%.

Additional details and impacted files

@@            Coverage Diff             @@
##           latest    #2598      +/-   ##
==========================================
+ Coverage   86.65%   92.84%   +6.19%     
==========================================
  Files         135      104      -31     
  Lines       15284    12482    -2802     
  Branches     2592     2602      +10     
==========================================
- Hits        13244    11589    -1655     
+ Misses       1740      593    -1147     
  Partials      300      300              

Flag	Coverage Δ
hypothesis-py	25.74% <0.00%> (-0.07%)	⬇️
python	92.84% <100.00%> (+0.01%)	⬆️
rust	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[peterjc]

Other possible names for the "order" column: "sort" or "index" - I have no strong preference, but can see how I might use this were my labels didn't have an alphabetic sorting.

[ctb]

7ffcb7b changes order to sort_order

[ctb]

Ready for review & merge @sourmash-bio/devs !

[bluegenes]

lgtm!

[ctb]

🎉