f4ace97438e173daf68c76153a4481de73879798 jcasper Fri Nov 8 16:46:02 2019 -0800 Initial commit of supporting docs for hic track type, refs #22316 diff --git src/hg/htdocs/goldenPath/help/hic.html src/hg/htdocs/goldenPath/help/hic.html new file mode 100755 index 0000000..d9af502 --- /dev/null +++ src/hg/htdocs/goldenPath/help/hic.html @@ -0,0 +1,151 @@ + + + + + + + +

hic Track Format

+

+Hic format +is an indexed binary format designed to permit fast random access to contact matrix heatmaps. The +format was designed by the Aiden Lab +at Baylor College of Medicine. +

+The format is used for displaying chromatin conformation data in the browser. After running a +chromatin conformation experiment like in situ Hi-C, researchers can pass their results through +the Juicer pipeline to produce +a hic file and place that file in a web-accessible space. Due to the large size of many of these +files, UCSC is not able to support direct upload via our Custom Track interface. UCSC does, +however, temporarily cache the accessed portions of the files to speed up interactive display. +If you do not have access to a web-accessible server and need hosting space for your VCF files, +please see the Hosting section of the Track Hub Help +documentation.

+ +

The UCSC tools currently support hic versions 6-8.

+ +

Generating a hic track

+

+The typical workflow for generating a hic custom track is this:

+
    +
  1. + Prepare your data by processing it with the Juicer pipeline to create a file in the hic format. +
  2. +
  3. + Move the hic file (my.hic) to an http, https, or ftp location.
  4. +
  5. + Construct a custom track using a single + track line. The basic version of the track line will look + something like this: +
    track type=hic name="My HIC" bigDataUrl=http://myorg.edu/mylab/my.hic
    +
  6. +
  7. + Paste the custom track line into the text box in the custom track management page, click "submit" and view in the Genome + Browser.
  8. +
+ +

Parameters for hic custom track definition lines

+

+All options are placed in a single line separated by spaces (lines are broken only for readability +here):

+
track type=hic bigDataUrl=http://...
+    name=track_label
+    description=center_label 
+    visibility=display_mode
+    priority=priority
+    db=db
+

+Note if you copy/paste the above example, you must remove the line breaks. +Click here for a text version that you can paste +without editing.

+

+The track type and bigDataUrl are REQUIRED:

+
type=hic bigDataUrl=http://myorg.edu/mylab/my.hic 
+

+The remaining settings are OPTIONAL:

+
name            track label                 # default is "User Track"
+description     center label                # default is "User Supplied Track"
+visibility      full|dense|hide             # default is hide (will also take numeric values 4|1|0)
+priority        N                           # default is 100
+db              genome database             # e.g. hg19 for Human Feb. 2009 (GRCh37) 
+Note that hic tracks currently only support the full, dense, and hide visibility modes. +The hic track configuration help page +describes the hic track configuration page options.

+ +

Example #1

+

+In this example, you will create a custom track for a hic file that is already on a public +server — data from an in situ Hi-C experiment on the HMEC cell line from the following paper, +mapped to the hg19 assembly:

+

+Rao SS, Huntley MH, Durand NC, Stamenova EK, Bochkov ID, Robinson JT, Sanborn AL, Machol I, Omer AD, +Lander ES et al. + +A 3D map of the human genome at kilobase resolution reveals principles of chromatin looping. +Cell. 2014 Dec 18;159(7):1665-80. +PMID: 25497547; PMC: PMC5635824 +

+

+The line breaks inserted here for readability must be removed before submitting the track line:

+
browser position chr21:33,034,804-33,037,719
+track type=hic name="hic Example One" description="hic Ex. 1: in situ Hi-C on HMEC"
+    db=hg19 visibility=dense
+    bigDataUrl=http://hgdownload.soe.ucsc.edu/gbdb/hg19/bbi/hic/GSE63525_HMEC_combined.hic
+

+The "browser" line above is used to view a small region of chromosome 21.

+

+Note if you copy/paste the above example, you must remove the line breaks (or, click +here for a text version that you can paste without +editing).

+

+Paste the "browser" line and "track" line into the +custom track management page for the human +assembly hg19 (Feb. 2009), then click the "submit" button. On the following page, click +the "chr21" link in the custom track listing to view the hic track in the Genome +Browser.

+ +

Example #2

+

+In this example, you will load a hub that has hic data described in a hub's trackDb.txt file. +First, navigate to the Basic Hub Quick Start Guide +and review an introduction to hubs.

+

+Visualizing hic files in hubs involves creating three text files: hub.txt, +genomes.txt, and trackDb.txt. The browser is passed a URL to the top-level +hub.txt file that points to the related genomes.txt and trackDb.txt +files. The trackDb.txt file contains stanzas for each track that outlines the details +and type of each track to display, such as these lines for a hic file located at the bigDataUrl +location:

+
track hic1
+bigDataUrl http://http://hgdownload.soe.ucsc.edu/gbdb/hg19/bbi/hic/GSE63525_GM12878_insitu_primary+replicate_combined.hic
+shortLabel hic example
+longLabel This hic file shows in situ Hi-C data from Rao et al. (2014) on the GM12878 cell line
+type hic
+visibility dense
+

+Note: there is now a useOneFile on hub setting that allows the hub +properties to be specified in a single file. More information about this setting can be found on the +Genome Browser User Guide.

+

+Here is a direct link to the trackDb.txt file to see more information about this example hub, and below +is a direct link to visualize the hub in the browser, where this example hic file displays in dense +mode alongside the other tracks in this hub. You can find more Track Hub hic display options on the +Track Database (trackDb) Definition +Document page.

+
http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg19&hubUrl=http://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/hub.txt 
+ +

Sharing Your Data with Others

+

+If you would like to share your hic data track with a colleague, there are a couple of options. +One method is to load your data track into the UCSC Genome Browser and then create a saved session +by following the instructions here. +If you are looking for a more automated method of sharing data, you may be interested to learn how to create +a direct URL that loads custom data files. For a demonstration of this, see Example 6 on the +custom tracks page.

+ +