Sessions User's Guide
Contents
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.
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:
-
Manually load and open the session. Open the Session tool. In the
Session Management section under the
Load Settings heading, enter this information:
user: Example
session name: hg17_chr2_primate
Click the submit button next to the session name box to load the session. To view
the session in the Genome Browser, click the Genome Browser link in the top blue
navigation bar.
-
Open a session link sent by email. After we created and saved this session, we
could have clicked the Email link to automatically send a message to one or more
recipients with the following contents and clickable link:
Here is a UCSC browser session I'd like to share with you:
http://genome.ucsc.edu/cgi-bin/hgTracks?hgS_doOtherUser=submit&hgS_otherUserName=Examples&hgS_otherUserSessionName=hg17_chr2_primate.
By clicking this link, you can open the session in your browser.
-
Open a session from a local file. Alternatively, if we had saved the browser
settings to a local file, we could have simply provided the location of that file for you to load
into your browser to view our session. Click here to
see such a settings file. This method works best when the file is in a location that you can
access from your own computer or network. For this example, you can copy this file and paste it
into a file on your own machine, then load it into the Session tool.
-
Open a session from a URL. Because you do not have access to our file system
where this session file resides, it will be easier for you to load it using a URL. To do this,
open the Session tool. In the
Session
Management section under the Load Settings header, enter the URL where this file
is located:
http://genome.ucsc.edu/goldenPath/help/examples/session_example1.txt
Then, click the submit button to load the session settings. To view the session in
the Genome Browser, press the Browser link in the Updated Session
section.
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:
-
Log in to the Genome Browser. To ensure privacy and security, you must
create an account and/or
log in to use the Session tool. You will not
have to repeat the login step unless you sign off from the Session tool or close your Genome
Browser.
-
Create a named session. Scroll down to the
Save Settings section of
the page. Type a name into the Save current settings as named session box. Choose
whether or not you would like to share your sessions with others. If the
allow this session to be loaded by others box is checked, anyone will be able to view
your Genome Browser settings (including your custom tracks) if you provide them with your user and
session name. Note that your session is not automatically available to the general public
if you choose this option: you must provide the user and session name to other individuals for
them to view it. This helps to ensure the confidentiality of your private data. After naming the
session and choosing your sharing option, click the submit button. Your session will
then be listed by name under My Sessions.
-
Save session settings to a file. Alternatively, you can create a file from your
session settings that can be saved to your local machine or posted to a URL for
access or sharing. To do this, go to the
Save Settings section.
Type a name into the Save current settings to a local file box. Click the
submit button to save or display the file. The session will be saved in plain text
(ascii) format by default. To select a compressed format, select one of the options from the
file type returned menu before clicking submit. If you simply wish to
preview the contents of the file in your browser window, leave the file name blank and click
submit.
Saved sessions will not be expired, and should persist until you
delete them. However, it is still recommended that you keep local backups of
your session contents and any associated custom tracks.
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 name. Click the session name to view it in the Genome Browser.
-
View/edit details. Click the
details button to edit the session
description and view session details such as creation date/time, assemblies with custom tracks and
more.
-
Delete the session. Click the
delete button to permanently remove
this session from the list.
-
Share with others: Check this box to allow others to access this session. By
default, this option is unchecked, which limits access to only the session owner.
-
Post in public listing: Check this box to add your session to the list of
Public Sessions. Sessions in the listing will be
available to be loaded and viewed by the world.
-
Email. Click this link to email this session to a
colleague.
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:
-
the user name and session name of the saved session
-
access privileges to a local file that contains the saved session information
-
the URL of a web-accessible session settings file
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:
-
Save the session URL. Immediately upon saving a new session, the top of the page
offers a
Browser hyperlink. Additionally, each session entry in the
My Sessions list has a Browser hyperlink. Click either Browser
link to open the Genome Browser with the session loaded. You can obtain the URL of the Genome
Browser page by capturing the Browser hyperlink via right-click before you proceed
to the Browser graphical view. You can then store the URL, create a bookmark or share the link
with others.
-
Email a session link. Each session entry in the My Sessions list also
has an
Email link. Click this link to automatically invoke your email tool with a
message containing the Genome Browser URL, which you can then send to others.
-
Share a session settings file. If you have saved your settings to a local file,
you can give others access to the file, or email the file to them as an attachment and instruct
them to load it using the Session tool.
-
Share a web URL. If you have saved your settings to a file on a web server, you
can provide a link like this to others:
http://genome.ucsc.edu/cgi-bin/hgSession?hgS_doLoadUrl=submit&hgS_loadUrlName=MyUrl
where MyUrl is the URL of your settings file, e.g.,
http://www.mysite.edu/~me/mySession.txt. In this type of link, you may replace
"hgSession" with "hgTracks" to proceed directly to
the Genome Browser.
-
List it on the Public Sessions page. The
"Public Sessions" tool allows you to
post and share your exciting and interesting Browser snapshots with the world. After having saved
your session, you can add it to this public listing by checking the box in the column under
"post in public listing?".
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.
-
Open a session from an email link. If you receive an email message with a link to
a colleague's shared session, simply click on the link to view the Genome Browser with the session
settings.
-
Open another user's session. If you know the name of another user's shared
session you can type in the user and session name in the "Restore Settings"
section and click "submit" This will generate an "Updated Session" message and
you can click on the Browser link to load the browser with the settings saved in this
session.
-
Open a session from a settings file. Open the Session tool, then scroll down to
Load Settings in the Session Management section. Type in the name of the
settings file, or click
Browse... to find the file on your computer. Click
submit to display the Genome Browser using these session settings.
-
Open a session specified by a URL. Open the Session tool, then scroll down to
Load Settings in the Session Management section. Type in the URL in the
Load settings from a URL box, then click submit to display the Genome
Browser using the new session settings. Note that you may also choose to save a copy of your
colleague's session as your own. Any changes you make to this newly saved session will not be seen
by your colleague until you resave it and share it with them.
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 be expired. BLAT results always have a lifespan of 48
hours, even if they are part of a session.
Deleting a session
In the Session Management section under My Sessions, press the
delete 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 NAR submitters
The 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:
-
Ensure the data file is formatted correctly.
-
Create a track line for your custom track.
-
Load the custom track by adding your track line to our
Custom Tracks page.
-
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:
-
Configure the Genome Browser to your preference
Make sure the display of your custom tracks is to your liking on the Genome Browser.
-
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.
-
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.
-
Save your session
Go to the Save Settings section and in the
Save current settings as named session text box, 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.
-
Edit the session description
Once the session is created, you can click the details button to add
a description to the session. If you eventually make a Public Session, and provide a detailed
description, anyone can find it by searching for terms you share. For example, navigate to the
Public Sessions page and search "NAR" to
see some example sessions.
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:
-
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.
-
Alternatively, you can right-click the session name and then click Copy Link Address to
save the session URL.
-
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.