Thread --dict through quant/multiplex-quant; add sample_bc_ori plumbing

Extends the dictionary-backend selection (previously wired only on
`simpleaf index`) to the two mapping commands so that the map-time
dictionary can be chosen explicitly when the index's embedded default
is not desired:

- `simpleaf quant`: `--dict {auto,sshash,tiny}` forwarded to
  `piscem map-sc`.
- `simpleaf multiplex-quant`: `--dict` forwarded to both `piscem build`
  (for the auto-built probe index) and `piscem map-sc`.

Adds `sample_bc_ori` support needed for correct Flex v2 processing
(where the sample BC on R1 downstream of the anchor is the reverse
complement of the vendor-published whitelist):

- `utils::chem_utils::SampleBcListInfo` gains an optional
  `sample_bc_ori` field carried in the chemistry registry.
- `multiplex-quant` forwards the chemistry's declared orientation as
  `--sample-bc-ori` to `alevin-fry generate-permit-list`.

Snapshot updates for `simpleaf index|quant|multiplex-quant --help`
reflect the new `--dict` option. Tui/workflow and rsjsonnet migration
work has been split onto the `tui-workflow` branch and will be merged
in a later release.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rob-p

src/simpleaf_commands.rs

@@ -184,6 +184,16 @@ pub struct MapQuantOpts {
         help_heading = "Piscem Mapping Options")]
     pub max_read_occ: u32,
 
+    /// Piscem dictionary backend to use at map time: `auto` (default, honors the
+    /// index's embedded choice), `sshash`, or `tiny`.
+    #[arg(
+        long,
+        value_enum,
+        default_value_t = PiscemDict::Auto,
+        help_heading = "Piscem Mapping Options"
+    )]
+    pub dict: PiscemDict,
+
     /// Path to a mapped output directory containing a RAD file to skip mapping
     #[arg(long = "map-dir", conflicts_with_all = ["index", "reads1", "reads2"], help_heading = "Mapping Options")]
     pub map_dir: Option<PathBuf>,
@@ -651,6 +661,16 @@ pub struct MultiplexQuantOpts {
     #[arg(long, default_value_t = DefaultParams::MAX_EC_CARD, help_heading = "Piscem Mapping Options")]
     pub max_ec_card: u32,
 
+    /// Piscem dictionary backend: `auto` (default), `sshash`, or `tiny`. Applies
+    /// both to the auto-built probe index (build time) and to map-sc (map time).
+    #[arg(
+        long,
+        value_enum,
+        default_value_t = PiscemDict::Auto,
+        help_heading = "Piscem Mapping Options"
+    )]
+    pub dict: PiscemDict,
+
     /// Minimum read count threshold for unfiltered permit list
     #[arg(long, default_value_t = 10, help_heading = "Permit List Options")]
     pub min_reads: usize,

src/simpleaf_commands/multiplex_quant.rs

@@ -356,7 +356,9 @@ pub fn multiplex_map_and_quant(af_home: &Path, opts: MultiplexQuantOpts) -> anyh
         .arg("--skipping-strategy")
         .arg(&opts.skipping_strategy)
         .arg("--max-ec-card")
-        .arg(format!("{}", opts.max_ec_card));
+        .arg(format!("{}", opts.max_ec_card))
+        .arg("--dict")
+        .arg(opts.dict.as_cli());
 
     let r1_str: Vec<String> = opts
         .reads1
@@ -404,6 +406,16 @@ pub fn multiplex_map_and_quant(af_home: &Path, opts: MultiplexQuantOpts) -> anyh
         .arg("--min-reads")
         .arg(format!("{}", opts.min_reads));
 
+    // If the chemistry declares a sample-barcode orientation (e.g. 10x Flex v2
+    // where the whitelist is the RC of what appears on the read), forward it.
+    if let Some(c) = chem.as_ref() {
+        if let Some(sbc_info) = c.sample_bc_list.as_ref() {
+            if let Some(ori) = sbc_info.sample_bc_ori.as_deref() {
+                gpl_cmd.arg("--sample-bc-ori").arg(ori);
+            }
+        }
+    }
+
     let gpl_cmd_str = prog_utils::get_cmd_line_string(&gpl_cmd);
     info!("generate-permit-list cmd: {}", gpl_cmd_str);
     let gpl_start = Instant::now();
@@ -650,6 +662,8 @@ fn build_index_from_probe_set(
         .arg(format!("{}", opts.kmer_length))
         .arg("-t")
         .arg(format!("{}", opts.threads))
+        .arg("--dict")
+        .arg(opts.dict.as_cli())
         .arg("--overwrite");
 
     info!(
@@ -841,6 +855,7 @@ mod tests {
             skipping_strategy: String::from("permissive"),
             struct_constraints: false,
             max_ec_card: 4096,
+            dict: crate::simpleaf_commands::PiscemDict::Auto,
             min_reads: 10,
             anndata_out: false,
         };

src/simpleaf_commands/quant.rs

@@ -429,6 +429,8 @@ fn run_mapping_stage(
                 piscem_quant_cmd
                     .arg("--threads")
                     .arg(format!("{}", setup.threads))
+                    .arg("--dict")
+                    .arg(opts.dict.as_cli())
                     .arg("-o")
                     .arg(&map_output);
 

src/utils/chem_utils.rs

@@ -143,6 +143,12 @@ pub struct SampleBcListInfo {
     pub plist_name: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub remote_url: Option<String>,
+    /// Orientation of the whitelist entries relative to how the sample BC
+    /// appears in the read. `"forward"` (default) means no transformation;
+    /// `"reverse"` means the observed BC on the read is the reverse
+    /// complement of the whitelist entry (e.g., 10x Flex v2).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sample_bc_ori: Option<String>,
 }
 
 /// Info for a specific probe set (organism-specific, for Flex protocols).

tests/snapshots/cli-help/simpleaf_index___help.txt

@@ -53,3 +53,7 @@ Piscem Index Options:
           index build fails) [default: 1]
       --work-dir <WORK_DIR>
           The working directory where temporary files should be placed [default: ./workdir.noindex]
+      --dict <DICT>
+          Piscem dictionary backend: `auto` (default, emits Tiny artifacts for small references),
+          `sshash` (compact), or `tiny` (fast-path) [default: auto] [possible values: auto, sshash,
+          tiny]

tests/snapshots/cli-help/simpleaf_multiplex_quant___help.txt

@@ -62,6 +62,10 @@ Piscem Mapping Options:
           If piscem >= 0.7.0, enable structural constraints
       --max-ec-card <MAX_EC_CARD>
           Maximum cardinality equivalence class to examine [default: 4096]
+      --dict <DICT>
+          Piscem dictionary backend: `auto` (default), `sshash`, or `tiny`. Applies both to the
+          auto-built probe index (build time) and to map-sc (map time) [default: auto] [possible
+          values: auto, sshash, tiny]
 
 Output Options:
       --anndata-out  Generate an anndata (h5ad format) count matrix from the standard (matrix-market

tests/snapshots/cli-help/simpleaf_quant___help.txt

@@ -42,6 +42,9 @@ Piscem Mapping Options:
           second pass and consider k-mers having <= --max-hit-occ-recover hits [default: 1024]
       --max-read-occ <MAX_READ_OCC>
           Threshold for discarding reads with too many mappings [default: 2500]
+      --dict <DICT>
+          Piscem dictionary backend to use at map time: `auto` (default, honors the index's embedded
+          choice), `sshash`, or `tiny` [default: auto] [possible values: auto, sshash, tiny]
 
 Permit List Generation Options:
   -k, --knee