{"id":38676697,"url":"https://github.com/wglab/linkedsv","last_synced_at":"2026-01-17T10:01:31.303Z","repository":{"id":55895873,"uuid":"83945866","full_name":"WGLab/LinkedSV","owner":"WGLab","description":null,"archived":false,"fork":false,"pushed_at":"2023-08-01T15:39:28.000Z","size":36749,"stargazers_count":21,"open_issues_count":14,"forks_count":8,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-07-31T20:29:11.685Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WGLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-03-05T04:55:34.000Z","updated_at":"2024-06-27T08:24:52.000Z","dependencies_parsed_at":"2022-08-15T08:50:53.323Z","dependency_job_id":"4b6557a9-b2ed-4510-8597-d436fdf5b7ce","html_url":"https://github.com/WGLab/LinkedSV","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/WGLab/LinkedSV","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FLinkedSV","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FLinkedSV/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FLinkedSV/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FLinkedSV/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WGLab","download_url":"https://codeload.github.com/WGLab/LinkedSV/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WGLab%2FLinkedSV/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28505570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T06:57:29.758Z","status":"ssl_error","status_checked_at":"2026-01-17T06:56:03.931Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T10:01:31.133Z","updated_at":"2026-01-17T10:01:31.288Z","avatar_url":"https://github.com/WGLab.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Users' Guide\n\nLinkedSV is a novel structural variant caller for 10X Genomics (linked-read) sequencing data. It detects deletions, duplications, inversions and translocations using evidence from the barcoded reads. \n\n## Table of Contents\n- [Installation](#Installation)\n  - [Prerequisites](#Prerequisites)\n  - [Compilation](#Compilation)\n  - [Conda](#Conda)\n- [Usage](#Usage)\n  - [General usage](#General_usage)\n  - [Use cases](#Use_cases)\n- [Output Files](#Output)\n  - [SV call file](#SV_call_file)\n  - [Intermediate files](#Intermediate_files)\n- [Visualization of SV calls](#Visualization)\n  - [Read depth](#read_depth)\n  - [Twin-window evidence](#Twin_window_evidence)\n  - [Heat Map of overlapping barcodes](#Heat_Map)\n- [Future extensions](#Future_extensions)\n- [Citation](#Citation)\n- [Getting Help](#Getting_Help)\n- [License Agreement](#License)\n\n\n\n\n## \u003ca name=\"Installation\"\u003e\u003c/a\u003eInstallation\n\n### \u003ca name=\"Prerequisites\"\u003e\u003c/a\u003e Prerequisites\n\nMost of the source code was written in Python, but the time-consuming steps were written in C++11. It uses htslib to process bam files.\n\nThe following software tools and packages are required for the installation of LinkedSV. \n\n1. c++ compiler (A c++ compiler that supports C++11 is needed to build LinkedSV. Development of the code is performed using g++ v4.8.5)\n\n2. Python (version: \u003e= 2.7 or python 3)\n\n3. Python packages: sklearn, scipy, numpy, gzip, psutil, subprocess, bisect, math, argparse, pandas, seaborn, datetime. Among these, `math`, `subprocess`, `gzip` and `bisect` are included in the python standard library, meaning that they should be already installed with python.\n\nYou can use `pip` to install a python package. You can use the following command to install all the required python packages. \n\n```\npip install scikit-learn scipy numpy psutil argparse pandas seaborn datetime\n```\n\nIf you don't have `pip` in your system, you can install pip according to the instructions [here](https://pip.pypa.io/en/stable/installing/)\n\n4. [SAMtools](https://github.com/samtools/samtools) (version \u003e= 1.5)\n\n5. [BEDTools](https://bedtools.readthedocs.io/en/latest/)\n\n6. perl. A recent version should work. If you have issues with perl, please submit an issue in the [issue page](https://github.com/WGLab/LinkedSV/issues). \n\n\n\n### \u003ca name=\"Compilation\"\u003e\u003c/a\u003e Compilation\n\nIf the above tools and packages are available, you can use the following command to download and compile LinkedSV: \n\n```\ngit clone https://github.com/WGLab/LinkedSV.git \ncd LinkedSV/\nmake\n```\n\n### \u003ca name=\"Conda\"\u003e\u003c/a\u003e Conda\n\nLinkedSV is available in [Bioconda](https://anaconda.org/bioconda/linkedsv) as well thanks to pdimens\n\n\n## \u003ca name=\"Usage\"\u003e\u003c/a\u003eUsage\n\n```\nusage: linkedsv.py [-h] -i input.phased_possorted_bam.bam -d output_directory\n                   -r ref.fa [-v version] [--gap_region_bed BED]\n                   [--black_region_bed BED] [-t num_thread]\n                   [--min_fragment_length INT] [--min_reads_in_fragment INT]\n                   [--min_supp_barcodes INT] [--samtools path/to/samtools]\n                   [--bedtools path/to/bedtools] [--wgs] [--targeted]\n                   [--germline_mode] [--somatic_mode] [--target_region BED]\n                   [--gap_distance_cut_off INT] [--save_temp_files]\n\n```\n## \u003ca name=\"General_usage\"\u003e\u003c/a\u003eGeneral usage\n\nThe `input.phased_possorted_bam.bam` is the input bam file, which contains the barcoded reads. LinkedSV read the barcodes from the `BX` tag in the bam TAG field. We recommend using the `phased_possorted_bam.bam` file generated by the official Longranger pipeline.\n\nThe `ref.fasta` file is the FASTA file of the reference genome. It should be the same fasta file that was used for alignment. The `ref.fasta` file should be indexed by samtools. You can use the following command to index a `ref.fasta` file:\n\n```\nsamtools faidx ref.fasta\n```\n\nThis command will generate a `ref.fasta.fai` file in the same directory of the `ref.fasta` file. \n\n`output_directory` is the directory where the output files will be generated. \n\n`black_region_bed` is the blacklist file for filtering SV calls. The blacklist contains a small set of regions that give consistently spurious signal across samples. We prepared `black_region_bed` for human reference genomes (versions: hg19, b37, hg38), so you don't need to provide it if you use hg19, b37, or hg38. \n\n`gap_region_bed` is the bed file of gap regions in the reference genome. It is used to filter the SV calls. LinkedSV provides `gap_region_bed` for human reference genomes (versions: hg19, b37, hg38), so you don't need to provide it if you use hg19, b37, or hg38. \n\n`ref_version` is used to tell LinkedSV which `black_region_bed` file and `gap_region_bed` file should be used. Currently we have generated blacklists for hg19 (style: \"chr1\"), b37 (style: \"1\") and hg38 (style: \"chr1\"). It is **highly recommended** to spcifiy `ref_version` if you are using these three versions. The valid values are: hg19, b37, hg38. \n\nIf you are using a different reference file, please generate the `black_region_bed` file and the `gap_region_bed` file by yourself and specify the `--gap_region_bed` and `--black_region_bed` parameters.\n\nIf you don't have samtools and bedtools in your path, please specify the path using `--samtools` and `--bedtools`. \n\n\n### \u003ca name=\"Use_cases\"\u003e\u003c/a\u003e Use cases: \n\n**Detection of germline SVs from whole-genome sequencing**\n\n```\npython linkedsv.py -i input.phased_possorted_bam.bam -d path/to/output_dir/ -r hg38.fa -v hg38 -t 4 --germline_mode\n```\n\nThe `-v hg38` parameter specify that the reference genome is hg38. If you use another version, please change accordingly. \nWe recommend using at least 4 threads to speed up the run. Each thread need 4GB memory.\n\n\n**Detection of germline SVs from targeted sequencing (e.g. whole-exome sequencing)**\n\n```\npython linkedsv.py -i phased_possorted_bam.bam -d path/to/output_dir/ -r ref.fasta -v hg38 -t 4 --targeted --target_region path/to/target_region.bed --germline_mode\n```\n\n`target_region.bed` is a bed file that contains the target regions (capture regions). \n\n**Detection of somatic SVs from whole-genome sequencing** \n\n```\npython linkedsv.py -i input.phased_possorted_bam.bam -d path/to/output_dir/ -r ref.fasta -v hg38 -t 4 --somatic_mode\n```\n\n\n## \u003ca name=\"Output\"\u003e\u003c/a\u003e Output Files\n\nLinkedSV will output the SV calls, as well as the figures that allow you to visualize the large SV calls. \n\n### \u003ca name=\"SV_call_file\"\u003e\u003c/a\u003e SV call file\n\nLinkedSV will output three SV call files, `prefix.small_deletions.bedpe`, `prefix.large_cnv.bedpe` and `prefix.filtered_large_svcalls.bedpe`. The `prefix.small_deletions.bedpe` file contains small deletions detected from short-read information (discordant paired-end reads and local assembly). The `prefix.large_cnv.bedpe` file contains copy number variants detected from an algorithm based on read depth. The `prefix.filtered_large_svcalls.bedpe` file contains the filtered SV calls detected from linked-reads using barcode information. \n\nThe BEDPE format was defined by BEDtools (https://bedtools.readthedocs.io/en/latest/content/general-usage.html). It can be used to concisely describe disjoint genome features, such as structural variations. We did not use BED format because BED format does not allow inter-chromosomal feature definitions.\n\nThe SV call file contains one SV per line with the following tab-delimited columns:\n\n|Column|Description|\n|:----|:-----------------------------------------|\n|chrom1|chrom of breakpoint 1|\n|start1|start position of breakpoint 1|\n|stop1|end position of breakpoint 1|\n|chrom2|chrom of breakpoint 2|\n|start2|start position of breakpoint 2|\n|stop2|end position of breakpoint 2|\n|sv_type|SV type inferred from breakpoints|\n|sv_id|unique ID of the SV|\n|sv_length|SV length|\n|qual|quality score|\n|filter|filter. 'PASS' if the call passed all filtering steps.| \n|info|detailed information of the SV call|\n\nFor the meaning of \"endpoint1_type\" and \"endpoint2_type\", please refer to our manuscript ([Citation](#Citation))\n\n### \u003ca name=\"Intermediate_files\"\u003e\u003c/a\u003e Intermediate files\n\nLinkedSV also outputs an intermediate files:\n\n```\nprefix.bcd21.gz\n```\n\nThis file contains the data that can be used to visualize the SV evidence. \n\nLinkedSV will also generate an `images` directory in the output directory. The figures showing the evidence of the SV are under this directory. Currently, only the evidence of SVs detected from linked-reads using barcode information (in the `prefix.filtered_large_svcalls.bedpe` file) are plotted.\n\n## \u003ca name=\"Visualization\"\u003e\u003c/a\u003e Visualization of SV calls\n\nAfter SV calling, LinkedSV will plot high-resolution figures showing the evidence of the SV, so that you can see them intuitively. \n\nCurrently, LinkedSV will plot 3 types of evidence:\n1) read depth (for all SV calls)\n2) evidence of decrease of overlapping barcodes between adjcent twin windows (for balanced SV calls)\n3) Heat maps of overlapping barcodes (for all SV calls)\n\nThese figures are generated in the `images` directory under the output directory. The structure of the `images` directory is:\n\n```\nlinkedsv_out_dir\n|-- images\n    |-- read_depth\n        |-- prefix.ID01.read_depth.png\n        |-- prefix.ID02.read_depth.png\n        \n    |-- twin_window_barcode_similarity\n        |-- prefix.ID01.breakpoint1.twin_window_barcode_similarity.png\n        |-- prefix.ID01.breakpoint2.twin_window_barcode_similarity.png\n        |-- prefix.ID02.both_breakpoints.twin_window_barcode_similarity.png \n        \n    |-- 2D_heatmap\n        |-- prefix.ID01.heatmap.png\n        |-- prefix.ID01.heatmap.png\n```\n\n\n### \u003ca name=\"read_depth\"\u003e\u003c/a\u003e Read depth\n\nHere are some example figures for different SV types. The figures were plotted from the SV calls on the [HX1 genome](http://dx.doi.org/10.1038/ncomms12065). The dotted blue line showed the average depth across the whole genome. The predicted breakpoints were indicated by vertical red lines. The black line showed the depth of confidently mapped reads (map quality \u003e= 20) and the grey line showed the depth of all reads (map quality \u003e= 0). The black line is in front of the grey line. So if you do not see the grey lines, then the black and grey lines are in the same place (i.e. the region is of high map quality). \n\n**Deletion**\n![DEL](example_plots/DEL/hx1_hg38.ID0097.read_depth.png)\nThe region between the two red lines has lower read depth. \n\n\n\n\n**Duplication**\n![DUP](example_plots/DUP/hx1_hg38.ID0137.read_depth.png)\nThe region between the two red lines has higher read depth. \n\n\n\n\n**Inversion**\n![INV](example_plots/INV/hx1_hg38.ID0132.read_depth.png)\nThe region between the two red lines has same read depth as the flanking regions. \n\n\n \n### \u003ca name=\"Twin_window_evidence\"\u003e\u003c/a\u003e Twin-window evidence\n\nLinkedSV plots the twin-window evidence for balanced SV events, such as inversions and balanced translocations. The barcodes between two nearby genome locations is highly similar because the two locations are spanned by almost the same set of input HMW DNA molecules. However, due to the genome rearrangement, the reads mapped to the left side and right side of a breakpoint may originate from different locations of the alternative genome and thus have different barcodes. \n\nDropped barcode similarity between two nearby loci therefore indicates a SV breakpoint. LinkedSV detects this type of evidence by a twin-window method, which uses two adjacent sliding windows to scan the genome and find regions where the barcode similarity between the two nearby window regions are significantly decreased. (Please refer to our manuscript for the detailed explaination: [Citation](#Citation) )\n\nHere is an example figure of the twin-window evidence. It was plotted from an inversion call on the HX1 genome. X-axis is the position of the middle of the twin windows. Y-axis is the -log10(P-value), where P-value means the probabity that the overlapping barcodes between the twin windows is less than or equal to the observed number assuming no SV. \n\nIn the following figure, the red line showed the predicted breakpoint. Since the P-value is very small at the breakpoints, Y values (-log10(P-value)) are very high and form two peaks at the breakpoints. \n\n\n**Inversion**\n![INV](example_plots/INV/hx1_hg38.ID0132.both_breakpoints.twin_window_barcode_similarity.png)\n\n\n\n\n\n\n### \u003ca name=\"Heat_Map\"\u003e\u003c/a\u003e Heat map of overlapping barcodes\n\n\nLinkedSV also plots the 2D heat maps of overlapping barcodes. This figure is similar to the figure showed by [Loupe](https://support.10xgenomics.com/genome-exome/software/visualization/latest/what-is-loupe), which was developped by 10X Genomics. The slight difference is that the color map of LinkedSV is of wider range (0-100). \n\nThe resolution is 1000 bp. The color of each dot indicates the number of overlapping barcodes between two genomics positions (X and Y coordinates of the dot). \n\nSome example figures are here. \n\n**Deletion**\n![DEL](example_plots/DEL/hx1_hg38.ID0097.heatmap.png)\n\n\n\n\n**Duplication**\n![DUP](example_plots/DUP/hx1_hg38.ID0231.heatmap.png)\n![DUP](example_plots/DUP/hx1_hg38.ID0137.heatmap.png)\n\n\n\n\n**Inversion**\n![INV](example_plots/INV/hx1_hg38.ID0132.heatmap.png)\n\n\n## \u003ca name=\"Future_extensions\"\u003e\u003c/a\u003e Future extensions \nRecently, [BGI](https://www.bgi.com/us/) and [Complete Genomics](https://www.completegenomics.com/) developped **single tube long fragment read (stLFR)** ([Genome Res. 2019](https://genome.cshlp.org/content/early/2019/04/02/gr.245126.118.abstract)), a technology that enables sequence data from long DNA molecules using second-generation sequencing technology. It is based on adding the same barcode sequence to sub-fragments of the original long DNA molecule (DNA co-barcoding). Since this technology is also a barcoded sequencing of long fragments, LinkedSV is planned to support stLFR in the near future. \n\n## \u003ca name=\"Citation\"\u003e\u003c/a\u003e Citation\nIf you use LinkedSV in your work, please cite:\n\u003e Li Fang, Charlly Kao, Michael V Gonzalez, Fernanda A Mafra, Renata Pellegrino da Silva, Mingyao Li, Soren Wenzel, Katharina Wimmer, Hakon Hakonarson, Kai Wang. [LinkedSV: Detection of mosaic structural variants from linked-read exome and genome sequencing data](https://www.nature.com/articles/s41467-019-13397-7). *Nature Communications*, 10:5585, 2019\n\n## \u003ca name=\"Getting_Help\"\u003e\u003c/a\u003e Getting Help\n\nPlease use the [GitHub's Issues page](https://github.com/WGLab/LinkedSV/issues) if you have questions.\n\n## \u003ca name=\"License\"\u003e\u003c/a\u003e License Agreement\n\nLinkedSV is under the [MIT license](https://wglab.mit-license.org/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwglab%2Flinkedsv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwglab%2Flinkedsv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwglab%2Flinkedsv/lists"}