328e57766a279798e1c9f370da17badb7cd16f6d dschmelt Tue Nov 12 16:52:57 2019 -0800 Minor proofread edits to Jonathan's Hic docs #22316 diff --git src/hg/htdocs/goldenPath/help/hic.html src/hg/htdocs/goldenPath/help/hic.html index 4712c76..f524c9d 100755 --- src/hg/htdocs/goldenPath/help/hic.html +++ src/hg/htdocs/goldenPath/help/hic.html @@ -2,37 +2,36 @@ <!--#set var="TITLE" value="Genome Browser hic Track Format" --> <!--#set var="ROOT" value="../.." --> <!-- Relative paths to support mirror sites with non-standard GB docs install --> <!--#include virtual="$ROOT/inc/gbPageStart.html" --> <h1>hic Track Format</h1> <p> <a href="https://github.com/aidenlab/juicer/wiki/Data/#hic-files" target="_blank">Hic format</a> is an indexed binary format designed to permit fast random access to contact matrix heatmaps. The format was designed by the <a href="https://www.aidenlab.org/" target="_blank">Aiden Lab</a> at <a href="https://www.bcm.edu/" target="_blank">Baylor College of Medicine</a>. </p><p> 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 <a href="https://github.com/aidenlab/juicer/wiki" target="_blank">Juicer</a> 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 <a href="hgTrackHubHelp.html#Hosting">Hosting</a> section of the Track Hub Help -documentation.</p> +the <a href="https://github.com/aidenlab/juicer/wiki" target="_blank">Juicer</a> pipeline to +produce a hic file. Due to the large size of many of these files, UCSC is not able to support +direct upload via our Custom Track interface. Instead, users should place their Hic files in a +web-accessible space and enter the URL as a bigDataUrl. If you do not have access to a +web-accessible server and need hosting space for your Hic files, please see the +<a href="hgTrackHubHelp.html#Hosting">Hosting</a> section of the Track Hub Help documentation.</p> <p>The UCSC tools currently support hic versions 6-8.</p> <h2>Generating a hic track</h2> <p> The typical workflow for generating a hic custom track is this:</p> <ol> <li> Prepare your data by processing it with the <a href= "https://github.com/aidenlab/juicer/wiki" target="_blank">Juicer</a> pipeline to create a file in the hic format. </li> <li> Move the hic file (<em>my.hic</em>) to an http, https, or ftp location.</li> <li> Construct a <a href="hgTracksHelp.html#CustomTracks">custom track</a> using a single @@ -42,83 +41,79 @@ </li> <li> Paste the custom track line into the text box in the <a href="../../cgi-bin/hgCustom" target="_blank">custom track management page</a>, click "submit" and view in the Genome Browser.</li> </ol> <h2>Parameters for hic custom track definition lines</h2> <p> All options are placed in a single line separated by spaces (lines are broken only for readability here):</p> <pre><code><strong>track type=hic bigDataUrl=</strong><em>http://...</em> <strong>name=</strong><em>track_label</em> <strong>description=</strong><em>center_label</em> <strong>visibility=</strong><em>display_mode</em> - <strong>priority=</strong><em>priority</em> <strong>db=</strong><em>db</em></code></pre> <p> Note if you copy/paste the above example, you must remove the line breaks. Click <a href="examples/hicExample.txt">here</a> for a text version that you can paste without editing.</p> <p> The track type and bigDataUrl are REQUIRED:</p> <pre><code><strong>type=hic bigDataUrl=</strong><em>http://myorg.edu/mylab/my.hic</em></strong> </code></pre> <p> The remaining settings are OPTIONAL:</p> <pre><code><strong>name </strong><em>track label </em> # default is "User Track" <strong>description </strong><em>center label </em> # default is "User Supplied Track" <strong>visibility </strong><em>full|dense|hide </em> # default is hide (will also take numeric values 4|1|0) -<strong>priority </strong><em>N </em> # default is 100 <strong>db </strong><em>genome database </em> # e.g. hg19 for Human Feb. 2009 (GRCh37) </code></pre> <p>Note that hic tracks currently only support the full, dense, and hide visibility modes. The <a target="_blank" href="hgHicTrackHelp.html">hic track configuration</a> help page describes the hic track configuration page options.</p> <h3>Example #1</h3> <p> 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:</p> -<p> -Rao SS, Huntley MH, Durand NC, Stamenova EK, Bochkov ID, Robinson JT, Sanborn AL, Machol I, Omer AD, -Lander ES <em>et al</em>. -<a href="https://linkinghub.elsevier.com/retrieve/pii/S0092-8674(14)01497-4" target="_blank"> -A 3D map of the human genome at kilobase resolution reveals principles of chromatin looping</a>. -<em>Cell</em>. 2014 Dec 18;159(7):1665-80. -PMID: <a href="https://www.ncbi.nlm.nih.gov/pubmed/25497547" target="_blank">25497547</a>; PMC: <a -href="https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5635824/" target="_blank">PMC5635824</a> -</p> -<p> -The line breaks inserted here for readability must be removed before submitting the track line:</p> -<pre><code>browser position chr21:33,034,804-33,037,719 +internet server — data from an in situ Hi-C experiment on the HMEC cell line +mapped to the hg19 assembly. Data cited at the bottom.</p> +<p> +The line breaks inserted in the track line for readability must be removed before submitting +this entry as a Custom Track. Click <a href="examples/hicExampleOne.txt">here</a> for a +text version you can paste without editing. The "browser" line above is used set +the default view to a region of chromosome 21.</p> +<pre><code>browser position chr21:32,000,000-35,000,000 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</code></pre> <p> -The "browser" line above is used to view a small region of chromosome 21.</p> -<p> -Note if you copy/paste the above example, you must remove the line breaks (or, click -<a href="examples/hicExampleOne.txt">here</a> for a text version that you can paste without -editing).</p> -<p> Paste the "browser" line and "track" line into the <a href="../../cgi-bin/hgCustom" target="_blank">custom track management page</a> 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.</p> +<p> +Rao SS, Huntley MH, Durand NC, Stamenova EK, Bochkov ID, Robinson JT, Sanborn AL, Machol I, Omer AD, +Lander ES <em>et al</em>. +<a href="https://linkinghub.elsevier.com/retrieve/pii/S0092-8674(14)01497-4" target="_blank"> +A 3D map of the human genome at kilobase resolution reveals principles of chromatin looping</a>. +<em>Cell</em>. 2014 Dec 18;159(7):1665-80. +PMID: <a href="https://www.ncbi.nlm.nih.gov/pubmed/25497547" target="_blank">25497547</a>; PMC: <a +href="https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5635824/" target="_blank">PMC5635824</a> +</p> + <h3>Example #2</h3> <p> In this example, you will load a hub that has hic data described in a hub's trackDb.txt file. First, navigate to the <a href="hubQuickStart.html" target="_blank">Basic Hub Quick Start Guide</a> and review an introduction to hubs.</p> <p> Visualizing hic files in hubs involves creating three text files: <em>hub.txt</em>, <em>genomes.txt</em>, and <em>trackDb.txt</em>. The browser is passed a URL to the top-level <em>hub.txt</em> file that points to the related <em>genomes.txt</em> and <em>trackDb.txt</em> files. The <em>trackDb.txt</em> 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:</p> <pre><code>track hic1 bigDataUrl http://http://hgdownload.soe.ucsc.edu/gbdb/hg19/bbi/hic/GSE63525_GM12878_insitu_primary+replicate_combined.hic shortLabel hic example