fix: forward --barcode-length, expose --with-position, retire two no-ops

Three findings from a pass over the option surface, comparing what simpleaf
accepts against what the child tools actually take.

`atac process --barcode-length` was parsed, documented with its own default of
16, and never forwarded; piscem spells it `--bclen`. Because both defaults are
16 this was invisible, but a non-16bp ATAC chemistry got a 16 bp barcode
extracted -- and since the length is written into the RAD tags and read back by
generate-permit-list, sort and deduplicate, every stage agreed with the wrong
value. This is the same failure as `--thr`, so both are now pinned by tests
that assert the built command line, on the ATAC and RNA sides alike.

`--use-chr` and `--check-kmer-orphan` are hidden and marked deprecated. piscem
accepts them and warns "not supported by piscem-rs and will be ignored", so
simpleaf was advertising behaviour no supported piscem implements.

`--with-position` is now exposed on `quant`. libradicl has a positional record
type and alevin-fry already dispatches on it in generate-permit-list, collate
and quant, so the flag needed no downstream counterpart -- only piscem had to
be told. Verified end to end on the 66.6 M-read pbmc set: the pipeline runs
through to a matrix identical to the non-positional run (0 differing entries of
5,573,896), with the RAD growing 2.6 GB -> 4.5 GB. Deliberately not offered on
`multiplex-quant`: there is no multi-barcode positional record type, and
get_record_type_from_prelude checks multi-barcode first, so such a RAD would be
read back as plain multi-barcode.

Also documents why the chemistry registry is served from `dev` rather than the
release branch, replacing a "TODO: change to main repo when we are ready" that
read as an oversight rather than a decision.

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,13 @@
   `multiplex-quant`, and `atac process`.
 * `--tmp-dir` and `--ram-limit-gib` are forwarded to `piscem build` from both
   index commands.
+* `--with-position` on `quant`, forwarded to piscem. Records each mapped read's
+  position in the RAD file; alevin-fry detects the positional record type from
+  the RAD header and adapts on its own, so no downstream option changes. The
+  RAD is larger (2.6 GB -> 4.5 GB on a 66.6 M-read set) and counts are
+  unchanged. Not offered on `multiplex-quant`: there is no multi-barcode
+  positional record type, and the multi-barcode layout wins when the record
+  type is resolved.
 * `--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`
@@ -41,6 +48,15 @@
 ### Bug fixes
 
 * `atac process --thr` was parsed and then never forwarded to piscem.
+* `atac process --barcode-length` was likewise never forwarded (piscem spells it
+  `--bclen`). Both defaults are 16, so it silently did nothing when set: any
+  non-16bp ATAC chemistry got a 16 bp barcode extracted, and because the length
+  is written into the RAD tags and read back by every later stage, the whole
+  pipeline agreed with itself and nothing looked wrong.
+* `atac process --use-chr` and `--check-kmer-orphan` are hidden and documented
+  as deprecated no-ops. piscem >= 0.22 accepts them for backward compatibility
+  and warns that they are ignored, so they were advertising behaviour that no
+  supported piscem implements.
 * `multiplex-quant` did not validate its `--geometry`, so a typo surfaced as a
   mapping failure partway through a run rather than as an error up front.
 * `multiplex-quant` logged its `map-sc` invocation as "piscem map-scrna cmd".

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

@@ -122,6 +122,14 @@ Piscem Mapping Options:
       --struct-constraints
           Enable structural constraints when mapping
 
+      --with-position
+          Record the position of each mapped read in the RAD file.
+          
+          alevin-fry detects the positional record type from the RAD header and adapts
+          automatically, so no downstream option needs to change. The RAD file is larger. Not
+          available for `multiplex-quant`: there is no multi-barcode positional record type, and the
+          multi-barcode layout takes precedence when the record type is resolved.
+
       --ignore-ambig-hits
           Skip checking of the equivalence classes of k-mers that were too ambiguous to be otherwise
           considered (passing this flag can speed up mapping slightly, but may reduce specificity)

src/atac/commands.rs

@@ -369,8 +369,10 @@ pub struct ProcessOpts {
     #[arg(long, help_heading = "Advanced Options")]
     pub no_poison: bool,
 
-    /// use chromosomes as color
-    #[arg(long, help_heading = "Advanced Options")]
+    /// Deprecated no-op. piscem-rs does not implement this; piscem >= 0.22
+    /// accepts the flag for backward compatibility and warns that it is
+    /// ignored. Retained so existing command lines keep working.
+    #[arg(long, help_heading = "Advanced Options", hide = true)]
     pub use_chr: bool,
 
     /// threshold to be considered for pseudoalignment
@@ -389,10 +391,10 @@ pub struct ProcessOpts {
     #[arg(long, help_heading = "Advanced Options")]
     pub no_tn5_shift: bool,
 
-    /// Check if any mapping kmer exist for a mate which is not mapped,
-    /// but there exists mapping for the other read. If set to true and a
-    /// mapping kmer exists, then the pair would not be mapped
-    #[arg(long, help_heading = "Advanced Options")]
+    /// Deprecated no-op. piscem-rs does not implement this; piscem >= 0.22
+    /// accepts the flag for backward compatibility and warns that it is
+    /// ignored. Retained so existing command lines keep working.
+    #[arg(long, help_heading = "Advanced Options", hide = true)]
     pub check_kmer_orphan: bool,
 
     /// determines the maximum cardinality equivalence class (number of

src/atac/process.rs

@@ -79,6 +79,15 @@ fn push_advanced_piscem_options(
     // used its own default. piscem's `map-sc-atac` takes it, so pass it on.
     piscem_map_cmd.arg("--thr").arg(opts.thr.to_string());
 
+    // Same story as `--thr`: `--barcode-length` was parsed and documented (with
+    // its own default of 16) and then never forwarded, so piscem fell back to
+    // its own default -- identical at 16, which is why this went unnoticed, but
+    // any user who set it got their value silently ignored. piscem spells it
+    // `--bclen`.
+    piscem_map_cmd
+        .arg("--bclen")
+        .arg(opts.barcode_length.to_string());
+
     Ok(())
 }
 
@@ -706,4 +715,75 @@ mod tests {
             err
         );
     }
+
+    fn args_of(cmd: &std::process::Command) -> Vec<String> {
+        cmd.get_args()
+            .map(|a| a.to_string_lossy().into_owned())
+            .collect()
+    }
+
+    /// Every scalar option that `atac process` accepts and hands to piscem must
+    /// actually appear on the child command line.
+    ///
+    /// Both `--thr` and `--barcode-length` were parsed, documented with their
+    /// own defaults, and then never forwarded. Neither failure was visible from
+    /// the outside: piscem's defaults happened to match, so the options simply
+    /// did nothing when set. This pins the pass-through so the next one is a
+    /// test failure rather than a silent no-op.
+    #[test]
+    fn advanced_piscem_options_reach_the_child_command() {
+        let mut opts = base_process_opts();
+        opts.thr = 0.55;
+        opts.barcode_length = 20;
+        opts.max_ec_card = 1234;
+        opts.max_hit_occ = 77;
+        opts.max_hit_occ_recover = 888;
+        opts.max_read_occ = 99;
+
+        let mut cmd = std::process::Command::new("echo");
+        push_advanced_piscem_options(&mut cmd, &opts).expect("should build args");
+        let args = args_of(&cmd);
+
+        for (flag, value) in [
+            ("--thr", "0.55"),
+            ("--bclen", "20"),
+            ("--max-ec-card", "1234"),
+            ("--max-hit-occ", "77"),
+            ("--max-hit-occ-recover", "888"),
+            ("--max-read-occ", "99"),
+        ] {
+            let pos = args.iter().position(|a| a == flag).unwrap_or_else(|| {
+                panic!("{} was never forwarded to piscem; args: {:?}", flag, args)
+            });
+            assert_eq!(
+                args.get(pos + 1).map(String::as_str),
+                Some(value),
+                "{} was forwarded with the wrong value; args: {:?}",
+                flag,
+                args
+            );
+        }
+    }
+
+    /// The boolean passthroughs are emitted only when set.
+    #[test]
+    fn boolean_piscem_options_are_conditional() {
+        let mut opts = base_process_opts();
+        opts.ignore_ambig_hits = false;
+        opts.no_poison = false;
+
+        let mut cmd = std::process::Command::new("echo");
+        push_advanced_piscem_options(&mut cmd, &opts).expect("should build args");
+        let args = args_of(&cmd);
+        assert!(!args.iter().any(|a| a == "--ignore-ambig-hits"));
+        assert!(!args.iter().any(|a| a == "--no-poison"));
+
+        opts.ignore_ambig_hits = true;
+        opts.no_poison = true;
+        let mut cmd = std::process::Command::new("echo");
+        push_advanced_piscem_options(&mut cmd, &opts).expect("should build args");
+        let args = args_of(&cmd);
+        assert!(args.iter().any(|a| a == "--ignore-ambig-hits"));
+        assert!(args.iter().any(|a| a == "--no-poison"));
+    }
 }

src/simpleaf_commands.rs

@@ -221,6 +221,16 @@ pub struct MapQuantOpts {
     #[arg(long, help_heading = "Piscem Mapping Options")]
     pub struct_constraints: bool,
 
+    /// Record the position of each mapped read in the RAD file.
+    ///
+    /// alevin-fry detects the positional record type from the RAD header and
+    /// adapts automatically, so no downstream option needs to change. The RAD
+    /// file is larger. Not available for `multiplex-quant`: there is no
+    /// multi-barcode positional record type, and the multi-barcode layout takes
+    /// precedence when the record type is resolved.
+    #[arg(long, help_heading = "Piscem Mapping Options")]
+    pub with_position: bool,
+
     /// Skip checking of the equivalence classes of k-mers that were too ambiguous to be otherwise
     /// considered (passing this flag can speed up mapping slightly, but may reduce specificity)
     #[arg(

src/simpleaf_commands/quant.rs

@@ -215,6 +215,13 @@ fn push_advanced_piscem_options(
         piscem_quant_cmd.arg("--struct-constraints");
     }
 
+    // alevin-fry resolves the positional record type from the RAD header
+    // (KnownRecordType::RnaShortPos) and switches record types itself, so this
+    // needs no counterpart on the generate-permit-list / collate / quant calls.
+    if opts.with_position {
+        piscem_quant_cmd.arg("--with-position");
+    }
+
     piscem_quant_cmd
         .arg("--max-hit-occ")
         .arg(format!("{}", opts.max_hit_occ));
@@ -733,4 +740,69 @@ mod tests {
             err
         );
     }
+
+    /// The piscem passthroughs on the RNA path must reach the child command.
+    ///
+    /// Same rationale as the ATAC-side test: `--thr` and `--barcode-length`
+    /// both rotted there by being parsed and never forwarded, which is
+    /// invisible from outside when the child's default happens to match.
+    #[test]
+    fn advanced_piscem_options_reach_the_child_command() {
+        let opts = parse_quant_opts(&[
+            "quant",
+            "-c",
+            "10xv3",
+            "-o",
+            "/tmp/out",
+            "-r",
+            "cr-like",
+            "--knee",
+            "--map-dir",
+            "/tmp/mapped",
+            "--with-position",
+            "--struct-constraints",
+            "--max-hit-occ",
+            "77",
+        ]);
+        let mut cmd = std::process::Command::new("echo");
+        push_advanced_piscem_options(&mut cmd, &opts).expect("should build args");
+        let args: Vec<String> = cmd
+            .get_args()
+            .map(|a| a.to_string_lossy().into_owned())
+            .collect();
+
+        assert!(
+            args.iter().any(|a| a == "--with-position"),
+            "--with-position was never forwarded; args: {:?}",
+            args
+        );
+        assert!(args.iter().any(|a| a == "--struct-constraints"));
+        let pos = args
+            .iter()
+            .position(|a| a == "--max-hit-occ")
+            .expect("flag");
+        assert_eq!(args.get(pos + 1).map(String::as_str), Some("77"));
+
+        // and the booleans stay off when not requested
+        let opts = parse_quant_opts(&[
+            "quant",
+            "-c",
+            "10xv3",
+            "-o",
+            "/tmp/out",
+            "-r",
+            "cr-like",
+            "--knee",
+            "--map-dir",
+            "/tmp/mapped",
+        ]);
+        let mut cmd = std::process::Command::new("echo");
+        push_advanced_piscem_options(&mut cmd, &opts).expect("should build args");
+        let args: Vec<String> = cmd
+            .get_args()
+            .map(|a| a.to_string_lossy().into_owned())
+            .collect();
+        assert!(!args.iter().any(|a| a == "--with-position"));
+        assert!(!args.iter().any(|a| a == "--struct-constraints"));
+    }
 }

src/utils/chem_utils.rs

@@ -10,8 +10,6 @@ use std::path::Path;
 use strum::EnumIter;
 use strum::IntoEnumIterator;
 
-// TODO: Change to main repo when we are ready
-
 pub(crate) type CustomChemistryMap = HashMap<String, CustomChemistry>;
 
 static GEOMETRY_KEY: &str = "geometry";

src/utils/constants.rs

@@ -6,6 +6,17 @@
 pub(crate) static CUSTOM_CHEMISTRIES_PATH: &str = "custom_chemistries.json";
 
 pub(crate) static CHEMISTRIES_PATH: &str = "chemistries.json";
+
+/// The chemistry registry is served from `dev`, deliberately, and not from the
+/// release branch. Chemistry definitions are data rather than code: a new or
+/// corrected geometry needs to reach users who are already on a released
+/// simpleaf, without waiting for the next release. `simpleaf chemistry refresh`
+/// therefore always fetches the newest registry.
+///
+/// The trade-off is that a released binary's chemistry definitions are whatever
+/// `dev` holds at the time of the fetch, not what shipped with it. Keep `dev`'s
+/// copy of `resources/chemistries.json` in sync when landing registry changes
+/// on `main`, or a released simpleaf will not see them.
 pub(crate) static CHEMISTRIES_URL: &str =
     "https://raw.githubusercontent.com/COMBINE-lab/simpleaf/dev/resources/chemistries.json";
 

tests/snapshots/cli-help/simpleaf_atac_process___help.txt

@@ -99,9 +99,6 @@ Advanced Options:
           the mapping results will be identical to those obtained as if no poison table was added to
           the index
 
-      --use-chr
-          use chromosomes as color
-
       --thr <THR>
           threshold to be considered for pseudoalignment
 
@@ -120,11 +117,6 @@ Advanced Options:
       --no-tn5-shift
           do not apply Tn5 shift to mapped positions
 
-      --check-kmer-orphan
-          Check if any mapping kmer exist for a mate which is not mapped, but there exists mapping
-          for the other read. If set to true and a mapping kmer exists, then the pair would not be
-          mapped
-
       --max-ec-card <MAX_EC_CARD>
           determines the maximum cardinality equivalence class (number of (txp, orientation status)
           pairs) to examine (cannot be used with --ignore-ambig-hits)

tests/snapshots/cli-help/simpleaf_quant___help.txt

@@ -38,6 +38,14 @@ Piscem Mapping Options:
       --struct-constraints
           Enable structural constraints when mapping
 
+      --with-position
+          Record the position of each mapped read in the RAD file.
+          
+          alevin-fry detects the positional record type from the RAD header and adapts
+          automatically, so no downstream option needs to change. The RAD file is larger. Not
+          available for `multiplex-quant`: there is no multi-barcode positional record type, and the
+          multi-barcode layout takes precedence when the record type is resolved.
+
       --ignore-ambig-hits
           Skip checking of the equivalence classes of k-mers that were too ambiguous to be otherwise
           considered (passing this flag can speed up mapping slightly, but may reduce specificity)