Quickstart

This page takes you from FASTQ files to a count matrix. It assumes Arcane is installed and you are in the arcane conda environment:

conda activate arcane

1. Get an index

Download a prebuilt human or mouse index, or build your own. You should end up with two files sharing a prefix:

myindex.hash
myindex.info

2. Run arcane express

arcane express runs barcode correction, mapping, and UMI resolution in one go:

arcane express \
    --index myindex \
    --R1 sample_S1_L001_R1_001.fastq.gz \
    --R2 sample_S1_L001_R2_001.fastq.gz \
    --out results/sample \
    --chemistry v3 \
    --kneemethod distance \
    --threads 16

• --R1 are the barcode+UMI reads, --R2 the cDNA sequence reads (CellRanger naming). Both accept multiple files — pass all lanes at once, keeping R1 and R2 in the same order.
• --chemistry must match the 10x Genomics chemistry your sample was generated with (v2, v3, v4, or v3-5p). For non-10x data, use --bc-umi instead. See chemistries.
• A cell-calling mode (to remove empty droplets) is required: one of --kneemethod, --forcecells, --minreads, or --onlist. There is no default — see cell calling.
• --out is a prefix, not a directory. It may contain a path, e.g. /path/to/results/samplename. The directory must exist.

5' protocol

For a 5' library, pass --chemistry v3-5p --direction r. --direction f (the default) is correct for the 10x 3' protocol.

3. Read the output

Three files appear next to your --out prefix:

results/sample_counts.mex.gz    # the gene x cell count matrix
results/sample_genes.tsv.gz     # gene ids, one per line = matrix rows
results/sample_barcodes.tsv.gz  # cell barcodes, one per line = matrix columns

The matrix is a gzipped MatrixMarket-like sparse triplet file:

%% Arcane count matrix
%
36601 4823 9127438
15 1 3
15 7 1
...

After the header line (<ngenes> <ncells> <nnz>), each line is <gene_row> <cell_col> <count>, both 1-based, indexing into genes.tsv.gz and barcodes.tsv.gz respectively. See File formats for the full details and how to load it.

Multiple lanes

Pass every file, in matching order:

arcane express \
    --index myindex \
    --R1 sample_S1_L001_R1_001.fastq.gz sample_S1_L002_R1_001.fastq.gz \
    --R2 sample_S1_L001_R2_001.fastq.gz sample_S1_L002_R2_001.fastq.gz \
    --out results/sample -c v3 --kneemethod distance --threads 16

Arcane warns if a paired R1/R2 filename looks mismatched, but it trusts the order you give — check it.

Common adjustments

You want	Use
A known number of cells	--forcecells 5000
A minimum read count per cell	--minreads 500
Keep every barcode on the inclusion list	--onlist
A different knee method	--kneemethod density
A 5' library	--chemistry v3-5p --direction r
Non-10x data (e.g. Drop-seq)	--bc-umi 12 8
Spliced/unspliced counts (RNA velocity)	--mapping-mode splice-aware
Map antisense reads	--map-antisense
QC plots	--plots
Progress output while mapping	--progress

See Running a sample for what these mean, or arcane express --help for the full list.

Running many samples

If you process several samples on one machine, load the index into shared memory once instead of having every process read its own copy — see Shared memory.

Running the steps separately

arcane express is a wrapper. For pipelines that need per-step control or timing, run correct → map → count yourself; see Running a sample.