{"id":13756405,"url":"https://github.com/tobiasrausch/wally","last_synced_at":"2025-04-13T16:21:50.035Z","repository":{"id":41108346,"uuid":"419066147","full_name":"tobiasrausch/wally","owner":"tobiasrausch","description":"Wally: Visualization of aligned sequencing reads and contigs","archived":false,"fork":false,"pushed_at":"2024-02-05T12:29:50.000Z","size":7315,"stargazers_count":89,"open_issues_count":1,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-02-12T15:54:59.339Z","etag":null,"topics":["alignment","assembly","contigs","genomics","mapping","plotting","sequencing","sequencing-data","visualization"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tobiasrausch.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,"roadmap":null,"authors":"AUTHORS","dei":null}},"created_at":"2021-10-19T19:34:08.000Z","updated_at":"2024-02-12T09:42:29.000Z","dependencies_parsed_at":"2024-02-05T13:39:46.050Z","dependency_job_id":null,"html_url":"https://github.com/tobiasrausch/wally","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobiasrausch%2Fwally","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobiasrausch%2Fwally/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobiasrausch%2Fwally/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobiasrausch%2Fwally/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tobiasrausch","download_url":"https://codeload.github.com/tobiasrausch/wally/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248741846,"owners_count":21154386,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["alignment","assembly","contigs","genomics","mapping","plotting","sequencing","sequencing-data","visualization"],"created_at":"2024-08-03T11:00:43.563Z","updated_at":"2025-04-13T16:21:50.029Z","avatar_url":"https://github.com/tobiasrausch.png","language":"C++","funding_links":[],"categories":["A list of software capable of analyzing mainly **eukaryotic** genomes for pangenomics.","Alignments"],"sub_categories":[],"readme":"[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat-square)](http://bioconda.github.io/recipes/wally/README.html)\n[![Anaconda-Server Badge](https://anaconda.org/bioconda/wally/badges/downloads.svg)](https://anaconda.org/bioconda/wally)\n[![C/C++ CI](https://github.com/tobiasrausch/wally/workflows/C/C++%20CI/badge.svg)](https://github.com/tobiasrausch/wally/actions)\n[![Docker CI](https://github.com/tobiasrausch/wally/workflows/Docker%20CI/badge.svg)](https://hub.docker.com/r/trausch/wally/)\n[![GitHub license](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/tobiasrausch/wally/blob/master/LICENSE)\n[![GitHub Releases](https://img.shields.io/github/release/tobiasrausch/wally.svg)](https://github.com/tobiasrausch/wally/releases)\n\n# Wally\n\nPlotting of aligned sequencing reads, assembled contigs or pan-genome graphs in BAM/CRAM format and visualization of genomic variants.\n\n## Installing Wally\n\nWally is available as a [Bioconda package](https://anaconda.org/bioconda/wally), as a pre-compiled static binary from the [release page](https://github.com/tobiasrausch/wally/releases/), as a singularity container [SIF file](https://github.com/tobiasrausch/wally/releases/) or as a minimal [Docker container](https://hub.docker.com/r/trausch/wally/). You can also build Wally from source using a recursive clone and make. \n\n`git clone --recursive https://github.com/tobiasrausch/wally.git`\n\n`cd wally/`\n\n`make all`\n\n\n## Running Wally\n\nWally uses subcommands for different visualization modes.\n\n## Subcommand `region`: Visualization of alignment regions\n\nWally needs a sorted and indexed BAM/CRAM file and a reference genome. The output is a genomic alignment plot of the region specified on the command-line.\n\n`wally region -r chrA:35-80 -g \u003cgenome\u003e \u003cinput.bam\u003e`\n\nYou can specify a plot name using another colon separator\n\n`wally region -r chrA:35-80:myplot -g \u003cgenome\u003e \u003cinput.bam\u003e`\n\nMost often you probably want to use a BED file with regions of interest and just execute wally in batch. The 4-th column specifies the plot name. For instance to plot variants from a VCF file you can use:\n\n`bcftools query -f \"%CHROM\\t%POS\\n\" \u003cinput.vcf.gz\u003e | awk '{print $1\"\\t\"($2-50)\"\\t\"($2+50)\"\\tid\"NR;}' \u003e regions.bed`\n\n`wally region -R regions.bed -g \u003cgenome\u003e \u003cinput.bam\u003e`\n\n### Gene annotations\n\nSimple BED files are used to provide gene or other annotations. The BED file needs to be bgzipped and indexed via tabix (`tabix -p bed input.bed.gz`). The required columns are chromosome, start, end and an identifier which is displayed if there is sufficient space.\n\n`wally region -b bed/gencode.hg19.bed.gz -r chr17:7573900-7574000 -g \u003cgenome\u003e \u003cinput.bam\u003e`\n\nThe chromosome names of the genome FASTA file, BAM file and BED annotation file need to match, \"chr11\" and \"11\" are not considered identical.\n\n### Custom colors for BED file annotations\n\nYou can specify custom colors for each annotation record in the BED file using Hex color codes (column 5 of the BED file). For instance, an annotation file `anno.bed` with this content:\n\n```\nchr17\t7350100\t7350900\tregRed\t0xFF0000\nchr17\t7351100\t7351900\tregLime\t0x00FF00\nchr17\t7352100\t7352900\tregBlue\t0x0000FF\nchr17\t7353100\t7353900\tregTeal\t0x008080\n```\n\ncan be visualized using\n\n`bgzip anno.bed`\n\n`tabix -p bed anno.bed.gz`\n\n`wally region -b anno.bed.gz -r chr17:7350000-7354000 -g \u003cgenome\u003e \u003cinput.bam\u003e`\n\n\n### Multiple BAM files\n\nYou can include multiple BAM files in a plot such as a tumor genome and a matched control in cancer genomics.\n\n`wally region -r chr17:7573900-7574000 -g \u003cgenome\u003e \u003ctumor.bam\u003e \u003ccontrol.bam\u003e`\n\nIn fact, wally can be used to create \"wallpapers\" of genomes which gave rise to the tool name. For instance, the below command can be used to create a full genome view of 96 samples of a full plate of SARS-CoV-2 genomes.\n\n`wally region -y 20480 -r NC_045512.2:1-30000 -g NC_045512.2.fa Plate*.bam`\n\n### Aligning multiple regions horizontally (split view)\n\nWally allows concatenating images of different regions horizontally using the `--split` option. This can be used, for instance, to zoom into a specific variant. On the command line the regions need to be separated by `,` without spaces. As an example, you can zoom into the N501Y variant of the alpha SARS-CoV-2 lineage using \n\n`wally region -s 3 -x 2048 -r NC_045512.2:22000-24000,NC_045512.2:23000-23100,NC_045512.2:23050-23070 -g NC_045512.2.fa \u003cinput.bam\u003e`\n\nYou can split horizontally and vertically at the same time to view, for instance, a somatic inter-chromosomal translocation.\n\n`wally region -s 2 -r chrA:35-80,chrB:60-80 -g \u003cgenome\u003e \u003ctumor.bam\u003e \u003ccontrol.bam\u003e`\n\nIf you specify the regions in a BED file using the `-R` option then the split parameter operates row-wise, e.g., for `-s 3` row 1-3 of the BED file make up the first image, row 4-6 the second image, and so on.\n\n### Paired-end view\n\nWith `-p` you can switch on the paired-end view. \n\n`wally region -p -r chrA:35-80 -g \u003cgenome\u003e \u003cinput.bam\u003e`\n\nThe paired-end coloring highlights candidate structural variants supported by read1 (R1) and read2 (R2). Below is a mapping of [delly's](https://github.com/dellytools/delly) structural variant types to [wally's](https://github.com/tobiasrausch/wally) paired-end coloring. For inter-chromosomal translocations I assumed for this illustration that R1 maps to chromosome A and R2 maps to chromosome B.\n\n- ![#3fafaf](https://via.placeholder.com/15/3fafaf/3fafaf.png) `  inversion-type paired-end, --R1--\u003e   --R2--\u003e, INV:3to3`\n- ![#4e64d5](https://via.placeholder.com/15/4e64d5/4e64d5.png) `  inversion-type paired-end, \u003c--R1--   \u003c--R2--, INV:5to5`\n- ![#d53f3f](https://via.placeholder.com/15/d53f3f/d53f3f.png) `   deletion-type paired-end, --R1--\u003e   \u003c--R2--, DEL:3to5`\n- ![#3faf3f](https://via.placeholder.com/15/3faf3f/3faf3f.png) `duplication-type paired-end, \u003c--R1--   --R2--\u003e, DUP:5to3`\n- ![#fb9a99](https://via.placeholder.com/15/fb9a99/fb9a99.png) `inter-chr paired-end, A:--R1--\u003e B:--R2--\u003e leads to --A--\u003e \u003c--B-- junction, BND:3to3`\n- ![#fdbf6f](https://via.placeholder.com/15/fdbf6f/fdbf6f.png) `inter-chr paired-end, A:\u003c--R1-- B:\u003c--R2-- leads to \u003c--A-- --B--\u003e junction, BND:5to5`\n- ![#ff8000](https://via.placeholder.com/15/ff8000/ff8000.png) `inter-chr paired-end, A:--R1--\u003e B:\u003c--R2-- leads to --A--\u003e --B--\u003e junction, BND:3to5`\n- ![#cab2d6](https://via.placeholder.com/15/cab2d6/cab2d6.png) `inter-chr paired-end, A:\u003c--R1-- B:--R2--\u003e leads to \u003c--A-- \u003c--B-- junction, BND:5to3`\n\nFor large and complex structural variants, wally supports split views (as explained above). For instance, for an inter-chromosomal translocation you probably want to use a 2-way horizontal split with a larger image size.\n\n`wally region -p -x 2048 -y 2048 -s 2 -r chrA:35-80,chrB:60-80 -g \u003cgenome\u003e \u003ctumor.bam\u003e \u003ccontrol.bam\u003e`\n\nTo visualize genomic breakpoints it's also helpful to highlight clipped reads `-c` and supplementary alignments `-u`.\n\n`wally region -cup -x 2048 -y 2048 -s 2 -r chrA:35-80,chrB:60-80 -g \u003cgenome\u003e \u003ctumor.bam\u003e \u003ccontrol.bam\u003e`\n\n## Subcommand `matches`: Visualization of chained alignment matches\n\nFor long read alignments or mappings of entire contigs, one often wants to explore all matches of a long input sequence with respect to the reference to visualize, for instance, complex rearrangements. For a single read or contig, you need a sorted and indexed BAM file and the reference genome.\n\n`wally matches -r \u003cread_name\u003e -g \u003cgenome\u003e \u003cinput.bam\u003e`\n\nForward matches are colored in blue, reverse matches in orange and the black line traces all alignment matches along the input read sequence. You can also plot multiple reads to inspect, for instance, alignment concordance or heterogeneity using a list of reads as an input file.\n\n`wally matches -R \u003cread.lst\u003e -g \u003cgenome\u003e \u003cinput.bam\u003e`\n\nFor many reads, this quickly leads to \"wall(y)papers\". With `-p` you get a separate plot for each read.\n\n`wally matches -p -R \u003cread.lst\u003e -g \u003cgenome\u003e \u003cinput.bam\u003e`\n\nYou can also compare assemblies or align contigs to a reference genome using a workflow like this:\n\n`minimap2 -ax asm5 ref.fa asm.fa | samtools sort -o assembly.bam -`\n\n`samtools index assembly.bam`\n\n`wally matches -r \u003ccontig_name\u003e -g ref.fa assembly.bam`\n\n## Subcommand `dotplot`: Pairwise sequence dotplots\n\nAll pairwise dotplots of a FASTA file can be generated using\n\n`wally dotplot sequences.fa`\n\nYou can also extract reads directly from the BAM file and generate a reference-independent dotplot that includes the genomic mapping locations of read segments.\n\n`wally dotplot -R reads -g hg38.fa input.bam`\n\nFor instance, to inspect haplotype differences or tumor heterogeneity at a given genomic locus (e.g., `chrA:1000-2000`) one can use:\n\n`samtools view input.bam chrA:1000-2000 | cut -f 1 | sort | uniq \u003e reads`\n\n`wally dotplot -R reads -g hg38.fa input.bam`\n\nInstead of plotting reads in pairs against each other, you can also calculate dot plots with respect to reference regions.\n\n`wally dotplot -g hg38.fa -R reads -e chrA:35000-80000 input.bam`\n\n`wally dotplot -g hg38.fa -e chrA:35000-80000 sequences.fa`\n\nA minimum contig or read length can be specified using `-s`\n\n`wally dotplot -s 10000 -R reads -g hg38.fa input.bam`\n\nLastly, you can flatten the genomic mappings into simple blocks using `-f`\n\n`wally dotplot -f -s 10000 -R reads -g hg38.fa input.bam`\n\nTo visualize a self-alignment of a read with reference mappings use `-a`\n\n`wally dotplot -a -r read_name -g hg38.fa input.bam`\n\n## Web application\n\nYou can try wally on some selected data sets using the [wally web application](https://www.gear-genomics.com/wally/).\n\n## Citation\n\nTobias Rausch, Rene Snajder, Adrien Leger, Milena Simovic, Mădălina Giurgiu, Laura Villacorta, Anton G. Henssen, Stefan Fröhling, Oliver Stegle, Ewan Birney, Marc Jan Bonder, Aurelie Ernst, Jan O. Korbel     \nLong-read sequencing of diagnosis and post-therapy medulloblastoma reveals complex rearrangement patterns and epigenetic signatures     \nCell Genomics, 2023, 100281, [DOI: 10.1016/j.xgen.2023.100281](https://doi.org/10.1016/j.xgen.2023.100281)     \n\n## License\n\nWally is distributed under the BSD 3-Clause license. Consult the accompanying [LICENSE](https://github.com/tobiasrausch/wally/blob/master/LICENSE) file for more details.\n\n## Credits\n\nWally relies heavily on the [HTSlib](https://github.com/samtools/htslib) and [OpenCV](https://github.com/opencv/opencv). The visualization of genomic alignments was heavily inspired by [IGV](https://github.com/igvteam/igv).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobiasrausch%2Fwally","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftobiasrausch%2Fwally","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobiasrausch%2Fwally/lists"}