Varlociraptor

https://varlociraptor.github.io/
Admin
Varlociraptor is a flexible, uncertainty-aware genomic and methylation variant caller supporting...
Tokens:19,535
Snippets:129
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install varlociraptor via Cargo

Source: https://varlociraptor.github.io/docs/installation

Installs varlociraptor using Cargo. Requires zlib, bzip2, xz, GSL (with --features gslv2 for GSLv2), and cmake.

```bash
cargo install varlociraptor
```

--------------------------------

### Example testcase.yaml structure

Source: https://varlociraptor.github.io/docs/reporting-issues

Example testcase.yaml generated by varlociraptor. The 'expected' section must be edited to denote expected alteration fractions and posterior probabilities; both fields are optional. The file contains necessary BAM files, candidate variant, reference sequence, and options.

```yaml
expected:
  altfracs:
    # write down a list of expressions of the form
    - sample_name > 0.45 && sample_name < 0.55
  posteriors:
    # write down a list of expressions of the form
    - PROB_SOMATIC_TUMOR <= 0.05
    - PROB_GERMLINE_HET > 0.05

# necessary bam files
samples:
  tumor:
    path: tumor.bam
    properties: '{"insert_size":{"mean":312.0,"sd":11.89254089203071},"max_del_cigar_len":30,"max_ins_cigar_len":12,"frac_max_softclip":0.69}'
  normal:
    path: normal.bam
    properties: '{"insert_size":{"mean":312.0,"sd":11.89254089203071},"max_del_cigar_len":30,"max_ins_cigar_len":12,"frac_max_softclip":0.69}'


# candidate variant
candidate: candidates.vcf

# reference sequence
reference:
  name: chr1
  seq: cccaaaatgctgggattataggcataagttaccatgcctggccATTTTTGTGTCTTTCTTGATGAGCAACTGCTCTGTTCCAGCCCTGTGCTGGGCATATTCACATCTTTTTCTTCTCTCTCTCTCTtttctttctttctttctttcttttctttctttctttctttcctttctttctttctttctttctttctttctttctttctttttctttttctttccttccttccttcttcctttctttctttctttctttctttttctttccttccttccttcttccttccttgcttgcttccttccttctttccctccctccctccctccctccttacttccctccctccctctctctttctctttccttctttttctttcgactgtgtcttgttct

options: '{"Call": {"kind": {"Variants": {"spurious_ins_rate": 2.8e-06, "spurious_del_rate":
  5.1e-06, "spurious_insext_rate": 0.0, "spurious_delext_rate": 0.0, "indel_window":
  100, "omit_snvs": false, "omit_indels": false, "max_indel_len": 1000, "max_depth":
  200, "reference": "../hg18/chr1.fa", "candidates": "candidates.vcf", "output": null,
  "testcase_locus": "chr1:17926776:1", "testcase_prefix": "/tmp/testcase", "mode":
  {"TumorNormal": {"tumor": "tumor.bam", "normal": "normal.bam", "purity": 1.0}}}}}}'
```

--------------------------------

### Check varlociraptor version

Source: https://varlociraptor.github.io/docs/installation

Prints the installed version of varlociraptor to verify it is the latest stable release.

```bash
varlociraptor --version
```

--------------------------------

### Generic calling grammar YAML example

Source: https://varlociraptor.github.io/docs/calling

Defines a normal/tumor/relapse model with a uniform prior (joint calling of tumor and relapse after therapy against normal). The YAML specifies sample resolutions, universes, contamination fractions, and event definitions using the variant calling grammar.

```yaml
samples:
  normal:
    resolution: 0.1
    universe: "0.0 | 0.5 | 1.0 | ]0.0,0.5["
  tumor:
    resolution: 0.01
    universe: "[0.0,1.0]"
    contamination:
      by: normal
      fraction: 0.25
  relapse:
    resolution: 0.01
    universe: "[0.0,1.0]"
    contamination:
      by: normal
      fraction: 0.53

events:
  germline:
    "normal:0.5 | normal:1.0"
  somatic_normal:
    "normal:]0.0,0.5["
  somatic_relapse:
    "normal:0.0 & tumor:0.0 & relapse:]0.0,1.0]"
  somatic_tumor:
    "normal:0.0 & tumor:]0.0,1.0] & l2fc(relapse, tumor) < 1.0"
  somatic_tumor_relapse_double:
    "normal:0.0 & tumor:]0.0,1.0] & l2fc(relapse, tumor) >= 1.0"

```

--------------------------------

### Population calling model configuration (YAML)

Source: https://varlociraptor.github.io/varlociraptor-scenarios/scenarios/population-prior

Defines species heterozygosity and ploidy for male and female, two samples with sexes, and an events expression. The values are examples; configure with your own expertise or literature research.

```yaml
species:
  heterozygosity: 0.001
  ploidy:
    male:
      all: 2
      Y: 1
      X: 1
    female:
      all: 2
      X: 2
      Y: 0

samples:
  a:
    sex: male
  b:
    sex: female

events:
  present: "a:0.5 | a:1.0 | b:0.5 | b:1.0"

```

--------------------------------

### Configure tumor/normal/relapse calling with priors (YAML)

Source: https://varlociraptor.github.io/varlociraptor-scenarios/scenarios/tumor-normal-relapse-prior

Configure Varlociraptor for tumor/normal/relapse calling with prior assumptions about mutation rate and heterozygosity. The values shown are examples; adjust them based on your expertise or literature research. The configuration defines species-level parameters, sample-specific inheritance and contamination, and event definitions for somatic and germline variants.

```yaml
species:
  heterozygosity: 0.001
  germline-mutation-rate: 1e-3
  ploidy:
    male:
      all: 2
      X: 1
      Y: 1
    female:
      all: 2
      X: 2
      Y: 0

samples:
  tumor:
    sex: male
    somatic-effective-mutation-rate: 1e-6
    inheritance:
      clonal:
        from: normal
        somatic: false
    contamination:
      by: normal
      fraction: 0.15
  relapse:
    sex: male
    somatic-effective-mutation-rate: 1e-6
    inheritance:
      subclonal:
        from: tumor
    contamination:
      by: normal
      fraction: 0.1
  normal:
    somatic-effective-mutation-rate: 1e-10
    sex: male

events:
  somatic_tumor: "normal:0.0 & tumor:]0.0,1.0]"
  somatic_relapse: "normal:0.0 & tumor:0.0 & relapse:]0.0,1.0]"
  germline: "normal:0.5 | normal:1.0"
  somatic_normal: "normal:]0.0,0.5["

```

--------------------------------

### Create conda environment for varlociraptor

Source: https://varlociraptor.github.io/docs/installation

Creates an isolated Bioconda environment named 'varlociraptor' and installs the varlociraptor package.

```bash
conda create --name varlociraptor varlociraptor
```

--------------------------------

### Varlociraptor configuration for single sample germline calling with priors

Source: https://varlociraptor.github.io/varlociraptor-scenarios/scenarios/single-sample-germline-prior

YAML configuration for Varlociraptor single sample germline calling. Sets species heterozygosity to 0.001, defines ploidy for male and female, assigns sample 'hamlet' as male, and defines events 'het' and 'hom' with allele frequencies 0.5 and 1.0. The heterozygosity value is an example and should be adjusted based on species or population.

```yaml
species:
  heterozygosity: 0.001
  ploidy:
    male:
      all: 2
      X: 1
      Y: 1
    female:
      all: 2
      X: 2
      Y: 0

samples:
  hamlet:
    sex: male

events:
  het: "hamlet:0.5"
  hom: "hamlet:1.0"

```

--------------------------------

### Show varlociraptor CLI help

Source: https://varlociraptor.github.io/docs/installation

Displays the command line interface help for varlociraptor.

```bash
varlociraptor --help
```

--------------------------------

### Run Varlociraptor Preprocessing

Source: https://varlociraptor.github.io/docs/calling

Executes the preprocessing command to generate per-sample observations from candidate alterations and BAM files.

```bash
varlociraptor preprocess variants reference.fa --alignment-properties sample.alignment-properties.json --bam sample.bam < candidates.bcf > sample.observations.bcf
```

--------------------------------

### Generate methylation candidates with `methylation-candidates`

Source: https://varlociraptor.github.io/docs/calling

Creates a candidate BCF file from a reference genome. Motifs are given as a comma-separated list; supported motifs are `CG`, `CHG`, `CHH`, `GATC`. Consider using the `--atomic-candidate-variants` flag if candidates are not merged into haplotypes.

```text
varlociraptor methylation-candidates --motifs <motifs> reference.fa candidates.bcf

```

--------------------------------

### Varlociraptor trio pedigree configuration

Source: https://varlociraptor.github.io/varlociraptor-scenarios/scenarios/simple-pedigree-prior

YAML configuration for Varlociraptor trio pedigree calling. Sets species heterozygosity, germline mutation rate, ploidy per sex, sample sexes, and Mendelian inheritance for the child. Defines events for de novo and inherited variants. Values are examples and should be adjusted based on expertise or literature.

```yaml
species:
  heterozygosity: 0.001
  germline-mutation-rate: 1e-3
  ploidy:
    male:
      all: 2
      X: 1
      Y: 1
    female:
      all: 2
      X: 2
      Y: 0

samples:
  mother:
    sex: female
  father:
    sex: male
  child:
    sex: male
    inheritance:
      mendelian:
        from:
          - mother
          - father

events:
  denovo_child: "(child:0.5 | child:1.0) & mother:0.0 & father:0.0"
  inherited: "!mother:0.0 | !father:0.0"

```

--------------------------------

### RNA-seq configuration: allele frequency universe and present event

Source: https://varlociraptor.github.io/varlociraptor-scenarios/scenarios/rna-seq-variant-calling

Configures sample with universe from 0.0 to 1.0 and defines event for presence above 0.0.

```yaml
samples:
  hamletsrna:
    universe: "[0.0,1.0]"

events:
  present: "hamletsrna:]0.0,1.0]"
```

--------------------------------

### Configure pedigree calling with priors

Source: https://varlociraptor.github.io/varlociraptor-scenarios/scenarios/pedigree-prior

Defines species parameters, sample relationships, and event logic for a pedigree including mother, father, child, and sibling. The 'other' event uses negation to cover all remaining possibilities.

```yaml
species:
  heterozygosity: 0.001
  germline-mutation-rate: 1e-3
  ploidy:
    male:
      all: 2
      X: 1
      Y: 1
    female:
      all: 2
      X: 2
      Y: 0

samples:
  mother:
    sex: female
  father:
    sex: male
  child:
    sex: male
    inheritance:
      mendelian:
        from:
          - mother
          - father
  sibling:
    sex: female
    inheritance:
      mendelian:
        from:
          - mother
          - father

events:
  denovo_child: "(child:0.5 | child:1.0) & mother:0.0 & father:0.0"
  denovo_sibling: "(sibling:0.5 | sibling:1.0) & mother:0.0 & father:0.0"
  other: "!($denovo_child | $denovo_sibling | $absent)"
```

--------------------------------

### Generate test case with --testcase-prefix and --testcase-anonymous

Source: https://varlociraptor.github.io/docs/reporting-issues

Creates a test case folder under the given prefix (here 'testcase') containing relevant BAM subsets, a VCF with the candidate variant, and a testcase.yaml file. CHROM:POS is the 1-based locus from the VCF. --testcase-anonymous anonymizes identifiers via uuid4 and sequences by randomly permuting the alphabet.

```bash
varlociraptor call variants --testcase-prefix testcase --testcase-locus CHROM:POS --testcase-anonymous tumor-normal --purity 0.75 --tumor tumor.bcf --normal normal.bcf
```

--------------------------------

### Split Candidates for Parallelization

Source: https://varlociraptor.github.io/docs/calling

Splits the candidate BCF file into multiple chunks using Rust-Bio-Tools to enable parallel processing.

```bash
rbt vcf-split candidates.bcf chunk{0..15}.bcf
```

--------------------------------

### Execute generic variant calling command

Source: https://varlociraptor.github.io/docs/calling

Run the varlociraptor call command using a specified scenario file and mapped observation files.

```bash
varlociraptor call variants generic --scenario scenario.yaml --obs relapse=relapse.sorted.bcf tumor=tumor.bcf normal=normal.bcf > calls.bcf
```

--------------------------------

### Estimate mutational burden with varlociraptor

Source: https://varlociraptor.github.io/docs/estimating

Computes the mutational burden from an annotated VCF/BCF file and produces a Vega-Lite JSON specification.

```bash
varlociraptor estimate mutational-burden --coding-genome-size 3e7 --sample tumor ---events SOMATIC_TUMOR < calls.annotated.bcf > tmb.vl.json
```

--------------------------------

### Convert Vega-Lite JSON to SVG

Source: https://varlociraptor.github.io/docs/estimating

Converts the generated Vega-Lite JSON specification into an SVG image using the vl2svg utility.

```bash
vl2svg tmb.vl.json tmb.svg
```

--------------------------------

### Tumor-normal calling command

Source: https://varlociraptor.github.io/docs/calling

Calls variants of all lengths from tumor and normal samples. The --purity option sets the purity (cancer cell content) of the tumor sample. The result is a statistical assessment of somatic and germline variants, and should be followed by controlling the false discovery rate (see Filtering).

```bash
varlociraptor call variants tumor-normal --purity 0.75 --tumor tumor.bcf --normal normal.bcf > calls.bcf

```

--------------------------------

### Define FFPE artifact model in YAML

Source: https://varlociraptor.github.io/varlociraptor-scenarios/scenarios/ffpe-artifact-handling

Defines a sample 'ffpetumor' with a universe and resolution, an expression 'ffpe_subst' for C>T or G>A substitutions, and events 'ffpe_artifact' and 'present' to filter artifacts based on allele frequency.

```yaml
samples:
  ffpetumor:
    universe: "[0.0,1.0]"
    resolution: 0.01

expressions:
  ffpe_subst: "C>T | G>A"

events:
  ffpe_artifact: "($ffpe_subst) & ffpetumor:]0.0,0.05["
  present: "(($ffpe_subst) & ffpetumor:]0.05,1.0]) | (!($ffpe_subst) & ffpetumor:]0.0,1.0[)"

```

--------------------------------

### Basic varlociraptor call command

Source: https://varlociraptor.github.io/docs/calling

The basic calling command. The dots (...) are a placeholder for the selected calling mode, which can be tumor-normal or generic.

```bash
varlociraptor call variants ...

```

--------------------------------

### Original varlociraptor call variants command

Source: https://varlociraptor.github.io/docs/reporting-issues

Original command that produced a variant call you believe to be wrong. Use this as the baseline for creating a test case.

```bash
varlociraptor call variants tumor-normal --purity 0.75 --tumor tumor.bcf --normal normal.bcf
```

--------------------------------

### Varlociraptor tumor-only scenario configuration

Source: https://varlociraptor.github.io/varlociraptor-scenarios/scenarios/tumor-only-prior

YAML configuration for tumor-only calling with a uniform prior. Defines species parameters, tumor sample with contamination by normal, and three events: somatic_tumor_high, somatic_tumor_low, and germline. The contamination fraction is 0.1, and the somatic effective mutation rate is 1e-6.

```yaml
species:
  heterozygosity: 0.001
  germline-mutation-rate: 1e-3
  ploidy:
    male:
      all: 2
      X: 1
      Y: 1
    female:
      all: 2
      X: 2
      Y: 0
  genome-size: 3.5e9

samples:
  tumor:
    sex: female
    somatic-effective-mutation-rate: 1e-6
    inheritance:
      clonal:
        from: normal
        somatic: true
    contamination:
      by: normal
      fraction: 0.1
  normal:
    sex: female

events:
  somatic_tumor_high: "normal:0.0 & tumor:[0.1,1.0]"
  somatic_tumor_low: "normal:0.0 & tumor:]0.0,0.1["
  germline: "normal:0.5 | normal:1.0"

```

--------------------------------

### Defining species and sample inheritance configuration

Source: https://varlociraptor.github.io/docs/calling

This configuration defines species-level properties like genome size and ploidy, alongside sample-specific inheritance models such as mendelian, clonal, and subclonal relationships.

```yaml
species:
  genome-size: 3.5e9
  heterozygosity: 0.001
  germline-mutation-rate: 1e-3
  ploidy:
    male:
      all: 2
      X: 1
      Y: 1
    female:
      all: 2
      X: 2
      Y: 0

samples:
  mother:
    sex: female
  father:
    sex: male
  daughter:
    sex: female
    somatic-effective-mutation-rate: 1e-10
    inheritance:
      mendelian:
        from:
          - mother
          - father
  tumor:
    sex: female
    somatic-effective-mutation-rate: 1e-6
    inheritance:
      clonal:
        from: daughter
        somatic: false
    contamination:
      by: normal
      fraction: 0.1
  
  relapse:
    sex: female
    somatic-effective-mutation-rate: 1e-6
    inheritance:
      subclonal:
        from: tumor
    contamination:
      by: normal
      fraction: 0.2

events:
  germline_denovo:    "(daughter:0.5 | daughter:1.0) & father:0.0 & mother:0.0"
  somatic_normal:     "daughter:]0.0,0.5["
  somatic_tumor:      "daughter:0.0 & tumor:]0.0,1.0]"
  somatic_relapse:    "daughter:0.0 & tumor:0.0 & relapse:]0.0,1.0]"
  germline_inherited: "!daugher:0.0 & (!father:0.0 | !mother:0.0)"
  germline_lost:      "daughter:0.0 & (!father:0.0 | !mother:0.0)"
```

--------------------------------

### Activate varlociraptor conda environment

Source: https://varlociraptor.github.io/docs/installation

Activates the conda environment so that varlociraptor is available in the PATH.

```bash
conda activate varlociraptor
```

--------------------------------

### Estimate alignment properties with varlociraptor

Source: https://varlociraptor.github.io/docs/estimating

Performs estimation of alignment properties from a sorted BAM file to save time during repeated variant calling runs.

```bash
varlociraptor estimate alignment-properties reference.fa --bam sample.bam > sample.alignment-properties.json
```
Tokens:
Raw