multiplex-quant command

The multiplex-quant command runs the end-to-end simpleaf pipeline for 10x Flex Gene Expression data and related multi-barcode assays. Unlike quant command, which is designed around standard single-cell RNA-seq chemistries and a single cell-barcode whitelist, multiplex-quant handles the extra resources and steps required for Flex assays:

• Flex chemistry lookup from the chemistry registry
• probe set selection by organism
• probe-set CSV to FASTA conversion and probe_t2g.tsv generation (excluded probes become index decoys)
• probe index construction with piscem build when needed
• cell barcode whitelist resolution
• sample barcode list resolution
• piscem map-scrna
• multi-barcode permit-list generation with alevin-fry generate-permit-list
• alevin-fry collate and alevin-fry quant

multiplex-quant typically runs against a registered Flex chemistry such as 10x-flexv1-gex-3p or 10x-flexv2-gex-3p, in which case the geometry, cell BC whitelist, sample BC list, and orientations are auto-resolved from the preset. 10x Flex Configuration B is registered as 10x-flexv2-gex-3p-config-b; it shares the v2 whitelists and probe sets but has its own geometry and reads the sample barcode off the opposite strand, so it is selected by name rather than by overriding the v2 preset. For chemistries not in the registry, the preset can be replaced with manual overrides — at minimum --geometry and --cell-bc-list, with optional --probe-set, --sample-bc-list, --expected-ori, and --sample-bc-ori as needed. piscem and alevin-fry must be configured with set paths.

Overview

The command needs:

1. paired-end reads via --reads1 and --reads2
2. an output directory via --output
3. either a registered chemistry name via --chemistry, or a manual --geometry string plus --cell-bc-list for chemistries not in the registry
4. an organism via --organism when using automatic probe-set selection (i.e. when --probe-set is not provided)

If the chemistry registry contains the needed metadata, simpleaf can automatically download and cache the probe set, the cell barcode whitelist, and the sample barcode list. If you already have local resources, you can override these defaults with --index, --probe-set, --cell-bc-list, or --sample-bc-list.

The default output is the standard Matrix Market directory under af_quant/alevin. If you pass --anndata-out, simpleaf will additionally write an AnnData .h5ad file at af_quant/alevin/quants.h5ad.

Barcode-correction controls

Correction decisions are made during alevin-fry generate-permit-list and reused by collation through its compiled correction plan. simpleaf exposes the same typed controls without duplicating alevin-fry’s protocol defaults:

Option	Inherited default	Destination
--cell-bc-correction {unique,frequency}	unique	permit-list generation
--cell-bc-neighborhood {hamming-1,substitution-or-shift-1}	protocol/filter-specific	permit-list generation
--cell-bc-confidence <CONFIDENCE>	0.975	permit-list generation
--sample-bc-correction {exact,unique,frequency}	exact	permit-list generation
--sample-bc-neighborhood {hamming-1,substitution-or-shift-1}	hamming-1 for non-exact correction	permit-list generation
--sample-bc-confidence <CONFIDENCE>	0.975	permit-list generation
--gpl-memory-limit <SIZE>	512 MiB	deferred sample-Frequency buffers
--gpl-tmp-dir <DIR>	permit-list output directory	compressed deferred runs
--collate-memory-limit <SIZE>	2 GiB	collation buffers

Confidence accepts decimals or exact fractions such as 39/40. Memory accepts human-readable values such as 512MiB, 1GiB, and 4GB. Values are validated before mapping begins but forwarded in their original spelling. If an override is omitted, simpleaf emits no corresponding child flag and alevin-fry remains the source of truth for the default.

The old hidden --sample-correction-mode option remains accepted for script compatibility. exact becomes --sample-bc-correction exact; 1-edit becomes --sample-bc-correction unique --sample-bc-neighborhood substitution-or-shift-1. New scripts should use the explicit controls above.

For multiplex output, the resulting AnnData object is intended to preserve the extra sample-level structure of the experiment:

• obs_names are sample-qualified cell identifiers
• obs["cell_barcode"] stores the corrected cell barcode without the sample prefix
• obs["sample_name"] stores the sample / probe-barcode assignment
• var["gene_id"] remains the matrix feature identifier
• var["gene_symbol"] is added when a gene_id_to_name.tsv mapping is available from the probe set or index
• uns stores the standard gpl_info, collate_info, quant_info, and simpleaf_map_info records, and for multiplex runs it also stores sample_info plus simpleaf_multiplex_quant_info

The relevant options (which you can obtain by running simpleaf multiplex-quant --help) are below:

quantify a multiplexed sample (e.g. 10x Flex, or any custom multi-barcode protocol)

Usage: simpleaf multiplex-quant [OPTIONS] --output <OUTPUT> --reads1 <READS1> --reads2 <READS2>

Options:
  -c, --chemistry <CHEMISTRY>
          Chemistry name (e.g. 10x-flexv1-gex-3p). Provides defaults for geometry, cell BC
          whitelist, sample BC list, and probe set. All can be overridden individually. If omitted,
          --geometry and --cell-bc-list are required

  -g, --geometry <GEOMETRY>
          Override the read geometry string (for example,
          `1{b[16]u[12]x[0-3]hamming(f[TTGCTAGGACCG],1)s[10]x:}2{r:}`)

      --organism <ORGANISM>
          Target organism for automatic probe set selection

          [possible values: human, mouse]

      --cell-bc-list <CELL_BC_LIST>
          Path to cell barcode whitelist (one barcode per line, overrides chemistry default)

      --expected-ori <EXPECTED_ORI>
          Expected read orientation (case-insensitive; `either` is also accepted, as a synonym for
          `both`)

          [default: both]
          [possible values: fw, rc, both]

      --sample-bc-ori <SAMPLE_BC_ORI>
          Sample barcode orientation: `forward` (whitelist matches read as-is) or `reverse`
          (reverse-complement the whitelist before lookup). Overrides the chemistry preset's
          `sample_bc_ori` when set. Useful for cycle-plan variants (e.g. 10x Flex Configuration B)
          where the sample BC is read off the opposite strand from the canonical preset. Vocabulary
          matches the preset JSON and alevin-fry's `--sample-bc-ori`

          [possible values: forward, reverse]

  -o, --output <OUTPUT>
          Path to output directory

  -t, --threads <THREADS>
          Number of threads to use. Values below two warn and use two

          [default: 16]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Advanced Barcode Correction Options:
      --cell-bc-correction <CELL_BC_CORRECTION>
          Cell-barcode collision policy (inherited default: unique)

          [possible values: unique, frequency]

      --cell-bc-neighborhood <CELL_BC_NEIGHBORHOOD>
          One-error cell-barcode neighbourhood. When omitted, alevin-fry chooses the
          protocol/filter-specific default

          [possible values: hamming-1, substitution-or-shift-1]

      --cell-bc-confidence <CONFIDENCE>
          Frequency confidence as a decimal or exact fraction. The inherited default is 97.5% for
          RNA and 90% for ATAC

      --sample-bc-correction <SAMPLE_BC_CORRECTION>
          Sample-barcode correction policy (inherited default: exact)

          [possible values: exact, unique, frequency]

      --sample-bc-neighborhood <SAMPLE_BC_NEIGHBORHOOD>
          Sample-barcode neighbourhood for non-exact correction (inherited default: Hamming-1)

          [possible values: hamming-1, substitution-or-shift-1]

      --sample-bc-confidence <CONFIDENCE>
          Sample-Frequency confidence as a decimal or exact fraction (inherited default: 97.5%)

Advanced Resource Options:
      --gpl-memory-limit <SIZE>
          Deferred GPL buffer budget (inherited default: 512 MiB)

      --gpl-tmp-dir <DIR>
          Temporary directory for compressed GPL correction runs (inherited default: the GPL output
          directory)

      --collate-memory-limit <SIZE>
          Collation buffer budget (inherited default: 2 GiB)

      --compress [<CODEC>]
          Compress the collated RAD file with a per-chunk codec. Compression is ON by default (lz4);
          pass `--compress none` to disable it, or `--compress zstd` (needs an alevin-fry build with
          the `zstd` feature — otherwise alevin-fry rejects `zstd` when the collate step runs).
          `--compress` with no value also selects lz4. The per-chunk framing keeps the collated RAD
          chunk-seekable, so the parallel reader still engages

          Possible values:
          - lz4:  lz4 (pure-Rust; always available in alevin-fry)
          - zstd: zstd (needs an alevin-fry built with the `zstd` feature)
          - none: No compression

          [default: lz4]

Mapping Options:
  -i, --index <INDEX>
          Path to pre-built probe index (overrides auto-build)

  -1, --reads1 <READS1>
          Comma-separated list of R1 FASTQ files

  -2, --reads2 <READS2>
          Comma-separated list of R2 FASTQ files

Probe Set Options:
      --probe-set <PROBE_SET>
          Path to probe set CSV or FASTA (overrides auto-download). If a CSV is provided, it is
          converted to FASTA and a t2g map is generated automatically

      --excluded-probes <EXCLUDED_PROBES>
          How probes flagged `included = FALSE` in a probe set CSV are treated when simpleaf builds
          the probe index. `decoy` (default) indexes their sequences as piscem decoys so reads from
          an excluded probe are recognised and discarded instead of being mis-assigned to a retained
          probe; `ignore` drops them from the reference entirely. Excluded probes are never
          quantified in either mode. Has no effect on a pre-built `--index`

          Possible values:
          - decoy:  Index excluded probes as decoys (piscem poison k-mers): reads from them are
            recognised and discarded rather than mis-assigned to a retained probe
          - ignore: Drop excluded probes from the reference entirely (the behavior of earlier
            releases)

          [default: decoy]

      --kmer-length <KMER_LENGTH>
          k-mer length for probe index building

          [default: 23]

Reference Options:
  -m, --t2g-map <T2G_MAP>
          Path to a transcript-to-gene map file. Use this instead of --probe-set when working with a
          transcriptome reference rather than a probe set

      --usa
          Resolve expression separately into spliced and unspliced counts (USA mode). Requires
          splicing-aware probe annotations: either a probe CSV with a `region` column (`spliced` /
          `unspliced`) or a pre-built index with an adjacent 3-column t2g file. By default,
          expression is grouped at the gene level.

          USA mode resolves over genes, so a probe-set reference is quantified by `quant` rather
          than per probe by `quant-probe`, which rejects a 3-column map. `--probe-mtx` is therefore
          not available with `--usa`.

      --sample-bc-list <SAMPLE_BC_LIST>
          Path to sample/probe barcode file with rotation mapping (overrides auto-download).
          3-column TSV: observed, canonical, sample_name

      --samples <SHEET>
          Select and name a subset of the chemistry's samples without hand-writing barcodes. TSV
          mapping a registry sample id to your name, one per line (e.g. `BC001<TAB>kidney`); a
          single-column line keeps the registry id as the name. The barcode sequences — every
          spelling — always come from the chemistry's registry list, so omitting a spelling (the
          usual cause of silent demultiplexing loss) is impossible. Requires --chemistry; cannot be
          combined with --sample-bc-list

Quantification Options:
      --gene-level
          Quantify per gene with alevin-fry's `quant`, even for a probe-set reference, which is
          otherwise quantified per probe by `quant-probe`.

          Counts differ slightly between the two. Over probes, a UMI whose reads do not single out
          one probe of its gene (they tie between two of its probes, or every read matches both) has
          no winning probe: `cr-like` drops it and the EM strategies divide it between those probes,
          while the gene axis counts it once. Pass this, together with `--excluded-probes ignore`,
          to reproduce a run made before per-probe quantification and excluded-probe decoys became
          the defaults. `--probe-mtx` is not available with it, since only `quant-probe` writes that
          matrix.

  -r, --resolution <RESOLUTION>
          UMI resolution mode

          `parsimony-gene` and `parsimony-gene-em` build equivalence classes with reads already
          projected to genes, so no per-probe assignment survives to sum. They are not available
          where a probe-set reference is quantified per probe: use `parsimony` or `parsimony-em`, or
          pass `--gene-level`.

          [default: cr-like]
          [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.

      --umi-edit-dist <N>
          UMI edit distance (0 or 1), forwarded to alevin-fry as `--umi-edit-dist`.

          With `cr-like` or `cr-like-em`, 1 merges UMIs of the same cell and feature that differ at
          one position before resolution, as Cell Ranger does. That correction is not available with
          `--usa`, and it turns off alevin-fry's small-cell fast path, so `--small-thresh` has no
          effect. With the `parsimony` strategies, 1 links UMIs one mismatch apart in the UMI graph
          and 0 links only identical ones.

          Left unset, alevin-fry's own default applies (0 for `cr-like` and `cr-like-em`, 1 for the
          `parsimony` strategies).

Piscem Mapping Options:
      --skipping-strategy <SKIPPING_STRATEGY>
          The skipping strategy to use for k-mer collection

          [default: permissive]
          [possible values: permissive, strict]

      --struct-constraints
          Enable structural constraints when mapping

      --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]

      --decoder <MODE>
          Gzip decoder selection passed to piscem: `auto`, `serial`, `parallel`, or `parallel=N`.

          `auto` lets piscem adapt the mapping/decode split while the run proceeds. `serial` gives
          mapping the whole budget. `parallel` forces the parallel decoder where the input allows
          it; `parallel=N` fixes N decode slots per gzip input and stops the adaptation. Inputs that
          cannot be read positionally (FIFOs, process substitution) stay serial regardless.

          [default: auto]

      --thread-policy <JSON_OR_PATH>
          Piscem thread and decoder policy, as inline JSON or a path to a JSON file.

          A value beginning with `{` is parsed as inline JSON; anything else is a path. Every field
          is optional and defaults to a measured value; an unrecognised field is an error rather
          than a silent no-op. Currently understood: `{"parallel_decode": {"min_threads_per_stream":
          8}}`, the number of threads that must be free per gzip input before the parallel decoder
          is engaged at all.

Permit List Options:
      --min-reads <MIN_READS>
          Minimum read count threshold for unfiltered permit list

          [default: 10]

Output Options:
      --anndata-out
          Generate an anndata (h5ad format) count matrix from the standard (matrix-market format)
          output

      --dump-molecules
          Also write alevin-fry's molecule table (`alevin/molecules.parquet`): one row per resolved
          molecule (cell barcode, UMI, feature, supporting reads, status), before molecules are
          summed into the count matrix.

          Requires an alevin-fry whose `quant-probe` (or `quant`, for a run quantified per gene) has
          `--dump-molecules`; simpleaf checks this before any work starts.

      --probe-mtx
          Also write the probe x cell count matrix that the gene matrix is summed from
          (`alevin/probe_quants_mat.mtx`, with its row and column files).

          Only a run quantified per probe has one, so this needs a probe-set reference (the
          chemistry's registered probe set, `--probe-set`, or a pre-built `--index` that simpleaf
          built from a probe CSV; not `--t2g-map`), neither `--usa` nor `--gene-level`, and an
          alevin-fry whose `quant-probe` has `--probe-mtx`. simpleaf checks all of these before any
          work starts.

Chemistry preset structure

A registered chemistry name (e.g. 10x-flexv1-gex-3p) selects a JSON entry in simpleaf’s chemistry registry (chemistries.json) that bundles every protocol-level parameter the pipeline needs. Each behavioral field has a corresponding CLI override; only a small set of internal metadata fields are not user-controllable.

Fields stored in a chemistry preset:

• geometry — piscem geometry string describing R1/R2 layout (cell BC, UMI, sample BC, biological-read offsets). CLI override: --geometry.
• expected_ori — orientation of the biological read relative to the reference (fw / rc / both). CLI override: --expected-ori.
• plist_name and remote_url — cached filename and download URL for the cell barcode whitelist. CLI override: --cell-bc-list (pass a local path; the URL itself is an internal detail).
• sample_bc_list (Flex only) — a nested record with plist_name, remote_url, and sample_bc_ori. CLI overrides: --sample-bc-list for the 3-column TSV path, and --sample-bc-ori (forward / reverse) for the orientation.
• probe_sets (Flex only) — an organism-keyed dictionary, e.g. { "human": {...}, "mouse": {...} }. Each entry stores a probe-CSV download URL plus probe-set metadata. CLI overrides: --organism selects which entry is consulted, and --probe-set bypasses the lookup entirely by supplying a local CSV/FASTA.
• version and meta — internal preset versioning and free-form metadata. Not exposed at the CLI; they do not affect pipeline behavior.

How --chemistry and --organism together locate a Flex configuration:

1. --chemistry resolves to a registered preset entry. That single lookup fixes the protocol parameters for the run: geometry, expected_ori, the cell barcode whitelist, the sample barcode list, and the sample barcode orientation. Any of these can be replaced individually with the corresponding CLI override flag listed above.
2. For Flex presets the preset’s probe_sets dict is keyed by organism. --organism (human, mouse, …) selects which entry’s probe CSV will be auto-downloaded. --probe-set supersedes the lookup, so when --probe-set is given --organism becomes optional.
3. --chemistry itself can also be omitted. In that case you must supply --geometry and --cell-bc-list at the CLI (and, for sample-multiplexed runs, --sample-bc-list, --sample-bc-ori, and --probe-set as well), since there is no preset to draw defaults from.

For non-Flex chemistries (presets without a probe_sets map), --organism is recorded in run metadata but is otherwise ignored.

Running without --chemistry

--chemistry can be omitted entirely when the protocol you want to run is not in the registry, or when you want full manual control over every resource. With no preset to draw defaults from, the pipeline requires you to supply every resource it would otherwise auto-resolve. simpleaf bails with an explicit error if any required input is missing.

Required CLI flags when --chemistry is omitted:

• --geometry — the piscem geometry string. Error: No geometry specified. Provide --geometry or --chemistry.
• --cell-bc-list — local path to the cell barcode whitelist (one barcode per line). Error: No cell barcode whitelist specified. Provide --cell-bc-list or --chemistry.
• --sample-bc-list — local path to the 3-column sample BC TSV (observed<TAB>canonical<TAB>sample_name). Error: Chemistry has no sample barcode list URL. Provide --sample-bc-list.
• --probe-set or --index — either a local probe-set CSV/FASTA or a pre-built piscem probe index. Without a preset, simpleaf cannot auto-download a probe set from a probe_sets dict. Error: No chemistry specified and no --probe-set or --index provided.

Optional CLI flags (defaults apply if unset):

• --expected-ori — defaults to both.
• --sample-bc-ori — when unset, no --sample-bc-ori is forwarded to alevin-fry, so its own default (forward) takes effect.
• --resolution — defaults to cr-like.
• --organism — irrelevant when --probe-set or --index is supplied (the preset’s probe_sets lookup is skipped).

Example: run a chemistry that is not yet in the registry (e.g. a 10x Flex v2 Configuration B variant) by supplying all resources manually:

$ simpleaf multiplex-quant \
    --geometry '1{b[16]u[12]x:}2{r[50]f[CCCATATAAGAAAACCTGAATACGCGGTT]s[10]x:}' \
    --expected-ori fw \
    --sample-bc-ori forward \
    --cell-bc-list /path/to/cell_bc_whitelist.txt \
    --sample-bc-list /path/to/sample_bc_rotation.tsv \
    --probe-set /path/to/probe_set.csv \
    --reads1 sample_R1.fastq.gz \
    --reads2 sample_R2.fastq.gz \
    --output flex_out

If your protocol becomes stable and reusable, consider proposing it as a chemistry preset upstream so future users can run it with just --chemistry.

Resource resolution

multiplex-quant resolves resources in the following order:

• Probe index: If --index is provided, simpleaf accepts either a simpleaf index output directory, its index/ subdirectory, the piscem_idx prefix within that directory, or a multiplex probe-index directory/prefix. It will reuse adjacent metadata and t2g files when present.
• Probe set: If --probe-set is provided, it overrides the registry entry. A CSV probe set is converted into a FASTA plus a gene-level probe_t2g.tsv automatically, and if probe region annotations are present it also produces a USA-mode t2g for --usa. A FASTA input is accepted as-is, and simpleaf generates an identity-style t2g mapping from the FASTA headers.
• Excluded probes: Probes a CSV probe set flags with included = FALSE (10x’s __EXCLUDED probes) are never quantified: they appear in neither the reference FASTA nor any t2g map, and do not contribute to the gene set. By default (--excluded-probes decoy) their sequences are written to probe_decoys.fa and passed to piscem build --decoy-paths, so reads that originate from an excluded probe are recognised and discarded instead of being mis-assigned to a retained probe. --excluded-probes ignore restores the previous behavior of dropping them entirely. The choice is recorded in probe_set_info.json (excluded_probes, num_excluded, num_decoy) and auto-built indices are cached separately per mode. The option has no effect on a pre-built --index.
• Automatic probe-set selection: If neither --index nor --probe-set is provided, simpleaf looks up the requested --organism in the selected chemistry’s registered probe sets, downloads the matching probe CSV if needed, and builds a cached probe index. The index is cached under $ALEVIN_FRY_HOME/probe_indices with a simpleaf_probe_index.json record of what built it: the registered piscem (its version and its executable’s path, size and modification time), the k-mer length and the --excluded-probes mode. A cached index is reused only when that record matches the current run; otherwise (for example after a piscem upgrade, which may change the index format) it is rebuilt, which takes a few seconds. Indices cached by simpleaf releases that did not write this record are rebuilt once. A cached index that cannot be rebuilt (for example, the cache is read-only, or the probe set is no longer in $ALEVIN_FRY_HOME/probe_indices/downloads and cannot be downloaded) is used as is, with a warning.
• Cell barcode whitelist: This is resolved from the selected chemistry’s permit-list metadata in the registry.
• Sample barcode list: This is resolved from --sample-bc-list if provided, otherwise from the selected chemistry’s registry metadata.
• Sample barcode orientation: By default, simpleaf forwards the chemistry preset’s declared sample_bc_ori (when present) to alevin-fry. Pass --sample-bc-ori {forward,reverse} to override the preset value at the CLI level. This is useful for cycle-plan variants where the sample BC is read from the opposite strand vs the canonical preset — for example, 10x Flex Configuration B (R1=28 / R2=90) uses --sample-bc-ori forward whereas the default 10x Flex v2 Configuration A preset declares reverse. The CLI value is forwarded verbatim to alevin-fry --sample-bc-ori; if nothing is set on the CLI and the preset is silent, alevin-fry defaults to forward.

USA-mode requirements

--usa is optional. If it is not provided, multiplex-quant collapses probe expression to the gene level even when splicing annotations are available.

If --usa is provided, the reference must carry splicing-aware annotations:

• For probe CSV input, the CSV must contain a region column and each included probe must have value spliced or unspliced.
• For pre-built indices, simpleaf must be able to find an adjacent 3-column t2g such as t2g_3col.tsv or probe_t2g_usa.tsv.
• FASTA probe sets do not encode splicing status, so they are not compatible with --usa unless you also provide an explicit splicing-aware --t2g-map.

If the required splicing annotations are not available, simpleaf will stop with an error that explains which input is missing the needed information and suggests rerunning without --usa.

--usa resolves over genes, so it runs alevin-fry quant rather than quant-probe; see Per-probe quantification.

Per-probe quantification

A probe-set reference is quantified per probe: alevin-fry quant-probe resolves UMIs over the probes the reads hit, then sums each gene’s probes into its count. This is the default, and it is the subcommand that decides the axis — nothing is recorded in the permit list, and quant is unchanged.

Four things keep a run on quant instead:

• the reference is not a probe set. --t2g-map marks a transcriptome, where resolving per target would discard UMIs shared by the isoforms of one gene; a pre-built --index given without --probe-set is quantified per probe only when simpleaf’s own metadata says it holds a probe set (probe_set_info.json beside a multiplex-quant probe index, or args.probe-csv in the index_info.json of a simpleaf index --probe-csv output). Any other index could hold either kind of reference, so it is quantified per gene, and the log says so; pass --probe-set with the probe set it was built from to quantify it per probe.
• the configured alevin-fry has no quant-probe (releases before 0.19.0). simpleaf reads this from alevin-fry quant-probe --help, because the version string does not tell builds apart, and says so in the log when it falls back.
• --usa, which resolves spliced and unspliced counts over a 3-column map. The probe axis has no counterpart for that and rejects such a map outright, so a USA run is quantified per gene exactly as before.
• --gene-level, which asks for the gene axis. Together with --excluded-probes ignore it reproduces a run made before per-probe quantification and excluded-probe decoys became the defaults; --gene-level alone still drops the reads of excluded probes, which changes a few counts.

--resolution parsimony-gene and parsimony-gene-em build equivalence classes with reads already projected to genes, so no per-probe assignment survives to sum. On a run that goes to quant-probe they are refused before any work starts, pointing at parsimony / parsimony-em, or at --gene-level.

Two optional outputs are forwarded only when requested:

• --dump-molecules writes the molecule table af_quant/alevin/molecules.parquet, with one row per resolved molecule. It is a quant and quant-probe option and does not depend on the axis.
• --probe-mtx writes the probe x cell matrix that the gene matrix is summed from (af_quant/alevin/probe_quants_mat.mtx, with its row and column files). Only quant-probe writes it, so it needs a run that goes there: with --usa, --gene-level, a non-probe-set reference, or an alevin-fry without quant-probe, simpleaf stops and names which of the four applies.

Each needs an alevin-fry that has the option, checked before any work starts. The matching quant.json entries (molecule_table; probe_mtx, num_probes, probe_nnz) are copied under quant_outputs into simpleaf_multiplex_quant_info.json.

Examples

Use a registry-backed Flex chemistry with automatic resource resolution:

$ export ALEVIN_FRY_HOME=/path/to/af_home
$ simpleaf multiplex-quant \
    --chemistry 10x-flexv2-gex-3p \
    --organism human \
    --reads1 sample_R1.fastq.gz \
    --reads2 sample_R2.fastq.gz \
    --output flex_out

Use local probe-set and sample-barcode files instead of downloading them:

$ simpleaf multiplex-quant \
    --chemistry 10x-flexv1-gex-3p \
    --organism mouse \
    --probe-set /path/to/probe_set.csv \
    --sample-bc-list /path/to/sample_bc.tsv \
    --reads1 lane1_R1.fastq.gz,lane2_R1.fastq.gz \
    --reads2 lane1_R2.fastq.gz,lane2_R2.fastq.gz \
    --output flex_out

Use a pre-built probe index:

$ simpleaf multiplex-quant \
    --chemistry 10x-flexv2-gex-3p \
    --organism human \
    --index /path/to/simpleaf_index_output \
    --reads1 sample_R1.fastq.gz \
    --reads2 sample_R2.fastq.gz \
    --output flex_out

Request AnnData output in addition to the Matrix Market output:

$ simpleaf multiplex-quant \
    --chemistry 10x-flexv1-gex-3p \
    --organism human \
    --reads1 sample_R1.fastq.gz \
    --reads2 sample_R2.fastq.gz \
    --output flex_out \
    --anndata-out

Request USA-mode probe quantification:

$ simpleaf multiplex-quant \
    --chemistry 10x-flexv2-gex-3p \
    --organism human \
    --probe-set /path/to/probe_set.csv \
    --usa \
    --reads1 sample_R1.fastq.gz \
    --reads2 sample_R2.fastq.gz \
    --output flex_out

Override the sample barcode orientation for a cycle-plan variant (e.g. 10x Flex v2 Configuration B, R1=28 / R2=90):

$ simpleaf multiplex-quant \
    --chemistry 10x-flexv2-gex-3p \
    --organism human \
    --geometry '1{b[16]u[12]x:}2{r[50]f[CCCATATAAGAAAACCTGAATACGCGGTT]s[10]x:}' \
    --sample-bc-ori forward \
    --reads1 sample_R1.fastq.gz \
    --reads2 sample_R2.fastq.gz \
    --output flex_out

Output

The command creates the requested output directory and writes:

• af_map/: the piscem mapping output
• af_quant/: the alevin-fry permit-list, collate, and quantification output
• af_quant/simpleaf_map_info.json: parsed mapping metadata copied into the quantification directory for downstream consumers such as AnnData conversion
• af_quant/simpleaf_multiplex_quant_info.json: multiplex pipeline metadata copied into the quantification directory so it can be embedded into AnnData uns
• af_quant/gene_id_to_name.tsv: optional gene ID to gene symbol/name mapping copied when available from the probe set or index
• af_quant/alevin/quants.h5ad: optional AnnData output written when --anndata-out is requested
• af_quant/alevin/molecules.parquet: optional molecule table written when --dump-molecules is requested
• af_quant/alevin/probe_quants_mat.mtx (with probe_quants_mat_rows.txt and probe_quants_mat_cols.txt): optional probe x cell matrix written when --probe-mtx is requested
• simpleaf_multiplex_quant_info.json: a metadata record describing the resolved inputs, executed commands, and step timings

Notes

• multiplex-quant is specific to registered Flex GEX chemistries and related multi-barcode protocols. For standard scRNA-seq chemistries and general custom geometries, use quant command.
• The Flex pipeline currently uses piscem for mapping.
• The count matrix is always per gene. On an alevin-fry with quant-probe it is summed from per-probe counts (see Per-probe quantification); pass --gene-level to resolve over genes instead. Pass --usa only when the input probe set or pre-built index carries explicit splicing annotations; it also resolves over genes.