caddsv 2.0

CADD-SV Structural Variant scoring Workflow

CADD-SV v2.0

CADD-SV is a command-line tool for scoring structural variants (SVs). The caddsv command wraps the packaged Snakemake workflow, prepares input files, runs scoring, and copies final score tables into a stable output directory.

Quick Start

Install from a source checkout:

conda create -n caddsv python=3.12 pip
conda activate caddsv
git clone https://github.com/kircherlab/CADD-SV.git
cd CADD-SV
pip install .

Download the annotation bundle:

caddsv get annotations --annotations-dir /data/caddsv/annotations

Score a BED file:

caddsv run examples/variants.bed \
  --annotations-dir /data/caddsv/annotations \
  --output-dir /data/caddsv/runs/variants \
  --threads 8

Final scores are copied to:

/data/caddsv/runs/variants/scored/variants_score.tsv

To run SegmentNT-backed modes, download the model files once:

caddsv get segmentnt --annotations-dir /data/caddsv/annotations

You can also download annotations and SegmentNT together:

caddsv get annotations \
  --annotations-dir /data/caddsv/annotations \
  --with-segmentnt

Installation Notes

CADD-SV installs with pip install . from this repository. The package includes the CLI and workflow files, but full scoring also needs conda at runtime because Snakemake creates the workflow environments on first use.

By default, those environments are cached under:

${XDG_CACHE_HOME:-$HOME/.cache}/caddsv/snakemake-conda/

Use --conda-prefix or CADD_SV_CONDA_PREFIX to place them on scratch or shared storage:

caddsv run sample.bed --conda-prefix /scratch/$USER/caddsv-conda

Data

Annotations

The annotation bundle is downloaded from:

https://kircherlab.bihealth.org/download/CADD-SV/v2.0/dependencies.tar.gz

The default destination is ./annotations. For reproducible runs, use an explicit path and pass the same path to caddsv run:

caddsv get annotations --annotations-dir /data/caddsv/annotations
caddsv run sample.bed --annotations-dir /data/caddsv/annotations

SegmentNT

--seqresolved and --seqonly require SegmentNT model files. The default local location is:

<annotations-dir>/segment_nt/

If the model lives somewhere else, set SEGMENTNT_MODEL:

SEGMENTNT_MODEL=/models/segment_nt \
caddsv run sample.bed --seqresolved --annotations-dir /data/caddsv/annotations

For offline runs, point to a local model directory and set:

HF_HUB_OFFLINE=1
TRANSFORMERS_OFFLINE=1
SEGMENTNT_LOCAL_FILES_ONLY=1

SegmentNT is downloaded from InstaDeepAI/segment_nt on Hugging Face and is licensed separately under CC BY-NC-SA 4.0.

Recommended Layout

Use explicit annotation and output paths when running from different working directories:

/data/caddsv/
  annotations/
    CADD/
    ucsc/
    segment_nt/
  runs/
    sample/

If paths are omitted, CADD-SV uses ./annotations and ./caddsv_results relative to the current working directory.

Running CADD-SV

Coordinate-Based Scoring

caddsv run examples/variants.bed \
  --annotations-dir /data/caddsv/annotations \
  --output-dir sample_results

Multiple BED files can be scored in one invocation:

caddsv run sample1.bed sample2.bed \
  --annotations-dir /data/caddsv/annotations \
  --output-dir batch_results

Sequence-Resolved Scoring

--seqresolved adds SegmentNT-derived features to coordinate-based scoring:

caddsv run sample.bed \
  --seqresolved \
  --annotations-dir /data/caddsv/annotations \
  --output-dir sample_seqresolved

This mode needs both the coordinate annotation bundle and SegmentNT model files. GPU execution is recommended for normal use; CPU execution is mainly practical for very small tests.

Sequence-Only Scoring

--seqonly scores REF/ALT sequence pairs instead of genomic coordinates:

caddsv run examples/sequences.tsv \
  --seqonly \
  --annotations-dir /data/caddsv/annotations \
  --output-dir seqonly_results

Sequence-only mode needs SegmentNT. It does not use coordinate annotation tracks, but --annotations-dir is still useful when SegmentNT is stored under <annotations-dir>/segment_nt.

Reusing Prepared Inputs

When a BED file is passed to caddsv run, CADD-SV writes a normalized copy to:

<output-dir>/input/id_<dataset>.bed

You can later rerun by dataset name:

caddsv run sample \
  --output-dir caddsv_results \
  --annotations-dir /data/caddsv/annotations

For --seqonly, the prepared input is input/id_<dataset>.tsv.

Inputs

BED

Coordinate-based modes use uncompressed .bed files with at least four tab-separated columns:

chrom    start    end    type    [sequence]

BED uses a 0-based start and 1-based end coordinate; interval length is end - start. Supported SV types are DEL, DUP, INS, and INV. SVs should be at least 50 bp; for INS, this means providing an inserted sequence of at least 50 bp in the optional fifth column when running --seqresolved.

The repository includes a minimal BED example at examples/variants.bed:

chr1    999999     1000049    DEL
chr2    2999999    3000000    INS    ACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGT

Before running Snakemake, the CLI adds missing chr prefixes, keeps standard chromosomes (chr1 through chr22, chrX, chrY), keeps supported SV types, skips short rows, sorts by chromosome and start, and writes the normalized file under <output-dir>/input/.

Compressed .bed.gz files are not auto-preprocessed; decompress them first or prepare the normalized input manually.

Sequence-Only TSV

--seqonly requires .tsv input with positional columns. Each row must include REF and ALT; TYPE and ID are optional. Do not include a header row unless it is an actual sequence record.

REF    ALT    TYPE    ID

Column	Required	Default
REF	Yes	None
ALT	Yes	None
TYPE	No	SV
ID	No	Blank; omitted from final output when absent

Sequence-only preprocessing uppercases sequences, requires matching 96 bp flanks, shrinks long middle sequence, and normalizes N runs for SegmentNT tokenization.

The repository includes a headerless sequence-only example with DEL and INS records at examples/sequences.tsv.

Outputs

For sample.bed and the default output directory:

caddsv_results/
  input/id_sample.bed
  beds/sample/
  scored/sample_score.tsv

For sequences.tsv --seqonly:

caddsv_results/
  input/id_sequences.tsv
  beds/sequences/
  scored/sequences_seqonly_score.tsv

The scored/ directory is the stable user-facing output location. The beds/ directory contains Snakemake intermediates and native workflow outputs.

Main score columns:

Mode	Main score columns
Coordinate scoring	CADD-SV_PHRED, CADD-SV_score
Sequence-resolved scoring	CADD-SV_PHRED, CADD-SV_score, CADD-SV-SR_PHRED, CADD-SV-SR_score
Sequence-only scoring	CADD-SV_seqonly_PHRED, CADD-SV_seqonly_score

The output also keeps annotation and model feature columns for downstream inspection.

Options

caddsv get

caddsv get annotations [--annotations-dir PATH] [--with-segmentnt] [--force-segmentnt]
caddsv get segmentnt   [--annotations-dir PATH] [--force-segmentnt] [--segmentnt-repo REPO]

Option	Meaning
--annotations-dir PATH	Annotation directory. Default: ./annotations.
--with-segmentnt	Also download SegmentNT into <annotations-dir>/segment_nt.
--force-segmentnt	Replace an existing local SegmentNT directory.
--segmentnt-repo REPO	Hugging Face SegmentNT repository. Default: InstaDeepAI/segment_nt.

caddsv run

caddsv run INPUT [INPUT ...] [OPTIONS]

Option	Meaning
--threads, -j	Maximum Snakemake jobs. Default: 4.
--annotations-dir PATH	Annotation directory. Default: ./annotations.
--output-dir, -o PATH	Results directory. Default: ./caddsv_results.
--conda-prefix PATH	Snakemake conda environment directory.
--config, -c PATH	Alternate Snakemake YAML configuration.
--seqresolved	Add SegmentNT-derived features to coordinate-based scoring.
--seqonly	Run sequence-only scoring from REF/ALT TSV input.
--force	Pass --forceall to Snakemake.
--unlock	Unlock a locked Snakemake output directory.
--check-time	Write a small resource summary log.

Runtime Notes

• First runs are slower because Snakemake creates conda environments.
• Use the same --output-dir to resume or reuse work from an interrupted run.
• Use a new --output-dir when comparing inputs with the same filename stem.
• --threads controls Snakemake cores, but some steps are I/O-bound.
• SegmentNT is much faster on GPU than CPU.
• Keep annotations and outputs on fast local storage when possible.

To remove cached Snakemake conda environments:

rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/caddsv/snakemake-conda"

To record a resource summary:

caddsv run sample.bed \
  --annotations-dir /data/caddsv/annotations \
  --check-time

This writes caddsv_run_<YYYYMMDD_HHMMSS>.log with the Snakemake command, return code, wall time, CPU time, CPU utilization, and maximum RSS.

Configuration

Most users should prefer CLI flags over editing config files. Use --config only when you need an alternate Snakemake YAML configuration:

caddsv run sample.bed --config custom.yml

The packaged default config is caddsv/config.yml.

Troubleshooting

Missing Annotations

Download annotations and run with the same path:

caddsv get annotations --annotations-dir /data/caddsv/annotations
caddsv run sample.bed --annotations-dir /data/caddsv/annotations

SegmentNT Downloads at Runtime

Download SegmentNT locally, then rerun with the same annotation directory:

caddsv get segmentnt --annotations-dir /data/caddsv/annotations
caddsv run sample.bed --seqresolved --annotations-dir /data/caddsv/annotations

If the model is outside the annotation directory, set SEGMENTNT_MODEL.

Locked Snakemake Directory

caddsv run sample.bed --unlock --output-dir caddsv_results

Then rerun the original command.

Existing Input Prompt

If <output-dir>/input/id_<dataset>.bed or .tsv exists with different content, CADD-SV asks before overwriting. Use a new --output-dir to avoid prompts when comparing inputs with the same dataset name.

Slow First Run

Common causes are conda environment creation, SegmentNT or PyTorch dependency setup, CPU-based SegmentNT execution, or annotation files on slow storage.

Minimal Smoke Test

With annotations already downloaded, run the included BED example:

caddsv run examples/variants.bed \
  --annotations-dir /data/caddsv/annotations \
  --output-dir test_run \
  --threads 1

Expected output:

test_run/scored/variants_score.tsv

For --seqresolved, download SegmentNT first and run:

caddsv run examples/variants.bed \
  --seqresolved \
  --annotations-dir /data/caddsv/annotations \
  --output-dir test_seqresolved \
  --threads 1

Expected output:

test_seqresolved/scored/variants_score.tsv

For --seqonly, download SegmentNT first and run:

caddsv run examples/sequences.tsv \
  --seqonly \
  --annotations-dir /data/caddsv/annotations \
  --output-dir test_seqonly \
  --threads 1

Expected output:

test_seqonly/scored/sequences_seqonly_score.tsv