This page gives basic information on how to use PyBamView. To learn how to set up a web server to host a PyBamView instance, see Serving PyBamView remotely. To automatically generate alignment snapshots on the command line, see Generating PyBamView Snapshots

example command

Here's an example command using files from the download to get you started. You can find the example data files here. Keep reading for more detailed instructions.

pybamview --bam examples/example.sorted.bam

This will open a browser pointing to 127.0.0.1:5000. Try navigating to different genomic locations, e.g. chr11:2192266.

getting started

To get started with PyBamView, make sure you have a BAM file that has been sorted and indexed using samtools. Assuming you already have samtools installed, this requires two simple commands:

samtools sort mybam.bam mybam.sorted

samtools index mybam.sorted.bam

Optionally, you can also provide a reference genome in fasta format. Then simply type:

pybamview --bam PATH/TO/BAM --ref REF.fasta

This will by default give you a localhost URL for port 5000. The default web browser will then be automatically opened pointing to 127.0.0.1:5000 and display the first reads it found in the BAM file.

Note, you can also use PyBamView to view alignments from multiple BAM files at once. To do this, use the "--bamdir" option to provide PyBamView with a directory. PyBamView will look for any indexed bams in that directory, detect which samples are in those bams, and display them as a checklist. If no samples are showing up, make sure you have indexed your bam files and that all reads are annotated with a read group (see here for more information about read groups and BAM faq). Select which samples you would like to view and click "View selected samples".

This will take you to a page visualizating the alignments. If you specified a reference genome, that will be displayed at the top of the alignments (else it will be all Ns). Below the reference is a section for each sample contained in the bam files. You can navigate to a specific genomic region by entering a location in the form "$chrom:position" (e.g. chr1:1000) in the box that says "Enter region". Mouse over a column to see which genomic position you're at. Use the zoom buttons to zoom in and out of the alignment view. Mouse over the question marks for usage tips.

exporting snapshots to PDF

PyBamView can easily export alignment snapshots to PDF format. When viewing an alignment, click the "Export snapshot" button on the top left. This will open a new window where you can tweak the alignment display. When you're happy with the region and samples selected, click "Download PDF" to obtain the PDF file.

viewing a set of target regions

If you're interested in a specific set of target regions (for instance, Y-STRs), you can upload a bed file containing these targets using the "--targets" option. An example targets file is included in the example data files. Then you'll see a drop down box on the alignment page that will allow you to quickly navigate to a marker of interest.

full command line usage

To see the usage information for PyBamView, type:

>pybamview --help
Usage: pybamview [options]

pybamview: An Python-based BAM alignment viewer.

Options:
  -h, --help         show this help message and exit
  --bam=BAM          Run Pybamview on this BAM file only. The file must be
                     indexed.
  --bamdir=BAMDIR    Directory to look for bam files. Bam files must be
                     indexed.
  --ref=REF          Path to reference fasta file. If no reference is given,
                     the reference track is displayed as Ns
  --ip=IP            Host IP. 127.0.0.1 for local host (default). 0.0.0.0 to
                     have the server available externally.
  --port=PORT        The port of the webserver. Defaults to 5000.
  --targets=TARGETS  Bed file with chrom, start, end, and name. Allows you to
                     easily jump to these targets.
  --buffer=BUFFER    How many nucleotides to load into memory. Default: 200.
                     Buffering more allows you to scroll farther. Buffering
                     less is faster.
  --maxzoom=MAXZOOM  Maximum number of times to be able to zoom out. E.g.
                     --maxzoom 10 allows zooming out up to 10x. Default: 100.
                     Must be between one of 1-10, 50, or 100.
  --no-browser       Do not automatically open the web browser.
  --debug            Run PyBamView in Flask debug mode