{"id":13756412,"url":"https://github.com/w-gao/pgv","last_synced_at":"2026-01-18T00:41:15.645Z","repository":{"id":150345188,"uuid":"591749269","full_name":"w-gao/pgv","owner":"w-gao","description":"A web-based, interactive pangenome visualization tool","archived":false,"fork":false,"pushed_at":"2023-04-10T17:52:42.000Z","size":1206,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-03-23T11:13:20.310Z","etag":null,"topics":["bioinformatics","genomics","genomics-visualization","variation-graph"],"latest_commit_sha":null,"homepage":"https://w-gao.github.io/pgv/","language":"TypeScript","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/w-gao.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":null,"dei":null}},"created_at":"2023-01-21T18:39:49.000Z","updated_at":"2024-03-23T11:13:29.151Z","dependencies_parsed_at":null,"dependency_job_id":"ebe6a2fd-fa78-46da-a7b6-365d779f6e07","html_url":"https://github.com/w-gao/pgv","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w-gao%2Fpgv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w-gao%2Fpgv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w-gao%2Fpgv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w-gao%2Fpgv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/w-gao","download_url":"https://codeload.github.com/w-gao/pgv/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253358069,"owners_count":21895967,"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":["bioinformatics","genomics","genomics-visualization","variation-graph"],"created_at":"2024-08-03T11:00:43.658Z","updated_at":"2026-01-18T00:41:15.639Z","avatar_url":"https://github.com/w-gao.png","language":"TypeScript","funding_links":[],"categories":["A list of software capable of analyzing mainly **eukaryotic** genomes for pangenomics."],"sub_categories":[],"readme":"# pgv\n\n\u003e A web-based, interactive pangenome visualization tool\n\n\u003cimg src=\"https://user-images.githubusercontent.com/20177171/223407059-c04406bd-4b6c-427f-b1c3-106aaad06257.png\" width=\"250px\" /\u003e\n\n[![demo](https://github.com/w-gao/pgv/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/w-gao/pgv/actions/workflows/deploy.yml)\n\n\n## Motivation\n\nA pangenome represents genetic variation in a population as a _variation graph_, which greatly reduces the reference\nbias that comes from using a linear reference genome. However, a linear reference genome is more intuitive to\nunderstand and has been the traditional way that bioinformaticians use. As an effort to make it easier to visualize\nand interpret variation graphs, I present `pgv`, an interactive visualization tool built on top of previous work\nthat aims to display structural variants in a variation graph interactively.\n\nInstead of fitting the nodes, edges, and paths of a variation graph in a 2-dimensional space, `pgv` draws the sequence\ngraph itself on the x-y plane, and paths are rendered as separate layers that can be interactively selected/highlighted.\n\n\n## Screenshots\n\n![image](https://user-images.githubusercontent.com/20177171/223253829-4691fe27-412e-4474-927e-9e246f777885.png)\n\n\n- The _paths_ in a variation grpah can be interactively selected/highlighted:\n\n![image](https://user-images.githubusercontent.com/20177171/222947953-805d83d4-a556-41d8-963b-0124ba374898.gif)\n\n\n## Getting Started\n\nA live demo is available at: https://w-gao.github.io/pgv.\n\nIf you want to try `pgv` yourself, you can get started in the following ways. **Keep in mind that this project is under\ndevelopment and may not work well with your own data**. If you encounter any issues, please let me know by\n[opening an issue](https://github.com/w-gao/pgv/issues).\n\n\n### Run via Docker\n\nThe easiest way to run `pgv` is through Docker:\n\n```console\n$ docker pull wlgao/pgv:latest\n```\n\nTo run a container:\n\n```console\n$ docker run -d --name pgv \\\n    -v \"$(pwd)/examples\":/pgv/ui/examples \\\n    -p 8000:8000 \\\n    wlgao/pgv:latest\n```\n\nThis creates a container in detach (`-d`) mode, exposes port `8000`, with a volume for the graph files.\n\nYou can add additional volumes if you want to construct your own graphs inside the container, or, if you have\n[`vg`](https://github.com/vgteam/vg/) installed on your local system, you can use the [pgv CLI](./cli.py) to\npre-process graphs.\n\nIf successful, `pgv` should be running at:\n\n```\nhttp://localhost:8000\n```\n\nTo stop the container, run:\n\n```concole\ndocker stop pgv\n```\n\n\n### Run from source\n\nAlternatively, you can pull the source code and build the project yourself. You would need the following minimum\nrequirements:\n\n```\n- Node.js \u003e= 16\n- Yarn \u003c 2\n- Python \u003e= 3.8\n```\n\nTo clone the repo:\n\n```console\nget clone https://github.com/w-gao/pgv.git\ncd pgv\n```\n\nThen, build the project:\n\n```console\n# Run the prebuild script.\n# Note: this script requires curl.\n./prebuild.sh\n\n# Build core package.\nyarn core:build\n\n# Build web package.\nyarn web:build\n\n# Start a preview HTTP server.\nyarn web:preview\n```\n\nIf successful, `pgv` should be running at:\n\n```\nhttp://localhost:8000\n```\n\n\n## UI - Usage\n\nWhen you select a graph, you are presented with this interface:\n\n![image](https://user-images.githubusercontent.com/20177171/223928293-6c678556-dbea-4936-933b-caa04e78333d.png)\n\n\nThis is split into three sections:\n\n- The header for graph selection and navigation\n- The [sequenceTubeMap](https://github.com/vgteam/sequenceTubeMap) render of the graph\n- The `pgv` render of the graph\n\n\n### Basic controls\n\n- To navigate the graph, you can use the `←` and `→` buttons in the header, or the `A` and `D` keys.\n- To cycle between the paths, you can use the `↑` and `↓` buttons, or the `up` and `down` arrow keys.\n- You can also move closer or away from the graph using the `W` and `S` keys, up and down using the `R` and `F` keys.\n- (controls such as movement speed are limited at the moment, but can be easily added if needed)\n\n\n## Using your own graph\n\nIf you want to use your own data, you need to pre-process the files first. This can be done by the [pgv CLI](./cli.py).\nCurrently supported file formats are: FASTA (`.fa`), VCF (`.vcf`, `.vcf.gz`), and GBWT (`.gbwt`).\n\nThe following assumes that you have [`vg`](https://github.com/vgteam/vg/) installed. You also need [`cli.py`](./cli.py),\nwhich is pre-installed inside the pgv container, or can be downloaded via:\n\n```console\ncurl -O https://raw.githubusercontent.com/w-gao/pgv/main/cli.py\n```\n\n\nFor example, to construct a graph from a FASTA file (`x.fa`) and a VCF file (`x.vcf.gz`), run:\n\n```console\n$ python3 cli.py add example \\\n        --reference x.fa \\\n        --vcf x.vcf.gz\n```\n\nThis will pre-process the input files and output the results to the folder set by `--dest`, which is `./examples/` by\ndefault. When running locally, the dev server symlinks to this default folder to grab the graph files. When running via\nDocker, the `/pgv/ui/examples` path inside the container is statically served. If you decide to modify this path, make\nsure to update the configuration for the respective places as well.\n\nGraph genomes are often large, so you can specify a range to only display a small chunk of the graph. Additionally, you\ncan also specify a GBWT file to include additional haplotypes for the particular range. For example, to limit the above\ngraph to nodes from `1:100`, with more haplotypes from `x.vg.gbwt`:\n\n```\n$ python3 cli.py add example \\\n        --reference x.fa \\\n        --vcf x.vcf.gz\n        --node-range 1:100 \\\n        --gbwt-name x.vg.gbwt\n```\n\nIf you have an existing graph but want to update the range, you can use the `update` subcommand so it doesn't have to\nre-construct and re-index the graph file:\n\n```\n$ python3 cli.py update example \\\n        --node-range 1:100 \\\n        --gbwt-name x.vg.gbwt\n```\n\nFor more information on the CLI, run:\n\n```\n$ python3 cli.py --help\n```\n\n\n## License\n\nCopyright (c) 2023 William Gao. MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw-gao%2Fpgv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fw-gao%2Fpgv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw-gao%2Fpgv/lists"}