CLI reference

arcane is a multi-command tool, like git. Every subcommand supports --help:

arcane --help
arcane express --help

Global options

Option	Description
--version	Show version and exit.
--debug, -D	Output debugging information. Repeat for more detail (-DD).

Subcommands

Command	Purpose
filter	Filter cDNA and extract genes; prepares the reference.
index	Build the index from a filtered reference.
express	Barcode correction + mapping + UMI resolution in one command.
correct	Barcode correction only.
map	Map sequence reads to genes.
count	UMI resolution and counting.
bulk	Bulk RNA-seq quantification.
load	Load an index into shared memory.
remove	Remove an index from shared memory.

Config files

index, express, correct, count, and map accept --cfg/--config with a YAML file, and also pick up a default config automatically if present:

Command	Default config files searched
index	packaged config/index.yaml, then config/index.yaml, index.yaml
map	config/map.yaml, map.yaml
correct	config/correct.yaml, correct.yaml
count	config/count.yaml, count.yaml
express	config/express.yaml, express.yaml

Only index.yaml ships with the package; it supplies the hash table defaults (see Building an index).

---

arcane filter

Filter cDNA and extract genes. Produces the reference FASTA that arcane index requires. See Building an index.

arcane filter --fasta genome.fa.gz --gtf annotation.gtf.gz \
    --mask '<mask>' --name human --prefix index/human

Option	Description
--gtf (required)	CellRanger GTF annotation file.
--fasta (required)	DNA (genome) FASTA file.
--prefix	Output folder for the new files.
--mask MASK	Gapped k-mer mask, quoted, e.g. '#__##_##__#'.
-w, --kmersize INT	k-mer size, for a contiguous k-mer.
--name	Species name used in output filenames. A trailing _ is appended if absent.
--include-attribute K:V [...]	GTF attribute values to include.
--exclude-attribute K:V [...]	GTF attribute values to exclude.
--extract_genes	Additionally write a FASTA of whole genes (start to end, introns included).

Exactly one of --mask / -w is required. --include-attribute and --exclude-attribute are mutually exclusive.

---

arcane index

Build the index. Writes <index>.hash and <index>.info. See Building an index.

arcane index --index myindex --ref index/human/arcane_human_ref.fa.gz \
    --mask '<mask>' -n 2_000_000_000

Option	Default	Description
--index (required)		Name/prefix of the resulting index.
--ref FASTA (required)		Reference created by arcane filter (a *ref.fa.gz).
-n, --nobjects INT (required)		Number of k-mers to store. No default — see sizing.
--mask MASK		Gapped k-mer mask, quoted.
-k, --kmersize INT		k-mer size, for a contiguous k-mer.
-c, --choices INT	2	Number of hash functions l used to build a (l, b) Cuckoo hash table.
--rcmode {f,max}	f	f (forward) for strand-specific protocols such as 10x scRNA-seq; max (canonical) for strand-unspecific protocols such as bulk RNA-seq.
--mature	off	Only store k-mers that occur in mature RNA molecules.
-b, -p, --bucketsize INT (required)	4 via config	Elements per bucket.
--fill FLOAT	0.95 via config	Desired fill rate (< 1.0). Slots = ceil(n/fill).
--subtables INT	auto	Number of subtables; subtables+1 threads are used. Must be odd.
--threads-read INT		Reader threads.
--threads-split INT		Splitter threads.
--hashfunctions, --functions SPEC	default	default, random, or func0:func1:func2:func3.
--aligned	off	Power-of-two-bit-aligned buckets: faster, but larger. Default is unaligned.
--statistics, --stats {none,summary,details,full}	summary	Level of statistics detail.
-W, --weakthreads INT	8 via config	Threads for computing weak k-mers.
--groupprefixlength INT	2 via config	Compute weak k-mers in groups sharing a prefix of this length.
--maxwalk INT	500 via config	Max random-walk length before an insertion fails.
--maxfailures INT	0 via config	Continue after this many failures; -1 = forever.
--walkseed INT	42 via config	Seed for insertion random walks.
--cfg, --config		YAML config file.

Exactly one of --mask / -k is required, and it must match the one used in arcane filter.

---

arcane express

Combined barcode correction, mapping, and UMI resolution. See the Quickstart.

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

Required arguments

Option	Description
--R1 FILE [...]	Barcode+UMI FASTQ files (CellRanger R1).
--R2 FILE [...]	Sequence FASTQ files (CellRanger R2), same order as R1.
--index	Index built with arcane index.
--out	Output prefix for the final results.

Parameters defining the chemistry (exactly one of the two is required)

Option	Description
-c, --chemistry {v2,v3,v4,v3-5p}	10x chemistry version; sets barcode length, UMI length, and inclusion list.
--bc-umi BASES BASES	Barcode and UMI length in bases, for non-10x protocols.

Parameters for barcode correction (exactly one mode is required)

Option	Default	Description
--forcecells INT		Keep only the INT barcodes with the highest read count.
--minreads INT		Keep only barcodes with more than INT reads.
--onlist	off	Keep all barcodes on the inclusion list.
--kneemethod {distance,density}		Cell-calling knee method.
--inclusion-list		Path to an alternative inclusion list (optional); not needed if --chemistry is given.

Parameters for gene mapping

Option	Default	Description
-d, --direction {f,r}	f	Direction of read 2 (cDNA). f for the 10x 3' protocol, r for 5' (or most DropSeq data).
--mapping-mode {splice-aware,color-only}	color-only	Mapping rules. Color-only provides gene-level information, splice-aware the gene with its splice state, see Mapping modes
--lookahead INT	8	Prefetch lookahead.
--map-antisense	off	Try to map unmapped reads in antisense direction.
--progress	off	Progress info for the mapping step.

Parameters for UMI resolution

Option	Default	Description
--umi-mode MODE	network	One of unique_unique, unique_all, all, max, threshold, network, unique_cluster.

Optional parameters

Option	Default	Description
--shared	off	Load the index from shared memory.
--threads INT	4	Maximum threads across all steps.
--buffersizes INT	65536	Buffer size for inter-thread communication.
--configpath	packaged	Directory containing the inclusion lists.
--tmpdir	arcane_tmpdir	Directory for intermediate results.
--keep-tmp	off	Keep the temporary files.
--plots	off	Create QC plots.
--cfg, --config		YAML config file.

---

arcane correct

Barcode correction. See Running the steps separately.

arcane correct --R1 $R1 --chemistry v3 --kneemethod distance \
    --output results/sample --tmpdir results/tmp

Option	Default	Description
--R1, -b FILE [...] (required)		Input FASTQ files with barcode-UMI reads.
-o, --output (required)		Output prefix for the barcode-UMI file, bitmap, and mapping.
--tmpdir		Directory for intermediate results.
--cfg, --config		YAML config file.

Parameters defining the chemistry (exactly one of --chemistry / --bc-umi is required)

Option	Description
-c, --chemistry {v2,v3,v4,v3-5p}	10x chemistry version.
--bc-umi BASES BASES	Barcode and UMI length in bases.
--inclusion-list	Path to an alternative optional inclusion list; not needed if --chemistry is given.

Parameters for barcode correction (exactly one mode is required)

Option	Default	Description
--forcecells INT		Keep only the INT barcodes with the highest read count.
--minreads INT		Keep only barcodes with more than INT reads.
--onlist	off	Keep all barcodes on the inclusion list (only valid if an inclusion list is available).
--kneemethod {distance,density}		Cell-calling knee method.
--plot	off	Create the barcode plot.
--inclusion_path	packaged	Directory containing the inclusion lists.
--threads INT	one per file	Threads for reading the files.
--compressionthreads INT	2	Threads to decompress .gz/.xz FASTQ.

---

arcane map

Map sequence reads to genes.

arcane map --index myindex --R1 $R1 --R2 $R2 --outprefix results/sample_ \
    --chemistry v3 --mapping-mode color-only --tmpdir results/tmp

Option	Default	Description
--index (required)		Arcane index.
--R2 FILE [...] (required)		Sequence FASTQ files (mostly R2).
--R1 FILE [...] (required)		Barcode/UMI FASTQ files (mostly R1), same order as R2.
--mapping-mode {color-only,splice-aware} (required)		Mapping rules.
--shared	off	Load the index from shared memory.
--outprefix	.	Result path/prefix.
-d, --direction {f,r}	f	Direction of read 2 (cDNA). f for the 10x 3' protocol, r for 5'.
--threads-mapping INT	8	Threads used to map reads.
--threads-reading INT	4	Threads used to read sequence files. Values > 1 only help with more than one file.
--lookahead INT	8	Prefetch lookahead.
--map-antisense	off	Try to map unmapped reads in antisense direction.
--buffersizes INT	65536	Buffer size for inter-thread communication.
--progress	off	Show the number of mapped reads.
--tmpdir		Directory for intermediate results.
--cfg, --config		YAML config file.

Parameters defining the chemistry (exactly one is required)

Option	Description
-c, --chemistry {v2,v3,v4,v3-5p}	10x chemistry version.
--bc-umi BASES BASES	Barcode and UMI length in bases.

---

arcane count

UMI resolution and counting; writes the count matrix.

arcane count --counts results/tmp/arcane_barcode_counts_sample.data \
    --umi-gene-array results/tmp/arcane_ug_sample.data \
    --chemistry v3 --ngenes 38606 --out results/sample --mode network

Option	Default	Description
-C, --counts (required)		Reads per valid barcode, produced by arcane correct.
-a, --umi-gene-array (required)		UMI-gene array, produced by arcane map.
--ngenes INT (required)		Number of distinct genes; the number of lines in the genes.txt from arcane filter or arcane map.
-o, --out (required)		Output prefix for the count matrix.
--mode MODE	network	UMI resolution mode: unique_unique, unique_all, all, max, threshold, network, unique_cluster. See UMI resolution modes.
--mapping-mode {splice-aware,color-only}	color-only	Must match what arcane map used, so genes are counted correctly.
--threads INT	4	Threads for reading the files.
--plot	off	Plot the UMI histogram before and after resolution.
--cfg, --config		YAML config file.

Parameters defining the chemistry (exactly one is required)

Option	Description
-c, --chemistry {v2,v3,v4,v3-5p}	10x chemistry version; sets barcode and UMI length.
--bc-umi BASES BASES	Barcode and UMI length in bases.

---

arcane load

Load an index into shared memory. See Shared memory.

arcane load --name myindex

Option	Description
--name (required)	Name (prefix) of the index to load.
-k, --keep-running	Keep running until killed by SIGTERM/SIGINT; the shared object is removed on exit.

---

arcane remove

Remove an index from shared memory.

arcane remove --name myindex

Option	Description
--name (required)	Name (prefix) of the index to remove.

arcane bulk

Quantification of bulk RNA data

arcane bulk arcane --fastq $R1 --pairs $R2 --index myindex --out results -d f

Option	Default	Description
--index (required)		Arcane index.
--fastq FILE [...] (required)		Sequence FASTQ files.
--pairs FILE [...] (required)		Sequence FASTQ files for paired end reads. Same order as --fastq.
--mapping-mode {color-only,splice-aware} (required)		Mapping rules.
--shared	off	Load the index from shared memory.
--outprefix	.	Result path/prefix.
-d, --direction {f,r,f-r,r-f,u} (required)		Direction of reads.
--threads-mapping INT	8	Threads used to map reads.
--threads-reading INT	1	Threads used to read sequence files. Values > 1 only help with more than one file.
--lookahead INT	8	Prefetch lookahead.
--buffersizes INT	65536	Buffer size for inter-thread communication.
--progress	off	Show the number of mapped reads.