[meta]
name = "survivor"
category = "structural-variants"
description = "SV simulation, merging, and comparison of structural variant calls across multiple callers and samples"
tags = ["sv", "structural-variants", "merging", "vcf", "long-read", "benchmarking", "consensus"]
author = "oxo-call built-in"
source_url = "https://github.com/fritzsedlazeck/SURVIVOR/wiki"

[context]
concepts = [
    "SURVIVOR merge combines SV calls from multiple VCF files using configurable distance, type agreement, and caller support thresholds.",
    "The merge command takes a plain text file listing VCF paths (one per line), not the VCFs directly on the command line.",
    "Merging parameters: max_distance (bp), min_callers_support, same_type_required (1/0), same_strand_required (1/0), estimate_SV_distance (1/0), min_sv_size.",
    "SURVIVOR stats provides summary statistics on SV sizes, types, and genotype distributions in a VCF.",
    "SURVIVOR filter removes SVs by size, type, allele frequency, or genotype quality to create a high-confidence call set.",
    "SURVIVOR simSV simulates structural variants on a reference genome for benchmarking purposes.",
]

pitfalls = [
    "The VCF list file for SURVIVOR merge must contain full or relative paths and have no trailing spaces or blank lines.",
    "All input VCFs must be uncompressed (not bgzipped); bgzipped VCFs must be decompressed with bgzip -d first.",
    "Setting same_type_required=0 allows merging of different SV types (DEL with INS), which is almost always incorrect — use 1.",
    "SURVIVOR merge distance (parameter 1) is the maximum breakpoint distance in bp; use 500-1000 for ONT, 50-100 for short-read callers.",
    "SURVIVOR does not sort output VCF; sort with bcftools sort before passing to downstream tools.",
    "min_callers_support=1 includes SVs from any single caller; for high-confidence consensus use 2 or more callers.",
]

[[examples]]
task = "merge SV VCFs from multiple callers requiring support from at least 2 callers"
args = "merge vcf_list.txt 500 2 1 1 0 50 merged_svs.vcf"
explanation = "args: vcf_list distance=500bp min_callers=2 same_type=1 same_strand=1 estimate_dist=0 min_size=50; output is merged_svs.vcf"

[[examples]]
task = "merge SV calls from a single caller across multiple samples"
args = "merge sample_vcfs.txt 1000 1 1 1 0 50 cohort_svs.vcf"
explanation = "distance=1000 for loose merging across samples; min_callers=1 includes private SVs; same_type=1 preserves type"

[[examples]]
task = "get summary statistics for SVs in a VCF"
args = "stats -i calls.vcf -o sv_stats.txt"
explanation = "outputs counts per SV type, size distributions, and genotype quality summaries"

[[examples]]
task = "filter SVs to a high-confidence set by size and minimum quality"
args = "filter -i calls.vcf -o filtered.vcf -s 50 -e 100000 -f 0"
explanation = "-s 50 minimum SV size; -e 100000 maximum SV size; -f 0 minimum allele frequency (0 = no AF filter)"

[[examples]]
task = "simulate structural variants on a reference genome for benchmarking"
args = "simSV reference.fasta parameter_file.txt 0 0 simulated"
explanation = "generates simulated SVs from a parameter file; outputs simulated_insertions.fa, simulated_SVs.vcf, and a modified FASTA"

[[examples]]
task = "create a VCF list file and merge three caller outputs"
args = "ls sniffles.vcf pbsv.vcf cutesv.vcf > vcf_list.txt && merge vcf_list.txt 500 2 1 1 0 50 consensus_svs.vcf"
explanation = "creates vcf_list.txt with three caller VCF paths; merge requires at least 2 callers to agree (min_callers=2)"
