Feat/lut bias table!

[St4NNi]

New Lut based Bias table

The initial bias implementation used a hard cutoff that heavily suppressed k-mers from the negative set and unknown k-mers, retaining only the most significant positive-enriched signal. While this gave strong compression and clean extraction of target features, it tended to over-correct, particularly when the positive training set was sparse, producing sketches that only reflected the learned positive population rather than the broader sequence space. This branch replaces the hard cutoff with a Look-Up Table (LUT) that assigns an independent effective fscale to each of the 255 quantized weight buckets. This allows fine-grained control over retention across the full enrichment spectrum, including a dedicated fscale for weight-zero buckets (k-mers equally present in positive and negative sets, this included "not seen" kmers). The result is a sketch that remains informative for any input sequence, with varying sensitivity depending on the sequence's similarity to the positive and negative sets.

Changes

• Adds soft filter mode to jam bias create via --positive-fscale and --negative-fscale: instead of a binary hard cutoff, each k-mer is sampled at a rate proportional to its enrichment in the positive set
• Bias weights (log-ratio of positive/negative CMS counts) are quantized to i8 and stored in a 255-entry lookup table; at sketch time each hash is assigned an effective fscale by a single LUT lookup with no floating-point overhead
• The LUT is calibrated empirically per weight bucket from the actual positive/negative hash frequency distributions
• K-mers enriched in both positive and negative sets are correctly handled: the background-subtraction step (negative minus positive, floored at zero) prevents shared k-mers from being incorrectly penalized as negative
• LUT optimizer maximizes pos_retention² / neg_retention via coarse grid + ternary search refinement, subject to a configurable --min-positive-retention floor (default 0.1)
• Sparse weight buckets (insufficient observations) inherit their fscale from the nearest reliable neighbor toward w=0, preventing noise from low-count bins
• New --unbiased-fscale flag pins the effective fscale for weight-zero buckets (k-mers equally present in positive and negative) independently of the optimizer
• Calibration output now reports eff. fscale (pos/neg/combined), the effective fscale experienced by each calibration population and their geometric mean, making the non-uniform sampling rate interpretable as a single equivalent fscale
• jam stats on a database built with an embedded bias table reports the combined effective fscale inline: Sample rate: 1/100 (effective: 1/432)
• bias stats --output json exposes the full 255-entry fscale LUT and per-bucket enrichment curve alongside the calibration metrics

[codecov]

Codecov Report

❌ Patch coverage is 67.37064% with 309 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.02%. Comparing base (dbc10e1) to head (beb3c56).
⚠️ Report is 12 commits behind head on main.

Files with missing lines	Patch %	Lines
src/bias.rs	77.11%	171 Missing and 18 partials ⚠️
src/cli/handlers.rs	0.00%	109 Missing ⚠️
src/lib.rs	0.00%	8 Missing ⚠️
src/sketch.rs	0.00%	2 Missing ⚠️
src/query.rs	0.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main       #9      +/-   ##
==========================================
- Coverage   72.12%   72.02%   -0.10%     
==========================================
  Files          11       11              
  Lines        4814     5655     +841     
  Branches     4814     5655     +841     
==========================================
+ Hits         3472     4073     +601     
- Misses       1233     1454     +221     
- Partials      109      128      +19     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.