Instructions to Set Up UCSC Cancer Genomics Browser

on an Existing UCSC Genome Browser Mirror Site

This document describes how to set up the UCSC Cancer Genomics Browser on an EXISTING mirror site of UCSC Genome Browser.

REQUIREMENTS

You will need the following components installed and functioning:

1. Linux (Centos 5.2 or similar)

2. MySQL (4.0 or later) database

3. Apache

4. gcc and g++ compilers

5. Web browser (IE 6+, Firefox 1.5+, Safari 1+)

6. Adequate disk space to accommodate the amount of data for Human Genome (hg18)

7. UCSC Genome Browser (with Human Genome, hg18) successfully installed and running

USEFUL RESOURCES ON HOW TO BUILD A FUNCTIONAL UCSC GENOME BROWSER

See detailed instructions on http://genome.ucsc.edu/admin/mirror.html and the associated Wiki site at http://genomewiki.ucsc.edu/index.php/Browser_Installation.

The source code of the UCSC Human Genome Browser and Cancer Genomics Browser are available from UCSC Genome Browser source download page http://hgdownload.cse.ucsc.edu/admin/jksrc.zip.

The download and installation instructions are at http://hgdownload.cse.ucsc.edu/downloads.html.

For questions on how to set up a Genome Browser mirror site, please see help resource available from http://genome.ucsc.edu/.

BUILD AND INSTALL THE UCSC CANCER GENOMICS BROWSER

1. Obtain the latest source (http://hgdownload.cse.ucsc.edu/admin/jksrc.zip).

Uncompress jksrc.zip.

Please note that our build process is somewhat different than the standard open-source build process.

2. Compile library code

a. cd kent/src

b. make clean; make alpha (note make alpha will overwrite cgi binaries)

3. Compile cancer genomics browser

a. cd kent/src/hg/instinct/

b. make clean; make

c. cd hgHeatmap2; make alpha (note make alpha will overwrite cgi binaries)

4. Add the following lines into /usr/local/apache/cgi-bin/hg.conf:

localDb.host=localhost

localDb.user=testUser

localDb.password=testPassword

Issue the following MySQL command to grant select permission to the user testUser:

GRANT SELECT on *.* TO 'testUser'@'localhost' IDENTIFIED BY 'testPassword';

flush privileges;

Substitute your own user ID and password in the above.

5. Check your local installation of the UCSC Cancer Genomics Browser CGI program is running. Go to http://YourHostName/hgHeatmap/ and you should see something like the following picture. The error message is due to that we have not loaded any data for the Cancer Genomics Browser yet.

POPULATE THE UCSC CANCER GENOMICS BROWSER WITH A NEW GENOMIC DATA TRACK

1. Download the test dataset located here.

Uncompress

cd testData

1. Load a new genomic data track into hg18 database

a. Genomic data are required to be in microarray format (i.e. bed15). For details see http://genome.cse.ucsc.edu/FAQ/FAQformat .

b. Test genomic dataset: testGenomics.bed15

c. Load the dataset to hg18 database. In order to match the test set configuration information supplied for this demonstration, the new genomic track table should be called "testGenomics". Use the following command to load the testGenomics.bed15 data file:

hgLoadBed hg18 testGenomics testGenomics.bed15

The hgLoadBed program is a utility program provided as part of the UCSC codebase.

See http://genomewiki.ucsc.edu/index.php/Building_a_new_genome_database on how to get source tree

and build utility programs.

2. Edit kent/src/hg/makeDb/hgCgiData/Human/microarrayGroups.ra file to add information about the testData.bed15 dataset

a. Test file: testGenomics.microarrayGroups.ra

b. Copy and paste all lines from the above test file into kent/src/hg/makeDb/hgCgiData/Human/microarrayGroups.ra (at the end).

c. cd kent/src/hg/makeDb/hgCgiData/

a. make alpha (note make alpha will overwrite cgi binaries)

3. (Optional) Register the new data track with the UCSC Human Genome Browser.

a. Refer to instructions on how to add a track to the UCSC Human Genome Browser, e.g. see:

http://genomewiki.ucsc.edu/index.php/Adding_New_Tracks_to_a_browser_installation

4. Create a probe to gene mapping table in hg18

a. Test file: testProbe.tab

b. Create and load table testProbe in hg18 using the test table schema in testProbe.sql. Use the hgLoadSqlTab utility program to load this data:

hgLoadSqlTab –notOnServer hg18 testProbe testProbe.sql testProbe.tab

The hgLoadSqlTab program is a utility program provided as part of the UCSC codebase.

5. Register the new data track with the UCSC Cancer Genomics Browser

a. Edit kent/src/hg/instinct/hgHeatmap2/hgHeatmapData/datasets.ra file to add information about the testData.bed15 dataset

b. Test file: testDatasets1.ra

c. Copy all lines from the test file to datasets.ra

d. cd kent/src/hg/instinct/hgHeatmap2/

b. make alpha (note make alpha will overwrite cgi binaries)

6. Check to see if the UCSC Cancer Genomics Browser is working and loaded with the testGenomics.bed15 dataset. You should see the following picture at http://YourHostName/hgHeatmap/:

LOAD AND CONFIGURE CLINICAL DATA THAT IS ASSOCIATED WITH THE NEW GENOMIC DATA TRACK

1. Create a clinical database called "tClinical".

2. Create and load clinical feature table, called "testClinical".

a. Test data file: testClinical.tab

b. Test table schema: testClinical.sql

c. Load the test data file to testClinical using hgLoadSqlTab

hgLoadSqlTab –notOnServer tClinical testClinical testClinical.sql testClinical.tab

3. Create and load the table that maps patient ids to samples. Let's call the table "testLabTrack" for demonstration purpose.

a. Test data file: testLabTrack.tab

b. Test table schema: testLabTrack.sql

c. Load the test data file to testLabTrack using hgLoadSqlTab

hgLoadSqlTab –notOnServer tClinical testLabTrack testLabTrack.sql testLabTrack.tab

4. Add configuration file testColumnDb.ra

a. Test data file: testColumnDb.ra

b. Copy test file to kent/src/hg/instinct/hgHeatmap2/hgHeatmapData/ directory.

5. Edit datasets.ra file to register the clinical information with its associated genomics data

a. Test file: testDatasets2.ra

b. Replace the section of testGenomics in kent/src/hg/instinct/hgHeatmap2/hgHeatmapData/datasets.ra with lines in the test file testDatasets2.ra.

c. cd kent/src/hg/instinct/hgHeatmap2/

c. make alpha (note make alpha will overwrite cgi binaries)

6. Check at the UCSC Cancer Genomics Browser again that the browser is working and now loaded with the associated clinical data. Sorting by clinical features should be functioning and can be tested by clicking on a clinical feature of interest (e.g. "Original Order") and seeing if the heatmap updates as expected. The browser should look something like this:

CREATE AND LOAD PATHWAY DATABASE (optional)

This part is optional. However it is required for the genesets view to function.

1. Create a database called "pathway"

2. Grant permissions to this database by issuing the following MySQL command (with the user ID and password you previously chosen for localDb in hg.conf).

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER on pathway.*

TO 'testUser'@'localhost' IDENTIFIED BY 'testPassword';

3. We supply a set of GO term genesets to get your browser started.

4. In "pathway" database, create and load table "genesets"

a. Schema: genesets.sql,

b. Data files: genesets.tab,

c. Load the table with hgLoadSqlTab

hgLoadSqlTab -notOnServer pathway genesets genesets.sql genesets.tab

5. Create table userGenesets in the pathway database

a. Create the table userGenesets using the schema: userGenesets.sql

6. You should see the following picture, after select "Genesets" of the "Display As" option (in the "Display Option" section):