Changelog and readme section for mcs

Author: marcelm

CHANGES.md

@@ -2,14 +2,20 @@
 
 ## development version
 
+* #476: Significantly improve speed and accuracy by enabling by default a new
+  variant of multi-context seeds: When no regular seeds - which consist
+  of two strobes - can be found for the entire query, strobealign attempts to find
+  single-strobe ("partial") seeds.
+  The `--mcs` option is still available for now. It is a bit slower, but
+  slightly more accurate.
 * #468: Be less strict when checking reference sequence names.
 
 ## v0.15.0 (2024-12-13)
 
 * #388 and #426: Increase accuracy and mapping rate for reads shorter than
   about 200 bp by introducing multi-context seeds.
-  Previously, seeds always consisted of two k-mers and would only be found if
-  both occur in query and reference.
+  Previously, seeds always consisted of two k-mers ("strobes") and would only
+  be found if both occur in query and reference.
   With this change, strobealign falls back to looking up just one of the k-mers
   when appropriate.
   This feature is currently *experimental* and only enabled when using the

README.md

@@ -223,6 +223,29 @@ actual mapping:
 - Index files are about four times as large as the reference.
 
 
+## Explanation
+
+### Multi-context seeds
+
+Strobealign uses randstrobes as seeds, which in our case consist of two k-mers
+("strobes") that are somewhat close to each other. When a seed is looked up
+in the index, it is only found if both strobes match. By changing the way in
+which the index is stored in v0.15.0, it became  possible to support
+*multi-context seeds*. With those changes, strobealign falls back to looking
+up only one of the strobes (a "partial seed") if the full seed cannot be found.
+This results in better mapping rate and accuracy for read lengths of up to
+about 200 nt.
+
+Usage of multi-context seeds is enabled by default in strobealign since v0.16.0.
+The strategy is to first search for all full seeds of the query and fall back to
+partial seeds if *no* seeds could be found.
+
+A slightly more accurate, but slower mode of using multi-context seeds is
+available by using option `--mcs`: With it, the strategy is changed to a
+fallback *per seed*: If an individual full seed cannot be found, its partial
+version is looked up in the index.
+
+
 ## Changelog
 
 See [Changelog](CHANGES.md).

src/cmdline.cpp

@@ -54,7 +54,7 @@ CommandLineOptions parse_command_line_arguments(int argc, char **argv) {
     args::ValueFlag<int> end_bonus(parser, "INT", "Soft clipping penalty [10]", {'L'});
 
     args::Group search(parser, "Search parameters:");
-    args::Flag mcs(parser, "mcs", "Use multi-context seeds for finding hits", {"mcs"});
+    args::Flag mcs(parser, "mcs", "Use extended multi-context seed mode for finding hits. Slightly more accurate, but slower", {"mcs"});
     args::ValueFlag<float> f(parser, "FLOAT", "Top fraction of repetitive strobemers to filter out from sampling [0.0002]", {'f'});
     args::ValueFlag<float> S(parser, "FLOAT", "Try candidate sites with mapping score at least S of maximum mapping score [0.5]", {'S'});
     args::ValueFlag<int> M(parser, "INT", "Maximum number of mapping sites to try [20]", {'M'});