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

paired-end reads via --reads1 and --reads2
an output directory via --output
either a registered chemistry name via --chemistry, or a manual --geometry string plus --cell-bc-list for chemistries not in the registry
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.

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>

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 (e.g.
          '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: fw, rc, or both

          [default: 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

          [default: 16]

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

  -V, --version
          Print version

Permit List Options:
      --sample-correction-mode <SAMPLE_CORRECTION_MODE>
          Sample barcode correction mode

          [default: exact]
          [possible values: exact, 1-edit]

      --min-reads <MIN_READS>
          Minimum read count threshold for unfiltered permit list

          [default: 10]

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

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

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

Quantification Options:
  -r, --resolution <RESOLUTION>
          UMI resolution mode

          [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. 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

          [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 <FILE>
          JSON file overriding piscem's thread and decoder policy.

          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.

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

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:

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

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
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.
By default, probe expression is grouped at the gene level. Pass --usa only when the input probe set or pre-built index carries explicit splicing annotations.