Sessions User's Guide

Contents

Introduction
Some simple examples
Creating a session
Creating a session — video demonstration
Session details
Sharing a session
Editing an existing session
Displaying your own tracks in a session
Deleting a session
Lifespan of a session
Session gallery
Help for Nucleic Acids Research submitters

Questions and feedback on this User's Guide are welcome.

User questions and answers on Sessions and other topics are available in the Genome Browser mailing list.

Introduction

The Session tool allows you to configure your browser with specific track combinations, including custom tracks, and save the configuration options. Multiple sessions may be saved for future reference, for comparing different data sets, or for sharing with your colleagues. Saved sessions will not be expired, however we still recommend that you keep local back-ups of your session contents and any associated custom tracks. BLAT result tracks persist for at least 48 hours after the last time they are viewed. The creation date of a session can be viewed in the Session Management menu. This date only reflects the initial creation of the Session and is not updated when sessions are edited. Descriptive text can also be added to a session in the Session Details menu.

This feature may be accessed via the Session link in the top blue navigation bar in any assembly. To ensure privacy and security, you must create an account and log in before using the session manager.

Individual sessions may be designated as either shared or non-shared to protect the privacy of confidential data. To avoid having a new shared session from someone else override your existing Genome Browser settings, you are encouraged to open a new web-browser instance or to save existing settings in a session before loading a new shared session.

Note that not all of the Genome Browser mirror sites have all of the session features enabled.

This User's Guide provides a few examples that introduce the features of the Session tool, followed by detailed directions on creating, saving, modifying and sharing sessions.

You may also wish to reivew two blog posts, How to share your UCSC screenthoughts and Sharing Data with Sessions and URLs for more discussions about sessions.

Some simple examples

This section contains some example sessions that demonstrate the use of the Session tool. To enable you to view these sessions, we have created a user account with the name Example.

Example 1

This example shows the primate (chimp and rhesus) nets for chromosome 2 in the hg17 human assembly — the primate chromosome that fused in humans. We first configured our browser view with the desired settings, and then saved the session so that we could share it. We named our session hg17_chr2_primate.

There are several ways for you to view this session:

Example 2

This example shows the Human Accelerated Region (HAR1) in the hg18 assembly. Eighteen differences exist in a region of 118 bases between human and all other mammals extending back to the chicken. The two sessions in this example show the same browser position at two levels of detail: Example 2a is zoomed out; Example 2b is zoomed in.

To view these sessions in your browser, you can use any of the methods described in Example 1:

Creating a session

It is easy to create a session to save or share. Simply configure the Genome Browser as you wish, then navigate to the Session tool by clicking on the My Data pulldown in the top blue navigation bar. Follow these steps to save your session:

How to back up text-based Custom Track data to a file

Creating a session — video demonstration

Visit our YouTube channel for more videos.

Opening a saved session

When you save a session, it is added to the My Sessions list on the Session page. Each session entry is listed by name and offers the following options to open, share, and manipulate it:

Session details

Each session has an associated details page that you can click into from the Session Management menu. The Session Details menu allows you to edit the Session Name, to add descriptive text and to change whether or not the session is shared with others. Like the Session Management menu, if you click "use" that session will be loaded as the current session and if you click "delete" the session will be deleted. The "Created on" date reflects the date that the session was originally created and will not be updated to reflect any edits.

Sharing a session

Shared vs. non-shared data

When you create a session using the Session tool, you may designate it as either shared or non-shared. By default, new sessions are created as shared and must be explicitly changed to non-shared status.

Shared sessions can be opened by other Genome Browser users to whom you've provided one of the following:

Sessions which you've added to the list of Public Sessions will available to the world. Note that unless you've added them to this list of Public Sessions, your shared sessions will not be available in a general way to other Genome Browser users; they will need at least one of these access methods.

If you choose to keep your session private, other users of the Genome Browser will not be able to access your data or browser configuration. Any confidential data or locations of interest that you are working with will be safe from viewing by others.

The most secure way to control your session is to save the settings to a local file, then deny access to that file by others.

Sharing your session with others

There are five ways to let others know about your saved sessions:

Opening a shared session

If you open a shared session while viewing the Genome Browser, it is possible to lose all of your own browser settings. That is, the settings for the newly-opened session will take precedence over your existing settings and will replace them. If you wish to preserve your original settings, you should first save your own settings as a session before opening a new session, or open a new tab or window in your internet browser before loading the new session.

There are four ways to open a shared session, depending on what information you have about the session. The instructions below assume that you want to replace your current session the new session. Be sure to preserve your original session first if you don't want to overwrite it.

Editing an existing session

It's easy to make changes to an existing session. Reconfigure the Genome Browser as you wish, then resave the session with the same name. The Session tool will warn you that you are about to overwrite an existing session.

You can also edit any descriptive text associated with your session as well as whether or not the session can be shared in the Session Details menu. Note that editing a session will not alter the creation date listed in the Session Management menu.

If you previously shared this session with others, they will not see the changes until they reload your newly-edited session.

Displaying your own tracks in a session

In addition to displaying standard UCSC tracks in your session, you can also display the following user-generated tracks:

Before you create and save your session, be sure to upload your Custom Track or Genome Graph track. These user-generated tracks associated with a saved session will not expire. BLAT results always have a lifespan of 48 hours, even if they are part of a session. However, if you generate a custom track from your BLAT results, they will be saved in your session.

Deleting a session

In the Session Management section under My Sessions, press the button next to the session name you would like to delete. This will permanently delete all details of the session from the UCSC server. Any saved links to that session will no longer work.

No other user can delete your saved sessions, even if you have provided access to your sessions to them. Other users simply have a copy of your session.

Unlike most other browser preferences, the session settings are not saved in your Genome Browser "cart". Therefore, if you choose to reset the Genome Browser, it will not delete your saved sessions.

Lifespan of a session

Your saved sessions will not be expired and will available you (and others if you share them) until you delete them. We have discontinued our previous policy of removing saved sessions and associated custom track data after four months. However, note that the UCSC Genome Browser is not a data storage service; please keep a local backup of your session contents and custom track data.

Session gallery

The Session Gallery is a collection of track views that help highlight viewing different topics in the browser. The sessions in the Session Gallery were created in the browser and then saved to a local file, which was then uploaded to an online location. This allows creating a single link, such as http://genome.ucsc.edu/cgi-bin/hgTracks?hgS_doLoadUrl=submit&hgS_loadUrlName=U, where U is the URL of the session file, e.g., http://www.mysite.edu/~me/mySession.txt, enabling users to maintain external control of the content file for easy update.

Help for Nucleic Acids Research submitters

The Nucleic Acids Research (NAR) journal now requires manuscript submissions to contain a private Session link to your data in the UCSC Genome Browser that allows reviewers to access data. These instructions will show you how to upload, view, and share your data.

Viewing your data on the Genome Browser

You can view your own private data by uploading your annotation files to the Genome Browser as custom tracks; visit our custom track help page to learn more. To summarize the steps to upload your data, you will need to:

  1. Ensure the data file is formatted correctly.
  2. Create a track line for your custom track.
  3. Load the custom track by adding your track line to our Custom Tracks page.
  4. View the data in the Genome Browser.

Custom track examples

Creating the track line may be the most challenging step since many configuration options exist. The track line begins with the track keyword, followed by one or more attribute=value pairs where the order of the attributes does not matter. Here are some examples:

BAM custom track

The simplest example of a BAM custom track is the following track line:

track name="My BAM" type=bam bigDataUrl=http://www.mysite.edu/~me/my_sorted.bam

In the example above, the name attribute defines the name of your custom track. The second attribute, type, is required for some data types, but not limited to: BAM, bigBed, WIG, bigWig, and VCF data types. The last attribute, bigDataUrl, is required for remotely hosted data types such as BAM, CRAM, bigBed, bigWig, and VCF.

Adding more attribute=value pairs can further customize the display. Here is a custom track that uses the visibility and description atrributes:

track type=bam visibility=dense name="My BAM" description="Example from the ENCODE RNA-seq CSHL track" bigDataUrl=http://hgdownload.soe.ucsc.edu/goldenPath/hg19/encodeDCC/wgEncodeCshlLongRnaSeq/wgEncodeCshlLongRnaSeqA549CellPapAlnRep1.bam

There are also options to configure the display of your BAM files, such as a density plot feature that will dynamically process the underlying BAM into a wiggle signal.


bigWig custom track

A bigWig file is useful when trying to display dense, continuous data. Read more on the bigWig track format help page. Here is an example bigWig track that is colored red, instead of the default black color, that can be pasted directly into the Custom Tracks Page:

track color=255,0,0 name="HeLa-S3 nucleus minus signal" description="RNA Subcellular CAGE Localization from ENCODE/RIKEN" type=bigWig visibility=full bigDataUrl=http://hgdownload.soe.ucsc.edu/goldenPath/hg19/encodeDCC/wgEncodeRikenCage/wgEncodeRikenCageHelas3NucleusPapMinusSignalRep1.bigWig

There are also options to configure the display of your wiggle tracks, such as changing the track height or type of graph.

Creating a session for NAR publications

After creating your custom tracks and viewing your data on the Genome Browser, you can save all of your tracks and settings to a snapshot of the Genome Browser called a session. You can easily save a session by following these five steps:

  1. Configure the Genome Browser to your preference
    Make sure the display of your custom tracks is to your liking on the Genome Browser.
  2. Navigate to the sessions page
    Once you are satisfied with the display, go to the My Sessions page by either:
    • Going to My Data -> My Sessions from the navigation bar.
    • Using the "s then s" keyboard shortcut when viewing the main page of the Genome Browser.
  3. Login to the UCSC Genome Browser
    You must sign in to be able to save named sessions which will then be displayed with Browser and Email links.
  4. Save your session
    Go to the Save Settings section and in the Save current settings as named session text box, and enter a name for your session. When saving the session, be sure to have the "allow this session to be loaded by others" option checked and then click submit.
    • You should then be able to copy and share a link similar to the following: http://genome.ucsc.edu/s/YourUserName/YourSessionName

  5. Edit the session description
    Once the session is created, under the "view/edit details" column you can click the view/edit button to add a description to the session.

  6. Publish your session as a Public Session for public discovery
    If you eventually make a Public Session of your session after your paper is published, and provide a detailed description, anyone can find it by searching for terms you share.

Sharing your session link

After saving your session, you will now be able to share your session link with others. There are three different ways that you can share your session:

  1. Immediately after creating a new session, the top of the page offers a Browser hyperlink that will allow you to view the newly saved session. You can right-click the Browser link to save the URL.
  2. Alternatively, you can right-click the session name and then click Copy Link Address to save the session URL.
  3. Adding your session to the Public Sessions page will provide a useful way of sharing your session with the world in the long run. You can add your session to our Public Sessions by selecting the "post in public listing?" checkbox.
Editing the session URL

You can edit URLs to directly go to different parts of the Genome Browser such as by changing hgSession to hgTracks, e.g.,

http://genome.ucsc.edu/cgi-bin/hgTracks?hgS_doOtherUser=submit&hgS_otherUserName=brianlee&hgS_otherUserSessionName=hg19.rela

Having hgTracks in the session URL will take the viewer to the main page of the Genome Browser instead of the sessions page.

Using track hubs to organize custom tracks

Creating a track hub allows you to group and organize your annotation tracks, but is limited to compressed binary indexed formats that can be remotely hosted. This will require the use of a web-accessible location to load the track hub in the UCSC Genome Browser. If your institution does not provide web space for you, you can look into hosting your binary files at a couple different web hosting services, such as CyVerse or figshare. If you would like to learn more about using track hubs, please read our Track Hub help page.

Genome Browser inquiries

If you have any questions regarding the creation of your custom track or session, please feel free to contact us. Before submitting a question, we strongly encourage you to search our mailing list archives, our website, and our wiki for the answer.