Tripal JBrowse

This package of modules integrates GMOD JBrowse into your Tripal site providing

1. A user interface for JBrowse instance creation and management via Tripal JBrowse Management
2. Drupal menu links and pages with embedded JBrowse instances via Tripal-JBrowse Page Integration

This powerful combination allows you to provide seamless genome browsing to your users in an administrator-friendly manner.

Installation

1) Dependencies

Please ensure that the following are installed on your server:

• JBrowse.
• Tripal

Note

JBrowse must be unpacked and ./setup.sh run. It must be located in a directory accessible by your webserver. We recommend [drupalsite]/tools/jbrowse.

2) Tripal JBrowse Management

Installation

1. Download the module to your Drupal modules folder
2. Run drush en -y tripal_jbrowse_mgmt or enable through the modules page
3. Visit the configuration page at Administration » Tripal » Extensions » Tripal JBrowse Management » Settings

Note

JBrowse must be unpacked and ./setup.sh run. It must be located in a directory accessible by your webserver. We recommend [drupalsite]/tools/jbrowse.

Configuration

In order for the module to function properly, you need to first configure it.

1. Visit your site through the browser and navigate to Administration » Tripal » Extensions » Tripal JBrowse Management » Settings.
2. Fill out the configuration form and click “Save Settings”. You will need to know information about your JBrowse instance.

3) Tripal JBrowse Page Integration

This module is available for download from github.com/tripal/tripal_jbrowse.

1. First install Tripal JBrowse Management
2. Run drush en -y tripal_jbrowse_page or enable through the modules page

Tripal JBrowse Nodes Migration

The old method of Tripal JBrowse page integration using nodes has been deprecated. If you are still using this method of integration, administrators will see a warning directing you here.

The new method of page integration using the Tripal JBrowse Management module to register instances with your Tripal site. The following steps will help you register your existing JBrowse instances with Tripal JBrowse Management in order to take advantage of the new page integration.

1. Enable Tripal JBrowse Management as you would any other Drupal/Tripal module. This can be done using drush pm-enable tripal_jbrowse_mgmt.
2. Download JBrowse and install a single instance in a web-accessible location. We recommend DRUPAL_ROOT/tools/jbrowse.
3. Create symbolic links to each of your existing instances where the name of the link matches the organism it is for: genus_species__common_name.

cd DRUPAL_ROOT/tools/jbrowse
mkdir data
cd data
ln -s path/to/existing/instance/data/directory genus_species__common_name

4. Navigate to Administration » Tripal » Extensions » Tripal JBrowse and click on “Settings”. Fill out the paths for your new single JBrowse instance.

Data Directory	DRUPAL_ROOT/tools/jbrowse/data
Data Path	./tools/jbrowse/data
Path to JBrowse’s Index File	./tools/jbrowse
Path to JBrowse’s bin Directory	DRUPAL_ROOT/tools/jbrowse/bin

5. Navigate to Administration » Tripal » Extensions » Tripal JBrowse and click on “Register Existing Instance”. Fill in the details for each of your existing instances.
6. Enable the new Tripal JBrowse Page Integration module and dynamic pages will now be available for each of your newly registered instances. This can be done using drush pm-enable tripal_jbrowse_page.
7. Delete your existing Tripal JBrowse Instance nodes under Admin » Content and disable the old module using drush pm-disable tripal_jbrowse.

Tripal JBrowse Management

Managing Instances

Listing and Creating Instances

To list all instances, visit Administration » Tripal » Extensions » Tripal JBrowse Management.

Creating Instances

As highlighted on the screenshot above, you can create new instances by clicking the “Create New Instance” link. This will create a new data directory based on the organism choosen. All instances created will use the same JBrowse installation, which makes it easier to update JBrowse.

Registering Existing Instances

You can also register existing JBrowse instances with this module. To do so 1. Create a symbolic link in your configured data directory where the name of the link matches the organism it is for: genus_species__common_name. 2. Click on “Register Existing Instance” as highlighted on the screenshot above. 3. Fill out the form to describe the existing JBrowse instance.

Note

If you would like to move an existing instance to the JBrowse managed by this module permanently then copy the data directory rather then creating a symbolic link.

Deleting Instances

To delete an instance, you must first visit the instances list page and clicking the delete instance link.

Warning

The actual files for the instance are not deleted. You will need to delete all files manually.

Note

If you accidentally delete an instance, you can use the “Register Existing Instance” process to re-register it with the system. All previously created tracks will no longer be able to be managed but you will be able to add new tracks, etc.

Managing Tracks

Creating and Deleting Tracks

To create a new track, you need visit the instances list page (Administration » Tripal » Extensions » Tripal JBrowse Management) and click Manage Tracks.

The manage tracks link, will lead to a page where you can create and delete tracks (see screenshot below).

Warning

Please note that files don’t get automatically removed. You have to manually remove the track files yourself.

Editing Tracks

This modules allows you to configure a track after it has been created. This provides a way to add the track to a category, change the colors and type of the track amongst other configuration options.

To edit a track, simply click the manage track button on the “manage tracks” page as shown on the screenshot above.

Tripal Page Integration

Embedded JBrowse Instance

This guide will show you how to embed a JBrowse instance within your Tripal site for an existing JBrowse instance. This ensures a consistent user experience by making the menu system of the Tripal site available to the user while browsing. If the user needs more space they can choose the FullScreen option to remove the menus.

Warning

This requires you already have a JBrowse instance created through the Tripal JBrowse Management sub-module. For information on how to do this, see the associated Tripal JBrowse Management documentation.

This is the default functionality of the “Tripal-JBrowse Page Integration” module. If you have already created your JBrowse instances using the “Tripal Jbrowse Management” module then enabling this module automatically creates pages and menu items for those instances!

Links to Original JBrowse

This guide will show you how to ensure the links created by this module direct users to the original JBrowse rather than to an embedded JBrowse page. This may be preferable if your theme does not provide much space to content thus causing the embedded JBrowse to be too small.

By installing the “Tripal-JBrowse Page Integration” module you will already have embedded JBrowse pages for all Tripal JBrowse instances created by the “Tripal JBrowse Management” module. To switch these links and pages to redirect to the original full-screen JBrowse, go to Administration Toolbar > Tripal > Extensions > Tripal JBrowse Management > Page Integration. Here you simply need to uncheck the “Embed JBrowse in your site” checkbox and click “Save Settings”

Now, all links in the yourdrupalsite.com/jbrowse listing and menu items will point the original, full screen JBrowse!

Exclude Specific JBrowse Instances

Sometimes you may want to manage a JBrowse Instance using “Tripal JBrowse Management” but not display it to users through “Tripal-JBrowse Page Integration”. For example, if you have just begun development and are not ready to release it. To do this, go to Administration Toolbar > Tripal > Extensions > Tripal JBrowse Management > Page Integration. Check the checkbox beside the instance you would like to exclude from menu items, lists and pages and click “Save Settings”.