Flexible record parsing and demultiplexing to FASTX/SAM/BAM/CRAM, splitcode-style.
The tool unmux reads multiple FASTX/SAM/BAM/CRAM inputs, identifies and extracts technical sequences (barcodes, UMIs, adapters) with error tolerance using the sassy approximate matcher, and writes FASTX/SAM/BAM/CRAM files with preserved per-record segment qualities, fanning a record pool out into per-sample, and optionally per-sample and per-library, files in a single pass.
It aims to do in one shot what otherwise would take a combination of separate tools.
barQC: extract, error-correct, and determine combinatorial cell barcodes and UMIs into uBAMfgbio FastqToBam: stitch multiple FASTQs into one unmapped BAM via read structures and SAM tagsfqtk: fast sample demultiplexing driven by per-read barcode structuresmatchbox: flexible read processor using matchbox scriptsPicard FastqToSam: convert raw FASTQs into an unmapped BAMqualrepair: repair the base qualities that splitcode mangles during extractionsamtools split: split one BAM into per-read-group (per-sample) BAMsseqproc: a general purpose read processor with a strict grammarsplitcode: identify, extract, and edit technical sequences from a declarative configsplitseq-toolbox: demultiplex SPLiT-seq combinatorial split-pool cell barcodesUMI-tools extract: pull UMIs out of records and onto the read names
Install with mamba, conda, or run directly with pixi:
pixi exec \
-c conda-forge -c bioconda \
unmux --helpProcess a SPLiT-seq run (splitcode's SPLiT-seq example) in one call: cDNA template on R1, 10 bp UMI and three rounds of 8 bp cell barcodes on R2, emitted as an unmapped BAM with CB and RX tags containing the error-corrected/canonical barcodes and their associated quality scores in tags CY and QX:
unmux "R1.fastq.gz" "R2.fastq.gz" \
--group "round1=round1.tags.txt" \
--group "round1::loc=1:78:86" \
--group "round1::dist=1" \
--group "round1::minFindsPerGroup=1" \
--group "round2=round2_3.tags.txt" \
--group "round2::loc=1:48:56" \
--group "round2::dist=1" \
--group "round2::minFindsPerGroup=1" \
--group "round3=round2_3.tags.txt" \
--group "round3::loc=1:10:18" \
--group "round3::dist=1" \
--group "round3::minFindsPerGroup=1" \
--extract "cdna=0:0:end" \
--extract "umi=1:0:10" \
--extract "bc1=@round1" \
--extract "bc2=@round2" \
--extract "bc3=@round3" \
--template "cdna" \
--tag "CB=bc1+bc2+bc3" \
--tag "CB::qual=CY" \
--tag "CB::sep=-" \
--tag "CB::qual-sep=%20" \
--tag "RX=umi" \
--tag "RX::qual=QX" \
--out "splitseq.unmapped.bam"- FASTX/SAM/BAM/CRAM in and out (SAM/BAM/CRAM written unmapped), with per-segment qualities carried through extraction.
- splitcode-style matching: tag groups, variable-length tags, location windows, mismatch/indel tolerance, sequential
next/prevanchoring,@extractspans, and error-correction to canonical barcodes. - Single-pass demultiplexing, optionally nested: split a pool into per-sample outputs and, if you like, each sample into sub-samples (a library of samples, sub-libraries of lysates, and so on), each written as its own FASTX/SAM/BAM/CRAM with
SM/LBread group identifiers. - Configured on the CLI or in sheets with the same grammar: flags repeat and accumulate, so a spec can be built up piece by piece (
--group g1::loc=... --group g1::dist=...), or written compactly with comma lists (--group g1::loc=...,dist=...).
See the contributing guide for more information.