Running a sample

The easiest way to process a sample is arcane express, which runs all three stages and cleans up temporary files itself:

arcane express --index myindex --R1 $R1 --R2 $R2 --out results/sample \
    -c v3 --kneemethod distance --threads 16

This page covers the options that change the result.

Chemistries

Every sample-processing command needs to know the barcode and UMI layout. Give it either --chemistry or --bc-umi — exactly one is required.

10x Genomics: --chemistry/-c

--chemistry sets the barcode length, UMI length, and inclusion list:

-c	Barcode	UMI	Inclusion list	Protocol
v2	16 bp	10 bp	737K-august-2016	3'
v3	16 bp	12 bp	3M-february-2018	3'
v4	16 bp	12 bp	3M-3pgex-may-2023	3'
v3-5p	16 bp	12 bp	3M-5pgex-jan-2023	5'

The lists ship with the package. --configpath (or --inclusion_path for arcane correct) points at a different directory if needed.

Other protocols: --bc-umi

For non-10x data (e.g. Drop-seq), give the barcode and UMI lengths directly.

arcane express --bc-umi 12 8 ...

--bc-umi BARCODE UMI takes two integers. Without --chemistry there is no built-in list. If the technology provides a custom inclusion list, use --inclusion-list. (required for --onlist and non 10x chemistries).

arcane express --bc-umi 12 8 --inclusion-list valid_barcodes.txt.gz ...

Note

If an inclusion list is provided, all barcodes on the list are assumed to be valid and invalid barcodes (barcodes not on the list) are corrected if they have a Hamming-distance-one neighbor on the inclusion list. The knee-method (or alternative strategies to remove empty droplets is performed after correction). If no inclusion list is provided (or the inclusion list should be ignored, i.e., provide --bc-umi) valid barcodes are first determined via the knee method (or --forcecells, --minreads, ...) and Hamming-distance-one neighbors are corrected afterwards.

Read direction

--direction/-d tells Arcane which strand the cDNA read (R2) is on:

Value	Use for
f	Default. 10x 3' protocols (v2, v3, v4).
r	5' protocols (v3-5p).

--map-antisense tries to map reads mapping antisense to the gene instead of discarding them.

Removing empty droplets

Arcane must be told how to separate cells from empty droplets. One of these four is required — there is no default:

Option	Behaviour
--kneemethod distance	Knee point by maximum distance. The most popular choice.
--kneemethod density	Knee point by density.
--forcecells INT	Keep exactly the INT barcodes with the highest read count. Or all if higher than distinct barcodes in the sample.
--minreads INT	Keep barcodes with more than INT reads.
--onlist	Keep every barcode on the inclusion list/ Requires an inclusion list.

--plots (or --plot on arcane correct) writes the barcode rank plot, which is worth checking whenever cell numbers look wrong.

Mapping modes

--mapping-mode controls what is recorded per read:

• color-only (default) — assign each read to a gene. One row per gene in the count matrix.

• splice-aware — additionally record whether the evidence is exonic, intronic, or spanning an exon-exon junction. The matrix gets four rows per gene, suffixed in genes.tsv.gz:

  Suffix	Meaning
  -E	only exon k-mers
  -U	unspliced (only intron k-mers)
  -S	spliced (exon and exon-exon junction k-mers)
  -I	intermediate (k-mers from exon-exon junctions and from introns)

  Use this for RNA-velocity analyses.

If you run the steps separately, pass the same --mapping-mode to arcane map and arcane count — count needs it to interpret the array correctly.

UMI resolution modes

--umi-mode on express (--mode on arcane count) selects how UMIs within a cell are collapsed into counts. UMIs are first clustered into Hamming-distance-1 connected components.

Mode	Behaviour
network	Default. Within a UMI cluster, count each UMI-gene pair whose supporting UMIs reach the cluster's mean read count once; if no pair exist, but the gene (summed over all UMIs for the gene) is above the mean, count the gene once. If no gene of the cluster reached the threshold count the gene with the highest UMI count once (e.g., cluster with a single UMI-gene pair, but a low UMI count, avoids discarding to many read at low duplicate rates).
unique_unique	No clustering; only unambiguous UMI-gene pairs.
unique_all	No clustering; count all unique UMI-gene pairs.
threshold	Count each gene whose supporting UMIs reach the cluster's mean read count.
all	Count all genes in a cluster once.
max	Count only the maximum-support gene of a cluster.
unique_cluster	Count only clusters with a unique gene assignment.

The non-default modes exist mainly for the comparisons in the paper. Depending on UMI length and error probabilities unique-all or all are good alternatives.

Threads

--threads on arcane express is the total budget; it is split across reading and mapping automatically. Reader threads only help when you pass more than one input file.

Running the steps separately gives finer control: arcane map takes --threads-mapping (default 8) and --threads-reading (default 4) independently.

Temporary files

The intermediate barcode and UMI-gene arrays can be large. --tmpdir puts them in a temporary folder (arcane creates a arcane_tmpdir/<seed> subdirectory with a random seed and removes it afterwards). --keep-tmp keeps them, which is what you want if you plan to re-run arcane count with a different --umi-mode without re-mapping (mainly for internal debugging).

Running the steps separately

Useful for pipelines, per-step timing, or re-running just the counting. The three commands, in order:

# 1. barcode correction: R1 -> corrected barcodes + counts
arcane correct \
    --R1 $R1_files \
    --chemistry v3 \
    --kneemethod distance \
    --output results/sample \
    --threads 8 \
    --tmpdir results/tmp

# 2. mapping: R1 + R2 -> UMI-gene array
arcane map \
    --index myindex \
    --R1 $R1_files \
    --R2 $R2_files \
    --outprefix results/sample_ \
    --chemistry v3 \
    --mapping-mode color-only \
    --threads-mapping 13 --threads-reading 2 \
    --tmpdir results/tmp

# 3. UMI resolution -> count matrix
arcane count \
    --counts results/tmp/arcane_barcode_counts_sample.data \
    --umi-gene-array results/tmp/arcane_ug_sample.data \
    --chemistry v3 \
    --ngenes $(wc -l < index/human/arcane_human_genes.txt) \
    --out results/sample \
    --mode network

Notes:

• correct and map must share a --tmpdir; count reads their intermediates from there. The sample part of the intermediate filenames is derived from the input filename.
• arcane map needs both --R1 and --R2, in matching order — it reads the barcode/UMI from R1 alongside the sequence from R2.
• --ngenes is the line count of the genes.txt from arcane filter.
• Keep --chemistry (or --bc-umi) and --mapping-mode consistent across all three commands.