26e75bcc08d44f024ac657e96ef829295411cb95 dschmelt Fri May 3 14:35:41 2019 -0700 Pushing changes including formatting, typo corrections, and composite track info #23131 diff --git src/hg/htdocs/FAQ/FAQlink.html src/hg/htdocs/FAQ/FAQlink.html index 91c8788..ed4fe58 100755 --- src/hg/htdocs/FAQ/FAQlink.html +++ src/hg/htdocs/FAQ/FAQlink.html @@ -1,143 +1,151 @@ <!DOCTYPE html> <!--#set var="TITLE" value="Genome Browser FAQ" --> <!--#set var="ROOT" value=".." --> <!-- Relative paths to support mirror sites with non-standard GB docs install --> <!--#include virtual="$ROOT/inc/gbPageStart.html" --> <h1>Frequently Asked Questions: Linking to the Genome Browser</h1> <h2>Topics</h2> <ul> -<li><a href="#link1">Creating a custom URL to view specific tracks</a></li> +<li><a href="#link1">Creating a sharable URL to view specific tracks</a></li> <li><a href="#link2">Linking to the Browser at a specific position</a></li> <li><a href="#link3">Linking to gene specific information</a></li> -<li><a href="#trackViz">Changing Track Visibilites via URL</a></li> +<li><a href="#trackViz">Changing Track Visibility via URL</a></li> <li><a href="#ctUrl">Adding Custom Tracks via URL</a></li> <li><a href="#hubUrl">Connection to a Track Hub via URL</a></li> <li><a href="../goldenPath/help/customTrack.html#optParams">Additional URL parameters</a></li> </ul> <a name="link1"></a> -<h2>Creating a custom URL to view specific tracks</h2> +<h2>Creating a sharable URL to view specific tracks</h2> <p> -The easiest way to save and share tracks via URL is by +The easiest way to save and share tracks from the URL is by <a href="../cgi-bin/hgLogin" TARGET="_blank">logging in</a> to your Genome Browser account and creating a <a href="../goldenPath/help/hgSessionHelp.html">saved session</a>. -Saved sessions are a versatile way to share data and may include native data, Custom Tracks, and +Saved sessions are a versatile way to share data that may include native data, Custom Tracks, and Track Hubs.</p> <p> -You will be able to save and restore Genome Browser sessions with the following formats: -<pre>http://genome.ucsc.edu/s/<em>userName</em>/<em>sessionName</em></pre></p> +You will be able to save and share Genome Browser sessions with the following format: +<p><code>http://genome.ucsc.edu/s/<em>userName</em>/<em>sessionName</em></code></p></p> <p> -Or if you prefer the modifiable, longer format URL, use this format:</p> -<pre>http://genome.ucsc.edu/cgi-bin/hgTracks?hgS_doOtherUser=submit&hgS_otherUserName=[<em>UserName</em>]&hgS_otherUserSessionName=[<em>SessionName</em>]</pre> +Or if you prefer the a modifiable, longer URL; use this format:</p> +<p><code>http://genome.ucsc.edu/cgi-bin/hgTracks?hgS_doOtherUser=submit&hgS_otherUserName=[<em>UserName</em>]&hgS_otherUserSessionName=[<em>SessionName</em>]</code></p> <p> For instructions on creating a saved session, go to the <a href="../goldenPath/help/hgSessionHelp.html#Create">Saved Session Help page</a>.</p> <p> -If you want to specify track settings in a URL directly, you can do so by naming the track and -visibility option directly in the URL. Note that these track parameters do not work on the shorter -session URLs. For example, the following URL parameters displays the hg38 genome database with the -Known Gene track in pack mode and the RefSeq Genes in full mode: -<pre><code><a href="http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&knownGene=pack&refGene=full">http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&knownGene=pack&refGene=full</a></code></pre> +If you want to specify track settings in a URL directly, please read the section on +<a href"#trackViz">changing track visibility via URL</a> for a complete description. +Note that these URL parameters do not work with the shorter session URLs. <a name="link2"></a> -<h2>Linking to a specific position in the Genome Browser</h2> +<h2>Linking to the Browser at a specific position</h2> <p> -You can link to a specific position in the Genome Browser using a URL with the <code>db=</code> -and <code>position=</code> parameters:</p> +You can link to a specific genome assembly and position in the Genome Browser using a URL with +the <code>db=</code> and <code>position=</code> parameters:</p> <p><code>http://genome.ucsc.edu/cgi-bin/hgTracks?db=[<em>db</em>]&position=[<em>position</em>]</code></p> <p> Where:</p> <ul> <li> <code>db</code> - designates a specific genome assembly. For example, <code>db=hg19</code> - refers to the Feb. 2009 human genome release. For a list of the db parameter values that + refers to the Feb. 2009 human genome release. For a list of db parameter values that correspond to UCSC assemblies, see the <a href="FAQreleases.html#release1">list of UCSC releases</a>.</li> - <li><code>position</code> - can be any search value valid for the genome specified, including + <li><code>position</code> - can be any seach term for the genome specified, including a position range or a gene identifier. This often takes the form of <code>position=chr1:35000-40000</code>.</li> </ul> <p>The following link is an example of a URL that declares assembly and position:</p> <p><code><a href=../cgi-bin/hgTracks?db=hg19&position=chr1:35000-40000>http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg19&position=chr1:35000-40000</a></code></p> <a name="hgsid"></a> <h2>The <em>hgsid</em> parameter</h2> -<p><code>hgsid=724184099_ZY6sql8XPIZcZx9b2RJm2aQBBZ78</code></p> - -<p>The hgsid is a temporary user ID that stores display setting and custom track information. -Including it in any shared URLs is a privacy concern, and should be removed when +<p>The hgsid is a temporary user ID that stores setting and custom track information in the URL. +Including it in any shared URLs is a privacy concern, and it should be removed when constructing any links to the Genome Browser. Creating -<a href="../goldenPath/help/hgSessionHelp.html#Create">Saved Sessions</a> is a much safer way to -share particular Genome Browser views. +<a href="../goldenPath/help/hgSessionHelp.html#Create">Saved Sessions</a> is the recommended way to +share Genome Browser information. </p> + <a name="trackViz"></a> <h2>Setting Track Visibitlies via URL</h2> <p> -You can control the visibility of tracks via the URL with the following parameters, -each linked by the & sign, similar to previous commands. Here are a few commands you can use -to control track visibility. Note that <em>italic text</em> indicates a user variable and not -a valid a option.</p> +You can control the visibility of tracks from the URL with the following parameters, +each linked by the "&" sign, similar to position commands. For the full list, please see the +<a href="../../goldenPath/help/customTrack.html#optParams" target ="_blank">optional URL +parameters</a> section of the Custom Tracks User's Guide. Note that <em>italic text</em> indicates +a user choice, not a working example.</p> <ul> <li>hideTracks=1</li> <li><em>trackName</em>=hide|dense|pack|full</li> <li>textSize=<em>number</em></li> -<li>ignoreCookie=1</li> -<li>position=chr1:25000-30000</li> -<li>position=<em>geneSymbol</em>&singleSearch=knownCanonical</li> </ul> <p> -For example, you can use the following command to only show the knownGene track:</p> -<pre><a href=../cgi-bin/hgTracks?db=hg38&hideTracks=1&knownGene=pack>http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hideTracks=1&knownGene=pack</a></pre> -<p>You can use the following command to go to a particular position: </p> -<pre><a href=../cgi-bin/hgTracks?db=hg19&position=chr1:25000-30000>http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg19&position=chr1:25000-30000</a></pre> -<p>You can use the following command to go to a particular gene:</p> -<pre><a href=../cgi-bin/hgTracks?db=hg38&position=KRAS&singleSearch=knownCanonical>http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&position=KRAS&singleSearch=knownCanonical</a></pre> -<p><a href="../../goldenPath/help/customTrack.html#optParams" target ="_blank">URL optional -parameters</a> section of the Custom Tracks User's Guide.</p> +For example, you can use the following command to hide every track and set the knownGene track to +the pack visibiblity:</p> +<p><code><a href=../cgi-bin/hgTracks?db=hg38&hideTracks=1&knownGene=pack>http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hideTracks=1&knownGene=pack</a></code></p> + +<p>Composite tracks have additional URL parameters that encode options to hide, select, and +display subtracks.</p> +<ul> +<li><em>trackName</em>_hideKids=1</li> +<li><em>trackName</em>_sel=1</li> +<li>ignoreCookie=1</li> +</ul> +<p>For example, the following URL hides all tracks (&hideTracks=1), hides a specific composite +track's default subtracks (&refSeqComposite_hideKids=1), turns on one specific subtrack +(&ncbiRefSeqCurated=full), and checks a box to display that subtrack +(&ncbiRefSeqCurated_sel=1). +<pre><a href="https://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hideTracks=1&refSeqComposite_hideKids=1&ncbiRefSeqCurated=full&ncbiRefSeqCurated_sel=1">https://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hideTracks=1&refSeqComposite_hideKids=1&ncbiRefSeqCurated=full&ncbiRefSeqCurated_sel=1</a></pre> <a name="link3"></a> <h2>Linking to the Browser to get gene information</h2> <p> To jump directly to a gene's position on the Genome Browser, set the position parameter in the -URL to a gene symbol (TP53, MTOR, KRAS, etc.) and add the -parameter <code>singleSearch=knownCanonical</code>. For example, this link will open the -Genome Browser for the hg19 human assembly at the position of the knownCanonical transcript -associated with TP53:</p> -<pre><code><a href="../cgi-bin/hgTracks?db=hg19&singleSearch=knownCanonical&position=TP53" target="_blank">http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg19&singleSearch=knownCanonical&position=TP53</a></code></pre> +URL to a gene symbol (e.g., TP53, MTOR, KRAS) and add the parameter +<code>&singleSearch=knownCanonical</code>. For example, the following link will open the +Genome Browser for the hg19 human assembly at the position of TP53 on the knownCanonical dataset +</p> +<p><code><a href="../cgi-bin/hgTracks?db=hg19&singleSearch=knownCanonical&position=TP53" target="_blank">http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg19&singleSearch=knownCanonical&position=TP53</a></code></p> <p> <a name="gene"></a> -You can also link directly to gene description pages from the URL. The following URL -connecting to 'hgGene' will open up the Genome Browser description page -containing funtion information, expression profile, and links to associated information for the above gene. -Note the use of the URL parameter <code>hgg_gene=</code>:</p> -<pre><code><a href="../cgi-bin/hgGene?db=hg19&hgg_gene=TP53" target="_blank">http://genome.ucsc.edu/cgi-bin/hgGene?db=hg19&hgg_gene=TP53</a> </code></pre> +You can also link directly to gene description pages from the URL. Instead of a position search, +gene descriptions use the <code>&hgg_gene=</code> URL parameter. The following URL connecting +to 'hgGene' will open up the Genome Browser description page containing protein function, +expression profile, and links to additional information for the gene TP53. +</p> +<p><code><a href="../cgi-bin/hgGene?db=hg19&hgg_gene=TP53" target="_blank">http://genome.ucsc.edu/cgi-bin/hgGene?db=hg19&hgg_gene=TP53</a> </code></p> <h2>Loading data using a URL</h2> <a name="ctUrl"></a> <h3>Load Custom Track data with a URL</h3> <p> -You can combine the URL visibility settings with the <code>hgct_customText=</code> parameter using +You can combine the URL visibility settings with the <code>&hgct_customText=</code> parameter using a track line you would otherwise put in the <a href=../cgi-bin/hgCustom>custom track -input box</a>. The following is an example of the hgct_customText URL variable:</p> +input box</a>. The following is an example of the <code>hgct_customText</code> URL variable, where +"%20" is the URL encoding for spaces:</p> <p> -Try the following example of the hgct_customText URL variable, note that the hub only has data -on chromosome 21: -<pre><a href=../cgi-bin/hgTracks?db=hg38&hgct_customText=track%20type=bigBed%20bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/bigBedExample.bb>http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hgct_customText=track%20type=bigBed%20bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/bigBedExample.bb</a></pre> +Try the following example of the hgct_customText URL variable. +<pre><a href=../cgi-bin/hgTracks?db=hg38&hgct_customText=browser%20position=chr1%20track%20type=bigBed%20bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/bigBedExample.bb>http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg38&hgct_customText=track%20type=bigBed%20bigDataUrl=https://genome.ucsc.edu/goldenPath/help/examples/bigBedExample.bb</a></pre> </p> <a name="hubUrl"></a> <h3>Load a Track Hub with a URL</h3> -<p>Similar to Custom Tracks, track hubs can be loaded into the URL usig the <code>hubUrl=</code> -parameter. This parameter takes input similar to the <a href=../cgi-bin/hgHubConnect#unlistedHubs>Track Hub interface</a>. Try the -following example for reference:</p> -<pre><a href=../cgi-bin/hgTracks?hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/hub.txt&genome=hg19>http://genome.ucsc.edu/cgi-bin/hgTracks?hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/hub.txt&genome=hg19</a></pre> - +<p>Similar to custom tracks, track hubs can be loaded into the URL using the +<code>&hubUrl=</code> parameter. This parameter takes input similar to the +<a href=../cgi-bin/hgHubConnect#unlistedHubs>track hub interface</a>. Try the following example +for reference:</p> +<pre><a href=../cgi-bin/hgTracks?hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/hub.txt&db=hg19>http://genome.ucsc.edu/cgi-bin/hgTracks?hubUrl=https://genome.ucsc.edu/goldenPath/help/examples/hubDirectory/hub.txt&db=hg19</a></pre> + +<p>Hubs track visibility can also be changed from the URL parameters. The following link loads a +specific track from a supertrack with multiple composite subtracks.</p> +<pre><a href"https://genome.ucsc.edu/cgi-bin/hgTracks?db=hg19&hubUrl=http://hgdownload.soe.ucsc.edu/hubs/gtex/hub.txt&hideTracks=1>exRnaSignalMaleYoung_hideKids=1>exRnaSignalMaleYoung=full>exRnaSignalSRR1311243=full&ignoreCookie=1">https://genome.ucsc.edu/cgi-bin/hgTracks?db=hg19&hubUrl=http://hgdownload.soe.ucsc.edu/hubs/gtex/hub.txt&hideTracks=1&gtexRnaSignalMaleYoung_hideKids=1&gtexRnaSignalMaleYoung=full&gtexRnaSignalSRR1311243=full&ignoreCookie=1</a></pre> <!--#include virtual="$ROOT/inc/gbPageEnd.html" -->