e45b31facc4d22170d23baa9016bfb82de3c55c1 brianlee Fri Jan 24 13:01:44 2020 -0800 Revising superTrack visibility explanations requested by Max refs #24746 diff --git src/hg/htdocs/goldenPath/help/hubQuickStartGroups.html src/hg/htdocs/goldenPath/help/hubQuickStartGroups.html index 20918e8..f477e68 100755 --- src/hg/htdocs/goldenPath/help/hubQuickStartGroups.html +++ src/hg/htdocs/goldenPath/help/hubQuickStartGroups.html @@ -53,31 +53,31 @@ <h2>The three types of track groupings</h2> <p> Now that you have the hub copied from above, start to edit some of the trackDb.txt settings to understand how they work. Read more about <a href="trackDb/trackDbHub.html" target="_blank">trackDb settings</a> in the definition document. Note that the Browser waits 5 minutes before checking for any changes to these files. <strong>When editing hub.txt, genomes.txt, trackDb.txt, and related hub files shorten this delay by adding <code>udcTimeout=1</code> to your URL.</strong> For more information, please see the <a href="hgTrackHubHelp.html#Debug" target="_blank">Debugging and Updating Track Hubs</a> section of the <a href="hgTrackHubHelp.html" target="_blank">Track Hub User Guide</a>. For more detailed instructions on setting up a hub, please see the <a href="hgTrackHubHelp.html#Setup" target="_blank">Setting Up Your Own Track Hub</a> section of the Track Hub User Guide. <ul> <li><strong><a href="#multiWig">Understanding multiWig tracks</a></strong> <li><strong><a href="#composite">Understanding composite tracks</a></strong> - <li><strong><a href="#superTrack">Understanding super-tracks</a></strong> + <li><strong><a href="#superTrack">Understanding supertracks</a></strong> </ul> <h2>Resources</h2> <ul> <li> <strong><a href="hgTrackHubHelp.html" target="_blank">Track Hub User Guide</a></strong></li> <li> <strong><a href="trackDb/trackDbHub.html" target="_blank">Track Database (trackDb) Definition Document</a></strong></li> <li> <strong><a href="http://genomewiki.ucsc.edu/index.php/Assembly_Hubs" target="_blank">Assembly Hubs Wiki</a></strong></li> <li> <strong><a href="http://genomewiki.ucsc.edu/index.php/Public_Hub_Guidelines" target="_blank">Public Hub Guidelines Wiki</a></strong></li> @@ -133,53 +133,71 @@ A composite track groups together related tracks, usually but not necessarily of a similar type, that you want to display together (referred to as "subtracks"). If you want to organize tracks into a hierarchy and there is a single level of grouping, use a composite. For example, you could group together called variants or ChIP-seq peaks with their underlying BAM reads or sequencing coverage. The <code><strong>compositeTrack</strong> on</code> line defines the parent track that will be later referenced as <code><strong>parent</strong> uniqueCompositeTrackName off</code> in each subtrack's stanza. Either "on" or "off" can be used to set a subtrack to be displayed or not displayed by default. Composite tracks can be broken apart further to group very similar tracks with the trackDb use of <a href="trackDb/trackDbHub.html#subGroups" target="_blank">subGroups</a> and <a href="trackDb/trackDbHub.html#view" target="_blank">views</a>, not demonstrated here. Read <a href="trackDb/trackDbHub.html#Composite_Track_Settings" target="_blank">all about composite tracks here</a>. See an <a href="http://genome.ucsc.edu/goldenPath/help/examples/hubExamples/hubGroupings/hg19/trackDb.txt" target="_blank">example trackDb.txt</a>.</p> -<!-- ========== super-tracks ==================== --> +<!-- ========== supertracks ==================== --> <a name="superTrack"></a><br> -<h2>Understanding super-tracks</h2> +<h2>Understanding supertracks</h2> <pre><code><strong>track</strong> <em>uniqueSuperTrackName</em> <strong>superTrack</strong> <em>on show</em> ... <strong>track</strong> <em>uniqueNameWithoutSpaces</em> <strong>parent</strong> <em>uniqueSuperTrackName</em> ... <strong>track</strong> <em>newUniqueNameWithoutSpaces</em> <strong>parent</strong> <em>uniqueSuperTrackName</em> ... <strong>track</strong> <em>uniqueCompositeTrackNameInSuperTrack</em> <strong>compositeTrack</strong> <em>on</em> <strong>parent</strong> <em>uniqueSuperTrackName</em> ... <strong>track</strong> <em>uniqueNameWithoutSpaces</em> <strong>parent</strong> <em>uniqueCompositeTrackNameInSuperTrack on</em> ... <strong>track</strong> <em>newUniqueNameWithoutSpaces</em> <strong>parent</strong> <em>uniqueCompositeTrackNameInSuperTrack off</em> </code></pre> <p> -A super-track groups together different types of tracks - typically composites - in -a high level folder. Use a super-track if you need a second layer of hierarchy after composites. +A supertrack groups together different types of tracks - typically composites - in +a high level folder. Use a supertrack if you need a second layer of hierarchy after composites. For example, you could have a composite with RNA-seq results and a composite with ChIP-Seq results grouped -together into a super-track describing a cell line. -Super-tracks contain composite tracks or container multiWigs, but not vice +together into a supertrack describing a cell line. +Supertracks contain composite tracks or container multiWigs, but not vice versa. The <code><strong>superTrack</strong> on show</code> line allows for this track to be later referenced as <code><strong>parent</strong> uniqueSuperTrackName</code> in each of the children subtracks (note how it is only required for direct children, and not for subtracks contained in a -composite inside the super-track). The "show" is optional and sets the super-track to -display by default. Read <a href="trackDb/trackDbHub.html#superTrack" target="_blank">all about -super-tracks here</a>. See an +composite inside the supertrack -more below). The "show" is optional and sets the supertrack to +display by default. It may help to think of the original declaring supertrack stanza as a light switch +that by default is off, and can be flipped on by adding show.</p> +<p> +All tracks that claim membership to the supertrack can then set their +own visibilities in lower stanzas by declaring settings such as by having +the parent line and a separate <code>visibility dense</code> line. +If no visibility setting is defined for a track, +the default setting of hide is assigned. This can cause confusion if one +mistakenly tries to set visibilities only at the top parent supertack stanza and +leaves out visibility declarations for all children.</p> +<p> Also do not confuse the parent line with how it is used in composites. For example, +in supertracks DO NOT try something like <strike><code>parent uniqueSuperTrackName [off/on]</code></strike>, +where the <code>[off/on]</code> will only work with composite tracks. +In the above nested example you do see <code>track uniqueNameWithoutSpaces</code> with a +setting line specific only to the fact it is a child of a composite, +<code><strong>parent</strong> <em>uniqueCompositeTrackNameInSuperTrack on</em></code>. The parent +of the child composite track is in turn is a child to a supertrack declared by +<code><strong>parent</strong> <em>uniqueSuperTrackName</em></code>. +Read <a href="trackDb/trackDbHub.html#superTrack" target="_blank">all about +supertracks here</a>. See an <a href="http://genome.ucsc.edu/goldenPath/help/examples/hubExamples/hubGroupings/hg19/trackDb.txt" target="_blank">example trackDb.txt</a>.</p> <!--#include virtual="$ROOT/inc/gbPageEnd.html" -->