Pybamview

Browser-based application for viewing bam alignments


Serving PyBamView remotely

PyBamView uses Flask, which starts up a web application. This means that as well as using PyBamView to browse alignments locally on your own computer, you can also serve PyBamView at a URL that is visible to remote collaborators for easy sharing of alignment views.

Serving PyBamView from your own server

  1. Install PyBamView by following the installation instructions.
  2. Determine the hostname of your server: 
    hostname -f
  3. Run PyBamView, following the usage instructions. Use the option "--ip 0.0.0.0", which will allow a remote user to view the results. Also set which port to serve the web application by setting "--port $PORT" where $PORT is some large number, between 1024-65535. This must be a port for which your server's security settings allow incoming http traffic. The default port for PyBamView is 5000. An example command is shown below: 
    pybamview --bamdir . --ref hg19.fa --ip 0.0.0.0 --port 5000
  4. Navigate to http://$HOSTNAME:$PORT in a web broswer, where $HOSTNAME is the hostname mentioned above, and $PORT is the argument you used for the port. You can share this URL, or navigate to an interesting alignment view and copy the resulting URL from the browser, with another person that has access to the same server. Note that if you need VPN to access the server, the other user will probably also need VPN access to view the URL.

Serving PyBamView from an Amazon EC2 instance

You may want to host a PyBamView instance somewhere besides your own server, for instance if you want to keep it running indefinitely to publicly host your alignment data. A good option for doing this is through Amazon Web Services.

There are existing tutorials online (e.g. Getting a simple Flask app running on Amazon EC2) for how to serve a Python Flask application using Amazon EC2. Below are specific instructions to go from a fresh Amazon EC2 instance to a URL where you can share PyBamView alignments. The instructions assume you have an AWS account and know how to launch EC2 instances. For more info, check out instructions on the AWS site.

  1. Start up an EC2 instance running Ubuntu through your Amazon Web Services console.

    Note, when choosing what type of instance to run, you'll want to make sure you have enough disk space to store your alignments and reference genome. If you have very high coverage data you might also need to take into account how much memory you will need. See this comparison of EC2 instance types to help you decide which type to use. A micro instance was sufficient for the example served from this site.

    You should also make sure your security group is configured to allow http connections. You can add rules to a security group in the "Security Groups" section of the AWS console, under the "Network & Security" options. Choose the security group you plan to use (or create a new one). Then go to the "Inbound" tab and click "Edit". Click "Add Rule" and select "HTTP" as the type. If you do not do this step, you won't be able to go to the URLs described below.

  2. Log into your EC2 instance through SSH. This usually goes something like this: 
    ssh -i $my_key.pem ubuntu@XX-XXX-XXX-XXX
    where $my_key.pem is your key pair you should have created before launching your EC2 instance.
  3. Load all of your data, including any alignments you will want to view plus an option reference genome fasta file, onto the instance. You can store data in the "/mnt/" directory. You can upload data to the instance using scp, wget, or directly from Amazon S3 using s3cmd or similar tools. I assume you have a way to do this and don't go into more details here.
  4. Run: 
    sudo apt-get update
    to update package lists.
  5. Install what you will need for running Python and using apache: 
    sudo apt-get install -y python-dev python-pip g++ libapache2-mod-wsgi apache2 libapache2-mod-python zlib1g-dev librsvg2-bin
  6. Use pip to install pybamview 
    sudo pip install pybamview
  7. Edit /etc/apache2/sites-enabled/000-default.conf to include the following between the "VirtualHost" tags: 
    <VirtualHost *:80>
        ProxyPass / http://localhost:5000/

        <Location />
                Order allow,deny
                allow from all
                deny from none
        </Location>

</VirtualHost>
  8. Run: 
    sudo a2enmod proxy_http
	    sudo a2enmod proxy
	    sudo service apache2 restart
  9. Now run PyBamView from port 5000. Use nohup so that it keeps running even after you log out of the instance: 
    nohup pybamview --bamdir /mnt/mybams --ref /mnt/myref.fa --ip 0.0.0.0 --port 5000 &
  10. Now you should be able to access PyBamView through any browser by navigating to the public IP of your EC2 instance. If you don't know what this is, you can find it on your Amazon Web Services console. Simply copy this to your browser, and if all is good you should see PyBamView running. If it's not working, check the apache2 log at /var/log/apache2/error.log to see some hopefully useful error messages.

    If you'd rather serve from a URL from your own custom domain, see this tutorial for how to set that up.