feat: forward --small-thresh to alevin-fry from quant and multiplex-quant

alevin-fry resolves cells below --small-thresh through a fast path that applies
cr-like semantics regardless of --resolution. That is a deliberate optimization
-- such cells carry one or two ambiguous UMIs and are filtered by any QC -- but
until now it was neither visible nor adjustable from simpleaf.

Forwarded only when the user sets it, so alevin-fry's own default stands
otherwise. alevin-fry < 0.17.1 parses the option and ignores it, which is noted
in the help text and the docs.

Verified end to end against the pbmc_1k_v3 mapping directory with
-r parsimony-em: unset records small_thresh=100 with 71,298 cells on the fast
path and 132 empty; --small-thresh 0 records small_thresh=0 with 0 on the fast
path and 0 empty, recovering 82,069 UMIs (0.53%) across 452,324 extra matrix
entries -- matching the figure measured by driving alevin-fry directly.

Also refreshes the docs' embedded --help blocks, which still carried the
"only if using piscem >= 0.7" text removed from --decoy-paths earlier.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VhyNvEWUgY8ALVacdJHxVJ

Author: rob-p

CHANGELOG.md

@@ -27,6 +27,11 @@
   `multiplex-quant`, and `atac process`.
 * `--tmp-dir` and `--ram-limit-gib` are forwarded to `piscem build` from both
   index commands.
+* `--small-thresh` on `quant` and `multiplex-quant`, forwarded to alevin-fry.
+  Cells below it are resolved by alevin-fry's tiny-cell fast path, which
+  applies `cr-like` semantics regardless of `--resolution`; `--small-thresh 0`
+  resolves every cell with the requested strategy. Requires alevin-fry
+  >= 0.17.1 (earlier versions parse the option and ignore it).
 * `--sample-bc-ori {forward,reverse}` on `multiplex-quant` (#199).
 * `10x-flexv2-gex-3p-config-b` chemistry preset (#201).
 * `gene_id_to_name.tsv` emitted from probe sets that carry a gene-name column,

docs-site/src/content/docs/flex-quant-command.md

@@ -146,6 +146,14 @@ Quantification Options:
           [possible values: cr-like, cr-like-em, parsimony, parsimony-em, parsimony-gene,
           parsimony-gene-em]
 
+      --small-thresh <N>
+          Cells with fewer than this many reads are resolved by alevin-fry's tiny-cell fast path,
+          which applies `cr-like` (winner-take-all) semantics regardless of `--resolution`. Pass 0
+          to resolve every cell with the requested strategy.
+          
+          Left unset, alevin-fry's own default applies. Requires alevin-fry >= 0.17.1; earlier
+          versions parse the option and ignore it.
+
 Piscem Mapping Options:
       --skipping-strategy <SKIPPING_STRATEGY>
           The skipping strategy to use for k-mer collection
@@ -154,7 +162,7 @@ Piscem Mapping Options:
           [possible values: permissive, strict]
 
       --struct-constraints
-          If piscem >= 0.7.0, enable structural constraints
+          Enable structural constraints when mapping
 
       --max-ec-card <MAX_EC_CARD>
           Maximum cardinality equivalence class to examine

docs-site/src/content/docs/index-command.md

@@ -137,7 +137,6 @@ Piscem Index Options:
 
       --decoy-paths <DECOY_PATHS>
           Paths to decoy sequence FASTA files used to insert poison k-mer information into the index
-          (only if using piscem >= 0.7)
 
       --seed <HASH_SEED>
           The seed value to use in SSHash index construction (try changing this in the rare event

docs-site/src/content/docs/quant-command.md

@@ -35,6 +35,40 @@ It is possible to have pieces of geometry repeated, in which case they will be e
 :::note
 If you use a custom geometry frequently, you can add it to the chemistries registry. For details on adding your own chemistry definition to the registry, please read about the [chemistry command](/simpleaf/chemistry-command/).
 :::
+## Tiny cells and `--small-thresh`
+
+`alevin-fry` resolves very small cells through a fast path that skips the
+equivalence-class machinery entirely. That path implements `cr-like`
+(winner-take-all) semantics, and it applies to cells below the threshold
+*regardless of what you pass to* `--resolution` — so under `parsimony-em`, a
+tiny cell whose UMIs are all gene-ambiguous is resolved by discarding them
+rather than by spreading them fractionally.
+
+This is deliberate. Cells that small carry on the order of one or two distinct
+UMIs, typically ambiguous between paralogous genes, and are removed by any
+reasonable QC filter whichever way they resolve. Skipping the full machinery
+for them is a large saving on datasets with many low-count barcodes.
+
+`--small-thresh` makes the behaviour visible and adjustable:
+
+```sh
+# resolve every cell with the requested strategy, however small
+simpleaf quant ... -r parsimony-em --small-thresh 0
+```
+
+Left unset, `alevin-fry`'s own default (currently 100 reads) applies. Which
+cells took the fast path is recorded in `af_quant/quant.json` as
+`num_tiny_cell_resolved` and `tiny_cell_resolved_cell_numbers`, so the choice
+is auditable after the fact.
+
+:::note
+This option requires **alevin-fry >= 0.17.1**. Earlier versions parse it and
+silently ignore it, so on 0.17.0 passing `--small-thresh 0` will have no
+effect. On a 73k-cell PBMC run, `--small-thresh 0` recovers about 0.53% of
+total UMI mass and empties no cells, against 132 zero-count cells at the
+default.
+:::
+
 ## Threads, and the shared decode budget
 
 As of `piscem` 0.22.0, the `-t`/`--threads` value is a single budget of execution
@@ -86,7 +120,7 @@ Mapping Options:
 
 Piscem Mapping Options:
       --struct-constraints
-          If piscem >= 0.7.0, enable structural constraints
+          Enable structural constraints when mapping
 
       --ignore-ambig-hits
           Skip checking of the equivalence classes of k-mers that were too ambiguous to be otherwise
@@ -189,6 +223,14 @@ UMI Resolution Options:
           [possible values: cr-like, cr-like-em, parsimony, parsimony-em, parsimony-gene,
           parsimony-gene-em]
 
+      --small-thresh <N>
+          Cells with fewer than this many reads are resolved by alevin-fry's tiny-cell fast path,
+          which applies `cr-like` (winner-take-all) semantics regardless of `--resolution`. Pass 0
+          to resolve every cell with the requested strategy.
+          
+          Left unset, alevin-fry's own default applies. Requires alevin-fry >= 0.17.1; earlier
+          versions parse the option and ignore it.
+
 Output Options:
       --anndata-out
           Generate an anndata (h5ad format) count matrix from the standard (matrix-market format)

src/simpleaf_commands.rs

@@ -330,6 +330,16 @@ pub struct MapQuantOpts {
     #[arg(short, long, help_heading = "UMI Resolution Options", value_parser = clap::builder::PossibleValuesParser::new(["cr-like", "cr-like-em", "parsimony", "parsimony-em", "parsimony-gene", "parsimony-gene-em"]))]
     pub resolution: String,
 
+    /// Cells with fewer than this many reads are resolved by alevin-fry's
+    /// tiny-cell fast path, which applies `cr-like` (winner-take-all) semantics
+    /// regardless of `--resolution`. Pass 0 to resolve every cell with the
+    /// requested strategy.
+    ///
+    /// Left unset, alevin-fry's own default applies. Requires alevin-fry
+    /// >= 0.17.1; earlier versions parse the option and ignore it.
+    #[arg(long, value_name = "N", help_heading = "UMI Resolution Options")]
+    pub small_thresh: Option<usize>,
+
     /// Generate an anndata (h5ad format) count matrix from the standard (matrix-market format)
     /// output.
     #[arg(long, help_heading = "Output Options")]
@@ -746,6 +756,16 @@ pub struct MultiplexQuantOpts {
         ]))]
     pub resolution: String,
 
+    /// Cells with fewer than this many reads are resolved by alevin-fry's
+    /// tiny-cell fast path, which applies `cr-like` (winner-take-all) semantics
+    /// regardless of `--resolution`. Pass 0 to resolve every cell with the
+    /// requested strategy.
+    ///
+    /// Left unset, alevin-fry's own default applies. Requires alevin-fry
+    /// >= 0.17.1; earlier versions parse the option and ignore it.
+    #[arg(long, value_name = "N", help_heading = "Quantification Options")]
+    pub small_thresh: Option<usize>,
+
     /// k-mer length for probe index building
     #[arg(long, default_value_t = 23, help_heading = "Probe Set Options")]
     pub kmer_length: usize,

src/simpleaf_commands/multiplex_quant.rs

@@ -474,6 +474,14 @@ pub fn multiplex_map_and_quant(af_home: &Path, opts: MultiplexQuantOpts) -> anyh
         .arg(&opts.resolution)
         .arg("--use-mtx");
 
+    // Only forwarded when the user set it, so alevin-fry's own default stands
+    // otherwise. alevin-fry < 0.17.1 parses this and ignores it.
+    if let Some(small_thresh) = opts.small_thresh {
+        quant_cmd
+            .arg("--small-thresh")
+            .arg(small_thresh.to_string());
+    }
+
     let quant_cmd_str = prog_utils::get_cmd_line_string(&quant_cmd);
     info!("quant cmd: {}", quant_cmd_str);
     let quant_start = Instant::now();
@@ -873,6 +881,7 @@ mod tests {
             reads1: Vec::new(),
             reads2: Vec::new(),
             resolution: String::from("cr-like"),
+            small_thresh: None,
             kmer_length: 23,
             skipping_strategy: String::from("permissive"),
             struct_constraints: false,

src/simpleaf_commands/quant.rs

@@ -555,6 +555,13 @@ fn run_quant_stage(
     alevin_quant_cmd.arg("-t").arg(format!("{}", setup.threads));
     alevin_quant_cmd.arg("-m").arg(setup.t2g_map_file.clone());
     alevin_quant_cmd.arg("-r").arg(&opts.resolution);
+    // Only forwarded when the user set it, so alevin-fry's own default stands
+    // otherwise. alevin-fry < 0.17.1 parses this and ignores it.
+    if let Some(small_thresh) = opts.small_thresh {
+        alevin_quant_cmd
+            .arg("--small-thresh")
+            .arg(small_thresh.to_string());
+    }
     let quant_cmd_string = prog_utils::get_cmd_line_string(&alevin_quant_cmd);
     info!("cmd : {:?}", alevin_quant_cmd);
     let input_files = vec![gpl_output.clone(), setup.t2g_map_file.clone()];

tests/snapshots/cli-help/simpleaf_multiplex_quant___help.txt

@@ -103,6 +103,14 @@ Quantification Options:
           [possible values: cr-like, cr-like-em, parsimony, parsimony-em, parsimony-gene,
           parsimony-gene-em]
 
+      --small-thresh <N>
+          Cells with fewer than this many reads are resolved by alevin-fry's tiny-cell fast path,
+          which applies `cr-like` (winner-take-all) semantics regardless of `--resolution`. Pass 0
+          to resolve every cell with the requested strategy.
+          
+          Left unset, alevin-fry's own default applies. Requires alevin-fry >= 0.17.1; earlier
+          versions parse the option and ignore it.
+
 Piscem Mapping Options:
       --skipping-strategy <SKIPPING_STRATEGY>
           The skipping strategy to use for k-mer collection

tests/snapshots/cli-help/simpleaf_quant___help.txt

@@ -139,6 +139,14 @@ UMI Resolution Options:
           [possible values: cr-like, cr-like-em, parsimony, parsimony-em, parsimony-gene,
           parsimony-gene-em]
 
+      --small-thresh <N>
+          Cells with fewer than this many reads are resolved by alevin-fry's tiny-cell fast path,
+          which applies `cr-like` (winner-take-all) semantics regardless of `--resolution`. Pass 0
+          to resolve every cell with the requested strategy.
+          
+          Left unset, alevin-fry's own default applies. Requires alevin-fry >= 0.17.1; earlier
+          versions parse the option and ignore it.
+
 Output Options:
       --anndata-out
           Generate an anndata (h5ad format) count matrix from the standard (matrix-market format)