GBrowse

This article is a draft

This is not a complete article: This is a draft, a work in progress that is intended to be published into an article, which may or may not be ready for inclusion in the main wiki. It should not necessarily be considered factual or authoritative.

Introduction

GBrowse is a combination of database and interactive web pages for manipulating and displaying annotations on genomes. It requires a web interface to display. GBrowse has been installed on cedar and the way we set it up is slightly different. Here we explain briefly how we setup Gbrowse on cedar. For more information about Gbrowse in general and how it works please take a look at Gbrowse official website: http://gmod.org/wiki/GBrowse

Gbrowse Installation

We have installed GBrowse on a server which has access to /home and /project directories of cedar. The server is called "cedar portal" and its web address is "https://gateway.cedar.computecanada.ca". On this server we have installed apache-2.4.6 web server with apache itk module. In order to be able to access files and directories of the the users while maintaining the security, we create a shared-account for each research group who is interested to have a GBrowse account. The itk module is used to assign uid of the shared-account for any member of the corresponding group who is successfully login to cedar portal. The user name and password are the same as the user name and password for any computecanada system. Each shared-account has its own GBowse instance. Therefore, every GBrowse instance act as a user with uid of that shared-account correspond to that group. In this way GBrowse is able to read files of users withing a research group. Please note that as GBrowse (shared-account) can read your GBrowse config files, any other member of your group can also read those particular config files. If you agree with that and If you need GBrowse on cedar portal please send a request to support@computecanada.ca

GBrowse Setup

Gbrowse Config Files

Since Gbrowse needs to be able to read config files of all users within a group, the config files for each group are installed by the admin in /project and on following directories:

/project/GROUPID/gbrowse/USERNAME/conf

where GROUPID is your group id and USERNAME is the your user name. There is a symbolic link from this directory to ${HOME}/gbrowse/conf just for simplicity so that you can get access to files within this directory easier. Files in this directory should be readable for all member of the group therefore, please do not change the group permission of files in this directory.

Input Files

GBrowse is able to read .bam files directly, e.g., you do not need to upload them to the database in order to display them. If you want GBrowse to read these kind files you need to pay attention to following:

• Files need to be copied to your /project directory and they should be readable for group.
• the directory that contains files and also all top directories should be readable by the group, e.g., the group mode of the group directories should have SGID bit (Set Group ID up on execution) with small "s" (not "S").
• make sure that your file's group in project directory is set to your group membership and not your username.
• Edit your conf file to specify the path to the bam file. Here is an example

         [example_bam:database]
         db_adaptor        = Bio::DB::Sam
         db_args           = -bam /project/GROUPID/USERNAME/gbrowse_bam_files/example_file.bam
         search options    = default

Setup Database

Before using GBrowse, you need to ask for an database account. Please send your request to support@computecanada.ca regarding a database account on cedar. Then you need to setup their own database. More information about setting up database on computecanada is here.

If you use MySQL, in order to make a MySQL connection from GBrowse you need to use the following setup in your corresponding GBrowse config files

                    [username_example_genome:database]
                    db_adaptor    =     Bio::DB::SeqFeature::Store
                    db_args       =    -adaptor DBI::mysql
                    -dsn DATABASE;mysql_read_default_file=~/.my.cnf
                    -user SHARED

where DATABASE is the name of your database. The .my.cnf file is a text file that is created by the administrator and it contains all information that is required for the shared-account to make a MySQL connection to MySQL. If you decide to use Postgres you need to use the following setup in your corresponding GBrowse config files

                    [username_example_genome:database]
                    db_adaptor    = Bio::DB::SeqFeature::Store
                    db_args       =  -adaptor -adaptor DBI::Pg
                    -dsn          =  dbi:Pg:dbname=DATABASE
                    

where DATABASE is the name of your database.

Upload Files to Database

This can be done by using BioPerl module. Here are commands that need to be run.

• module load bioperl/1.7.1
• bp_seqfeature_load.pl -c –d DATABASE:mysql_read_default_file=/home/USERNAME/.my.cnf example_genomic_sequence.fa header_file

where in this example DATABASE is the name of your DATABASE and example_genomic_sequence.fa is the fasta file containing the entire genome that you want to visualize on gbrowse. header_file contains details about the length of the chromosomes. Here is an example of header file:

##sequence-region I 1 15072434
##sequence-region II 1 15279421
##sequence-region III 1 13783801
##sequence-region IV 1 17493829
##sequence-region V 1 20924180
##sequence-region X 1 17718942
##sequence-region MtDNA 1 13794

We would like to remind you that running above commands need to be performed by job scheduler, (do not run it on the head node)