draugr-demultiplexing

Draugr Demultiplexing Skill

Draugr (Demultiplexing wRapper And Updated GRiffin) is FGCZ's automated demultiplexing system for short-read sequencing runs.

• Interfaces with B-Fabric for sample metadata and barcodes
• Performs barcode validation/correction via the "Demultiplexing Wizard"
• Executes demultiplexing using bcl2fastq, bases2fastq
• Generates SUSHI import scripts and archives data to gStore

Repository: github.com/fgcz/draugr (active development — Falko Noé) | Python: 3.12+

Remote gotcha: draugr lives on two diverged remotes. The canonical/active repo is github.com/fgcz/draugr; a local ~/git/draugr clone usually points at gitlab.bfabric.org/Genomics/draugr, which is a stale mirror (its branches can lag the github ones by many commits and can look "merged" when github's are far ahead). Before reading, mapping, or basing work on draugr source — especially a feature branch like lib-specific-bases-mask — verify against the live github remote (git ls-remote / gh api repos/fgcz/draugr/...) and clone the exact branch fresh rather than trusting a local checkout: gh repo clone fgcz/draugr <dest> -- --branch <b> --single-branch --depth 1.

Architecture

Three-Component System

┌─────────────────────────────────────────────────────────────────┐
│                    AUTOMATED PIPELINE                           │
└─────────────────────────────────────────────────────────────────┘

1. populate_queue.py (cron)      2. monitor_runs.py (screen)      3. draugr.py (per-run)
   │                                │                                │
   │ Scans for completed runs       │ Watches queue folder           │ Executes demux
   │ Creates *-QUEUE markers        │ Spawns draugr subprocess       │ Updates B-Fabric
   │                                │                                │ Copies to gStore
   ▼                                ▼                                ▼
/export/local/data/           /export/local/analyses/         /srv/gstore/projects/
   (BCL files)                draugr_queue/ (markers)           pXXXXX/ (final)

Key Directories

Path	Purpose	Server
/export/local/data/	Raw sequencing runs (BCL files)	Demux server
/export/local/analyses/	Demultiplexing output (FASTQs)	Demux server
/export/local/analyses/draugr_queue/	Queue marker files	Demux server
/export/local/analyses/draugr_exec/	Draugr execution directory	Demux server
/srv/GT/analysis/datasets/	SUSHI import scripts	Shared storage
/srv/GT/analysis/falkonoe/dmx_logs/	Draugr log files	Shared storage
/srv/gstore/projects/pXXXXX/	Long-term archival storage	gStore

Integration Points

• B-Fabric: Metadata source (runs, samples, orders, barcodes), status updates, link registration
• gStore: Long-term archival via g-req commands
• SUSHI: Dataset generation and import script creation

CLI Commands Reference

draugr.py - Main Entry Point

The primary command for running demultiplexing on a sequencing run.

cd ~/git/draugr
uv run python draugr.py -r <RUN_FOLDER> [OPTIONS]

Required Arguments:

-r, --run-folder PATH          Path to the sequencing run folder (required)

Common Options:

-l, --login-config PATH        B-Fabric credentials YAML (default: ~/bfabric_cred/.bfabricpy.yml)
-o, --analysis-folder PATH     Output directory (default: /export/local/analyses)
-s, --scripts-destination PATH SUSHI scripts output (default: /srv/GT/analysis/datasets)
-lf, --logger-rep PATH         Log directory (default: /srv/GT/analysis/falkonoe/dmx_logs/test)
--version                      Show version and exit

Mode Control Flags:

--demux-only-mode              Skip RawQC and sample sheet generation
--skip-ss-generation           Skip sample sheet generation only
--skip-demux                   Skip demultiplexing (rerun post-processing)
--skip-post-demux              Skip post-demultiplexing steps
--skip-gstore-copy             Skip copying files to gStore
--rawqc-only-mode              Only generate RawQC report (exclusive)
--skip-rawqc                   Skip RawQC generation
-t, --test-mode                Test mode (no gStore copy, uses test B-Fabric)
-e, --disable-email            Disable email notifications
--disable-wizard               Skip barcode validation wizard

Reprocessing:

--reprocess-orders IDS         Comma-delimited order IDs to reprocess

Custom Tool Flags:

--custom-bcl2fastq-flags FLAGS Custom bcl2fastq arguments (pipe-delimited)
--custom-bases2fastq-flags FLAGS Custom bases2fastq arguments (semicolon-delimited)

Other Options:

--keep-internal-samples        Include internal/test samples in output
--disable-bfabric-sample-update Skip updating B-Fabric with results

monitor_runs.py - Queue Monitoring

Daemon that watches for queued runs and spawns draugr processes.

cd ~/git/draugr
uv run python monitor_runs.py \
  -q <QUEUE_FOLDER> \
  -r <RUNS_FOLDER> \
  --draugr-login-config <CONFIG> \
  --draugr-logger-rep <LOG_DIR> \
  --draugr-analysis-folder <ANALYSIS_DIR> \
  --draugr-scripts-destination <SCRIPTS_DIR> \
  [--dry-run]

Arguments:

-q, --queue-folder PATH                  Queue folder with *-QUEUE markers
-r, --runs-folder PATH                   Folder containing sequencing runs
--draugr-login-config PATH               B-Fabric credentials for draugr
--draugr-logger-rep PATH                 Log directory for draugr
--draugr-analysis-folder PATH            Analysis output directory
--draugr-scripts-destination PATH        SUSHI scripts destination
--dry-run                                Watch only, don't execute draugr

query_orders.py - Order Metadata Query

Retrieve sample/order metadata from B-Fabric.

cd ~/git/draugr
uv run python query_orders.py \
  -l <LOGIN_CONFIG> \
  -i <ORDER_ID_1> <ORDER_ID_2> ... \
  -o <OUTPUT_TSV>

Arguments:

-l, --login-config PATH        B-Fabric credentials (default: ~/.bfabricpy.yml)
-i, --order-ids IDS            Space-separated order IDs (required)
-o, --output-tsv PATH          Output TSV file path (required)

bin/populate_queue.py - Queue Population

Scans for completed runs and creates queue markers.

cd ~/git/draugr
uv run python -m bin.populate_queue \
  -d <DATA_FOLDER> \
  -q <QUEUE_FOLDER>

Arguments:

-d, --data-folder PATH         Directory containing run folders
-q, --queue-folder PATH        Queue output directory

Trigger Files: Creates {RUN_NAME}-QUEUE when RTAComplete.txt or RunUploaded.json is found.

Operational Tasks

Start Automated Monitoring

# SSH to demultiplexing server
ssh fgcz-h-031

# Load required modules
source /usr/local/ngseq/etc/lmod_profile && lmodInit
module load Dev/Python
module load Tools/bcl2fastq

# Start in screen session
screen -S draugr_monitor
cd /export/local/analyses/draugr_exec
uv run python monitor_runs.py \
  -q /export/local/analyses/draugr_queue \
  -r /export/local/data \
  --draugr-login-config ~/bfabric_cred/.bfabricpy.yml \
  --draugr-logger-rep /srv/GT/analysis/falkonoe/dmx_logs/prod \
  --draugr-analysis-folder /export/local/analyses \
  --draugr-scripts-destination /srv/GT/analysis/datasets

# Detach: Ctrl+A, D
# Reattach: screen -r draugr_monitor

Manually Run Single Run

cd ~/git/draugr
uv run python draugr.py \
  --run-folder /export/local/data/220728_A00460_0947_AHGFMLDRX2 \
  --login-config ~/bfabric_cred/.bfabricpy.yml \
  --analysis-folder /export/local/analyses \
  --logger-rep /srv/GT/analysis/falkonoe/dmx_logs/prod

Reprocess Specific Orders

cd ~/git/draugr
uv run python draugr.py \
  --run-folder /export/local/data/220728_A00460_0947_AHGFMLDRX2 \
  --reprocess-orders 12345,56789 \
  --login-config ~/bfabric_cred/.bfabricpy.yml

Test Mode (No gStore Copy)

cd ~/git/draugr
uv run python draugr.py \
  --run-folder /export/local/data/test_run \
  --test-mode

Query Order Metadata

cd ~/git/draugr
uv run python query_orders.py \
  -i 26102 27246 \
  -o ~/tmp/order_metadata.tsv

Supported Platforms

Illumina Instruments

Instrument	Example IDs
NovaSeq	A01251, LH00289, VH00139, VH00407
NextSeq	VH00139, VH00407, NS500415
iSeq	FS10001154, FS10002504
MiSeq	M01742, SY-410-1003, SH00201, SL00436
HiSeq	K00206, D00418, 700523F
MiniSeq	MN00710

Element Biosciences

Instrument	Example IDs
Aviti	AV233803

Demultiplexing Tools

Tool	Used For
bcl2fastq	Standard Illumina samples
bases2fastq	Element/Aviti samples

B-Fabric Integration

Run Status Workflow

PROCESSING → DEMULTIPLEXING → DEMULTIPLEXING_FINISHED (success)
                           ↘
                             DEMULTIPLEXING_FAILED (error)

Data Updated in B-Fabric

Entity	Fields Updated
Run	status, datafolder, serverlocation, processingtime, links (RawQC, DRAUGR_REPORT)
Sample	barcode1, barcode2 (if wizard corrected), read_count, processingtime

Custom Run Attributes (B-Fabric Web)

Set these on the run edit page to customize behavior:

Attribute	Values	Purpose
BasesMask	String	Custom bases mask for bcl2fastq/bases2fastq

Setting base masks via Python / bfabricpy

bf.save('run', {'id': RUN_ID, 'customattribute': [
    {'name': 'BasesMask', 'value': 'y50n*,I8n*,I24n*,y49n*'}
]})

Do NOT use the DraugrUI custom flags field for base masks — shell quoting bug causes -- flags to be mishandled.

Base mask defaults

The default mask for 10x dual-index runs is y28n*,I10n*,I10n*,y* (ILLUMINA_10X_DUAL_BASES_MASK in draugr/src/constants.py).

Always verify RunInfo.xml cycle counts before setting a custom mask.

Per-chemistry read structures and base masks

For the full per-chemistry table (3' GEX v2/v3/v4, 5' GEX/VDJ in all R1/R2/PE variants, ATAC solo, Multiome GEX+ATAC, Visium frozen/FFPE/CytAssist/HD, Flex GE/Protein v2), CellRanger internal barcode/UMI offsets, and recommended sequencing depths: see references/sequencing-read-requirements.md.

Key gotchas surfaced there:

• ATAC i5 uses lowercase y (e.g. y16n* / y24n*) — the i5 read IS the 10x cell barcode and must be emitted as a regular read so the full barcode is preserved; CellRanger ARC / cellranger-atac read it from there.
• Multiome ATAC i5 = 24bp (16bp barcode + 8bp linker), ATAC solo i5 = 16bp.
• Visium FFPE R2 = 50bp, frozen/CytAssist R2 = 90bp, VisiumHD R1 = 43bp — masks differ; do not reuse.
• 5' R1-only (SC5P-R1) requires R1 ≥ 41bp (43bp for v3) because RNA starts at offset 26/28 on R1.
• ATAC / Multiome ATAC currently need a manual bcl2fastq demux. Draugr's 10x dual-index path hardcodes the GEX mask y28n*,I10n*,I10n*,y* and ignores the BasesMask B-Fabric override, so lanes sent through draugr produce FASTQs that cellranger-atac count / cellranger-arc count reject (i5 ends up in I2 instead of R2; R1 too short). Falko has work in flight to honor BasesMask on the dual-index path; until then, run bcl2fastq by hand with the mask from the table (see spaceranger-fgcz SKILL → "Manual bcl2fastq workflow").

Mixed-run warning

BasesMask is global — it applies to all bcl2fastq/bases2fastq paths on the run. If a lane contains both standard samples and a special chemistry (e.g., Visium HD), setting a Visium HD mask will break the standard samples. In that case, leave BasesMask unset and run bcl2fastq manually for the special-chemistry path.

Troubleshooting

Log Locations

Log Type	Path
Draugr run logs	/srv/GT/analysis/falkonoe/dmx_logs/{prod,test}/{RUN_NAME}.log
Draugr error logs	/srv/GT/analysis/falkonoe/dmx_logs/{prod,test}/{RUN_NAME}.err
Monitor output	Console (screen session)

Common Issues

Issue	Likely Cause	Solution
Run stuck in "Demultiplexing"	draugr crashed	Check logs, restart with --demux-only-mode
Missing barcodes	B-Fabric entry error	Check wizard corrections in logs
gStore copy failed	Network/permission issue	Manually run g-req commands
Sample sheet errors	Invalid barcode config	Check B-Fabric sample setup
Low read counts	Barcode collisions	Check Hamming distance, review wizard output

Check Run Status

# Check B-Fabric via web
# URL: https://fgcz-bfabric.uzh.ch/bfabric/show.html?id={RUN_ID}

# Check queue status
ls -la /export/local/analyses/draugr_queue/

# Check if monitor is running
screen -ls | grep draugr

# View recent logs
tail -100 /srv/GT/analysis/falkonoe/dmx_logs/prod/$(ls -t /srv/GT/analysis/falkonoe/dmx_logs/prod/*.log | head -1)

Recovering from Failures

1. Check the log file for the specific error
2. Fix the issue (B-Fabric metadata, permissions, etc.)
3. Rerun with appropriate flags:
   • --demux-only-mode if sample sheets are already correct
   • --skip-rawqc if RawQC already completed
   • --skip-demux to only redo post-processing
   • --reprocess-orders to redo specific orders

Pipeline Flow

1. Setup
   ├─ Parse run folder (RunInfo.xml)
   ├─ Connect to B-Fabric
   ├─ Retrieve run/sample metadata
   └─ Update status → DEMULTIPLEXING

2. RawQC (optional)
   ├─ Generate pre-demux QC report
   └─ Link in B-Fabric

3. Sample Sheet Generation
   ├─ Build CSVs per sample type
   └─ Split by lane-order units

4. Demultiplexing Wizard (optional)
   ├─ Test subset for barcode issues
   ├─ Auto-correct systematic errors
   └─ Majority voting (75% threshold)

5. Demultiplexing
   ├─ Standard → bcl2fastq/bases2fastq
   ├─ 10X single → bcl2fastq/bases2fastq
   └─ 10x dual → bcl2fastq/bases2fastq

6. Post-Demultiplexing
   ├─ Update B-Fabric barcodes
   ├─ Rename/organize FASTQs
   ├─ Generate reports
   └─ Create dataset.tsv

7. gStore Archival
   ├─ Compute MD5 checksums
   ├─ Queue copy via g-req
   └─ Register links in B-Fabric

8. Completion
   ├─ Update status → DEMULTIPLEXING_FINISHED
   └─ Send notification email

SUSHI Script Execution

After draugr completes, run the generated SUSHI import scripts:

# SSH to appropriate server
ssh trxcopy@fgcz-h-031

# List available scripts
ls -lh /srv/GT/analysis/datasets/*_readQC_*.sh

# Run the script
cd /srv/GT/analysis/datasets
bash 220728_A00460_0947_AHGFMLDRX2_readQC_p12345,p67890.sh

# Scripts move to processed/ after completion

Repository Documentation

The draugr repository includes comprehensive documentation:

File	Content
docs/draugr.md	Main usage guide
docs/automated_execution.md	Automation setup
docs/draugr_advanced_usage.md	Advanced features
docs/query_orders.md	Query tool documentation

Quick Reference

Environment Setup

# Using uv (recommended)
cd ~/git/draugr
uv sync
uv run python draugr.py [args]

Module Loading (for tools)

source /usr/local/ngseq/etc/lmod_profile && lmodInit
module load Dev/Python
module load Tools/bcl2fastq Tools/Bases2Fastq

B-Fabric Credentials

Location: ~/.bfabric_cred/.bfabricpy.yml or ~/bfabric_cred/.bfabricpy.yml

GENERAL:
  default_config: PRODUCTION

PRODUCTION:
  login: <username>
  password: <hashed_password>
  base_url: http://fgcz-bfabric.uzh.ch/bfabric

---

Version: 1.1.0 Last Updated: 2026-04-23 Maintained by: FGCZ Bioinformatics Team