GW - Genome Browser¶

GW is a fast, terminal-based genome browser that enables interactive visualisation and annotation of genomic sequencing data directly from the command line. GW provides high-performance viewing of:

Alignment data: BAM and CRAM files with read-level detail
Variant data: VCF and BCF files with annotation capabilities
Feature tracks: BED files, labels, and other genomic features
Images: PNG thumbnails and static image generation

GW can display multiple regions side-by-side, supports real-time navigation and filtering, and allows you to save annotations and generate publication-quality images without leaving the terminal environment.

Why it's helpful¶

GW addresses several key challenges in genomic data analysis within the Research Environment:

Speed and efficiency: GW is optimised for fast rendering of large genomic datasets, making it ideal for reviewing alignment quality, investigating structural variants, and validating variant calls across multiple samples.

Terminal-based workflow: GW runs from the terminal making it easy to integrate with command-line workflows.

Variant annotation: GW provides an interactive interface for reviewing and annotating variants, allowing you to label variants with custom categories and save annotations for further analysis or reporting.

Multiple views: GW can display multiple genomic regions and tracks simultaneously: - Tumour-normal pairs in cancer samples - Breakpoint regions in structural variants - Homologous regions across different chromosomes - Mate pair locations in discordant read pairs

Flexible output: Generate static images programmatically with support for PNG, PDF and SVG formats.

How to use it¶

Installation¶

GW is not pre-installed in the Research Environment. You will need to install it using conda within your personal environment.

Follow the instructions for setting up conda in the RE then set up the environment like:

conda create -n gw_env -c conda-bioconda -c conda-conda-forge gw --prefix $HOME/conda_envs/gw_env

This creates a new environment called gw_env in your home directory with GW installed. Activate the environment with:

conda activate $HOME/conda_envs/gw_env

You're now ready to use GW! To verify installation:

gw --version

Setting up a reference genome¶

Due to network restrictions in the RE, you cannot use the online reference genomes that GW downloads automatically. Instead, you must use local reference genome files.

Option 1: Use public reference genomes available in the REOption 2: Use your own reference genome

The RE provides reference genome files at: - GRCh38/hg38: /public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa - GRCh37/hg19: /public_data_resources/reference/hs37d5.fa

If you have imported your own reference genome, ensure it is: - In FASTA format - Indexed with samtools (.fai file present) - Accessible from your working directory or provide the full path

Basic usage examples¶

View a genomic region¶

To view alignments for a specific region, specify the reference genome and BAM file:

gw /public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa \
   -b /path/to/your.bam \
   -r chr1:1000000-1020000

View multiple regions side-by-side¶

Compare two different genomic regions simultaneously:

gw /public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa \
   -b /path/to/your.bam \
   -r chr1:1000000-1020000 \
   -r chr2:5000000-5020000

Load multiple BAM files¶

Compare alignments from different samples or analyses:

gw /public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa \
   -b tumour.bam \
   -b normal.bam \
   -r chr17:7571720-7590868

View variants¶

Open a VCF/BCF/BED file, this will generate tiled-images of variants from the bam file:

gw /public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa \
   -b /path/to/your.bam \
   -v /path/to/variants.vcf \
   -r chr1:1000000-1020000

Add genomic feature tracks¶

Include BED files or other tracks, these are displayed below the alignments:

gw /public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa \
   -b /path/to/your.bam \
   --track genes.bed \
   -r chr1:1000000-1020000

Interactive commands¶

Once GW is running, you can use commands by pressing : or /:

Command	Description
`help`	Display help menu with all commands
`chr1:1000000-1020000`	Navigate to a specific genomic region
`add chr2:1-50000`	Add a new region view
`rm 1`	Remove region at column index 1
`rm bam1`	Remove BAM file at row index 1
`mate`	Jump to the mate pair location of selected read
`mate add`	Add mate pair location in new view
`line`	Toggle vertical reference line
`ylim 100`	Set read depth view limit to 100
`find QNAME`	Highlight all reads with specific QNAME
`filter mapq >= 10`	Filter reads by mapping quality
`count`	Display read counts for all views
`snapshot`	Save screenshot as PNG
`man COMMAND`	View manual for specific command

Variant annotation¶

GW provides an interactive workflow for annotating variants:

Load a VCF file with your BAM:

gw /public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa \
   -b sample.bam \
   -v variants.vcf \
   --labels Pathogenic,Benign,Uncertain

Navigate through variants using the thumbnail view (tiles display at the bottom)
Click on variant tiles to jump to that location
Assign labels to variants as you review them
Save your annotations directly from GW interface:
```
save annotations.tsv
```

Or, use the --out-labels option when you start GW: bash gw /public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa \ -b sample.bam \ -v variants.vcf \ --labels Pathogenic,Benign,Uncertain --out-labels annotations.tsv

Generating images for reports¶

Single region screenshot¶

Generate a PNG image of a specific region:

gw /public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa \
   -b sample.bam \
   -r chr1:1000000-1020000 \
   -n > region_view.png

PDF output¶

For publication-quality figures:

gw /public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa \
   -b sample.bam \
   -r chr1:1000000-1020000 \
   -n --fmt pdf -f figure1.pdf

Batch processing¶

Generate images for multiple chromosomes in parallel (useful for quality control reports, or checking for CNVs quickly):

gw /public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa \
   -t 24 \
   -b sample.bam \
   -n --outdir chromosome_plots

Saving reference genome in settings¶

To avoid typing the reference genome path each time you launch GW, you can save it in the GW configuration:

Step 1: Find your GW config file¶

gw --config

Step 2: Add reference genome paths¶

In the configuration file, add or edit the [genome] section with your preferred reference genome:

[genome]
hg38=/public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa
hg19=/public_data_resources/reference/hs37d5.fa

Step 3: Save and exit¶

Save the configuration file and exit the text editor. The next time you launch GW, you can simply use:

gw hg38 -b your.bam -r chr1:1000000-1020000

Instead of typing the full path to the reference genome each time.

FAQs¶

Installation and setup

Can I install GW directly with conda install gw?

Not without specifying the correct channels and prefix. You must use the conda proxy channels configured in .condarc and specify a personal installation location as shown in the installation steps above.

How do I activate GW after installation?

Each time you want to use GW, you need to:

source /resources/conda/miniconda3/bin/activate
conda activate $HOME/conda_envs/gw_env

Consider adding an alias to your .bashrc file for convenience:

echo "alias gw_activate='source /resources/conda/miniconda3/bin/activate && conda activate $HOME/conda_envs/gw_env'" >> ~/.bashrc

Reference genomes

Can I use the built-in GW reference genomes (hg19, hg38, etc.)?

No. The built-in genomes require internet access to download, which is restricted in the RE. You must use local reference genome files.

What reference genome file should I use?

For GRCh38, use:

/public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa

For GRCh37, use:

/public_data_resources/reference/hs37d5.fa

Ensure the reference genome matches the alignment build of your BAM/CRAM files.

Using GW

Can I view CRAM files?

Yes, GW supports CRAM files. Make sure to specify the reference genome that was used for CRAM compression:

gw /public_data_resources/reference/GRCh38_full_analysis_set_plus_decoy_hla.fa \
   -b sample.cram \
   -r chr1:1000000-1020000

How do I navigate to a new region?

Press / to open the command box, then type the region (e.g., chr1:1000000-1020000) and press Enter.

How do I compare two positions (e.g., read and its mate)?

Click on a read, then use the command mate add to open the mate location in a new panel.

File formats

What file formats does GW support?

GW supports:

Alignments: BAM, CRAM (both must be indexed with .bai or .crai)
Variants: VCF, BCF (can be compressed with bgzip and indexed with tabix)
Tracks: BED, GFF, GTF
Images: PNG

My BAM file won't load

Ensure:

The BAM file is indexed (.bai file present)
You have read permissions for both files
The BAM file is not corrupted

Generate an index if missing:

samtools index input.bam

Performance and resources

What resources does GW need?

GW is relatively lightweight:

Memory: 1-4GB typically sufficient (depends on coverage and region size)
CPU: 1 core is usually adequate (can use multiple cores with -t for batch image generation)
Display: Requires X11 forwarding if accessing remotely

Output and export

How do I save images?

For interactive viewing, use the snapshot command to save a PNG of the current view.

For programmatic image generation:

gw reference.fa -b sample.bam -r chr1:1000000-1020000 -n > output.png

Can I export my variant annotations?

Yes, use the --out-labels option:

gw reference.fa -b sample.bam -v variants.vcf --labels Pass,Fail --out-labels annotations.tsv

What format are the annotation outputs?

Annotations are saved as tab-separated values (TSV) files that can be opened in Excel, R, or Python for further analysis.

Troubleshooting

I get "command not found" when running gw

Make sure you've activated the conda environment:

source /resources/conda/miniconda3/bin/activate
conda activate $HOME/conda_envs/gw_env

Where can I find more help?

1. View the in-app help: Type /help within GW 2. Read the full documentation: https://kcleal.github.io/gw/ 3. Check the command manual: Use /help COMMAND for specific commands 4. Contact RE support through the standard support channels for general usage questions

I found a bug or want to request a feature

As this is a community-shared resource, we cannot guarantee bug fixes or feature additions. You may view the GitHub repository at https://github.com/kcleal/gw for technical information, but please do not contact the creator directly for support.