defacab8acb926ded12e379c9efb840ce3e31da2
gperez2
Mon Oct 24 12:42:34 2022 -0700
Creating a new GB page for public hub guidelines, Docs #28424
diff --git src/hg/htdocs/goldenPath/help/publicHubGuidelines.html src/hg/htdocs/goldenPath/help/publicHubGuidelines.html
old mode 100644
new mode 100755
index bea0b78..805eb57
--- src/hg/htdocs/goldenPath/help/publicHubGuidelines.html
+++ src/hg/htdocs/goldenPath/help/publicHubGuidelines.html
@@ -1,15 +1,267 @@
-Required Guidelines
+Public Hub Guidelines
-This page is intended to lay out guidelines for those who are trying to create Public Hubs.
-If you’ve created a hub that you feel meets these requirements and is of general interest to
-the research community, please contact us at genome-www@soe.ucsc.edu to have it added to the list.
-false positives in a collection of scores.
+The Genome Browser provides links to a collection of public hubs that have been registered
+with UCSC and are available to view on the Public Hubs page.
+Here are guidelines for those who are trying to make a hub a UCSC public hub. If you have created a
+hub that meets the requirements and is of general interest to the research community, please
+contact us at
+
+genome-www@soe.ucsc.edu
+ to have it added to the list.
+
+As a reference for interpreting trackDb.txt settings use the Hub Track Database Definition glossary. For information on using the Track
+Hub features, refer to the Genome Browser Track Hub User Guide.
+See also the Basic Hub Quick Start Guide, Quick Start Guide to Organizing Track Hubs into
+Groupings, Track hub settings blog post, Quick Start Guide to Assembly Hubs and Quick Start Guide to Searchable Track Hubs.
+
+
+Contents
+
+
+
+
+
+
+Required Guidelines
+The following guidelines must be met before your hub will be added to our public list:
+Required for both track and assembly hubs:
+
+ - You MUST have a description page for every configuration page (composite, superTrack or stand
+ alone track). Note that multiple tracks and/or composites can use the same description page
+ with the "html" setting. You can
+ find more information on creating track description pages in the
+ recommendations section below.
+
+ - All of your description pages MUST have a contact email address prominently displayed.
+
+ - Try to have no more than 10 tracks with visibility set to display (in full, pack, dense,
+ or squish) as default upon first connecting your hub.
+
+ - Have a descriptionUrl html page specified in your hub.txt. This should be a URL to a description
+ page for your entire hub, often public hubs will link to a full-text paper or to their
+ laboratory webpage that describes the research presented in the hub. These links are presented
+ on the Public Hubs page as a hyperlink on the longLabel presented in the hub.txt, while the
+ shortLabel is a hyperlink to the hub.txt location.
+
+
+
+Required for only assembly hubs:
+
+ - Add a gateway page for each assembly by having a htmlPath line for each genome not already
+ hosted by UCSC in the genomes.txt.
+
+ - The following settings should properly be set in your genomes.txt (The last 3 settings will make
+ it easier to find assembly hub species in hgGateway by UI search):
+
+
+ - defaultPos
+ - scientificName
+ - organism
+ - description
+
+
+
+
+Recommended Guidelines
+These guidelines in the following sections are recommended to improve user experience, but are
+ not required to be implemented before the hub is added to our list of Public Hubs.
+Track organization recommendations
+
+Related tracks can be grouped in a few different ways, namely superTracks, multiWigs, and composites. If your hub includes a large number of tracks, the grouping of
+tracks may be necessary. This will prevent your hub's track group from being an overwhelming mess
+of individual tracks and can make user configuration of your tracks easier.
+
+Composite tracks
+
+Related tracks of the same data type (e.g. a set of related bigBed tracks) should be combined into
+composites where
+appropriate.
+
+ - Have multi-view 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.
+ - Recommendations for using dimensions with your composite tracks:
+
+ - There should be no
+ dimensions 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.
+ - 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.
+ - Using two dimensions: use dimX and dimY (e.g. dimensions dimX=cell dimY=mark)
+ - 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)
+ - The A,B,C.. dimensions should probably use filterComposite (e.g. filterComposite dimA)
+ - 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=+).
+
- 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
+ - 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.
+
+
+
+Super tracks
+
+Extremely large hubs may use superTracks 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.
+
+Track display recommendations
+
+ - 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.
+ - The shortLabel text should be under 17 characters, or meaningful information may be cut off
+ from display when tracks are set to "dense" visibility.
+
+
+Track description page recommendations
+
+ - 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 template page.
+ - Your track description pages should provide meaningful documentation for your tracks.
+
+ - 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
+ - The Methods section expand upon the overview of the Description section and provide more
+ details about how the data for the track was produced
+ - 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.
+
+ - 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.
+
+
+
+Public Hub Examples
+
+Many of the public hubs 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 glossary.
+
+Some Hub Track Database Definition settings like filters have additional help documentation. Also note that if
+you are only displaying one genome you can use the useOneFile on setting.
+
+Example Track Hubs
+Example 1
+The Principal Splice Isoforms APPRIS hub provides a good example of basic hub that
+includes a few different annotation tracks. Each track includes its own description page and is
+colored in such a way that distinguishes it from the other tracks in the hub and native track in
+the UCSC Genome Browser.
+
+Here are some links to their configuration files and some description pages:
+
+
+Example 2
+The Roadmap Epigenomics Integrative Analysis Hub provides a great example of how
+you might use organize your hub if you have thousands of different tracks. The hub uses composites
+with dimensions to organize thousands of different tracks across a number of cell lines and uses
+supertracks to group these tracks even further.
+
+Here are some links to their configuration files and some description pages:
+
+
+Example Assembly Hub
+The C elegans isolates hub provides an excellent example of what your assembly hub could
+look like. The hub creators provide a detailed description page for each assembly, many different annotations
+tracks each with their own description page, and clearly defined track groups with those related
+tracks grouped together.
+
+Here are some links to their configuration files and some description pages:
+