Attention

These docs have moved. The current simpleaf documentation lives at https://combine-lab.github.io/simpleaf and is the only version that is updated. This readthedocs site is a frozen snapshot of the 0.27.0 docs and will not track later releases.

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. For chemistries not in the registry (or cycle-plan variants such as 10x Flex Configuration B), 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 command.

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.

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 -h) 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 override: ``forward`` (whitelist matches read as-is) or ``reverse`` (reverse-complement the whitelist before lookup). Overrides the chemistry preset's ``sample_bc_ori`` when set; otherwise the preset value (if any) is used. Vocabulary matches the chemistry preset JSON and ``alevin-fry --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
  -V, --version                  Print version

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)
      --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
      --usa                          Resolve expression into separate spliced and unspliced counts. This requires splicing-aware probe annotations: either a probe CSV with a ``region`` column containing ``spliced`` / ``unspliced`` values, or a pre-built index with an adjacent 3-column t2g file
      --sample-bc-list <SAMPLE_BC_LIST>
                                      Path to sample/probe barcode file with rotation mapping. 3-column TSV: observed, canonical, sample_name. Overrides the chemistry preset's auto-downloaded sample BC list.

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 to use at map time: ``auto`` (default, honors the index's embedded choice), ``sshash``, or ``tiny`` [default: auto] [possible values: auto, sshash, tiny]

Quantification Options:
      --gene-level               Quantify per gene with ``quant``, even for a probe-set reference, which is otherwise quantified per probe by ``quant-probe``
  -r, --resolution <RESOLUTION>  UMI resolution mode [default: cr-like] [possible values: cr-like, cr-like-em, parsimony, parsimony-em, parsimony-gene, parsimony-gene-em]

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]

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:

  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 and does not depend on the axis, and --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 the probe matrix, so --probe-mtx 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 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. The collated RAD is compressed per-chunk with lz4 by default; pass --compress none for an uncompressed file, or --compress zstd (requires a zstd-enabled alevin-fry build)

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