DOCSEARCHbyAlgolia
Submit Docs

JASMINE (Jointly Accurate Sv Merging with Intersample Network Edges)

repository·master·Indexed 42 days ago

https://github.com/mkirsche/jasmine

A tool for merging structural variants (SVs) across multiple biological samples using a network-based approach and a modified minimum spanning forest algorithm. It identifies analogous variants to create a unified, accurate merged VCF and is compatible with SV calls from any caller. The tool includes a CLI for preprocessing, normalization, and merging, as well as a Snakemake pipeline for alignment and SV calling workflows using Winnowmap, Sniffles, and Iris.

Tokens
2.5K
Snippets
8
Records
12
Agent score
54%

What's inside Jasmine

  1. What is Jasmine?

    master

    JASMINE (Jointly Accurate Sv Merging with Intersample Network Edges) is a tool designed to merge structural variants (SVs) across multiple samples.

    It represents the set of all SVs across samples as a network and utilizes a modified minimum spanning forest algorithm. This approach determines the optimal way to merge variants so that each merged variant represents a set of analogous variants occurring in different samples. It is compatible with SV calls from any caller, including short-read callers.

  2. Pipeline Overview: Alignment and SV Calling Workflow

    master

    The Jasmine pipeline automates the process of alignment and Structural Variant (SV) calling in long-read datasets through the following stages:

    1. Alignment: Reads are aligned using Winnowmap.
    2. SV Calling: Sniffles is used to call SVs with sensitive parameters.
    3. Preprocessing (Duplication to Insertion): Duplications are temporarily converted to insertions for breakpoint refinement using jasmine --dup_to_ins.
    4. Refinement: SVs are refined using Iris.
    5. Normalization: SV types are normalized using jasmine --preprocess_only --pre_normalize.
    6. Specificity Marking: High-confidence callsets are marked using jasmine --mark_specific.
    7. Deduplication: Duplicate calls are removed using jasmine with --nonlinear_dist.
    8. Merging: Per-sample VCFs are merged into a single file using jasmine.
    9. Postprocessing: Insertions are converted back to duplications using jasmine --dup_to_ins --postprocess_only.
    10. Filtering: Low-confidence or imprecise calls are removed via grep filtering on the final VCF.

  3. Run Jasmine for SV merging

    master

    After installation or building, you can run the jasmine executable. Running it without arguments will display a usage menu with all required and optional arguments.

    To merge structural variants (SVs) from multiple samples, provide a file list containing the paths to your VCF files.

    # Example: Merging files from a list
ls *.vcf > filelist.txt
jasmine file_list=filelist.txt out_file=merged.vcf

# Example: Running with specific flags
jasmine --dup_to_ins --postprocess_only out_file=merged.vcf

  4. Install the Jasmine pipeline

    master

    The Jasmine pipeline requires snakemake to be installed on your system. To install the pipeline, clone the repository into a general location on your computing cluster.

    git clone https://github.com/mkirsche/Jasmine.git /path/to/pipelines

  5. Build Jasmine from source

    master

    To build Jasmine from the source repository, use the provided build script.

    Note on Iris Preprocessing: If you intend to use the Iris preprocessing option (which refines sequences and breakpoints for high-error reads), you must ensure samtools, minimap2, and racon are installed and available in your PATH or specified via the iris_args parameter.

    path_to_jasmine_repo/build_jar.sh

  6. Use the IGV visualization module

    master

    The igv_jasmine executable automates the creation of IGV (Integrative Genomics Viewer) screenshots for variants of interest.

    Requirements:

    • BAM files for each sample.
    • The reference genome.
    • The merged VCF file (or a BED file specifying regions of interest).

    Output: Running this module generates a folder containing:

    1. IGV screenshots for each variant (optionally filtered).
    2. A .bat file. To use this, open IGV and select Tools -> Run Batch Script, then navigate to the generated .bat file.

  7. Install Jasmine via Conda

    master

    The recommended way to install Jasmine is using the Bioconda channel. This typically takes less than a minute.

    conda config --add channels bioconda
conda config --add channels conda-forge
conda install jasminesv

  8. Set up an experiment run

    master

    To run an experiment, follow these steps within your dedicated experiment folder:

    1. Symlink pipeline files: Create symlinks to all *snakefile and *.py files from the Jasmine/pipeline master folder into your current directory.
    2. Copy configuration: Copy all *yaml files from the Jasmine/pipeline master folder into your current directory.
    3. Configure dataset: Edit the data.yaml file to set up your targeted dataset.
    4. Dry run: Execute a dry run using snakemake to verify the pipeline logic before committing resources.

    Dry run command:

    snakemake -s pipeline.snakefile -npr
    # Symlink snakefiles and python files
ln -s /path/to/pipelines/Jasmine/pipeline/*snakefile .
ln -s /path/to/pipelines/Jasmine/pipeline/*py .

# Copy yaml configs
cp /path/to/pipelines/Jasmine/pipeline/*yaml .

# Run dry run
snakemake -s pipeline.snakefile -npr

  9. Run the pipeline on a SLURM cluster

    master

    You can execute the pipeline using snakemake with a SLURM cluster configuration. The following example demonstrates a production run that:

    • Limits concurrent job submissions to 20 (-j 20).
    • Regenerates any incomplete results from previous failed runs (--rerun-incomplete).
    • Uses a --cluster flag to submit jobs via sbatch to a specific partition with defined resource limits (e.g., 3 days time limit, 24G RAM).

    Example SLURM command:

    snakemake -s pipeline.snakefile --latency-wait 200 -pr -j 20 --rerun-incomplete --cluster "sbatch --account={cluster.account} --partition={cluster.partition} --job-name={cluster.name} --nodes={cluster.nodes} --cpus-per-task={cluster.nCPUs} --time={cluster.time} --out={cluster.out} --err={cluster.err} --mem={cluster.mem_mb}M"

  10. Jasmine CLI Reference

    master

    The jasmine CLI tool is used throughout the pipeline for various preprocessing, normalization, and merging tasks. Most commands utilize --comma_filelist to accept input files.

    Preprocessing and Normalization

    • Convert duplications to insertions: jasmine --dup_to_ins --preprocess_only vcf_filelist=<vcf> --comma_filelist
    • Normalize SV types: jasmine --preprocess_only --pre_normalize --comma_filelist file_list=<vcf>
    • Mark high-confidence (specific) calls: jasmine file_list=<vcf> --comma_filelist --preprocess_only --mark_specific spec_reads=<min(10, 25% average coverage)> spec_len=30

    Deduplication and Merging

    • Remove duplicate calls: jasmine file_list=<vcf> max_dist=200 --allow_intrasample out_file=<outputvcf> --comma_filelist --nonlinear_dist
    • Merge SVs across samples: jasmine file_list=<vcflist> out_file=<outputmergedvcf> --comma_filelist
    • Convert insertions back to duplications: jasmine --dup_to_ins --postprocess_only out_file=<mergedvcf> --comma_filelist
    # Example: Mark high-confidence calls
jasmine file_list=samples.vcf --comma_filelist --preprocess_only --mark_specific spec_reads=15 spec_len=30

# Example: Merge VCFs
jasmine file_list=vcf_list.txt out_file=merged.vcf --comma_filelist

  11. Configure Jasmine pipeline stages

    master

    The execution flow of Jasmine is controlled by several configuration flags (managed by the Settings class). While the exact CLI flag syntax is not defined in this file, the following behaviors are toggled by these settings:

    Pipeline Control

    • POSTPROCESS_ONLY: If true, skips preprocessing and the core merging stage.
    • PREPROCESS_ONLY: If true, skips the core merging and postprocessing stages.
    • USING_FILE_LIST: If true, Settings.FILE_LIST is treated as a file containing a list of input files rather than a single input file.

    Preprocessing Options

    • CONVERT_DUPLICATIONS: When enabled, converts duplications to insertions during preprocessing and converts them back during postprocessing.
    • MARK_SPECIFIC: Marks calls with strong read support and long length as specific calls.
    • RUN_IRIS: Triggers the IRIS tool within the pipeline.
    • PRE_NORMALIZE: Triggers type normalization.

    Postprocessing & Output

    • OUTPUT_GENOTYPES: Triggers the addition of genotypes during the postprocessing stage.
    • OUT_FILE: Specifies the destination path for the merged variants output.

  12. Run Jasmine via the CLI

    master

    Jasmine is executed via a Java Main class. The application processes structural variant (SV) data through a pipeline consisting of three main stages: Preprocessing, Running Jasmine (Merging), and Postprocessing.

    Depending on the command-line arguments provided (parsed via Settings.parseArgs(args)), you can run the full pipeline or specific stages:

    1. Full Pipeline: Runs preprocessing, merging, and postprocessing.
    2. Preprocessing Only: Runs only the preprocess stage (e.g., converting duplications to insertions, marking specific calls, running IRIS, or normalizing types).
    3. Postprocessing Only: Runs only the postprocess stage (e.g., converting insertions back to duplications or adding genotypes).
    4. Merging Only: Runs the core runJasmine logic which reads variant files, bins them into graphs, and performs parallel merging.
    java Main [args]