9ef756f18472a7b7f750f80bfa29836372aeaeb4 gperez2 Tue Nov 1 18:07:03 2022 -0700 Code review edits for the public hub guidelines page, refs #30206 diff --git src/hg/htdocs/goldenPath/help/publicHubGuidelines.html src/hg/htdocs/goldenPath/help/publicHubGuidelines.html index 88706f5..ba10de9 100755 --- src/hg/htdocs/goldenPath/help/publicHubGuidelines.html +++ src/hg/htdocs/goldenPath/help/publicHubGuidelines.html @@ -92,90 +92,90 @@ of individual tracks and can make user configuration of your tracks easier.</p> <h6>Composite tracks</h6> <p> Related tracks of the same data type (e.g. a set of related bigBed tracks) should be combined into <a href="trackDb/trackDbHub.html#compositeTrack" target="_blank">composites</a> where appropriate.</p> <ul> <li>Have <a href="trackDb/trackDbHub.html#view" target="_blank">multi-view</a> only when there is more than one view. Views ideally give alternate access to the same data (e.g. signals and called peaks). Keep in mind that the value of views is that they allow for more than one data/configuration type (e.g. bigBed and bigWig) in a single composite. All subtracks of a view must have the same data type. Likewise, all subtracks of a non-multi-view composite must be the same type.</li> <li>Recommendations for using dimensions with your composite tracks:</li> - <ol> + <ul> <li>There should be no <a href="trackDb/trackDbHub.html#dimensions" target="_blank"> dimensions</a> with a single entry (do not have only one cell line represented in dimX=cell), unless data growth is expected to fill in additional entries.</li> <li>Using only one dimension: preferably use dimX (e.g. dimensions dimX=cell). This saves vertical User Interface space, but is not always the best choice.</li> <li>Using two dimensions: use dimX and dimY (e.g. dimensions dimX=cell dimY=mark)</li> <li>Using more than two: use dimX, dimY on the most important dimensions. Then use dimA,B,C as needed on lesser dimensions. (e.g. dimensions dimX=cell dimY=mark dimA=donor_id)</li> <li>The A,B,C dimensions should probably use <a href="trackDb/trackDbHub.html#filterComposite" target="_blank">filterComposite</a> (e.g. filterComposite dimA)</li> <li>Each dimension and views should be represented in sortOrder, ideally in order of dimX, dimY, dimA,B,C, view (e.g. sortOrder cell_type=+ mark=+ donor_id=+ view=+). <li>Tags of subGroup/dimension should be short and sweet with no special chars. Also labels can have HTML codes embedded (e.g. NOT CPG_methylation_%=CPG_methylation_% RATHER mpct=CPG_methylation_&_#37)</li> <li>Never represent the same subgroup in both view and as a dimension (e.g. NOT dimensions dimX=view). A subgroup should never be in two dimensions (e.g. NOT dimensions dimX=cell dimY=mark dimA=cell). The composite will appear to function but multiple ways of selecting the same thing will create a confusing and inconsistent user interface.</li> - </ol> + </ul> </ul> <h6>Super tracks</h6> <p> Extremely large hubs may use <a href="trackDb/trackDbHub.html#superTrack" target="_blank">superTracks</a> as well to achieve a meaningful hierarchy. Super tracks can be used to group together any type of related tracks; for example, you could combine a multiWig, a composite, and a bigBed track together into a single superTrack.</p> <h3>Track display recommendations</h3> <ul> <li>Avoid setting a composite track and all of its subtracks to the same visibility. When you have composite tracks that are hidden by default, it is best to still designate some subtracks to display when the composite track is turned on (visibility dense, versus the default of hide). This provides an example of your track data to users who turn on your composite track. If no subtracks are turned on by default, a user who changes your composite track visibility to "show" won't see anything.</li> <li>The shortLabel text should be under 20 characters, or meaningful information may be cut off from display when tracks are set to "dense" visibility.</li> </ul> <h3>Track description page recommendations</h3> <ul> <li>The description page should preferably contain UCSC's standard track description, Display Conventions and Configuration, Methods, Credits, and References. More information can be found on the <a href="examples/hubExamples/templatePage.html" target="_blank">template page</a>.</li> <li>Your track description pages should provide meaningful documentation for your tracks. - <ol> + <ul> <li>If you are creating a hub based on a paper, use the paper's abstract as a starting point for your track's description section</li> <li>The Methods section expand upon the overview of the Description section and provide more details about how the data for the track was produced</li> <li>You should assume a broad audience of students and researchers will use your hubs. You should spell out common acronyms for those who may be new to genomics. For example, you might write out a term and its acronym as follows "Fluorescent in situ hybridization (FISH)" which spells it out and then provides the acronym that you can use throughout the rest of your description page.</li> - </ol> + </ul> <li>It might be a good idea to include a "Data Access" section on your track description page which describes how to access the data in your hub and where to download the raw data for the tracks in your hub.</li> </ul> <a id="publicHubExamples"></a> <h2>Public Hub Examples</h2> <p>Many of the <a target="_blank" href="../../cgi-bin/hgHubConnect?#publicHubs" >public hubs</a> in the Genome Browser provide excellent examples or templates for creating your own hub. As a reference for interpreting trackDb.txt lines used in these example hubs, please refer to the Hub Track Database Definition <a target="_blank" href="trackDb/trackDbHub.html#loc">glossary</a>.</p> <p>Some Hub Track Database Definition settings like <a target="_blank" href="hubQuickStartFilter.html">filters</a> have additional help documentation. Also note that if